From 063ee268d9a38508821811465c345978c7c15c12 Mon Sep 17 00:00:00 2001
From: jedarden <github@jedarden.com>
Date: Sat, 23 May 2026 23:46:37 -0400
Subject: [PATCH] docs(pdftract-26pc): add verification note for
 pdftract-docs-build template

Documents the Argo WorkflowTemplate implementation for building and
deploying mdBook documentation to Cloudflare Pages at pdftract.com.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 notes/pdftract-26pc.md | 87 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 notes/pdftract-26pc.md

diff --git a/notes/pdftract-26pc.md b/notes/pdftract-26pc.md
new file mode 100644
index 0000000..dca915e
--- /dev/null
+++ b/notes/pdftract-26pc.md
@@ -0,0 +1,87 @@
+# pdftract-26pc: Argo WorkflowTemplate pdftract-docs-build
+
+## Summary
+
+Created the Argo WorkflowTemplate `pdftract-docs-build` that builds mdBook documentation and deploys to Cloudflare Pages.
+
+## Implementation
+
+### File Created
+- `jedarden/declarative-config/k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml`
+
+### Template Features
+
+1. **Build Process**
+   - Clones pdftract repo at specified tag
+   - Installs mdBook and mdbook-linkcheck via cargo (cached in emptyDir for speed)
+   - Runs mdbook-linkcheck with fail-on-internal-error policy
+   - Builds mdBook to `docs/user-docs/build/user-docs/`
+   - Validates build output (index.html, schema directory)
+
+2. **Cloudflare Pages Deploy**
+   - Uses wrangler to deploy `build/user-docs/` directory
+   - Project name: `pdftract-com`
+   - Branch: set to `$TAG` for metadata
+   - Uses `--commit-dirty=true` for non-git deployments
+
+3. **Secret Management**
+   - Cloudflare API token from ExternalSecret `cloudflare-pages-secret`
+   - Key: `CF_API_TOKEN`
+   - Sourced from OpenBao via ESO (`rs-manager/iad-ci/cloudflare/pages`)
+
+4. **Idempotency**
+   - Re-running against same tag overwrites deployment cleanly
+   - Uses wrangler's default deploy behavior
+
+5. **Resource Limits**
+   - Requests: 500m CPU, 1Gi memory
+   - Limits: 2000m CPU, 4Gi memory
+   - Active deadline: 1200 seconds (20 minutes)
+
+### ArgoCD Integration
+- Template lives in `k8s/iad-ci/argo-workflows/` directory
+- Synced via ArgoCD Application `argo-workflows-ns-iad-ci`
+- Auto-sync enabled with prune and self-heal
+
+## Acceptance Criteria
+
+### PASS
+- [x] `k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml` exists in declarative-config
+- [x] Template synced via ArgoCD (included in `argo-workflows-ns-iad-ci` app)
+- [x] Cloudflare token sourced from OpenBao via ESO (`cloudflare-pages-secret`)
+- [x] Template is re-runnable (wrangler overwrites on deploy)
+- [x] Uses proper secret reference (`CF_API_TOKEN` from `cloudflare-pages-secret`)
+
+### WARN (Infrastructure constraints)
+- [ ] Manual workflow submission testing - requires kubectl access to iad-ci cluster
+- [ ] Milestone tag deployment verification - requires actual milestone tag and Cloudflare Pages setup
+
+### FAIL
+- None
+
+## Git Commits
+
+- declarative-config: `c51ff5f fix(pdftract-26pc): correct docs build paths and Cloudflare Pages config`
+
+## Notes
+
+The template follows the same pattern as `website-build-workflowtemplate.yml`:
+- Uses wrangler for Cloudflare Pages deploy
+- References the same shared `cloudflare-pages-secret` ExternalSecret
+- Uses Rust base image (rust:1.83-slim) for cargo tooling
+
+Key difference from generic website-build:
+- Specialized for pdftract docs (hardcoded repo, build command, output dir)
+- Includes mdbook-linkcheck validation step
+- Builds mdBook instead of npm-based sites
+
+## Cloudflare Pages Configuration
+
+- **Project**: `pdftract-com`
+- **Domain**: pdftract.com (DNS configured separately)
+- **Production branch**: Configured in Cloudflare Pages dashboard
+- **Account ID**: e26f015c7ba47a6ad6219385e77072b7
+
+## Trigger
+
+The template is designed to be triggered on milestone tags (e.g., v0.3.0) via the `pdftract-release-cascade` workflow, which chains `pdftract-crates-publish` before this template to ensure docs.rs links resolve.