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.)

Your Task

User Request: $ARGUMENTS

Generate a documentation site for this ArcKit repository.

Step 0: Determine Repository Info

Determine the repository name and URL:

1. Read the .git/config file and find the [remote "origin"] section to get the remote URL
2. Extract the repo name and owner from the URL (e.g. https://github.com/owner/repo-name → repo name is repo-name, owner is owner)
3. If .git/config doesn't exist or has no remote, use the current directory name as the repo name

Step 1: Discover Repository Structure

Use Glob and Read tools to scan the repository. Do NOT use ls, find, for loops, head, grep, sed, or any Bash commands for file discovery.

1.1 Guides (Command Documentation)

Guide sync and title extraction are handled automatically by the sync-guides hook which runs before this command executes. The hook copies all guide .md files from the plugin to docs/guides/ and extracts the first # heading from each file — zero tool round-trips.

• If the hook systemMessage is present (mentions "Guide Sync Complete" and contains a guideTitles JSON map): guides are synced and titles are pre-extracted. Use the guideTitles map directly — do NOT use Glob or Read on guide files. The map keys are repo-relative paths (e.g., docs/guides/requirements.md, docs/guides/roles/enterprise-architect.md) and values are the extracted titles (with " — ArcKit Command Guide" suffix already stripped for role guides).
• If no hook message (hook unavailable or failed): fall back to manual sync and title extraction:
  1. Use Glob to list all .md files in .arckit/docs/guides/ (and any subdirectories like uk-government/, uk-mod/, roles/)
  2. For each guide file, Read from the plugin path and Write to the corresponding path under docs/guides/, creating subdirectories as needed
  3. Use Glob to scan docs/guides/*.md then Read (with limit: 5) each file to extract the # title

Use the titles (from hook or manual extraction) to build the guides array for top-level guides (excluding roles/ subdirectory) and the roleGuides array for role guides. Role guides in docs/guides/roles/ are added to a separate roleGuides array in manifest.json (see DDaT Role Guides section below).

Guide grouping model:

Use .arckit/config/guide-groups.mjs as the source of truth for guide category, section, optional pack, and status. Do not maintain a separate filename-to-category table in this command text. Add guideSectionOrder and guideCategoryOrder to manifest.json from that same config so the browser UI 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). If the hook provided guideTitles, use titles from the map for docs/guides/roles/*.md paths (suffix already stripped). Otherwise, use Glob to scan docs/guides/roles/*.md (excluding README.md) and Read (with limit: 5) to extract the title from the first # heading (strip " — ArcKit Command Guide" suffix). Map the DDaT family from the filename using the table above. Count the rows in the "Primary Commands" table 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-RSCH-v1.0.md     # Research Findings
│   ├── 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
│   │
│   ├── # 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
│   ├── 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
│   │   └── {topic-slug}.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:

Step 2: Generate manifest.json

Create docs/manifest.json with the discovered 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"
        }
      ],
      "external": [
        {
          "path": "projects/001-project-name/external/rfp-document.pdf",
          "title": "rfp-document.pdf",
          "type": "pdf"
        }
      ]
    }
  ]
}

Step 3: Generate index.html

3.1 Read the template (MANDATORY)

Read the template (with user override support):

• First, check if .arckit/templates/pages-template.html exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/pages-template.html (default)

Tip: Users can customize templates with /skill:arckit-customize pages

This template is the single source of truth for the pages site — it contains all HTML structure, CSS styling, and JavaScript functionality.

1. Read the appropriate template file (custom override or default) using the Read tool
2. Store the entire template content in memory
3. Replace the placeholder values in memory (string replacement) with actual repository details:
   • '{{REPO}}' → the repository name (e.g. 'arckit-test-project-v17-fuel-prices')
   • '{{REPO_URL}}' → the full repository URL (e.g. 'https://github.com/tractorjuice/arckit-test-project-v17-fuel-prices')
   • '{{CONTENT_BASE_URL}}' → the raw content base URL for fallback loading (e.g. 'https://raw.githubusercontent.com/tractorjuice/arckit-test-project-v17-fuel-prices/main'). For GitHub repos use https://raw.githubusercontent.com/{owner}/{repo}/{branch}. For non-GitHub hosting set to '' (empty string).
   • '{{VERSION}}' → the ArcKit version from the plugin's VERSION file (.arckit/VERSION)
   • '{{DEFAULT_DOC}}' → the default document path (principles if exists, or '')
4. Write the final HTML to docs/index.html using the Write tool

IMPORTANT: Do NOT use sed, cp, or any Bash commands for template processing. Read the template with the Read tool, perform all placeholder replacements in memory, then write the result with the Write tool. This ensures cross-platform compatibility (Windows, macOS, Linux).

Do NOT generate HTML from scratch. Do NOT modify the template structure, CSS, or JavaScript. Only replace the {{...}} config placeholders.

If the template file does not exist, STOP and show an error: Tell the user to run arckit init to install templates, or check that the template exists. Do NOT generate fallback HTML.

Step 4: Write Output Files

IMPORTANT: Use the Write tool to create all three files.

4.1 Write manifest.json

docs/manifest.json

4.2 Write index.html

docs/index.html

4.3 Write llms.txt

Generate docs/llms.txt following the llmstxt.org standard so LLM agents and crawlers can discover every artifact. Structure:

• First line: <!-- Generated by ArcKit /skill:arckit-pages --> (generation marker)
• H1: repository name
• Blockquote: one-paragraph summary of the repository (what it contains, produced with ArcKit)
• Paragraph: explain the ArcKit traceability chain and artifact layout
• ## Documentation site — ./index.html and ./manifest.json with descriptions
• ## Global artifacts — one - [Title](url): Category · \DocId`.bullet per entry inmanifest.global`
• ## Projects — for each project, an H3 with project name and a bulleted list of all documents, diagrams, decisions, wardley maps, data contracts, research, reviews, vendors, vendor profiles, tech notes
• ## ArcKit guides — grouped by category, bullets linking to ./guides/*.md (relative paths)
• ## DDaT role guides — bullets linking to ./guides/roles/*.md
• ## Optional — source repo URL, arckit.org, GitHub ArcKit repo, and any external/ files

URL rules:

• Project markdown artifacts → {CONTENT_BASE_URL}/{path} (raw.githubusercontent.com)
• Site-local resources (index.html, manifest.json, guides under docs/) → relative paths like ./index.html, ./guides/requirements.md
• When CONTENT_BASE_URL is empty (non-GitHub hosting), use relative paths like ../projects/{path}

Skip logic: Before writing, use the Read tool to check if docs/llms.txt exists. If it exists and does NOT contain the string <!-- Generated by ArcKit /skill:arckit-pages -->, it is hand-curated — do not overwrite it. Note this in the Step 5 summary.

docs/llms.txt

Step 5: Provide Summary

After generating, provide this 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}
- Vendor Documents: {vendor_doc_count}
- Vendor Profiles: {vendor_profile_count}
- Tech Notes: {tech_note_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 `/skill:arckit-health JSON=true` to generate docs/health.json
- Re-run `/skill: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

Cross-Platform Compatibility

This command MUST work on Windows, macOS, and Linux without modification. To achieve this:

• Use Glob for all file discovery (never ls, find, or for loops in bash)
• Use Read + Write for all file copying (never cp, cp -r, or mkdir -p in bash)
• Use Read + in-memory string replacement + Write for template processing (never sed)
• Use Grep for content searching (never grep or head in bash)
• Do NOT use Bash at all — all operations can be done with Glob/Read/Write/Grep

File Discovery

• Only include files that actually exist in the repository
• Use Glob to discover files (never bash commands)
• Don't include placeholder entries for missing files

Error Handling

The generated HTML should handle:

• Missing documents gracefully (show "Document not found")
• Failed fetch requests (show error message)
• Invalid markdown (display raw content)
• Invalid mermaid syntax (show error, display raw code)

Mobile Responsiveness

• Sidebar should collapse on mobile
• Content should be readable on all screen sizes
• Touch-friendly navigation

Accessibility

• Proper heading hierarchy
• ARIA labels for navigation
• Keyboard navigation support
• Skip to content link

Performance

• Lazy load documents (only fetch when selected)
• Cache fetched documents in memory
• Show loading indicator during fetch

Remember: You MUST read and use .arckit/templates/pages-template.html as the base for docs/index.html. The template is the source of truth for all HTML, CSS, and JavaScript. Only replace the {{...}} config placeholders with actual values.

• Cross-platform: Do NOT use Bash for file operations. Use Glob/Read/Write/Grep tools exclusively. The only acceptable Bash use is a single simple git command (no pipes, no &&, no $()).
• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji