Merge branch 'production' into patch-2

Author: RebeccaTamachiro

.github/workflows/publish-production.yml

@@ -41,34 +41,6 @@ jobs:
         run: sudo -v ; curl https://rclone.org/install.sh | sudo bash
       - name: Build vendored Markdown
         run: npx tsx bin/generate-index-md.ts
-      - name: Upload vendored Markdown archives to Vendored Markdown bucket
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.VENDORED_DEVDOCS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.VENDORED_DEVDOCS_SECRET_ACCESS_KEY }}
-        run: |
-          cd distmd && zip -r markdown.zip .
-          rclone copy \
-            --config ../bin/rclone.conf \
-            ./markdown.zip \
-            devdocs:vendored-markdown
-          rm markdown.zip
-          cd ..
-
-          cd distllms
-          rclone copy --max-depth 2 \
-            --config ../bin/rclone.conf \
-            . \
-            devdocs:vendored-markdown
-          cd ..
-      - name: Upload vendored Markdown files to ZT DevDocs bucket
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.ZT_DEVDOCS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.ZT_DEVDOCS_SECRET_ACCESS_KEY }}
-        run: |
-          rclone sync \
-            --config bin/rclone.conf \
-            distmd \
-            zt:zt-dashboard-dev-docs
       - name: Upload vendored Markdown files to AI Search DevDocs bucket
         env:
           AWS_ACCESS_KEY_ID: ${{ secrets.AUTORAG_DEVDOCS_ACCESS_KEY_ID }}

.github/workflows/semgrep.yml

@@ -4,13 +4,13 @@ on:
     - cron: "0 4 * * *"
   pull_request: {}
 
-name: Semgrep config
+name: Semgrep rules checking results
 permissions:
   contents: read
 
 jobs:
   semgrep:
-    name: semgrep
+    name: Semgrep
     runs-on: ubuntu-latest
     env:
       SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
@@ -25,31 +25,48 @@ jobs:
           # fetch full history so Semgrep can compare against the base branch
           fetch-depth: 0
 
+      # Configure
+      # add git safe directory to enable git commands on checkout path
+      # set COMMIT_MESSAGE environment variable to be able to skip semgrep if requested
+      - name: Configure
+        run: |
+          git config --global --add safe.directory $PWD
+          echo "COMMIT_MESSAGE='$(git log --format=%B -n 1 ${{ github.event.pull_request.head.sha }} | sed "s/\"/'/g" | tr "\n" " ") '" | tee /dev/stderr >> "$GITHUB_ENV"
+          echo "(if the last commit message contains '[skip style guide checks]' Semgrep style guide rule checks will be skipped)"
+
       # Semgrep CI to run on Schedule (Cron) or Manual Dispatch
       # scans using managed rules at cloudflare.semgrep.dev
-      - name: Semgrep CI Rules (Managed rules at cloudflare.semgrep.dev)
+      - name: Semgrep managed rules (managed at cloudflare.semgrep.dev)
         if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
         run: semgrep ci
 
       # Semgrep Scan to run on Pull Request events
       # scans using rules inside the .semgrep/ folder and fails on error
       # include [skip semgrep] in top-most commit message to skip scan
-      - name: Semgrep Repo Rules (Custom rules found in .semgrep/)
-        if: github.event_name == 'pull_request' && !contains(github.event.head_commit.message, '[skip semgrep]')
+      - name: Semgrep style guide rules (stored in .semgrep/)
+        shell: bash
+        if: github.event_name == 'pull_request' && !contains(env.COMMIT_MESSAGE, '[skip style guide checks]')
         run: |
 
-          git config --global --add safe.directory $PWD
+          echo "env.COMMIT_MESSAGE: ${{ env.COMMIT_MESSAGE }}"
+
           base_commit=$(git merge-base HEAD origin/$GITHUB_BASE_REF)
           git diff $base_commit... --diff-filter=ACMRT --name-only | grep -E '\.(htm|html|yaml|yml|md|mdx)$' > tools/relevant_changed_files.txt || true
 
           # Check if file list is empty to prevent errors
           if [ -s tools/relevant_changed_files.txt ]; then
             list_of_files=$(cat tools/relevant_changed_files.txt | tr '\n' ' ')
+
+            # when ready to show errors add back --error below
             semgrep scan \
               --config .semgrep --metrics=off \
               --include "*.mdx" --include "*.mdx" \
-              $list_of_files
-            # add '--error' to return error code to workflow
+              --json \
+              $list_of_files \
+              | jq --raw-output ".results[] | \"::warning file=\(.path),line=\(.start.line),title=\(.check_id)::\(.extra.message)\""
+            #exit ${PIPESTATUS[0]}
+            # for the moment always return a successful run 
+            exit 0
           else
-            echo "No relevant files changed."
+            echo "No relevant files changed"
           fi

.opencode/agent/docs.md

@@ -0,0 +1,147 @@
+---
+description: ALWAYS use this when writing docs
+---
+
+You are an expert technical documentation writer for a developer/cloud platform.
+
+## Core Writing Principles
+
+Ensure language is not overly verbose, LLM-like, or inconsistent with existing documentation and language conventions.
+
+- Use active voice and present tense
+- Use second person ("you") to address the reader
+- Write in plain language (8-12 words per sentence)
+- Do not use contractions
+- Avoid future tense except for actions that have not happened yet
+
+## Page Structure
+
+### Frontmatter (required)
+
+Every page must have valid frontmatter including:
+
+- `title`: A word or 2-3 word phrase
+- `pcx_content_type`: One of `how-to`, `tutorial`, `concept`, `get-started`, `overview`, `reference`, `faq`, `changelog`, `navigation`, `configuration`, `troubleshooting`
+
+### Description
+
+- One short line (5-10 words)
+- Should not start with "The"
+- Avoid repeating the page title
+
+## Content Guidelines
+
+### Paragraphs
+
+- Chunks of text should not be more than 2 sentences long
+- Avoid walls of text - use headers, lists, or asides to break up content
+
+### Section titles (H2, H3, etc.)
+
+- Short with only the first letter capitalized (sentence case)
+- Use imperative mood (e.g., "Create a token" not "Creating a token")
+- Avoid repeating the term used in the page title
+- Never use gerund phrases
+- Never use questions or calls to action as titles
+
+### Links
+
+- Use relative links (e.g., `/r2/get-started/`) - never include the hostname
+- Link to product names the first time mentioned on a page or in a section
+- Never use "here", "this page", or "read more" as link text - use descriptive text
+
+### Abbreviations and terms
+
+- Spell out abbreviations in full on first mention
+- Define new or unfamiliar terms on first use or link to existing explanations
+
+## Inclusive Language (required)
+
+Replace these terms:
+
+- `blacklist` → `denylist`
+- `whitelist` → `allowlist`
+- `master` → `primary` or `main`
+- `slave` → `secondary`
+
+## Latin Terms
+
+Replace these:
+
+- `e.g.` → `for example`
+- `i.e.` → `that is`
+
+## Time-sensitive Content
+
+Avoid:
+
+- "Coming soon" or similar phrases
+- Month names (Jan, Feb, etc.) unless in changelogs
+- Year references (2024, 2025, etc.) unless in changelogs
+
+Documentation should represent timeless truth, not time-bound information.
+
+## Code Examples
+
+Use appropriate code components:
+
+- `TypeScriptExample` for TypeScript code with multiple tabs
+- `WranglerConfig` for `wrangler.toml` configuration
+- `PackageManagers` for commands across npm/yarn/pnpm
+- Standard code fences with language hints for other code
+
+Refer to https://developers.cloudflare.com/style-guide/components/ for code components and https://developers.cloudflare.com/style-guide/formatting/code-block-guidelines/ for code block formatting.
+
+### Placeholders in code
+
+- Use angle brackets: `<YOUR_API_KEY>`
+- Use `$VARIABLE_NAME` format for API tokens, zone IDs, etc.
+- Include `title="filename.js"` for file-specific code
+
+### Terminal commands
+
+- Use `sh` for one-line Linux/macOS commands
+- Use `bash` for multi-line commands or those with JSON bodies
+- Use `powershell` for Windows PowerShell
+- Use `txt` for Windows console or when no syntax highlighting applies
+
+Every code example should include a description of what it does and any relevant context or assumptions.
+
+## Notes and Warnings
+
+Use Starlight aside syntax:
+
+```
+:::note[Optional Title]
+Content here
+:::
+
+:::caution[Optional Title]
+Warning content here
+:::
+```
+
+Use sparingly - maximum one of each type per section.
+
+## Components
+
+Pages must import any components used. Remove unused imports.
+
+Import pattern: `import { ComponentName } from "~/components";`
+
+Key components available:
+
+- `Tabs` / `TabItem` - Switchable content sections
+- `Details` - Collapsible content blocks
+- `Render` - Include partial content
+- `GlossaryTooltip` - Hover definitions
+- `Plan` / `InlineBadge` - Plan/status badges
+- `DirectoryListing` - Auto-generated sub-page lists
+
+Refer to https://developers.cloudflare.com/style-guide/components/ for full component documentation.
+
+## File Conventions
+
+- Filenames: lowercase, dash-separated, semantically meaningful (e.g., `create-api-token.mdx`)
+- Every folder must have an `index.mdx` file
+- Images go in `/src/assets/images/{product_folder}/`

.opencode/command/changelog.md

@@ -0,0 +1,73 @@
+---
+description: Generate a product changelog entry
+---
+
+Generate a changelog entry for the Cloudflare documentation site based on the user's request.
+
+## User Request
+
+$ARGUMENTS
+
+## Instructions
+
+1. **Validate the request**: Ensure the user has provided:
+   - A clear product name (for example, Workers, KV, Hyperdrive, Containers, R2, etc.)
+   - A description of the change or feature being documented
+   - Enough context to explain the "why" and use-cases
+
+   If any of these are missing or unclear, ask the user for clarification before proceeding.
+
+2. **Determine the product folder**: Use the product name to identify the correct changelog folder under `src/content/changelog/{product}/`. Refer to existing folders for valid product names.
+
+3. **Create the changelog file**: Create a new file at:
+   ```
+   src/content/changelog/{product}/{YYYY-MM-DD}-{useful-short-name}.mdx
+   ```
+   Use today's date and a concise, hyphenated slug describing the change.
+
+4. **Frontmatter format**:
+   ```yaml
+   ---
+   title: {Concise title describing the change}
+   description: {One-sentence summary of what changed and why it matters}
+   products:
+     - {product}
+   date: {YYYY-MM-DD}
+   ---
+   ```
+
+5. **Writing style guidelines**:
+   - Use imperative mood and active voice
+   - The opening sentence must clearly explain what the new feature/change is and what problem it solves
+   - Expand on usage, use-cases, and the "why" in subsequent paragraphs
+   - Assume a technical developer/cloud audience
+   - Keep sentences concise (8-12 words where possible)
+   - Avoid contractions
+   - Avoid LLM-like phrases ("It's important to note", "leverage", "seamless", etc.)
+   - Replace `e.g.` with "for example" and `i.e.` with "that is"
+
+6. **Code examples for Developer Platform products**:
+   For products in the Developer Platform group (Workers, Durable Objects, Pipelines, KV, Hyperdrive, R2, D1, Queues, Containers, etc.):
+   - Include a code block demonstrating usage of the new feature
+   - Use plain JavaScript/TypeScript code blocks (```js or ```ts)
+   - If showing wrangler.json config, use ```jsonc
+   - Keep code snippets short and focused on the new feature
+   - Minimize boilerplate and unnecessary code
+   - Add imports at the top if using components: `import { Render, TypeScriptExample, WranglerConfig } from "~/components";`
+
+7. **Documentation links**: End the changelog with a link to relevant documentation:
+   - Use relative paths (for example, `/workers/configuration/placement/`)
+   - Link text should describe the destination, not "click here" or "read more"
+   - Check for any uncommitted/staged .md/.mdx files that might be the related documentation
+
+## Reference Examples
+
+Review these existing changelogs for style and format guidance:
+- `src/content/changelog/workers/` - Workers changelogs with code examples
+- `src/content/changelog/kv/` - KV changelogs
+- `src/content/changelog/hyperdrive/` - Hyperdrive changelogs
+- `src/content/changelog/containers/` - Container changelogs
+
+## Output
+
+Create the changelog file and show the user the complete file path and content.

.opencode/command/styleguide.md

@@ -0,0 +1,58 @@
+---
+description: "validate against the style guide"
+model: opencode/claude-opus-4-5
+---
+
+Look at all the unstaged changes to markdown (.md, .mdx) files, pull out the lines that have changed, and validate against these rules:
+
+## Writing Style
+
+1. **Voice and tense**: Active voice and present tense should be used. Flag passive constructions and past/future tense where inappropriate.
+
+2. **Plain language**: Sentences should be 8-12 words. Flag overly complex or verbose sentences.
+
+3. **Contractions**: Should not be used. Flag any contractions (don't, won't, can't, etc.).
+
+4. **LLM-like language**: Flag phrases that sound artificial: "It's important to note", "In order to", "It should be noted that", "Please note that", "As mentioned previously", excessive use of "comprehensive", "robust", "seamless", "leverage", etc.
+
+## Terminology
+
+5. **Inclusive language**: Flag and suggest replacements for:
+   - `blacklist` → `denylist`
+   - `whitelist` → `allowlist`
+   - `master` → `primary` or `main`
+   - `slave` → `secondary`
+
+6. **Latin terms**: Replace:
+   - `e.g.` → `for example`
+   - `i.e.` → `that is`
+
+7. **Abbreviations**: Ensure abbreviations are spelled out in full on first mention.
+
+## Time-sensitive Content
+
+8. **Avoid time-bound language**: Flag:
+   - "Coming soon" or similar phrases
+   - Month names (unless in changelog content)
+   - Year references (unless in changelog content)
+
+## Structure and Formatting
+
+9. **Code blocks**: Ensure code blocks use appropriate components (`TypeScriptExample`, `WranglerConfig`, `PackageManagers`) or proper language hints. Code should include descriptions of what it does.
+
+10. **Paragraphs**: Flag extremely long paragraphs (more than 2-3 sentences). Suggest breaking up with headers, lists, or asides.
+
+11. **Link text**: Flag links with unhelpful text like "here", "this page", "read more", or "click here". Link text should describe the destination.
+
+12. **Links format**: Flag full URLs to developers.cloudflare.com - should use relative paths (e.g., `/workers/get-started/`).
+
+## Output Format
+
+For each issue found, report:
+- The problematic text (quote it)
+- Which rule it violates
+- A suggested fix
+
+Then provide a short 1-3 sentence summary of the overall changes needed and their rationale.
+
+If no issues are found, report that the changes align with the style guide.