Documentation and Knowledge Management workflows (documentation-and-knowledge-management-workflows).
SaaS template selection workflow (saas-template-selection-workflow).

📦 Documentation Site Generator Agent Specification¶

📌 Purpose¶

The Documentation Site Generator Agent installs ConnectSoft.DocumentationTemplate, runs dotnet new connectsoft-documentation, and verifies mkdocs build using the Python dependencies listed in the generated requirements.txt. It aligns with the canonical CLI reference: Documentation Template Parameters.

What the template guarantees (ground truth)¶

Guaranteed by template	Notes
MkDocs + Material `mkdocs.yml`, `docs/` starter tree, `requirements.txt`	Plugins: search, panzoom, exclude; Mermaid via pymdownx.superfences
log4brains hooks (`package.json`, `docs/adr/`, `.log4brains.yml`)	ADR build merged in CI is shown in `azure-pipelines-documentation.yml` sample
Sample Azure Pipelines YAML, staticwebapp.config.json	Not GitHub Actions unless the agent adds it

What the agent may do beyond the template (not guaranteed by `dotnet new`)¶

Area	Typical agent assistance
`mkdocs.yml` nav	Edit `nav:` when new pages are added—manual or semi-automated; not magic auto-repair
CI/CD	Extend or duplicate the Azure sample; GitHub Actions only if explicitly requested
Hosting	Azure Static Web Apps matches the repo sample; GitHub Pages (`mkdocs gh-deploy`) is optional
Drift	May flag orphan pages vs `nav`; fixing requires explicit edits

🧾 ConnectSoft.DocumentationTemplate does not ship GitHub Actions or auto-nav repair. The agent operationalizes scaffolding and handoff; DevOps and Documentation Writer may own ongoing deployment and content.

🎯 Primary Goals¶

Goal	Description
📦 Scaffold MkDocs projects	`dotnet new connectsoft-documentation` with correct kebab-case flags per `dotnet new -h`
🧭 Nav assistance	Update `mkdocs.yml` nav when new content is introduced (explicit edits)
⚙️ CI/CD	Start from `azure-pipelines-documentation.yml`; add other hosts when requested
🔗 ADR tooling	Use existing log4brains scripts; merge ADRs in pipeline per sample
🚀 Deploy	Coordinate with DevOps for SWA or other targets; credentials are never embedded by the template

🧠 Core Role in the Factory¶

The agent sits in Documentation and Knowledge Management as the scaffold and build-verification layer for MkDocs sites. Other agents produce Markdown; this agent ensures reproducible installs, valid builds, and clear handoff to pipelines and hosting.

🧩 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	Install template; run `dotnet new connectsoft-documentation`; verify `pip install -r requirements.txt` and `mkdocs build`
🧭 Navigation Management	Edit `mkdocs.yml` nav when pages are added—explicit updates, not guaranteed automation
⚙️ CI/CD	Use template `azure-pipelines-documentation.yml` as baseline; extend or add GitHub Actions only when requested
🔗 ADR Integration	Run log4brains per generated README / package.json; align pipeline merge steps with sample
🎨 Theme and plugins	Match template: Material, panzoom, exclude, pymdownx Mermaid
🚀 Deployment	Hand off to DevOps / SWA deployment; optional `mkdocs gh-deploy` for GitHub Pages

📤 Deliverables¶

Deliverable Type	Description
📦 `documentation-site`	MkDocs project as produced by the template, build-verified
🧭 `mkdocs-config`	Updated `mkdocs.yml` when nav or metadata changes
⚙️ `doc-pipeline`	Often starts as template Azure YAML; other hosts are additive
🔗 `log4brains-config`	Uses template `.log4brains.yml` and npm scripts

📘 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:
  - panzoom
  - search
  - exclude

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 -r requirements.txt
      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	Prefer every intended `.md` under `docs/` reachable from `nav` (warn on orphans)
🔗 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	Propose `nav` edits or ask owner; do not silently rewrite without policy
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 template-driven scaffold and build-verification path for ConnectSoft MkDocs sites:

📦 Install + dotnet new against ConnectSoft.DocumentationTemplate with parameters from parameters.md
🔨 mkdocs build success using requirements.txt (Material, panzoom, exclude)
🧭 Nav and pipeline changes as explicit follow-up work—not all automatic
☁️ Deployment coordinated with DevOps; template includes Azure sample and SWA config

🧩 Position in the ConnectSoft Platform¶

flowchart TD
    CONTENT_AGENTS[ContentAgents] --> DOC_SITE[DocSiteGenerator]
    DOC_SITE --> BUILD[MkdocsBuild]
    BUILD --> DEPLOY[Deploy]
    DEPLOY --> AZURE_SWA[AzureStaticWebApps]
    DEPLOY --> GH_PAGES[GitHubPagesOptional]
    DOC_SITE --> STUDIO[StudioDashboard]

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

The template turns Markdown into a buildable site. Publishing still depends on pipelines, credentials, and review—owned jointly with DevOps and content owners.

Related workflows¶

📦 Documentation Site Generator Agent Specification¶

📌 Purpose¶

What the template guarantees (ground truth)¶

What the agent may do beyond the template (not guaranteed by dotnet new)¶

🎯 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¶

What the agent may do beyond the template (not guaranteed by `dotnet new`)¶

📘 Example Output: `mkdocs.yml`¶