Reference Operations / External Content Sync

CTX Cloudflare Repo Update

Instructions for refreshing the local and GitLab-hosted Cloudflare documentation context repository. Cloudflare as DNS, Cloudflare Tunnel, Cloudflare Access, public site deployment support, developer-platform infrastructure, API-managed infrastructure, and MCP/AI-agent-related reference material for the service.

Text size
Status: publishedCreated: 06/28/2026Last updated: 06/28/2026

Document Scope

Just Headlines uses Cloudflare for DNS, Cloudflare Tunnel, Cloudflare Access, public site deployment support, developer-platform infrastructure, API-managed infrastructure, and MCP/AI-agent-related Cloudflare reference workflows.

This document defines the repeatable process for updating the Just Headlines Cloudflare documentation context repository. The purpose of this task is to keep a focused copy of selected official Cloudflare documentation and source material available inside the Just Headlines development environment so human developers, Codex sessions, AI agents, AI-assisted development tools, automation workers, and future MCP/RAG tooling can read the relevant Cloudflare documentation locally without repeatedly relying on external website lookups or pasted documentation links.

This document is written for both human operators and AI agents. It explains what the local context repository is, why it exists, which official Cloudflare sources are copied into the context repository, and what PowerShell block should be run whenever the Cloudflare documentation context needs to be refreshed.

1. Purpose

The Cloudflare documentation context repository exists so that Just Headlines has a local and GitLab-hosted copy of selected official Cloudflare reference material needed for DNS, Cloudflare Tunnel, Cloudflare Access, public site deployment support, developer-platform infrastructure, API-managed infrastructure, and MCP/AI-agent-related reference work.

Unlike a context repository that mirrors one selected folder from one upstream Git repository, the Cloudflare context repository is assembled from several official Cloudflare sources. A normal git pull inside C:\dev\ctx-cloudflare only updates the local copy from the Just Headlines GitLab context repository. It does not refresh the context repository from Cloudflare's official sources.

The Cloudflare update process does the following:

  1. Pulls the latest selected files from the official Cloudflare documentation repository.
  2. Copies the main Cloudflare documentation content folder.
  3. Copies Cloudflare documentation partials.
  4. Copies Cloudflare changelog material.
  5. Copies Cloudflare glossary material.
  6. Copies the Cloudflare documentation AGENTS.md file.
  7. Downloads the current Cloudflare AI-readable documentation files.
  8. Pulls the latest selected material from the official Cloudflare API schemas repository.
  9. Pulls the latest selected material from the official Cloudflare MCP server repository.
  10. Records the upstream commit values used for the refresh.
  11. Commits and pushes the refreshed context repository only if content changed.

The Cloudflare documentation products path is optional. The live Cloudflare documentation checkout did not contain src/content/products when the repository was created. The refresh script keeps a docs-repo\products folder as a placeholder, but a zero-file count in that folder is not treated as a failure.

The main Cloudflare developer documentation URL is:

https://developers.cloudflare.com/

2. Operational Use

Run this task whenever the Cloudflare documentation context should be refreshed from official Cloudflare sources.

This may be done manually during active DNS, Cloudflare Tunnel, Cloudflare Access, Pages, Workers, API, MCP, AI-agent, deployment, or infrastructure development, especially before asking Codex or another AI coding agent to rely on Cloudflare implementation details.

After this task runs successfully, the local folder at C:\dev\ctx-cloudflare should contain the latest selected Cloudflare reference content, and the GitLab repository should contain a committed copy of that same refreshed context if any source content changed.

If the official Cloudflare content has not changed, the script should not create an unnecessary commit.

3. Source and Destination

Official Cloudflare developer documentation URL:

https://developers.cloudflare.com/

Official Cloudflare API documentation URL:

https://developers.cloudflare.com/api/

Cloudflare global LLM documentation URL:

https://developers.cloudflare.com/llms.txt

Cloudflare full LLM documentation URL:

https://developers.cloudflare.com/llms-full.txt

Official Cloudflare documentation source:

https://github.com/cloudflare/cloudflare-docs.git

Included Cloudflare documentation branch:

production

Included Cloudflare documentation paths:

AGENTS.md
src/content/docs
src/content/partials
src/content/changelog
src/content/glossary

Optional Cloudflare documentation path:

src/content/products

The src/content/products path is optional because the live Cloudflare documentation checkout did not contain that path when this context repository was created.

Official Cloudflare API schemas source:

https://github.com/cloudflare/api-schemas.git

Official Cloudflare MCP server source:

https://github.com/cloudflare/mcp-server-cloudflare.git

Local Just Headlines context repository:

C:\dev\ctx-cloudflare

Temporary source checkout folder:

C:\dev\_cloudflare-source

GitLab context repository remote:

git@gitlab-sudostac:sudostac/ctx-cloudflare.git

Refresh report path:

C:\dev\ctx-cloudflare-refresh-report.txt

4. What This Script Does

This script performs the following task sequence:

  1. Changes the working directory to C:\dev.
  2. Removes the temporary Cloudflare source checkout folder if it already exists.
  3. Creates the expected local context repository folder if it does not already exist.
  4. Clones the official Cloudflare documentation repository from the production branch.
  5. Copies selected Cloudflare documentation folders into the local context repository.
  6. Copies the Cloudflare documentation AGENTS.md file.
  7. Creates an empty docs-repo\products folder if the live Cloudflare documentation source does not contain src/content/products.
  8. Downloads the current Cloudflare llms.txt file.
  9. Downloads the current Cloudflare llms-full.txt file.
  10. Clones the official Cloudflare API schemas repository.
  11. Copies the Cloudflare API schemas material into the local context repository.
  12. Clones the official Cloudflare MCP server repository.
  13. Copies the Cloudflare MCP server material into the local context repository.
  14. Writes source URL metadata.
  15. Writes source commit metadata.
  16. Ensures the local context folder is a Git repository.
  17. Ensures the GitLab SSH remote is set correctly.
  18. Stages the refreshed Cloudflare context content.
  19. Creates a verbose Git commit only if the context content changed.
  20. Pushes the update to GitLab only if a commit was created.
  21. Prints a file count summary.
  22. Prints the final Git status.
  23. Removes the temporary source checkout folder.
  24. Writes a refresh report to C:\dev\ctx-cloudflare-refresh-report.txt.

5. PowerShell Refresh Script

Run this block from a normal PowerShell window.

cd C:\dev

$ErrorActionPreference = "Stop"

$LocalRepo = "C:\dev\ctx-cloudflare"
$TempRoot = "C:\dev\_cloudflare-source"
$ReportPath = "C:\dev\ctx-cloudflare-refresh-report.txt"

$DocsSource = Join-Path $TempRoot "cloudflare-docs"
$ApiSchemasSource = Join-Path $TempRoot "api-schemas"
$McpSource = Join-Path $TempRoot "mcp-server-cloudflare"

$GitLabRemote = "git@gitlab-sudostac:sudostac/ctx-cloudflare.git"

$CloudflareDocsRepo = "https://github.com/cloudflare/cloudflare-docs.git"
$CloudflareApiSchemasRepo = "https://github.com/cloudflare/api-schemas.git"
$CloudflareMcpRepo = "https://github.com/cloudflare/mcp-server-cloudflare.git"

$LlmsUrl = "https://developers.cloudflare.com/llms.txt"
$LlmsFullUrl = "https://developers.cloudflare.com/llms-full.txt"

$ReportLines = New-Object System.Collections.Generic.List[string]

function Add-Line {
    param ([string]$Text)

    $script:ReportLines.Add($Text)
    Write-Host $Text
}

function Count-Files {
    param ([string]$Path)

    if (Test-Path -LiteralPath $Path) {
        return (Get-ChildItem -LiteralPath $Path -Recurse -File -Force -ErrorAction SilentlyContinue | Measure-Object).Count
    }

    return "MISSING"
}

function Copy-PathRequired {
    param (
        [string]$Source,
        [string]$Destination
    )

    if (-not (Test-Path -LiteralPath $Source)) {
        throw "Required source path missing: $Source"
    }

    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue

    $Parent = Split-Path -Parent $Destination
    New-Item -ItemType Directory -Force $Parent | Out-Null

    Copy-Item -Recurse -Force -LiteralPath $Source -Destination $Destination
}

function Copy-PathOptional {
    param (
        [string]$Source,
        [string]$Destination,
        [string]$Label
    )

    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue

    if (Test-Path -LiteralPath $Source) {
        $Parent = Split-Path -Parent $Destination
        New-Item -ItemType Directory -Force $Parent | Out-Null
        Copy-Item -Recurse -Force -LiteralPath $Source -Destination $Destination
        Add-Line "Copied optional source: $Label"
    } else {
        New-Item -ItemType Directory -Force $Destination | Out-Null
        Add-Line "WARN - Optional source not found; created empty destination: $Label"
    }
}

function Copy-DirectoryContentsRequired {
    param (
        [string]$Source,
        [string]$Destination
    )

    if (-not (Test-Path -LiteralPath $Source)) {
        throw "Required source directory missing: $Source"
    }

    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue
    New-Item -ItemType Directory -Force $Destination | Out-Null

    Get-ChildItem -LiteralPath $Source -Force | Where-Object {
        $_.Name -ne ".git"
    } | ForEach-Object {
        Copy-Item -Recurse -Force -LiteralPath $_.FullName -Destination $Destination
    }
}

Add-Line "***** BEGIN CTX CLOUDFLARE REFRESH *****"
Add-Line "Started: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
Add-Line ""

Remove-Item -Recurse -Force $TempRoot -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force $TempRoot | Out-Null
New-Item -ItemType Directory -Force $LocalRepo | Out-Null

Add-Line "Cloning Cloudflare documentation repository..."
git clone --depth 1 --branch production $CloudflareDocsRepo $DocsSource

cd $DocsSource
$CloudflareDocsCommit = git rev-parse --short HEAD
cd C:\dev

Add-Line "Copying Cloudflare documentation content..."
Copy-PathRequired "$DocsSource\AGENTS.md" "$LocalRepo\docs-repo\AGENTS.md"
Copy-PathRequired "$DocsSource\src\content\docs" "$LocalRepo\docs-repo\docs"
Copy-PathRequired "$DocsSource\src\content\partials" "$LocalRepo\docs-repo\partials"
Copy-PathRequired "$DocsSource\src\content\changelog" "$LocalRepo\docs-repo\changelog"
Copy-PathRequired "$DocsSource\src\content\glossary" "$LocalRepo\docs-repo\glossary"
Copy-PathOptional "$DocsSource\src\content\products" "$LocalRepo\docs-repo\products" "src/content/products"

Add-Line "Downloading Cloudflare AI-readable documentation files..."
Remove-Item -Recurse -Force "$LocalRepo\developer-site" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\developer-site" | Out-Null
Invoke-WebRequest -Uri $LlmsUrl -OutFile "$LocalRepo\developer-site\llms.txt"
Invoke-WebRequest -Uri $LlmsFullUrl -OutFile "$LocalRepo\developer-site\llms-full.txt"

Add-Line "Cloning Cloudflare API schemas repository..."
git clone --depth 1 $CloudflareApiSchemasRepo $ApiSchemasSource

cd $ApiSchemasSource
$ApiSchemasCommit = git rev-parse --short HEAD
cd C:\dev

Add-Line "Copying Cloudflare API schemas content..."
Copy-DirectoryContentsRequired $ApiSchemasSource "$LocalRepo\api-schemas"

Add-Line "Cloning Cloudflare MCP server repository..."
git clone --depth 1 $CloudflareMcpRepo $McpSource

cd $McpSource
$McpCommit = git rev-parse --short HEAD
cd C:\dev

Add-Line "Copying Cloudflare MCP server content..."
Copy-DirectoryContentsRequired $McpSource "$LocalRepo\mcp"

Add-Line "Writing source metadata..."
Remove-Item -Recurse -Force "$LocalRepo\source-metadata" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\source-metadata" | Out-Null

@"
Official Cloudflare developer documentation URL:
https://developers.cloudflare.com/

Official Cloudflare API documentation URL:
https://developers.cloudflare.com/api/

Official Cloudflare documentation repository:
https://github.com/cloudflare/cloudflare-docs

Included documentation repository paths:
https://github.com/cloudflare/cloudflare-docs/tree/production/src/content/docs
https://github.com/cloudflare/cloudflare-docs/tree/production/src/content/partials
https://github.com/cloudflare/cloudflare-docs/tree/production/src/content/changelog
https://github.com/cloudflare/cloudflare-docs/tree/production/src/content/glossary
https://github.com/cloudflare/cloudflare-docs/blob/production/AGENTS.md

Optional documentation repository path:
https://github.com/cloudflare/cloudflare-docs/tree/production/src/content/products

Included AI-readable documentation files:
https://developers.cloudflare.com/llms.txt
https://developers.cloudflare.com/llms-full.txt

Official Cloudflare API schemas repository:
https://github.com/cloudflare/api-schemas

Official Cloudflare MCP server repository:
https://github.com/cloudflare/mcp-server-cloudflare
"@ | Set-Content -Encoding UTF8 "$LocalRepo\source-metadata\source-urls.md"

@"
# Cloudflare Context Repository Source Metadata

This repository contains selected official Cloudflare documentation and source material for local development, AI-agent reference, AI-assisted development tools, automation, and future MCP/RAG workflows.

## Source Commits

Cloudflare documentation repository:
- Repository: https://github.com/cloudflare/cloudflare-docs.git
- Branch: production
- Commit: $CloudflareDocsCommit

Cloudflare API schemas repository:
- Repository: https://github.com/cloudflare/api-schemas.git
- Branch: default
- Commit: $ApiSchemasCommit

Cloudflare MCP server repository:
- Repository: https://github.com/cloudflare/mcp-server-cloudflare.git
- Branch: default
- Commit: $McpCommit

## Downloaded Documentation Files

- https://developers.cloudflare.com/llms.txt
- https://developers.cloudflare.com/llms-full.txt

## Optional Source Note

The Cloudflare docs product metadata path `src/content/products` is treated as optional. If the live Cloudflare documentation checkout does not contain that path, this script creates `docs-repo\products` as an empty placeholder.

## Refresh Rule

A normal git pull inside this context repository only updates the local copy from the configured GitLab remote. It does not refresh current official Cloudflare source material. To refresh current official Cloudflare content, run this repeat-safe PowerShell refresh script.
"@ | Set-Content -Encoding UTF8 "$LocalRepo\source-metadata\refresh-metadata.md"

Add-Line "Preparing Git repository..."
cd $LocalRepo

if (-not (Test-Path ".git")) {
    git init
    git branch -M main
}

git remote get-url origin *> $null
if ($LASTEXITCODE -ne 0) {
    git remote add origin $GitLabRemote
} else {
    git remote set-url origin $GitLabRemote
    git remote set-url --push origin $GitLabRemote
}

git add -A
git diff --cached --quiet

if ($LASTEXITCODE -eq 0) {
    Add-Line "No Cloudflare documentation context changes to commit."
} else {
    $CommitBody = @"
Refreshes the local GitLab context copy of selected official Cloudflare documentation, API schema, and MCP reference material.

Changed behavior:
- Replaces the stored Cloudflare documentation repository context with a verified copy from the production branch.
- Stores the Cloudflare documentation AGENTS.md file.
- Stores selected Cloudflare documentation content folders.
- Downloads Cloudflare AI-readable documentation files from developers.cloudflare.com.
- Replaces the stored Cloudflare API schemas context.
- Replaces the stored Cloudflare MCP server context.
- Stores source metadata showing the upstream commits used for this refresh.
- Treats the Cloudflare docs products metadata path as optional when the source checkout does not contain it.

Source:
- Developer docs URL: https://developers.cloudflare.com/
- Developer API docs URL: https://developers.cloudflare.com/api/
- LLM docs URL: https://developers.cloudflare.com/llms.txt
- Full LLM docs URL: https://developers.cloudflare.com/llms-full.txt
- Cloudflare documentation repository: https://github.com/cloudflare/cloudflare-docs.git at $CloudflareDocsCommit
- Included documentation paths: AGENTS.md, src/content/docs, src/content/partials, src/content/changelog, src/content/glossary
- Optional documentation path: src/content/products
- Cloudflare API schemas repository: https://github.com/cloudflare/api-schemas.git at $ApiSchemasCommit
- Cloudflare MCP server repository: https://github.com/cloudflare/mcp-server-cloudflare.git at $McpCommit

Operational context:
- Maintains an updated local and GitLab-hosted documentation context for Cloudflare.
- Supports Cloudflare Tunnel, Cloudflare Access, DNS, Pages, Workers, developer platform, Cloudflare API, and MCP/AI-agent reference work.
- Supports local review, AI-assisted development tool access, future documentation indexing, and future MCP/RAG workflows.
- Avoids depending only on live website lookup when AI agents need stable local Cloudflare reference material.

Validation performed:
- Cloned the Cloudflare documentation repository from the production branch.
- Verified required source paths before copying.
- Downloaded the current Cloudflare AI-readable documentation files.
- Cloned Cloudflare API schema reference material.
- Cloned Cloudflare MCP server reference material.
- Staged only the resulting context-repository changes.
"@

    git commit -m "Update Cloudflare documentation context" -m "$CommitBody"
    git push origin main
}

Add-Line ""
Add-Line "File count summary:"
Add-Line "docs files: $(Count-Files "$LocalRepo\docs-repo\docs")"
Add-Line "partials files: $(Count-Files "$LocalRepo\docs-repo\partials")"
Add-Line "changelog files: $(Count-Files "$LocalRepo\docs-repo\changelog")"
Add-Line "glossary files: $(Count-Files "$LocalRepo\docs-repo\glossary")"
Add-Line "products files: $(Count-Files "$LocalRepo\docs-repo\products")"
Add-Line "developer-site files: $(Count-Files "$LocalRepo\developer-site")"
Add-Line "api-schemas files: $(Count-Files "$LocalRepo\api-schemas")"
Add-Line "mcp files: $(Count-Files "$LocalRepo\mcp")"
Add-Line "source-metadata files: $(Count-Files "$LocalRepo\source-metadata")"
Add-Line "total ctx-cloudflare files: $(Count-Files "$LocalRepo")"

Add-Line ""
Add-Line "Git status:"
$GitStatus = git status 2>&1
foreach ($Line in $GitStatus) {
    Add-Line $Line
}

cd C:\dev
Remove-Item -Recurse -Force $TempRoot -ErrorAction SilentlyContinue

Add-Line ""
Add-Line "Temporary source folder removed: $TempRoot"
Add-Line "Finished: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
Add-Line "Report file: $ReportPath"
Add-Line "***** END CTX CLOUDFLARE REFRESH *****"

$ReportLines | Set-Content -Encoding UTF8 $ReportPath

6. Expected Result

If the official Cloudflare context material changed, the script should create and push a new commit with this subject:

Update Cloudflare documentation context

If the official Cloudflare context material did not change, the script should print:

No Cloudflare documentation context changes to commit.

If a commit is created, the script pushes it to:

git@gitlab-sudostac:sudostac/ctx-cloudflare.git

In either case, the final git status should show the current state of the local context repository.

A successful final Git status should look like this:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

The script also writes a refresh report to:

C:\dev\ctx-cloudflare-refresh-report.txt

A successful refresh should show nonzero file counts for:

docs
partials
changelog
glossary
developer-site
api-schemas
mcp
source-metadata

The products count may be zero. That is acceptable because the live Cloudflare documentation checkout did not contain src/content/products when this repository was created.

7. AI Agent Instructions

When using this repository for Cloudflare-related work, AI agents should treat C:\dev\ctx-cloudflare as the local Cloudflare documentation and source-material context.

AI agents should use the local context repository as the first reference source for work involving Cloudflare DNS, Cloudflare Tunnel, Cloudflare Access, Pages, Workers, developer-platform infrastructure, API-managed infrastructure, MCP, or Cloudflare AI-agent-related workflows.

The Cloudflare developer website, Cloudflare API documentation, or public upstream Cloudflare source repositories may still be used when the local context appears incomplete, stale, missing, or insufficient for a specific implementation question.

Do not assume that a normal git pull inside C:\dev\ctx-cloudflare refreshes the repository from Cloudflare's official sources. It only refreshes the local copy from the Just Headlines GitLab context repository. To update from official Cloudflare sources, run the PowerShell refresh script in this document.

Do not treat the docs-repo\products folder as required content unless the official Cloudflare documentation repository later restores or adds src/content/products.

8. Human Operator Notes

This script is safe to run repeatedly. It replaces the stored Cloudflare context content with a fresh copy of the selected official source material.

The script does not store SSH keys, passphrases, API keys, Cloudflare API tokens, Cloudflare account IDs, Cloudflare zone IDs, tunnel tokens, GitLab tokens, company secrets, service secrets, environment files, or application configuration secrets.

Git authentication is handled by the existing local SSH configuration on the operator's computer.

If GitLab asks for the SSH key passphrase, enter the passphrase for the local SSH key used with the gitlab-sudostac SSH configuration.

If GitLab does not ask for the SSH key passphrase, that does not automatically mean the push failed. It may mean that no commit was created, the SSH key is already unlocked in the current session, or the system has cached the SSH key.

If GitLab blocks a push because the branch is protected, check the GitLab branch protection settings for the ctx-cloudflare repository and confirm that normal pushes to main are permitted for the account performing this task.

The temporary source checkout folder is:

C:\dev\_cloudflare-source

The script removes that folder at the end of the run. It is not part of the permanent context repository.

9. Validation Checklist

After running the script, confirm the following:

  1. C:\dev\ctx-cloudflare\docs-repo\AGENTS.md exists.
  2. C:\dev\ctx-cloudflare\docs-repo\docs exists.
  3. C:\dev\ctx-cloudflare\docs-repo\docs contains Cloudflare documentation files.
  4. C:\dev\ctx-cloudflare\docs-repo\partials exists.
  5. C:\dev\ctx-cloudflare\docs-repo\partials contains Cloudflare documentation partial files.
  6. C:\dev\ctx-cloudflare\docs-repo\changelog exists.
  7. C:\dev\ctx-cloudflare\docs-repo\changelog contains Cloudflare changelog files.
  8. C:\dev\ctx-cloudflare\docs-repo\glossary exists.
  9. C:\dev\ctx-cloudflare\docs-repo\glossary contains Cloudflare glossary files.
  10. C:\dev\ctx-cloudflare\docs-repo\products exists.
  11. C:\dev\ctx-cloudflare\developer-site\llms.txt exists.
  12. C:\dev\ctx-cloudflare\developer-site\llms-full.txt exists.
  13. C:\dev\ctx-cloudflare\api-schemas exists.
  14. C:\dev\ctx-cloudflare\api-schemas contains selected Cloudflare API schema material.
  15. C:\dev\ctx-cloudflare\mcp exists.
  16. C:\dev\ctx-cloudflare\mcp contains selected Cloudflare MCP server material.
  17. C:\dev\ctx-cloudflare\source-metadata\source-urls.md exists.
  18. C:\dev\ctx-cloudflare\source-metadata\refresh-metadata.md exists.
  19. The local context repository contains selected official Cloudflare documentation, AI-readable documentation files, API schema material, and MCP server material.
  20. git status does not show unexpected staged changes.
  21. If changes were found, a commit was created.
  22. If a commit was created, it was pushed to git@gitlab-sudostac:sudostac/ctx-cloudflare.git.
  23. The temporary folder C:\dev\_cloudflare-source was removed.
  24. The refresh report exists at C:\dev\ctx-cloudflare-refresh-report.txt.

The docs-repo\products folder may contain zero files. That is acceptable because the live Cloudflare documentation checkout did not contain src/content/products when this repository was created.

10. Related Repositories

This document concerns the Cloudflare documentation context repository only:

C:\dev\ctx-cloudflare

It does not define the Just Headlines Cloudflare implementation itself. Production implementation belongs in the applicable Just Headlines application, site, admin, or server repository.

Related implementation repositories may include:

C:\dev\site
C:\dev\admin
C:\dev\news
C:\dev\server

The Cloudflare context repository is a reference repository. It stores selected official Cloudflare documentation and source material for local review, AI-assisted development, automation, and future MCP/RAG workflows. It does not store Cloudflare secrets, tunnel credentials, API tokens, account credentials, zone secrets, environment files, or production configuration secrets.