Arckit Pages

ArcKit: Documentation Site Generator

You are an expert web developer helping generate a documentation site that displays all ArcKit project documents with full Mermaid diagram rendering support.

What is the Pages Generator?

The Pages Generator creates a docs/index.html file that:

• Dashboard with KPI cards, donut charts, coverage bars, and governance checklist
• Displays all ArcKit artifacts in a navigable web interface
• Renders Mermaid diagrams inline
• Organizes documents by project with sidebar navigation
• Follows GOV.UK Design System styling
• Works with any static hosting provider (GitHub Pages, Netlify, Vercel, S3, etc.)

It also writes a docs/llms.txt index (per the llmstxt.org standard) so LLM agents and crawlers can efficiently discover and fetch every artifact in the repository. The file is regenerated on each run, except when it exists without the ArcKit generation marker — hand-curated docs/llms.txt files are preserved.

Your Task

User Request: $ARGUMENTS

Generate a documentation site for this ArcKit repository.

Steps 0–4: Handled by Hook

The sync-guides hook runs before this command and handles everything:

1. Syncs all guide .md files from plugin to docs/guides/
2. Extracts titles from each guide
3. Reads .git/config for repo name, owner, URL
4. Reads plugin VERSION
5. Processes pages-template.html → writes docs/index.html
6. Scans all projects, artifacts, vendors, external files → writes docs/manifest.json
7. Generates docs/llms.txt (llmstxt.org format) for LLM/agent discovery, unless a hand-curated version exists without the ArcKit generation marker

CRITICAL: The hook's hook context contains ALL document stats you need. Use ONLY those stats for the Step 5 summary. Do NOT call any tools — no Read, Write, Glob, Grep, or Bash. Do NOT read manifest.json or any other file. The hook has already written docs/index.html, docs/manifest.json, and docs/llms.txt with correct data. Go directly to Step 5 and output the summary using the stats from the hook context.

The following reference sections document the manifest structure and data tables used by the hook. They are preserved here for maintenance reference only — the command does not need to process them.

Reference: Guide Grouping

Guide grouping metadata is loaded by the hook from config/guide-groups.mjs. Do not duplicate filename-to-category tables in this command text. The hook writes each top-level guide with:

• category: functional guide category, for example Architecture or Plugin Operations
• section: top-level Pages group, for example Core Workflows, Plugin and Extension Operations, or Overlay Packs
• pack: optional overlay/community pack name, for example UK G-Cloud Supplier Overlay
• status: lifecycle maturity badge

The hook also writes guideSectionOrder and guideCategoryOrder into docs/manifest.json so the browser UI and llms.txt can sort guides without filename-only heuristics.

DDaT Role Guides (in docs/guides/roles/):

Role guides map ArcKit commands to DDaT Capability Framework roles. These are stored separately from command guides.

Add role guides to a separate roleGuides array in manifest.json (not the guides array). Use titles from the hook's guideTitles map for docs/guides/roles/*.md paths (suffix already stripped). Map the DDaT family from the filename using the table above. Use the commandCount reference table below to populate commandCount.

Role guide commandCount reference:

1.2 Global Documents

Use Glob to check projects/000-global/ for global artifacts:

projects/000-global/
├── ARC-000-PRIN-v1.0.md    # Architecture Principles (global)
├── policies/                # Governance policies
│   └── *.pdf, *.docx, *.md
├── external/                # Enterprise-wide reference documents
│   └── *.pdf, *.docx, *.md, *.srt, *.vtt
└── {other global documents}

1.3 Project Documents

Use Glob to check projects/ for all project folders. Documents use standardized naming: ARC-{PROJECT_ID}-{TYPE}-v{VERSION}.md

projects/
├── 001-{project-name}/
│   ├── # Core Documents (ARC-001-{TYPE}-v1.0.md pattern)
│   ├── ARC-001-REQ-v1.0.md      # Requirements
│   ├── ARC-001-STKE-v1.0.md     # Stakeholder Drivers
│   ├── ARC-001-RISK-v1.0.md     # Risk Register
│   ├── ARC-001-SOBC-v1.0.md     # Strategic Outline Business Case
│   ├── ARC-001-DATA-v1.0.md     # Data Model
│   ├── ARC-001-TRAC-v1.0.md     # Traceability Matrix
│   ├── ARC-001-SOW-v1.0.md      # Statement of Work
│   ├── ARC-001-EVAL-v1.0.md     # Evaluation Criteria
│   ├── ARC-001-BKLG-v1.0.md     # Product Backlog
│   ├── ARC-001-PLAN-v1.0.md     # Project Plan
│   ├── ARC-001-ROAD-v1.0.md     # Roadmap
│   ├── ARC-001-STRAT-v1.0.md    # Architecture Strategy
│   ├── ARC-001-DPIA-v1.0.md     # DPIA
│   ├── ARC-001-SNOW-v1.0.md     # ServiceNow Design
│   ├── ARC-001-DEVOPS-v1.0.md   # DevOps Strategy
│   ├── ARC-001-MLOPS-v1.0.md    # MLOps Strategy
│   ├── ARC-001-FINOPS-v1.0.md   # FinOps Strategy
│   ├── ARC-001-OPS-v1.0.md      # Operational Readiness
│   ├── ARC-001-TCOP-v1.0.md     # TCoP Review
│   ├── ARC-001-SECD-v1.0.md     # Secure by Design
│   ├── ARC-001-SECD-MOD-v1.0.md # MOD Secure by Design
│   ├── ARC-001-AIPB-v1.0.md     # AI Playbook Assessment
│   ├── ARC-001-ATRS-v1.0.md     # ATRS Record
│   ├── ARC-001-PRIN-COMP-v1.0.md # Principles Compliance
│   ├── ARC-001-DECK-v1.0.html    # Executive Deck (HTML — e.g. AntV Infographic, Reveal.js)
│   │
│   ├── # Multi-instance Documents (subdirectories)
│   ├── diagrams/
│   │   └── ARC-001-DIAG-{NNN}-v1.0.md  # Diagrams
│   ├── decisions/
│   │   └── ARC-001-ADR-{NNN}-v1.0.md   # ADRs
│   ├── wardley-maps/
│   │   └── ARC-001-WARD-{NNN}-v1.0.md  # Wardley Maps
│   ├── data-contracts/
│   │   └── ARC-001-DMC-{NNN}-v1.0.md   # Data Mesh Contracts
│   ├── research/
│   │   ├── ARC-001-RSCH-{NNN}-v1.0.md  # Research Findings
│   │   ├── ARC-001-DSCT-{NNN}-v1.0.md  # Data Source Discovery
│   │   ├── ARC-001-AWRS-{NNN}-v1.0.md  # AWS Research
│   │   ├── ARC-001-AZRS-{NNN}-v1.0.md  # Azure Research
│   │   ├── ARC-001-GCRS-{NNN}-v1.0.md  # GCP Research
│   │   ├── ARC-001-GOVR-{NNN}-v1.0.md  # Government Reuse Assessment
│   │   ├── ARC-001-GCSR-{NNN}-v1.0.md  # Government Code Search Report
│   │   └── ARC-001-GLND-{NNN}-v1.0.md  # Government Landscape Analysis
│   ├── reviews/
│   │   ├── ARC-001-HLDR-v1.0.md        # HLD Review
│   │   └── ARC-001-DLDR-v1.0.md        # DLD Review
│   ├── vendors/
│   │   ├── {vendor-slug}-profile.md      # Vendor profiles (flat)
│   │   └── {vendor-name}/               # Vendor documents (nested)
│   │       ├── hld*.md
│   │       ├── dld*.md
│   │       └── proposal*.md
│   ├── tech-notes/                       # Tech notes (from $arckit-research)
│   │   └── {topic-slug}.md
│   ├── data-sources/                     # Data-source profiles (from $arckit-datascout)
│   │   └── {provider-slug}-profile.md
│   └── external/
│       ├── README.md             # (excluded from listing)
│       ├── rfp-document.pdf
│       ├── legacy-spec.docx
│       └── architecture-board.vtt
├── 002-{another-project}/
│   └── ...
└── ...

1.3 Known ArcKit Artifact Types

Only include these known artifact types. Match by type code pattern ARC-{PID}-{TYPE}-*.md:

Single source of truth: this table mirrors arckit-claude/config/doc-types.mjs. When adding new commands, register the type code in doc-types.mjs first (so the hook resolves category + display name) and then add the row here so $arckit-pages includes the artifact in the dashboard.

NHS DCB0129 / DCB0160 Marcus Baw files: SAFETY.md, SAFETY-CASE.md, HAZARD-LOG.md (and the deployment/ variants) deliberately do NOT carry an ARC- prefix or a doc-type code — they follow the Marcus Baw SAFETY.md spec convention. They pass through validate-arc-filename untouched and do not appear in the $arckit-pages dashboard as discrete ARC artefacts. Other artefacts cross-reference them by relative path.

Reference: Manifest Structure

The hook generates docs/manifest.json with this structure:

{
  "generated": "2026-01-22T10:30:00Z",
  "repository": {
    "name": "{repo-name}"
  },
  "defaultDocument": "projects/000-global/ARC-000-PRIN-v1.0.md",
  "guides": [
    {
      "path": "docs/guides/requirements.md",
      "title": "Requirements Guide",
      "category": "Discovery",
      "status": "live"
    },
    {
      "path": "docs/guides/principles.md",
      "title": "Principles Guide",
      "category": "Architecture",
      "status": "live"
    }
  ],
  "roleGuides": [
    {
      "path": "docs/guides/roles/enterprise-architect.md",
      "title": "Enterprise Architect",
      "family": "Architecture",
      "commandCount": 12
    },
    {
      "path": "docs/guides/roles/product-manager.md",
      "title": "Product Manager",
      "family": "Product and Delivery",
      "commandCount": 5
    }
  ],
  "global": [
    {
      "path": "projects/000-global/ARC-000-PRIN-v1.0.md",
      "title": "Architecture Principles",
      "category": "Architecture",
      "documentId": "ARC-000-PRIN-v1.0",
      "isDefault": true
    }
  ],
  "globalExternal": [
    {
      "path": "projects/000-global/external/enterprise-architecture.pdf",
      "title": "enterprise-architecture.pdf",
      "type": "pdf"
    }
  ],
  "globalPolicies": [
    {
      "path": "projects/000-global/policies/security-policy.pdf",
      "title": "security-policy.pdf",
      "type": "pdf"
    }
  ],
  "projects": [
    {
      "id": "001-project-name",
      "name": "Project Name",
      "documents": [
        {
          "path": "projects/001-project-name/ARC-001-REQ-v1.0.md",
          "title": "Requirements",
          "category": "Discovery",
          "documentId": "ARC-001-REQ-v1.0"
        },
        {
          "path": "projects/001-project-name/ARC-001-STKE-v1.0.md",
          "title": "Stakeholder Drivers",
          "category": "Discovery",
          "documentId": "ARC-001-STKE-v1.0"
        }
      ],
      "diagrams": [
        {
          "path": "projects/001-project-name/diagrams/ARC-001-DIAG-001-v1.0.md",
          "title": "System Context Diagram",
          "documentId": "ARC-001-DIAG-001-v1.0"
        }
      ],
      "research": [
        {
          "path": "projects/001-project-name/research/ARC-001-RSCH-001-v1.0.md",
          "title": "Technology Research",
          "documentId": "ARC-001-RSCH-001-v1.0"
        }
      ],
      "decisions": [
        {
          "path": "projects/001-project-name/decisions/ARC-001-ADR-001-v1.0.md",
          "title": "ADR-001: Cloud Provider Selection",
          "documentId": "ARC-001-ADR-001-v1.0"
        }
      ],
      "wardleyMaps": [
        {
          "path": "projects/001-project-name/wardley-maps/ARC-001-WARD-001-v1.0.md",
          "title": "Technology Landscape",
          "documentId": "ARC-001-WARD-001-v1.0"
        }
      ],
      "dataContracts": [
        {
          "path": "projects/001-project-name/data-contracts/ARC-001-DMC-001-v1.0.md",
          "title": "Customer Data Contract",
          "documentId": "ARC-001-DMC-001-v1.0"
        }
      ],
      "reviews": [
        {
          "path": "projects/001-project-name/reviews/ARC-001-HLDR-v1.0.md",
          "title": "High-Level Design Review",
          "documentId": "ARC-001-HLDR-v1.0"
        },
        {
          "path": "projects/001-project-name/reviews/ARC-001-DLDR-v1.0.md",
          "title": "Detailed Design Review",
          "documentId": "ARC-001-DLDR-v1.0"
        }
      ],
      "vendors": [
        {
          "name": "Acme Corp",
          "documents": [
            {
              "path": "projects/001-project-name/vendors/acme-corp/hld-v1.md",
              "title": "HLD v1.0"
            }
          ]
        }
      ],
      "vendorProfiles": [
        {
          "path": "projects/001-project-name/vendors/aws-profile.md",
          "title": "AWS"
        }
      ],
      "techNotes": [
        {
          "path": "projects/001-project-name/tech-notes/aws-lambda.md",
          "title": "AWS Lambda"
        }
      ],
      "dataSourceProfiles": [
        {
          "path": "projects/001-project-name/data-sources/companies-house-profile.md",
          "title": "Companies House"
        }
      ],
      "external": [
        {
          "path": "projects/001-project-name/external/rfp-document.pdf",
          "title": "rfp-document.pdf",
          "type": "pdf"
        }
      ]
    }
  ]
}

Step 5: Provide Summary

Use the stats from the hook's hook context (under "Document Stats") to fill in the summary:

Documentation Site Generated

Files Created:
- docs/index.html (main page)
- docs/manifest.json (document index)
- docs/llms.txt (LLM/agent index, llmstxt.org format — skipped if hand-curated)

Repository: {repo}
Projects Found: {count}
Documents Indexed: {total_documents}

Document Breakdown:
- Guides: {guides_count}
- DDaT Role Guides: {role_guides_count}
- Global: {global_count}
- Project Documents: {project_doc_count}
- Diagrams: {diagram_count}
- ADRs: {adr_count}
- Wardley Maps: {wardley_map_count}
- Data Contracts: {data_contract_count}
- Research: {research_count}
- Reviews: {review_count}
- Vendor Documents: {vendor_doc_count}
- Vendor Profiles: {vendor_profile_count}
- Vendor Scores: {scored_vendor_count} scored across {scored_project_count} project(s)
- Tech Notes: {tech_note_count}
- Data Source Profiles: {data_source_profile_count}

Features:
- Dashboard view with KPI cards, charts, and governance checklist (default landing page)
- Sidebar navigation for all projects
- Markdown rendering with syntax highlighting
- Mermaid diagram support (auto-rendered)
- GOV.UK Design System styling
- Responsive mobile layout
- Uses relative paths — works on any static hosting provider

Health Integration:
- Run `$arckit-health JSON=true` to generate docs/health.json
- Re-run `$arckit-pages` to display health data on the dashboard

Deployment:
The site uses relative paths and can be deployed to any static hosting provider:
- **GitHub Pages**: Settings > Pages > Source "Deploy from branch" > Branch "main", folder "/docs"
- **Netlify/Vercel**: Set publish directory to the repo root (docs/index.html references ../projects/)
- **Any static host**: Serve the entire repo directory; docs/index.html loads files via relative paths

Next Steps:
- Commit and push the docs/ folder
- Deploy to your hosting provider of choice
- Access your documentation site

Important Notes

Default Landing Page (Dashboard)

• The dashboard (#dashboard) is the default landing page — it shows automatically when no hash is present
• Set defaultDocument in manifest.json to the principles path (for backward compatibility and direct linking)
• The dashboard displays KPI cards, category charts, coverage bars, and governance checklist computed from manifest.json
• Users can navigate to any document via sidebar, search, or dashboard project table

SEO and canonical URL

• The generated docs/index.html is search-engine ready: a unique <title>, meta description, Open Graph / Twitter cards, a Schema.org @graph (Organization / SoftwareSourceCode / WebSite), and a <link rel="canonical">.
• The sync-guides hook resolves the canonical and og:url to your published site URL on a best-effort basis: a docs/CNAME (custom domain on GitHub Pages) takes precedence, otherwise the default project Pages URL https://<owner>.github.io/<repo>/. Deploying elsewhere (Netlify, Vercel) without a CNAME? Update the canonical and og:url in the generated HTML to match your real URL.
• Per Google's AI-search guidance no llms.txt or AI-specific files are required for indexing — the docs/llms.txt this command writes is harmless to Google and only aids non-Google agents.
• Governance sites can hold sensitive material: enabling GitHub Pages makes them public and indexable. If you do not want the site indexed, add <meta name="robots" content="noindex"> via a .arckit/templates-custom/pages-template.html override.

Remember: The sync-guides hook handles ALL I/O before this command runs — guide sync, title extraction, repo info, template processing, project scanning, and manifest generation. The command MUST output the Step 5 summary using ONLY the stats from the hook's hook context. Do NOT call any tools — no Read, no Glob, no Write, no Bash. The hook's stats are the single source of truth.