Move zk cards to docs/zk/ for documentation restructuring (#84)

## Summary
- Move all existing zettelkasten cards from `docs/` to `docs/zk/` as a temporary holding area
- Update `zk-docs` mise task to look in the new location
- Add `docs/README.md` explaining the Diataxis-based restructuring plan and target audiences

## Context
This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences:
1. Erich (owner) - knowledge graph/zk
2. Claude/AI agents - memory and context enrichment
3. New external readers - high-level overview
4. Potential operators/contributors - onboarding
5. Replicators - people wanting to duplicate the approach

## Testing
- [x] Verified `mise run zk-docs` still works with the new path
- [x] Updated obsidian.nvim config (in ~/.config/nvim) to point to new path

## Note
The obsidian.nvim config change is outside this repo but was made as part of this work.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/84

.forgejo/workflows/build-blumeops.yaml

@@ -0,0 +1,164 @@
+# BlumeOps Release Workflow
+#
+# Creates a versioned release of BlumeOps with all build artifacts.
+# Currently includes:
+#   - Documentation site (Quartz static build)
+#
+# Future additions may include other release artifacts.
+#
+# Usage:
+#   1. Go to Actions > Build BlumeOps > Run workflow
+#   2. Enter a version tag (e.g., v1.2.0) or leave empty to auto-increment patch
+#   3. The workflow creates a release with attached artifacts
+#
+# Documentation asset URL:
+#   https://forge.ops.eblu.me/eblume/blumeops/releases/download/<tag>/docs-<version>.tar.gz
+
+name: Build BlumeOps
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version (e.g., v1.2.0) or empty to auto-increment patch (v_._.+1)'
+        required: false
+        default: ''
+        type: string
+
+jobs:
+  build:
+    runs-on: k8s
+    steps:
+      - name: Resolve version
+        id: version
+        run: |
+          INPUT_VERSION="${{ inputs.version }}"
+
+          if [ -n "$INPUT_VERSION" ]; then
+            # User provided a version - validate it
+            if [[ ! "$INPUT_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "Error: Version must be in format vX.Y.Z (e.g., v1.0.0)"
+              exit 1
+            fi
+            VERSION="$INPUT_VERSION"
+            echo "Using provided version: $VERSION"
+          else
+            # Auto-increment patch version from latest release
+            echo "Fetching latest release..."
+            LATEST=$(curl -sf "https://forge.ops.eblu.me/api/v1/repos/eblume/blumeops/releases/latest" | jq -r '.tag_name // empty')
+
+            if [ -z "$LATEST" ]; then
+              VERSION="v1.0.0"
+              echo "No previous releases found, starting at: $VERSION"
+            else
+              # Parse vX.Y.Z and increment patch
+              VERSION=$(echo "$LATEST" | awk -F. '{print $1"."$2"."$3+1}')
+              echo "Auto-incremented from $LATEST to: $VERSION"
+            fi
+          fi
+
+          # Check if this version already exists
+          if curl -sf "https://forge.ops.eblu.me/api/v1/repos/eblume/blumeops/releases/tags/$VERSION" > /dev/null 2>&1; then
+            echo "Error: Release $VERSION already exists"
+            echo "See: https://forge.ops.eblu.me/eblume/blumeops/releases/tag/$VERSION"
+            exit 1
+          fi
+
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Building BlumeOps release: $VERSION"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build docs
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          echo "Node version: $(node --version)"
+          echo "NPM version: $(npm --version)"
+
+          # Clone Quartz from local mirror
+          git clone --depth 1 https://forge.ops.eblu.me/eblume/quartz.git /tmp/quartz
+          cd /tmp/quartz
+
+          # Install dependencies
+          npm ci
+
+          # Copy our configuration (lives in docs/ to keep repo root clean)
+          cp "$GITHUB_WORKSPACE/docs/quartz.config.ts" .
+          cp "$GITHUB_WORKSPACE/docs/quartz.layout.ts" .
+
+          # Copy docs as content (includes index.md)
+          rm -rf content
+          cp -r "$GITHUB_WORKSPACE/docs" content
+
+          # Build
+          echo "Building static site..."
+          npx quartz build
+
+          # Create tarball
+          TARBALL="docs-${VERSION}.tar.gz"
+          echo "Creating tarball: $TARBALL"
+          tar -czf "$GITHUB_WORKSPACE/$TARBALL" -C public .
+
+          echo "Build complete!"
+          ls -lh "$GITHUB_WORKSPACE/$TARBALL"
+
+      - name: Create release
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          TARBALL="docs-${VERSION}.tar.gz"
+
+          echo "Creating release $VERSION..."
+
+          # Use Forgejo API to create release
+          RELEASE_DATA=$(cat <<EOF
+          {
+            "tag_name": "$VERSION",
+            "name": "BlumeOps $VERSION",
+            "body": "BlumeOps release $VERSION\n\n## Documentation\n\nDownload \`$TARBALL\` and configure the quartz container with:\n\n\`\`\`\nDOCS_RELEASE_URL=https://forge.ops.eblu.me/eblume/blumeops/releases/download/$VERSION/$TARBALL\n\`\`\`",
+            "draft": false,
+            "prerelease": false
+          }
+          EOF
+          )
+
+          RELEASE_RESPONSE=$(curl -sf \
+            -X POST \
+            -H "Content-Type: application/json" \
+            -d "$RELEASE_DATA" \
+            "https://forge.ops.eblu.me/api/v1/repos/eblume/blumeops/releases")
+
+          RELEASE_ID=$(echo "$RELEASE_RESPONSE" | jq -r '.id')
+
+          if [ -z "$RELEASE_ID" ] || [ "$RELEASE_ID" = "null" ]; then
+            echo "Error: Failed to create release"
+            echo "Response: $RELEASE_RESPONSE"
+            exit 1
+          fi
+
+          echo "Created release ID: $RELEASE_ID"
+
+          # Upload the asset
+          echo "Uploading $TARBALL..."
+          curl -sf \
+            -X POST \
+            -H "Content-Type: application/gzip" \
+            --data-binary "@$TARBALL" \
+            "https://forge.ops.eblu.me/api/v1/repos/eblume/blumeops/releases/$RELEASE_ID/assets?name=$TARBALL"
+
+          echo ""
+          echo "Release created successfully!"
+
+      - name: Summary
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          TARBALL="docs-${VERSION}.tar.gz"
+          echo "================================================"
+          echo "BlumeOps Release: $VERSION"
+          echo "================================================"
+          echo ""
+          echo "Release URL:"
+          echo "  https://forge.ops.eblu.me/eblume/blumeops/releases/tag/$VERSION"
+          echo ""
+          echo "Asset URL (for DOCS_RELEASE_URL ConfigMap):"
+          echo "  https://forge.ops.eblu.me/eblume/blumeops/releases/download/$VERSION/$TARBALL"

README.md

@@ -80,10 +80,11 @@ This repo uses [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/)
 
 ## Documentation
 
-Documentation lives in `docs/` and covers infrastructure, services, and operational runbooks. View all docs with:
+Documentation lives in `docs/` and is being restructured to follow the [Diataxis](https://diataxis.fr/) framework. See [`docs/README.md`](docs/README.md) for the restructuring plan and current status.
 
+**Quick reference (zettelkasten cards):**
 ```bash
 mise run zk-docs
 ```
 
-The docs use [Obsidian](https://obsidian.md) wiki-link syntax (`[[link]]`) for cross-references. Edit with any markdown editor, or use [obsidian.nvim](https://github.com/obsidian-nvim/obsidian.nvim) for enhanced navigation and completion.
+The zk cards in `docs/zk/` use [Obsidian](https://obsidian.md) wiki-link syntax (`[[link]]`) for cross-references. Edit with any markdown editor, or use [obsidian.nvim](https://github.com/obsidian-nvim/obsidian.nvim) for enhanced navigation and completion.

containers/quartz/Dockerfile

@@ -0,0 +1,52 @@
+# Quartz Static Site Server
+# Downloads and serves a Quartz-built static site from a release bundle
+#
+# Configuration (via environment):
+#   DOCS_RELEASE_URL - URL to download the static site tarball
+#
+# The container downloads the tarball on startup, extracts it, and serves with nginx.
+
+FROM nginx:alpine
+
+# Install curl for downloading release assets
+RUN apk add --no-cache curl
+
+# Copy startup script
+COPY start.sh /start.sh
+RUN chmod +x /start.sh
+
+# Custom nginx config for SPA routing
+RUN cat > /etc/nginx/conf.d/default.conf << 'EOF'
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Enable gzip compression
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # SPA fallback - serve index.html for client-side routing
+    location / {
+        try_files $uri $uri/ $uri.html /index.html;
+    }
+
+    # Health check endpoint
+    location /healthz {
+        access_log off;
+        return 200 "ok\n";
+        add_header Content-Type text/plain;
+    }
+}
+EOF
+
+EXPOSE 80
+
+CMD ["/start.sh"]

containers/quartz/start.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+set -e
+
+HTML_DIR="/usr/share/nginx/html"
+
+# Check for required environment variable
+if [ -z "$DOCS_RELEASE_URL" ]; then
+    echo "Error: DOCS_RELEASE_URL environment variable is required"
+    echo "Set it to the URL of the static site tarball to serve"
+    exit 1
+fi
+
+echo "Downloading docs from: $DOCS_RELEASE_URL"
+
+# Download the tarball
+if ! curl -fsSL "$DOCS_RELEASE_URL" -o /tmp/docs.tar.gz; then
+    echo "Error: Failed to download docs from $DOCS_RELEASE_URL"
+    exit 1
+fi
+
+# Clear existing content and extract
+rm -rf "${HTML_DIR:?}"/*
+echo "Extracting docs to $HTML_DIR"
+tar -xzf /tmp/docs.tar.gz -C "$HTML_DIR"
+rm /tmp/docs.tar.gz
+
+echo "Docs extracted successfully"
+echo "Starting nginx..."
+
+# Start nginx in foreground
+exec nginx -g "daemon off;"

docs/README.md

@@ -0,0 +1,126 @@
+# BlumeOps Documentation
+
+> **Note on naming**: The project is properly stylized as **BlumeOps**, though "blumeops" and "Blue Mops" are also commonly used interchangeably.
+
+This directory contains documentation for BlumeOps, Erich Blume's personal infrastructure GitOps repository.
+
+## Documentation Restructuring (In Progress)
+
+The documentation is being restructured to follow the [Diataxis](https://diataxis.fr/) documentation framework while serving multiple audiences.
+
+### Target Audiences
+
+1. **Erich (owner)** - A knowledge graph/zettelkasten for quickly recalling important facts about BlumeOps infrastructure and operations.
+
+2. **Claude/AI agents** - Memory and context enrichment for AI-assisted operations and development.
+
+3. **New external readers** - People who want to understand "what is BlumeOps?" at a high level.
+
+4. **Potential operators/contributors** - External readers who want to help operate, modify, or answer questions about BlumeOps, or onboard as a member.
+
+5. **Replicators** - People who want to duplicate this approach for their own personal infrastructure operations.
+
+### Requirements
+
+- **Source format**: Markdown with optional YAML frontmatter
+- **Editing**: Compatible with [Obsidian](https://obsidian.md) and [obsidian.nvim](https://github.com/obsidian-nvim/obsidian.nvim)
+- **Cross-references**: Wiki-link syntax (`[[link]]`) for internal links
+- **Output formats**: HTML (for web hosting) and PDF (for offline reference)
+- **Changelog**: Track significant documentation changes
+
+### Tooling
+
+**Selected**: [Quartz](https://quartz.jzhao.xyz/) - A TypeScript-based static site generator designed for Obsidian vaults. Features wiki-link support, backlinks, graph view, and excellent Obsidian compatibility.
+
+**Architecture**:
+- **Source**: Markdown files in `docs/` with optional YAML frontmatter
+- **Build**: Quartz builds static HTML/CSS/JS via Forgejo workflow
+- **Release**: Built assets published as Forgejo release attachments
+- **Hosting**: `quartz` container downloads release bundle on startup and serves via nginx
+- **URL**: `docs.ops.eblu.me` (planned)
+
+## Restructuring Phases
+
+### Phase 1a: Foundation & CI (Current)
+- [x] Move existing zk cards to `docs/zk/`
+- [x] Update `zk-docs` mise task for new path
+- [x] Create this README with restructuring plan
+- [x] Select documentation tooling (Quartz)
+- [x] Create Quartz configuration (`quartz.config.ts`, `quartz.layout.ts`)
+- [x] Create `quartz` container for serving static sites
+- [x] Create `build-blumeops` workflow for building releases
+- [ ] Test the build workflow and verify release creation
+- [ ] Create `CHANGELOG.md`
+
+### Phase 1b: CD & Hosting
+- [ ] Create ArgoCD manifests for `quartz` deployment
+- [ ] Add `docs.ops.eblu.me` to Caddy reverse proxy
+- [ ] Configure deployment to pull from release URL
+- [ ] Test end-to-end: commit -> build -> release -> deploy
+
+### Phase 2: Tutorials
+Learning-oriented content for getting started.
+
+- [ ] Create `tutorials/` directory
+- [ ] "Getting Started with BlumeOps" - What this is and how to explore it
+- [ ] "Setting Up a Similar Environment" - For replicators
+- [ ] "Your First Contribution" - For potential contributors
+
+### Phase 3: How-to Guides
+Task-oriented instructions for specific operations.
+
+- [ ] Create `how-to/` directory
+- [ ] Migrate operational content from zk cards
+- [ ] "How to deploy a new Kubernetes service"
+- [ ] "How to add a new Ansible role"
+- [ ] "How to update Tailscale ACLs"
+- [ ] "How to troubleshoot common issues"
+
+### Phase 4: Reference
+Information-oriented technical descriptions.
+
+- [ ] Create `reference/` directory
+- [ ] Service reference pages (migrate from zk cards)
+- [ ] Infrastructure inventory
+- [ ] Configuration reference
+- [ ] API/CLI reference for mise tasks
+
+### Phase 5: Explanation
+Understanding-oriented discussion of concepts and decisions.
+
+- [ ] Create `explanation/` directory
+- [ ] "Why GitOps?" - Philosophy and approach
+- [ ] "Architecture Overview" - How everything fits together
+- [ ] "Security Model" - Tailscale, secrets management, etc.
+- [ ] "Decision Log" - ADRs (Architecture Decision Records)
+
+### Phase 6: Integration & Cleanup
+- [ ] Migrate remaining useful content from `docs/zk/`
+- [ ] Decide fate of zk cards (archive, delete, or keep as separate knowledge base)
+- [ ] Update CLAUDE.md to reference new doc structure
+- [ ] Mirror docs to GitHub Pages for public access (optional)
+
+## Current Directory Layout
+
+```
+docs/
+├── README.md          # This file
+├── CHANGELOG.md       # Documentation changelog (planned)
+├── tutorials/         # Learning-oriented (planned)
+├── how-to/            # Task-oriented (planned)
+├── reference/         # Information-oriented (planned)
+├── explanation/       # Understanding-oriented (planned)
+└── zk/                # Zettelkasten cards (temporary)
+    ├── 1767747119-YCPO.md  # Main blumeops overview card
+    └── ...                  # Service-specific cards and notes
+```
+
+## Viewing the ZK Cards
+
+To view all BlumeOps zettelkasten cards:
+
+```fish
+mise run zk-docs
+```
+
+This displays all cards tagged with `blumeops`, starting with the main overview card.

docs/index.md

@@ -0,0 +1,7 @@
+---
+title: BlumeOps Documentation
+---
+
+Welcome to the BlumeOps documentation.
+
+[[README|Documentation Home]]

docs/quartz.config.ts

@@ -0,0 +1,91 @@
+import { QuartzConfig } from "./quartz/cfg"
+import * as Plugin from "./quartz/plugins"
+
+/**
+ * Quartz configuration for BlumeOps documentation
+ * See https://quartz.jzhao.xyz/configuration
+ */
+const config: QuartzConfig = {
+  configuration: {
+    pageTitle: "BlumeOps Docs",
+    pageTitleSuffix: "",
+    enableSPA: true,
+    enablePopovers: true,
+    analytics: null,
+    locale: "en-US",
+    baseUrl: "docs.ops.eblu.me",
+    ignorePatterns: ["private", "templates", ".obsidian"],
+    defaultDateType: "modified",
+    theme: {
+      fontOrigin: "googleFonts",
+      cdnCaching: true,
+      typography: {
+        header: "Schibsted Grotesk",
+        body: "Source Sans Pro",
+        code: "IBM Plex Mono",
+      },
+      colors: {
+        lightMode: {
+          light: "#faf8f8",
+          lightgray: "#e5e5e5",
+          gray: "#b8b8b8",
+          darkgray: "#4e4e4e",
+          dark: "#2b2b2b",
+          secondary: "#284b63",
+          tertiary: "#84a59d",
+          highlight: "rgba(143, 159, 169, 0.15)",
+          textHighlight: "#fff23688",
+        },
+        darkMode: {
+          light: "#161618",
+          lightgray: "#393639",
+          gray: "#646464",
+          darkgray: "#d4d4d4",
+          dark: "#ebebec",
+          secondary: "#7b97aa",
+          tertiary: "#84a59d",
+          highlight: "rgba(143, 159, 169, 0.15)",
+          textHighlight: "#fff23688",
+        },
+      },
+    },
+  },
+  plugins: {
+    transformers: [
+      Plugin.FrontMatter(),
+      Plugin.CreatedModifiedDate({
+        priority: ["frontmatter", "git", "filesystem"],
+      }),
+      Plugin.SyntaxHighlighting({
+        theme: {
+          light: "github-light",
+          dark: "github-dark",
+        },
+        keepBackground: false,
+      }),
+      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
+      Plugin.GitHubFlavoredMarkdown(),
+      Plugin.TableOfContents(),
+      Plugin.CrawlLinks({ markdownLinkResolution: "shortest" }),
+      Plugin.Description(),
+      Plugin.Latex({ renderEngine: "katex" }),
+    ],
+    filters: [Plugin.RemoveDrafts()],
+    emitters: [
+      Plugin.AliasRedirects(),
+      Plugin.ComponentResources(),
+      Plugin.ContentPage(),
+      Plugin.FolderPage(),
+      Plugin.TagPage(),
+      Plugin.ContentIndex({
+        enableSiteMap: true,
+        enableRSS: true,
+      }),
+      Plugin.Assets(),
+      Plugin.Static(),
+      Plugin.NotFoundPage(),
+    ],
+  },
+}
+
+export default config

docs/quartz.layout.ts

@@ -0,0 +1,54 @@
+import { PageLayout, SharedLayout } from "./quartz/cfg"
+import * as Component from "./quartz/components"
+
+/**
+ * Quartz layout configuration for BlumeOps documentation
+ * See https://quartz.jzhao.xyz/layout
+ */
+
+// Components shared across all pages
+export const sharedPageComponents: SharedLayout = {
+  head: Component.Head(),
+  header: [],
+  afterBody: [],
+  footer: Component.Footer({
+    links: {
+      "GitHub": "https://github.com/eblume/blumeops",
+      "Forge": "https://forge.ops.eblu.me/eblume/blumeops",
+    },
+  }),
+}
+
+// Components for pages that list posts (folder pages, tag pages)
+export const defaultContentPageLayout: PageLayout = {
+  beforeBody: [
+    Component.Breadcrumbs(),
+    Component.ArticleTitle(),
+    Component.ContentMeta(),
+    Component.TagList(),
+  ],
+  left: [
+    Component.PageTitle(),
+    Component.MobileOnly(Component.Spacer()),
+    Component.Search(),
+    Component.Darkmode(),
+    Component.DesktopOnly(Component.Explorer()),
+  ],
+  right: [
+    Component.Graph(),
+    Component.DesktopOnly(Component.TableOfContents()),
+    Component.Backlinks(),
+  ],
+}
+
+export const defaultListPageLayout: PageLayout = {
+  beforeBody: [Component.Breadcrumbs(), Component.ArticleTitle(), Component.ContentMeta()],
+  left: [
+    Component.PageTitle(),
+    Component.MobileOnly(Component.Spacer()),
+    Component.Search(),
+    Component.Darkmode(),
+    Component.DesktopOnly(Component.Explorer()),
+  ],
+  right: [],
+}

mise-tasks/zk-docs

@@ -4,7 +4,7 @@
 set -euo pipefail
 
 # Blumeops docs now live in the repo itself (symlinked into zk)
-DOCS_DIR="$(cd "$(dirname "$0")/.." && pwd)/docs"
+DOCS_DIR="$(cd "$(dirname "$0")/.." && pwd)/docs/zk"
 MAIN_CARD="$DOCS_DIR/1767747119-YCPO.md"
 
 # Find all files tagged with blumeops (excluding main card)