@deftai/directive-content 0.55.0

package/deployments/cloud-gov/services.md

@@ -0,0 +1,72 @@
+---
+applyTo: "**/*.py,**/*.js,**/*.ts,**/*.rb,**/*.java,**/*.go,**/manifest*.yml"
+---
+
+# Cloud.gov Services Instructions (Deft)
+
+Guidance for provisioning and using cloud.gov managed services.
+
+## Core Rules
+
+- ! Never hardcode credentials
+- ! Read credentials from `VCAP_SERVICES`
+- ~ Prefer bound services over service keys
+- ~ Document services in `manifest.yml`
+
+## Service Lifecycle
+
+```bash
+cf marketplace
+cf create-service <SERVICE> <PLAN> <INSTANCE_NAME>
+cf bind-service <APP_NAME> <INSTANCE_NAME>
+cf restage <APP_NAME>
+```
+
+## VCAP_SERVICES (Python example)
+
+```python
+import json, os
+
+vcap_services = json.loads(os.environ.get("VCAP_SERVICES", "{}"))
+db_credentials = vcap_services.get("aws-rds", [{}])[0].get("credentials", {})
+
+DATABASE_URL = db_credentials.get("uri")
+```
+
+## Relational Databases (RDS)
+
+- ~ Use redundant plans for production
+- ~ Rotate credentials regularly
+
+```bash
+cf create-service aws-rds micro-psql my-database
+cf create-service aws-rds small-psql-redundant my-database
+cf update-service my-database -c '{"rotate_credentials": true}'
+```
+
+## S3 Storage
+
+```bash
+cf create-service s3 basic my-s3-bucket
+```
+
+## Redis
+
+```bash
+cf create-service aws-elasticache-redis redis-dev my-redis
+```
+
+## Service Keys
+
+- ~ Use only when necessary (CI/CD, external access)
+
+```bash
+cf create-service-key my-s3-bucket external-access
+cf service-key my-s3-bucket external-access
+```
+
+## References
+
+- https://docs.cloud.gov/platform/deployment/managed-services/
+- https://docs.cloud.gov/platform/services/relational-database/
+- https://docs.cloud.gov/platform/services/s3/

package/deployments/cloud-gov/upstream/README.md

@@ -0,0 +1,18 @@
+# Upstream Snapshot (cloud-gov-instructions)
+
+This directory stores the pinned upstream release used for translation.
+
+## Current Pin
+
+- Repository: `adhocteam/cloud-gov-instructions`
+- Version: `v1.1.0`
+
+## Sync
+
+Use:
+
+```
+task cloudgov:sync
+```
+
+This downloads the release tarball and extracts it here for reference.

package/deployments/cloudflare/README.md

@@ -0,0 +1,33 @@
+# Cloudflare Deployment Module
+
+Deft guidance for deploying to Cloudflare Pages and Workers.
+
+## Status
+
+- ! Optional module
+- ~ Good for Deft usage
+
+## Deployment Methods
+
+| File | Method | Best For |
+|------|--------|----------|
+| `via-git.md` | Git Integration (GitHub/GitLab) | Teams wanting automated deploy-on-push |
+| `via-wrangler.md` | Wrangler CLI | Local deploys, CI pipelines, Workers |
+| `via-dashboard.md` | Dashboard Direct Upload | Quick one-off deploys, non-developers |
+| `via-github-actions.md` | GitHub Actions CI/CD | Automated pipelines with custom build steps |
+| `via-terraform.md` | Terraform IaC | Infrastructure-as-code, multi-resource management |
+
+## Important Note
+
+Cloudflare deprecated Pages as a standalone product in April 2025, pushing toward
+a unified Workers platform. The `wrangler deploy` and Workers-based workflows are
+the recommended path forward. Git integration and direct upload still work but
+now operate under the Workers & Pages umbrella in the dashboard.
+
+## Quick Decision Guide
+
+- **Simplest path**: `via-git.md` — connect repo, push, done
+- **Most control**: `via-wrangler.md` — CLI deploys with full config
+- **CI/CD pipelines**: `via-github-actions.md` — automated with `wrangler-action`
+- **IaC teams**: `via-terraform.md` — manage Cloudflare alongside other infra
+- **One-off / non-dev**: `via-dashboard.md` — drag and drop in browser

package/deployments/cloudflare/via-dashboard.md

@@ -0,0 +1,83 @@
+# Deploy to Cloudflare via Dashboard Direct Upload
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [README.md](./README.md) | [via-git.md](./via-git.md) | [via-wrangler.md](./via-wrangler.md)
+
+## Overview
+
+Upload pre-built static assets directly to Cloudflare Pages through the web
+dashboard using drag-and-drop. No CLI, Git, or build pipeline required.
+
+**Best for**: Quick one-off deploys, non-developers, prototypes, or teams without CI/CD.
+
+## Prerequisites
+
+- Cloudflare account
+- Pre-built static site files (HTML, CSS, JS, images) ready on local disk
+
+## Setup
+
+### First Deployment
+
+1. Go to the Cloudflare dashboard → **Workers & Pages**
+2. Select **Create application** → **Pages** tab → **Upload assets**
+3. Enter a **Project name** (becomes `<name>.pages.dev`)
+4. Drag and drop your build output directory into the upload frame
+5. Select **Save and Deploy**
+
+### Subsequent Deployments
+
+1. Go to your Pages project in the dashboard
+2. Select **Create a new deployment**
+3. Choose **Production** or **Preview** environment
+4. If preview, specify a branch name (for the preview URL alias)
+5. Drag and drop the updated build directory
+6. Select **Save and Deploy**
+
+## Standards
+
+### Project Structure
+- ! Include a top-level `index.html` in the uploaded directory
+- ! Ensure all asset paths are relative (not absolute filesystem paths)
+- ~ Include `_redirects` and/or `_headers` files for routing and header configuration
+- ~ Verify the build output locally before uploading
+
+### Deployment
+- ! Understand that each deployment replaces the entire site — there is no partial/incremental upload
+- ! Verify the deployment at `<project>.pages.dev` after upload
+- ~ Use preview deployments for testing before deploying to production
+- ? Use the Wrangler CLI for repeated deployments (more efficient than dashboard)
+
+### Custom Domains
+- ! Configure custom domains via project **Custom Domains** settings after the first deploy
+- ~ Use Cloudflare DNS for automatic CNAME configuration
+
+### Limits
+- ! Be aware that individual file upload size is limited (25 MB per file on free plan)
+- ! Stay within the 500 deploys/month limit on the free plan
+- ~ Check for red warning icons next to files that failed to upload due to size limits
+
+## 🔧 Patterns
+
+**Simple static site**:
+- Build locally → drag the `dist/` or `build/` folder → deploy
+
+**Preview before production**:
+- Create new deployment → select **Preview** → upload → verify at preview URL → redeploy to Production
+
+## Anti-Patterns
+
+- ⊗ Upload source code (e.g. `node_modules/`, `.git/`) — upload only the build output directory
+- ⊗ Expect to switch a Direct Upload project to Git integration later (not supported — must create a new project)
+- ⊗ Use dashboard uploads as a primary production workflow for active projects
+- ≉ Rely on drag-and-drop for team workflows — use Git integration or Wrangler for repeatability
+- ≉ Upload without building first — the dashboard does not run build commands
+- ≉ Re-upload individual files to "patch" a deployment — each deployment is a complete replacement
+
+## Compliance Checklist
+
+- ! Build output verified locally before upload
+- ! `index.html` present at top level
+- ! No secrets, source code, or `node_modules` in the uploaded directory
+- ~ Custom domain configured after first successful deploy

package/deployments/cloudflare/via-git.md

@@ -0,0 +1,90 @@
+# Deploy to Cloudflare via Git Integration
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [README.md](./README.md) | [via-wrangler.md](./via-wrangler.md) | [via-github-actions.md](./via-github-actions.md)
+
+## Overview
+
+Connect a GitHub or GitLab repository to Cloudflare Pages. Every push to the
+configured branch triggers an automatic build and deploy on Cloudflare's edge
+network. Preview deployments are created for pull requests.
+
+**Best for**: Teams that want zero-config continuous deployment with preview URLs on every PR.
+
+## Prerequisites
+
+- Cloudflare account
+- GitHub or GitLab repository with your project
+- Build command and output directory known (e.g. `npm run build` → `dist/`)
+
+## Setup
+
+1. In the Cloudflare dashboard, go to **Workers & Pages**
+2. Select **Create application** → **Pages** tab → **Import an existing Git repository**
+3. Authorize GitHub/GitLab and select the repository
+4. Configure the build settings:
+   - **Project name**: defaults to repo name (becomes `<name>.pages.dev`)
+   - **Production branch**: typically `main`
+   - **Build command**: e.g. `npm run build` (use `exit 0` for pre-built static HTML)
+   - **Build output directory**: e.g. `dist/`, `build/`, `public/`
+5. Select **Save and Deploy**
+
+## Standards
+
+### Configuration
+- ! Set the production branch to match your team's trunk branch (`main`, `master`, etc.)
+- ! Configure the correct build output directory for your framework
+- ~ Use `exit 0` as the build command if deploying pre-built static assets
+- ~ Pin the Node.js version via environment variable `NODE_VERSION` if builds require it
+
+### Preview Deployments
+- ! Understand that preview URLs (`<hash>.<project>.pages.dev`) are public by default
+- ~ Enable Cloudflare Access on preview deployments for private projects
+- ~ Use branch deployment controls to exclude noisy branches (e.g. `dependabot/*`)
+- ? Limit preview branches to specific patterns (e.g. `feature/*`, `staging`)
+
+### Custom Domains
+- ! Add custom domains via the Pages project **Custom Domains** settings
+- ! Use a CNAME record pointing to `<project>.pages.dev` for external DNS
+- ~ Let Cloudflare auto-configure DNS if the domain is already on Cloudflare
+
+### Environment Variables & Secrets
+- ! Set sensitive values (API keys, tokens) as encrypted environment variables in the dashboard
+- ! Configure separate values for Production and Preview environments
+- ⊗ Commit secrets to the repository
+
+### Build Settings
+- ~ Use framework presets when available (React, Vue, Hugo, Next.js, etc.)
+- ~ Set `NODE_VERSION` and `NPM_VERSION` environment variables for reproducible builds
+- ? Add a `_redirects` or `_headers` file in the output directory for routing/header rules
+
+## 🔧 Patterns
+
+**Static HTML (no build)**:
+- Build command: `exit 0`
+- Output directory: `/` (or whichever folder contains `index.html`)
+
+**Monorepo with subdirectory**:
+- Set **Root directory** in build settings to the subdirectory path
+- Build command and output are relative to that root
+
+**Branch-based environments**:
+- Production branch → `<project>.pages.dev` + custom domains
+- All other branches → `<branch>.<project>.pages.dev` preview URLs
+
+## Anti-Patterns
+
+- ⊗ Switch a Direct Upload project to Git integration (not supported — must create a new project)
+- ⊗ Leave preview deployments public for projects containing sensitive content
+- ⊗ Use different build tooling locally vs. in Cloudflare's build environment without pinning versions
+- ≉ Store environment-specific config in the repo — use Cloudflare's environment variable settings
+- ≉ Rely on Cloudflare's build cache for reproducibility — pin all dependency versions explicitly
+
+## Compliance Checklist
+
+- ! Build output directory correctly configured
+- ! Production branch matches team convention
+- ! Secrets stored as encrypted environment variables (not in repo)
+- ! Preview access controls reviewed
+- ~ `_redirects` / `_headers` files present for SPA routing

package/deployments/cloudflare/via-github-actions.md

@@ -0,0 +1,185 @@
+# Deploy to Cloudflare via GitHub Actions
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [README.md](./README.md) | [via-wrangler.md](./via-wrangler.md) | [via-git.md](./via-git.md)
+
+## Overview
+
+Use the official `cloudflare/wrangler-action` GitHub Action to deploy Workers
+and Pages projects as part of a GitHub Actions CI/CD pipeline. This gives you
+full control over the build process while automating deployments on push/merge.
+
+**Best for**: Teams that need custom build steps, test gates, or multi-step pipelines before deploying.
+
+## Prerequisites
+
+- Cloudflare account with API token
+- GitHub repository
+- `wrangler.toml` or `wrangler.jsonc` in the project (for Workers)
+
+## Secrets Setup
+
+In GitHub: **Settings → Secrets and variables → Actions**, add:
+
+- `CLOUDFLARE_API_TOKEN` — API token with Workers/Pages edit permissions
+- `CLOUDFLARE_ACCOUNT_ID` — your Cloudflare account ID
+
+## Workflow Examples
+
+### Workers Deploy on Push to Main
+
+```yaml
+name: Deploy Worker
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+### Pages Deploy with Build Step
+
+```yaml
+name: Deploy Pages
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run build
+      - name: Deploy to Pages
+        id: deploy
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy dist --project-name=my-site
+      - name: Print URL
+        run: echo "${{ steps.deploy.outputs.deployment-url }}"
+```
+
+### Preview Deploy on PR
+
+```yaml
+name: Preview Deploy
+on: pull_request
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm run build
+      - name: Deploy Preview
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy dist --project-name=my-site --branch=${{ github.head_ref }}
+```
+
+## Standards
+
+### Action Configuration
+- ! Use `cloudflare/wrangler-action@v3` (v3 or later with the `v` prefix)
+- ! Pass `apiToken` and `accountId` via GitHub Secrets — never hardcode
+- ~ Pin the action to a specific version tag (e.g. `@v3.14.0`) for reproducibility
+- ~ Specify `packageManager` if not using npm (e.g. `packageManager: pnpm`)
+
+### Secrets Management
+- ! Store `CLOUDFLARE_API_TOKEN` in GitHub Secrets (encrypted, not printed in logs)
+- ! Store `CLOUDFLARE_ACCOUNT_ID` in GitHub Secrets (or as a repository variable)
+- ! Scope the API token to the minimum required permissions
+- ⊗ Use legacy API keys — use API tokens
+- ⊗ Echo or log the API token value in workflow steps
+
+### Workflow Design
+- ! Run build and test steps before the deploy step
+- ! Use `actions/checkout@v4` to check out the repository
+- ~ Use `actions/setup-node@v4` with a pinned Node.js version
+- ~ Use `npm ci` (not `npm install`) for deterministic dependency installation
+- ~ Output the deployment URL for PR comments or downstream steps
+- ? Add a test/lint gate job that must pass before the deploy job runs
+
+### Workers-Specific
+- ! Ensure `wrangler.toml` includes `account_id` or pass `accountId` in the action
+- ~ Use `--strict` flag in CI to prevent accidental overrides of remote settings
+- ~ Use Wrangler environments for staging vs. production deploys
+
+### Pages-Specific
+- ! Use the `command:` input with `pages deploy <dir> --project-name=<name>`
+- ~ Use `--branch=${{ github.head_ref }}` for PR preview deployments
+- ~ Access `deployment-url` and `pages-deployment-alias-url` outputs for downstream use
+
+## 🔧 Patterns
+
+**Deploy only when tests pass**:
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm test
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+```
+
+**Comment preview URL on PR**:
+- Use the `deployment-url` output from the action with a PR comment action
+
+**Multi-environment deploy**:
+```yaml
+- uses: cloudflare/wrangler-action@v3
+  with:
+    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+    environment: staging
+```
+
+## Anti-Patterns
+
+- ⊗ Hardcode API tokens or account IDs in workflow files
+- ⊗ Use `wrangler-action@1` or `wrangler-action@2` (Wrangler v1/v2 are EOL)
+- ⊗ Deploy without running tests first in production pipelines
+- ≉ Use `npm install` in CI — use `npm ci` for deterministic installs
+- ≉ Skip the `accountId` input — Wrangler may prompt interactively and hang in CI
+- ≉ Use `uses: cloudflare/wrangler-action@3.x.x` (must use `@v3.x.x` with the `v` prefix)
+
+## Compliance Checklist
+
+- ! `CLOUDFLARE_API_TOKEN` stored in GitHub Secrets
+- ! `CLOUDFLARE_ACCOUNT_ID` stored in GitHub Secrets or Variables
+- ! `cloudflare/wrangler-action@v3` used with `v` prefix
+- ! Build/test steps precede deploy step
+- ! Node.js version pinned in workflow
+- ~ Deployment URL captured in outputs

package/deployments/cloudflare/via-terraform.md

@@ -0,0 +1,157 @@
+# Deploy to Cloudflare via Terraform
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [README.md](./README.md) | [via-wrangler.md](./via-wrangler.md) | [via-github-actions.md](./via-github-actions.md)
+
+## Overview
+
+Use HashiCorp Terraform with the [Cloudflare provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest)
+to manage Pages projects, Workers, DNS records, and other Cloudflare resources as
+infrastructure-as-code. Terraform handles project creation and configuration but
+actual content deployments still require Wrangler or Git integration.
+
+**Best for**: Teams managing Cloudflare alongside other infrastructure (DNS, tunnels, WAF rules),
+or organizations requiring versioned, reviewable infrastructure changes.
+
+## Prerequisites
+
+- Cloudflare account with API token
+- Terraform CLI installed
+- Cloudflare provider `~> 5`
+
+## Authentication
+
+```bash
+# Set via environment variable (recommended)
+export CLOUDFLARE_API_TOKEN=<token>
+
+# Or in provider block (less secure)
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token
+}
+```
+
+## Example: Pages Project with Git Integration
+
+```hcl
+terraform {
+  required_providers {
+    cloudflare = {
+      source  = "cloudflare/cloudflare"
+      version = "~> 5"
+    }
+  }
+}
+
+variable "cloudflare_account_id" {}
+variable "cloudflare_api_token" {}
+
+provider "cloudflare" {
+  api_token = var.cloudflare_api_token
+}
+
+resource "cloudflare_pages_project" "my_site" {
+  account_id        = var.cloudflare_account_id
+  name              = "my-site"
+  production_branch = "main"
+
+  source {
+    type = "github"
+    config {
+      owner             = "my-org"
+      repo_name         = "my-repo"
+      production_branch = "main"
+    }
+  }
+
+  build_config {
+    build_command   = "npm run build"
+    destination_dir = "dist"
+  }
+}
+
+resource "cloudflare_pages_domain" "custom_domain" {
+  account_id   = var.cloudflare_account_id
+  project_name = cloudflare_pages_project.my_site.name
+  domain       = "www.example.com"
+}
+```
+
+## Standards
+
+### Provider Configuration
+- ! Use the Cloudflare provider version `~> 5` (latest major)
+- ! Authenticate via `CLOUDFLARE_API_TOKEN` environment variable
+- ! Use API tokens (not legacy API keys)
+- ⊗ Hardcode API tokens in `.tf` files
+
+### State Management
+- ! Store Terraform state remotely (Terraform Cloud, S3, GCS, etc.)
+- ! Never commit `terraform.tfstate` to version control
+- ! Add `terraform.tfvars`, `.terraform/`, and `*.tfstate*` to `.gitignore`
+- ~ Use state locking to prevent concurrent modifications
+
+### Variables & Secrets
+- ! Define `cloudflare_account_id` and `cloudflare_api_token` as variables
+- ! Pass sensitive values via environment variables or a secrets manager
+- ⊗ Commit `terraform.tfvars` containing secrets to version control
+- ~ Mark sensitive variables with `sensitive = true`
+
+### Resource Management
+- ! Use `cloudflare_pages_project` to create and configure Pages projects
+- ! Use `cloudflare_pages_domain` to attach custom domains
+- ~ Use `cloudflare_dns_record` to manage DNS records alongside the Pages project
+- ~ Use `terraform plan` before every `terraform apply`
+- ? Use `cloudflare_worker_script` for Workers deployments (content must be provided inline or from file)
+
+### Limitations
+- ! Understand that Terraform creates the Pages project but does **not trigger the first deployment**
+  - After `terraform apply`, you must push to the Git repo or manually trigger a deploy
+- ~ Use Wrangler or GitHub Actions for the actual content deployment
+- ~ Use Terraform for the infrastructure layer (project, DNS, domains, WAF rules)
+
+## 🔧 Patterns
+
+**Pages project + DNS in one config**:
+```hcl
+resource "cloudflare_pages_project" "site" {
+  account_id        = var.cloudflare_account_id
+  name              = "my-site"
+  production_branch = "main"
+  # ... source and build_config
+}
+
+resource "cloudflare_dns_record" "site_cname" {
+  zone_id = var.cloudflare_zone_id
+  name    = "www"
+  content = "my-site.pages.dev"
+  type    = "CNAME"
+  proxied = true
+}
+```
+
+**Separate environments with workspaces**:
+```bash
+terraform workspace new staging
+terraform workspace new production
+terraform apply -var-file=staging.tfvars
+```
+
+## Anti-Patterns
+
+- ⊗ Store API tokens in `.tf` files or commit `terraform.tfvars` with secrets
+- ⊗ Expect Terraform to deploy site content — it manages infrastructure only
+- ⊗ Run `terraform apply` without `terraform plan` first
+- ⊗ Manage Terraform state locally for team projects
+- ≉ Mix Terraform-managed and dashboard-managed settings for the same resource — pick one source of truth
+- ≉ Use the Terraform provider alone for the full deployment lifecycle — pair with Wrangler or Git for content
+
+## Compliance Checklist
+
+- ! Cloudflare provider `~> 5` specified in `required_providers`
+- ! API token passed via environment variable, not hardcoded
+- ! State stored remotely with locking
+- ! `terraform plan` reviewed before every `terraform apply`
+- ! `terraform.tfvars` and `*.tfstate*` in `.gitignore`
+- ~ DNS records managed alongside Pages project in the same config