docs: add VitePress documentation with GitHub Pages deployment

- VitePress config with canonical URLs to core.help - Developer preview banner linking to main docs - Documentation pages: quick-start, commands, core-folder, repos-yaml - GitHub Actions workflow for Pages deployment Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 20:28:07 +00:00 · 2026-01-31 20:28:07 +00:00 · 97aab0fcca
commit 97aab0fcca
parent 8a921dfb2d
12 changed files with 768 additions and 0 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@ -0,0 +1,59 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [dev, main]
+    paths:
+      - 'doc/**'
+      - '.vitepress/**'
+      - 'package.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@ -0,0 +1,78 @@
+import { defineConfig } from 'vitepress'
+
+const pkg = 'devops'
+const canonical = `https://core.help/packages/${pkg}/`
+
+export default defineConfig({
+  title: 'Host UK DevOps',
+  description: 'Developer workspace orchestrator for Host UK',
+
+  srcDir: 'doc',
+  outDir: '.vitepress/dist',
+
+  head: [
+    ['link', { rel: 'canonical', href: canonical }],
+    ['meta', { property: 'og:site_name', content: 'Host UK Documentation' }],
+  ],
+
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'core.help', link: 'https://core.help' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Guide',
+        items: [
+          { text: 'Introduction', link: '/' },
+          { text: 'Quick Start', link: '/quick-start' },
+          { text: 'Commands', link: '/commands' },
+        ]
+      },
+      {
+        text: 'Configuration',
+        items: [
+          { text: '.core/ Folder', link: '/core-folder' },
+          { text: 'repos.yaml', link: '/repos-yaml' },
+        ]
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'Package Types', link: '/package-types' },
+          { text: 'Troubleshooting', link: '/troubleshooting' },
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/host-uk/core-devops' }
+    ],
+
+    footer: {
+      message: 'Released under the EUPL-1.2 License.',
+      copyright: 'Copyright © Host UK'
+    },
+
+    search: {
+      provider: 'local'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/host-uk/core-devops/edit/dev/doc/:path',
+      text: 'Edit this page on GitHub'
+    }
+  },
+
+  sitemap: {
+    hostname: canonical
+  },
+
+  transformHead({ pageData }) {
+    const head: any[] = []
+    const pagePath = pageData.relativePath.replace(/\.md$/, '.html').replace(/index\.html$/, '')
+    head.push(['link', { rel: 'canonical', href: `${canonical}${pagePath}` }])
+    return head
+  }
+})
--- a/.vitepress/theme/custom.css
+++ b/.vitepress/theme/custom.css
@ -0,0 +1,33 @@
+.dev-banner {
+  background: linear-gradient(90deg, #7c3aed 0%, #2563eb 100%);
+  color: white;
+  padding: 0.5rem 1rem;
+  text-align: center;
+  font-size: 0.875rem;
+  position: sticky;
+  top: 0;
+  z-index: 100;
+}
+
+.dev-banner a {
+  color: #fbbf24;
+  font-weight: 600;
+  text-decoration: underline;
+}
+
+.dev-banner a:hover {
+  color: #fcd34d;
+}
+
+.VPNav {
+  top: 36px !important;
+}
+
+.VPSidebar {
+  top: calc(var(--vp-nav-height) + 36px) !important;
+  height: calc(100vh - var(--vp-nav-height) - 36px) !important;
+}
+
+.VPContent {
+  padding-top: 36px;
+}
--- a/.vitepress/theme/index.ts
+++ b/.vitepress/theme/index.ts
@ -0,0 +1,21 @@
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import type { Theme } from 'vitepress'
+import './custom.css'
+
+const Banner = () => {
+  return h('div', { class: 'dev-banner' }, [
+    h('span', '📚 Developer preview. '),
+    h('a', { href: 'https://core.help/packages/devops/', target: '_blank' }, 'Visit core.help'),
+    h('span', ' for the complete documentation.')
+  ])
+}
+
+export default {
+  extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      'layout-top': () => h(Banner)
+    })
+  }
+} satisfies Theme
--- a/doc/commands.md
+++ b/doc/commands.md
@ -0,0 +1,134 @@
+# Commands Reference
+
+All `core` CLI commands available in the workspace.
+
+## Workspace Commands
+
+### `core health`
+
+Quick status summary of all repos.
+
+```bash
+core health
+# Output: 18 repos │ 2 dirty │ synced
+```
+
+### `core work`
+
+Full workflow: status → commit → push.
+
+```bash
+core work              # Interactive
+core work --status     # Status table only
+```
+
+### `core commit`
+
+Claude-assisted commits for dirty repos.
+
+```bash
+core commit            # Interactive
+core commit --all      # Commit all without prompting
+```
+
+### `core push`
+
+Push repos with unpushed commits.
+
+```bash
+core push              # Interactive
+core push --force      # Push without confirmation
+```
+
+### `core pull`
+
+Pull repos that are behind.
+
+```bash
+core pull              # Interactive
+core pull --all        # Pull all repos
+```
+
+## GitHub Integration
+
+### `core issues`
+
+List open issues across repos.
+
+```bash
+core issues                    # All open issues
+core issues --assignee @me     # Assigned to you
+```
+
+### `core reviews`
+
+List PRs needing review.
+
+```bash
+core reviews
+```
+
+### `core ci`
+
+GitHub Actions workflow status.
+
+```bash
+core ci
+```
+
+## Analysis
+
+### `core impact`
+
+Show what depends on a package.
+
+```bash
+core impact core-php
+```
+
+## Package Commands
+
+### `core php test`
+
+Run Pest tests in the active package.
+
+```bash
+core php test
+core php test --filter=ClassName
+```
+
+### `core php lint`
+
+Run Pint linter in the active package.
+
+```bash
+core php lint
+```
+
+### `core php dev`
+
+Start Vite dev server in the active package.
+
+```bash
+core php dev
+```
+
+## Setup Commands
+
+### `core setup`
+
+Clone repos into the workspace.
+
+```bash
+core setup                           # Default (foundation + module)
+core setup --only foundation,module  # Specific types
+```
+
+### `core doctor`
+
+Check environment health.
+
+```bash
+core doctor           # Check only
+core doctor --fix     # Attempt to fix issues
+```
--- a/doc/core-folder.md
+++ b/doc/core-folder.md
@ -0,0 +1,80 @@
+# .core/ Folder
+
+The `.core/` folder provides workspace configuration and Claude Code integration.
+
+## Structure
+
+```
+.core/
+├── workspace.yaml       # Workspace configuration
+├── plugin/
+│   ├── plugin.json      # Claude Code manifest
+│   ├── skills/          # Context-aware skills
+│   └── hooks/           # Command hooks
+└── docs/
+    └── core-folder-spec.md  # Full specification
+```
+
+## workspace.yaml
+
+Defines the active package and workspace settings.
+
+```yaml
+version: 1
+
+# Active package for `core php test`, etc.
+active: core-php
+
+# Default package types for `core setup`
+default_only:
+  - foundation
+  - module
+
+# Paths
+packages_dir: ./packages
+
+# Settings
+settings:
+  suggest_core_commands: true
+  show_active_in_prompt: true
+```
+
+## Changing Active Package
+
+Edit `.core/workspace.yaml`:
+
+```yaml
+active: core-tenant
+```
+
+Then commands run from workspace root target that package:
+
+```bash
+core php test    # Now runs in core-tenant
+```
+
+## Claude Code Plugin
+
+The `plugin/` folder integrates with Claude Code:
+
+### plugin.json
+
+Manifest defining skills and commands.
+
+### skills/
+
+Markdown files providing context-aware guidance:
+
+- `workspace.md` - Multi-repo navigation
+- `switch-package.md` - Package switching
+- `package-status.md` - Status checking
+
+### hooks/
+
+Shell scripts that run before/after commands:
+
+- `prefer-core.sh` - Suggests `core` commands
+
+## Full Specification
+
+See `.core/docs/core-folder-spec.md` for the complete specification that packages should follow.
--- a/doc/index.md
+++ b/doc/index.md
@ -0,0 +1,56 @@
+---
+layout: home
+hero:
+  name: "core-devops"
+  text: "Developer Workspace"
+  tagline: Unified entry point for Host UK development
+  actions:
+    - theme: brand
+      text: Quick Start
+      link: /quick-start
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/host-uk/core-devops
+features:
+  - title: One Command Setup
+    details: Clone and run `make setup` to get a complete development environment with all dependencies.
+  - title: Multi-Repo Management
+    details: Manage 18+ Laravel packages from a single workspace using the `core` CLI.
+  - title: Agentic-First
+    details: Designed for AI-assisted development with structured issues and Claude Code integration.
+---
+
+# Host UK DevOps
+
+The developer workspace orchestrator for Host UK - a federated monorepo containing 18 Laravel packages.
+
+## What's Included
+
+| Component | Purpose |
+|-----------|---------|
+| `repos.yaml` | Package registry with dependencies |
+| `.core/` | Workspace configuration and Claude Code plugin |
+| `scripts/` | Cross-platform setup scripts |
+| `Makefile` | Setup orchestration |
+
+## Quick Start
+
+```bash
+git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
+```
+
+## Core CLI
+
+The workspace is managed by the `core` CLI:
+
+```bash
+core health          # Status summary
+core work            # Commit and push workflow
+core issues          # GitHub issues across repos
+```
+
+## Next Steps
+
+- [Quick Start Guide](/quick-start) - Get up and running
+- [Commands Reference](/commands) - All available commands
+- [.core/ Configuration](/core-folder) - Workspace configuration
--- a/doc/package-types.md
+++ b/doc/package-types.md
@ -0,0 +1,58 @@
+# Package Types
+
+Host UK packages are organised into types based on their purpose.
+
+## Foundation
+
+Base framework with no dependencies.
+
+| Package | Description |
+|---------|-------------|
+| `core-php` | Event-driven modules, lifecycle management |
+
+## Modules
+
+Infrastructure services that extend the foundation.
+
+| Package | Description | Dependencies |
+|---------|-------------|--------------|
+| `core-tenant` | Multi-tenancy, workspaces, users | core-php |
+| `core-admin` | Admin panel, Livewire, Flux UI | core-php |
+| `core-api` | REST API, rate limiting, webhooks | core-php, core-tenant |
+| `core-mcp` | Model Context Protocol server | core-php |
+| `core-agentic` | AI agent orchestration | core-php, core-tenant, core-mcp |
+| `core-commerce` | Billing, subscriptions, Stripe | core-php, core-tenant |
+| `core-content` | CMS, pages, blog posts | core-php, core-tenant |
+| `core-tools` | Developer utilities | core-php |
+| `core-uptelligence` | Server monitoring | core-php, core-tenant |
+| `core-developer` | Developer portal, OAuth | core-php, core-tenant, core-api |
+
+## Products
+
+User-facing applications.
+
+| Package | Description | Domain |
+|---------|-------------|--------|
+| `core-bio` | Link-in-bio pages | bio.host.uk.com |
+| `core-social` | Social media scheduling | social.host.uk.com |
+| `core-analytics` | Privacy-first analytics | analytics.host.uk.com |
+| `core-notify` | Push notifications | notify.host.uk.com |
+| `core-trust` | Social proof widgets | trust.host.uk.com |
+| `core-support` | Helpdesk, ticketing | - |
+
+## Templates
+
+Starter templates for new projects.
+
+| Package | Description |
+|---------|-------------|
+| `core-template` | Starter template |
+
+## Meta
+
+Workspace and tooling repos.
+
+| Package | Description |
+|---------|-------------|
+| `core-devops` | This workspace |
+| `core` | Go CLI and framework |
--- a/doc/quick-start.md
+++ b/doc/quick-start.md
@ -0,0 +1,63 @@
+# Quick Start
+
+Get a complete Host UK development environment in under 5 minutes.
+
+## Prerequisites
+
+- Git
+- GitHub CLI (`gh`)
+- SSH key configured with GitHub
+
+## Installation
+
+### macOS / Linux
+
+```bash
+git clone git@github.com:host-uk/core-devops.git
+cd core-devops
+make setup
+```
+
+### Windows (PowerShell as Admin)
+
+```powershell
+git clone git@github.com:host-uk/core-devops.git
+cd core-devops
+.\scripts\install-deps.ps1
+.\scripts\install-core.ps1
+core setup
+```
+
+## What Happens
+
+`make setup` does three things:
+
+1. **Installs dependencies** - PHP 8.3+, Composer, Node 20+, pnpm, GitHub CLI
+2. **Installs the `core` CLI** - Multi-repo management tool
+3. **Clones all packages** - Into `packages/` (foundation and modules by default)
+
+## Verify Installation
+
+```bash
+core doctor
+```
+
+This checks that all required tools are installed and configured.
+
+## Next Steps
+
+```bash
+# See workspace status
+core health
+
+# Run tests in the active package
+core php test
+
+# Work on a specific package
+cd packages/core-php
+composer test
+```
+
+## Troubleshooting
+
+See the [Troubleshooting Guide](/troubleshooting) for common issues.
--- a/doc/repos-yaml.md
+++ b/doc/repos-yaml.md
@ -0,0 +1,78 @@
+# repos.yaml
+
+The package registry defining all repositories in the workspace.
+
+## Format
+
+```yaml
+version: 1
+org: host-uk
+base_path: ./packages
+
+repos:
+  core-php:
+    type: foundation
+    description: Core PHP framework
+    docs: true
+    ci: github-actions
+
+  core-tenant:
+    type: module
+    depends_on: [core-php]
+    description: Multi-tenancy, workspaces
+
+defaults:
+  ci: github-actions
+  license: EUPL-1.2
+  branch: main
+```
+
+## Fields
+
+### Repository Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | string | Package type (see below) |
+| `depends_on` | array | Dependencies on other packages |
+| `description` | string | Short description |
+| `docs` | boolean | Has documentation |
+| `ci` | string | CI system (github-actions) |
+| `domain` | string | Production domain (products only) |
+| `clone` | boolean | Whether to clone (default: true) |
+
+### Package Types
+
+| Type | Purpose | Examples |
+|------|---------|----------|
+| `foundation` | Base framework, no dependencies | core-php |
+| `module` | Infrastructure services | core-tenant, core-admin |
+| `product` | User-facing applications | core-bio, core-social |
+| `template` | Starter templates | core-template |
+| `meta` | Workspace repos | core-devops |
+
+## Using with CLI
+
+```bash
+# Clone specific types
+core setup --only foundation,module
+
+# Show what depends on a package
+core impact core-php
+```
+
+## Dependency Graph
+
+The `depends_on` field creates a dependency graph:
+
+```
+core-php (foundation)
+├── core-tenant
+├── core-admin
+├── core-api
+│   └── core-developer
+└── core-mcp
+    └── core-agentic
+```
+
+Products depend on both `core-php` and `core-tenant`.
--- a/doc/troubleshooting.md
+++ b/doc/troubleshooting.md
@ -0,0 +1,93 @@
+# Troubleshooting
+
+Common issues and solutions.
+
+## Installation Issues
+
+### "core: command not found"
+
+The Core CLI isn't installed or not in PATH.
+
+```bash
+make install-core
+```
+
+Or manually:
+
+```bash
+./scripts/install-core.sh
+```
+
+### "gh: command not found"
+
+Install GitHub CLI:
+
+```bash
+# macOS
+brew install gh
+
+# Then authenticate
+gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
+```
+
+### Clone failures
+
+Check your SSH keys:
+
+```bash
+ssh -T git@github.com
+```
+
+If using HTTPS:
+
+```bash
+gh auth setup-git
+```
+
+## GitHub Issues
+
+### "refusing to allow an OAuth App to create or update workflow"
+
+Missing `workflow` scope:
+
+```bash
+gh auth refresh -h github.com -s workflow
+```
+
+### "missing required scopes [read:project]"
+
+Missing project scope:
+
+```bash
+gh auth refresh -h github.com -s read:project,project
+```
+
+## Workspace Issues
+
+### Tests failing in wrong package
+
+Check the active package in `.core/workspace.yaml`:
+
+```yaml
+active: core-php  # Should match the package you're testing
+```
+
+### Packages not found
+
+Run setup to clone packages:
+
+```bash
+core setup
+```
+
+Or clone specific types:
+
+```bash
+core setup --only foundation,module
+```
+
+## Getting Help
+
+1. Run `core doctor` to check environment
+2. Check GitHub issues: https://github.com/host-uk/core-devops/issues
+3. Ask in Discord: https://discord.gg/host-uk
--- a/package.json
+++ b/package.json
@ -0,0 +1,15 @@
+{
+  "name": "@host-uk/devops-docs",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.5.0",
+    "vue": "^3.5.0"
+  }
+}