Skip to content

Project: XIOPro Documentation Site

1. Project Brief

What

Build a static documentation site at docs.struxio.ai that publishes the 14 XIOPro Blueprint v5 parts plus key activation and rule files as a navigable, searchable documentation website.

Why

  1. Validate the template system: This is the first project to exercise the Documentation Site template (tpl_docs_site) end-to-end through all 9 stages, proving the XIOPro project lifecycle pipeline works. Addresses review item N25.
  2. Produce a useful deliverable: The blueprint is currently 14 large Markdown files in a repo directory. A structured docs site makes it navigable, cross-referenced, and accessible to anyone with the URL.
  3. Establish precedent: Future projects will reference this one as proof that the template system works and as a pattern for how project instances are defined.

Who

Role Agent Responsibility
PO PO-Docs Owns project lifecycle, gate approvals, scope control
Content Specialist SPEC-Content Structures docs, audits content, defines navigation
Site Builder Worker WRK-Build Scaffolds SSG, configures theme, builds, deploys

Scope

In scope: - 14 Blueprint v5 parts (Part 1 through Part 14) - ACTIVATE_GO.md, key rule files (as an "Operations" section) - MkDocs Material theme with STRUXIO branding - Deploy to docs.struxio.ai via Caddy on Hetzner - Responsive layout, dark/light mode toggle - Built-in search (MkDocs Material search plugin)

Out of scope: - Auth / access control (site is internal-access via Tailscale initially) - CMS or editing interface - Auto-sync from Git (manual rebuild for now; CI/CD can be added later) - Custom plugins or extensions beyond MkDocs Material defaults - API documentation (separate project if needed)

Template Reference

This project instantiates: TEMPLATE_test_project.md (tpl_docs_site v1.0.0)

2. Stage-by-Stage Plan

Stage 1: Idea (0.5h)

Entry gate: This document serves as the ticket.

Tasks: - [x] Idea captured: publish XIOPro blueprint as a docs site - [x] Audience: Shai (C0), GO, future team members, external reviewers - [x] Source inventory: 14 Blueprint parts + activation files

Exit gate: PO-Docs reviews this brief and approves.

Stage 2: Research (1h)

Entry gate: Idea brief approved.

Tasks: 1. Source audit: Inventory all 14 blueprint files. Check formatting consistency, frontmatter presence, heading levels, internal cross-references. - Source path: ~/STRUXIO_Workspace/struxio-design/02_xiopro_architecture/blueprint_xiopro_v5/ - Expected: 14 files, ~100k+ words total 2. Tool evaluation: Compare MkDocs Material vs Docusaurus vs VitePress. - Recommendation: MkDocs Material (Python, minimal config, excellent search, Markdown-native, dark mode built-in, widely used for technical docs) 3. Hosting evaluation: Caddy on Hetzner (already running, free, Tailscale-accessible) vs Cloudflare Pages (public, free tier). - Recommendation: Caddy on Hetzner behind Tailscale for initial internal access. 4. Reference sites: Review Stripe Docs, FastAPI Docs, MkDocs Material demo site.

Exit gate: Research memo produced and approved by PO-Docs.

Stage 3: Brainstorm (0.5h)

Entry gate: Research memo approved.

Tasks: 1. Option A — Flat structure: All 14 parts at top level, no grouping. - Pro: Simple. Con: Long nav, no logical grouping. 2. Option B — Domain grouping: Group by domain (Architecture, Agents, Governance, Operations). - Pro: Navigable, logical. Con: Slightly more config work. 3. Option C — Progressive disclosure: Landing page with domain cards, drill into parts. - Pro: Good UX. Con: Requires custom page, more effort.

Decision: Option B — Domain grouping. Balances usability with effort.

Proposed grouping: 

Home
Getting Started
  - Overview (Part 1 intro)
  - Activation (ACTIVATE_GO.md)
Architecture
  - System Architecture (Part 2)
  - Data Model (Part 3)
  - Agent Hierarchy (Part 4)
  - Execution Fabric (Part 5)
  - Infrastructure (Part 8)
Governance
  - Governance Engine (Part 6)
  - Cost & Optimization (Part 7)
  - System Review (Part 11)
Projects
  - Project Templates (Part 9)
  - Swarm Coordination (Part 10)
  - Work Plan (Part 12)
Operations
  - Control Center (Part 13)
  - External Integration (Part 14)
  - Key Rules (selected rule files)
Resources
  - Template: Documentation Site
  - This Project Instance

Exit gate: PO-Docs approves grouping and MkDocs Material selection.

Stage 4: Manifest (0.5h)

Entry gate: Approach selected.

Scope lock: - 14 Blueprint parts + 3-5 supplementary files = ~20 pages - MkDocs Material, default plugins (search, tags), STRUXIO color scheme - Deploy to Caddy as static files

Success criteria: | # | Criterion | Test | |---|-----------|------| | S1 | All 14 blueprint parts render as pages | Page count = 14+ in build output | | S2 | Navigation works (all pages reachable in 2 clicks) | Manual nav walkthrough | | S3 | Search returns results for "ODM", "governor", "swarm" | Search 3 terms | | S4 | Site loads in under 2 seconds | curl timing or browser devtools | | S5 | SSL valid at docs.struxio.ai | HTTPS request returns 200 | | S6 | Responsive at 375px, 768px, 1280px | Browser resize or devtools | | S7 | Dark/light mode toggle works | Click toggle, verify styles change |

Resource estimate: | Resource | Estimate | |----------|----------| | Agent hours | 8-12h total | | Token budget | < $3 | | Compute | Existing Hetzner, no new containers | | Storage | < 50 MB built output |

Exit gate: PO-Docs approves manifest.

Stage 5: Blueprint (1h)

Entry gate: Manifest approved.

Tasks: 1. Directory layout: 

~/STRUXIO_Workspace/struxio-app/docs-site/
  mkdocs.yml
  docs/
    index.md                    # Home page
    getting-started/
      overview.md
      activation.md
    architecture/
      system-architecture.md    # Part 2
      data-model.md             # Part 3
      agent-hierarchy.md        # Part 4
      execution-fabric.md       # Part 5
      infrastructure.md         # Part 8
    governance/
      governance-engine.md      # Part 6
      cost-optimization.md      # Part 7
      system-review.md          # Part 11
    projects/
      project-templates.md      # Part 9
      swarm-coordination.md     # Part 10
      work-plan.md              # Part 12
    operations/
      control-center.md         # Part 13
      external-integration.md   # Part 14
      rules.md                  # Key rules summary
    resources/
      template-docs-site.md
      project-instance.md

  1. MkDocs config:
  2. Theme: Material with STRUXIO blue (#0066CC) primary, dark mode toggle
  3. Plugins: search, tags
  4. Extensions: admonitions, code blocks, tables, toc

  5. Footer: Copyright STRUXIO.ai 2026

  6. Deployment pipeline:

  7. Build: mkdocs build produces site/ directory
  8. Deploy: Copy site/ to Caddy-served directory
  9. Caddy config: Add docs.struxio.ai block pointing to static dir
  10. DNS: Add A record for docs.struxio.ai (or CNAME if behind proxy)

Exit gate: PO-Docs reviews and approves blueprint.

Stage 6: Work Plan (0.5h)

Entry gate: Blueprint approved.

Sprint: 1 sprint, 1-2 days.

Ticket Title Role Estimate Depends On
TKT-D001 Content preparation: copy, clean, add frontmatter to all 14+ files SPEC-Content 2-3h --
TKT-D002 Site scaffolding: init MkDocs project, install Material theme WRK-Build 0.5h --
TKT-D003 Site configuration: mkdocs.yml, nav, theme, plugins WRK-Build 1h TKT-D002
TKT-D004 Local build and verify: all pages render, no warnings WRK-Build 0.5h TKT-D001, TKT-D003
TKT-D005 DNS and Caddy setup for docs.struxio.ai WRK-Build 0.5h --
TKT-D006 Deploy: copy built site to Caddy; verify HTTPS WRK-Build 0.5h TKT-D004, TKT-D005
TKT-D007 Verification: run all test criteria (S1-S7) PO-Docs 0.5h TKT-D006

Parallelization: TKT-D001 and TKT-D002 run in parallel. TKT-D005 runs in parallel with content/build work.

Critical path: TKT-D001 -> TKT-D004 -> TKT-D006 -> TKT-D007

Exit gate: PO-Docs approves sprint plan.

Stage 7: Test Plan (0.5h)

Entry gate: Work plan approved.

Test criteria (mapped to success criteria):

Test ID Success Criterion Test Method Pass Condition
T1 S1: All parts render mkdocs build output check 14+ HTML files in site/
T2 S2: Nav works Manual click-through of all nav items Every nav link leads to correct page
T3 S3: Search works Type "ODM", "governor", "swarm" in search Each returns at least 1 result
T4 S4: Load time < 2s curl -w "%{time_total}" https://docs.struxio.ai/ time_total < 2.0
T5 S5: SSL valid curl -I https://docs.struxio.ai/ HTTP 200, no cert errors
T6 S6: Responsive Browser devtools at 375px, 768px, 1280px Layout adapts, no overflow
T7 S7: Dark/light toggle Click theme toggle Colors switch, no rendering artifacts
T8 -- (bonus) Broken link check (linkchecker or mkdocs strict mode) Zero broken links

Exit gate: PO-Docs approves test plan.

Stage 8: Review (0.5h)

Entry gate: All plans approved.

Checklist: - [ ] Manifest exists and is current - [ ] Blueprint exists with directory layout, config, deployment plan - [ ] Work plan has 7 tickets with ACs and estimates - [ ] Test plan maps all 7 success criteria to tests - [ ] Total estimate (8-12h) fits within 2-day ceiling - [ ] Token budget ($3) fits within project limit - [ ] No contradictions between artifacts

Go/no-go decision: Recorded on Bus by PO-Docs.

Exit gate: Go decision recorded.

Stage 9: Execute (4-10h)

Entry gate: Review passed with go decision.

Sub-stage 9A: Content Preparation (2-3h) - SPEC-Content copies all 14 Blueprint v5 parts to docs source directory - Adds/fixes MkDocs-compatible frontmatter to each file - Normalizes heading levels (H1 = page title, H2+ = sections) - Fixes cross-references to use relative links between site pages - Creates index.md home page with project overview - Creates getting-started/activation.md from ACTIVATE_GO.md

Sub-stage 9B: Build (1.5-2h) - WRK-Build initializes MkDocs project with Material theme - Configures mkdocs.yml per blueprint spec - Runs local build, fixes any warnings or errors - Verifies all pages render correctly in local preview

Sub-stage 9C: Deploy (1h) - WRK-Build sets up DNS record for docs.struxio.ai - Configures Caddy with a site block for docs.struxio.ai - Copies built site to Caddy-served directory - Verifies HTTPS access and SSL certificate

Sub-stage 9D: Verify (0.5h) - PO-Docs runs all test criteria T1-T8 - Records results on Bus - Signs off on project completion

Exit gate: All tests pass; PO-Docs records completion on Bus.

3. Agent Roster

agents:
  - id: "PO-Docs"
    role: PO
    scope: "Project lifecycle, gate approvals, final verification"
    spawned_by: GO
    persistence: project_lifetime

  - id: "SPEC-Content"
    role: content_specialist
    scope: "Content structure, cleanup, navigation, quality"
    spawned_by: PO-Docs
    persistence: project_lifetime
    spawns:
      - WRK-Build (if needed for parallel content work)

  - id: "WRK-Build"
    role: developer
    scope: "SSG scaffolding, config, build, deploy"
    spawned_by: SPEC-Content
    persistence: task_lifetime

4. Success Criteria Summary

# Criterion Measurable Target
S1 All blueprint parts published 14+ pages in built site
S2 Navigation functional All pages reachable in 2 clicks from home
S3 Search functional 3 test terms each return results
S4 Performance Page load < 2 seconds
S5 SSL Valid HTTPS at docs.struxio.ai
S6 Responsive Renders at 375px, 768px, 1280px
S7 Theme toggle Dark/light mode works

5. Budget Estimate

Item Estimate Notes
Agent compute (tokens) < $3 Content cleanup + config generation
Agent time 8-12 hours Across PO, Specialist, Worker
Infrastructure $0 Existing Hetzner + Caddy
DNS $0 Existing domain, add A record
Total < $3 + 8-12h

6. Template Validation Checklist

This project also serves as a validation of the template system itself. After completion, the following must be confirmed:

  • All 9 stages were exercised (not skipped)
  • Every stage gate was formally evaluated before proceeding
  • Step-level verification was performed within each stage
  • Agent roster matched the template spec (PO + 1 Specialist + 1 Worker)
  • Resource estimates were roughly accurate (within 2x)
  • The template was sufficient to guide the project without ad-hoc invention
  • Any template gaps are documented as feedback for template v1.1

7. Risks

Risk Probability Impact Mitigation
Blueprint files have inconsistent formatting High Low Content cleanup step handles this
MkDocs build fails on large files Low Medium Split oversized files if needed
DNS propagation delay Low Low Use existing DNS infrastructure
Scope creep (search customization, CI/CD) Medium Medium Explicit out-of-scope list enforced by PO

8. Timeline

Day 1 (morning):  Stages 1-4 (Idea through Manifest)         ~2h
Day 1 (afternoon): Stages 5-8 (Blueprint through Review)      ~3h
Day 1 (evening):  Execute sub-stages 9A-9B (Content + Build)  ~4h
Day 2 (morning):  Execute sub-stages 9C-9D (Deploy + Verify)  ~1.5h
Day 2:            Template validation checklist                ~0.5h
                                                        Total: ~11h