Initial setup: ADP documentation repository

.github/test-docs.yml

@@ -0,0 +1,100 @@
+name: Run doc tests
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  pull_request:
+    types: [opened, reopened, synchronize]
+  workflow_dispatch:
+  repository_dispatch:
+    types: [trigger-tests]
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      console: ${{ steps.filter.outputs.console }}
+      quickstart: ${{ steps.filter.outputs.quickstart }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Determine changed paths
+        id: filter
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            console:
+              - 'modules/console/**'
+            quickstart:
+              - 'modules/get-started/pages/quick-start.adoc'
+
+  run-tests:
+    needs: setup
+    # Skip the entire job for fork PRs
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork != true
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    strategy:
+      matrix:
+        os: [ubuntu-latest]  # Only using Linux for now since macOS doesn't include Docker
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ vars.RP_AWS_CRED_REGION }}
+          role-to-assume: arn:aws:iam::${{ secrets.RP_AWS_CRED_ACCOUNT_ID }}:role/${{ vars.RP_AWS_CRED_BASE_ROLE_NAME }}${{ github.event.repository.name }}
+      - uses: aws-actions/aws-secretsmanager-get-secrets@v2
+        with:
+          secret-ids: |
+            ,sdlc/prod/github/actions_bot_token
+          parse-json-secrets: true
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ env.ACTIONS_BOT_TOKEN }}
+          path: redpanda-docs
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+        working-directory: redpanda-docs
+
+      - name: Set GitHub token
+        run: |
+          echo "REDPANDA_GITHUB_TOKEN=${{ env.ACTIONS_BOT_TOKEN }}" >> $GITHUB_ENV
+
+      - name: Run all tests
+        if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch' || github.event_name == 'schedule' }}
+        uses: doc-detective/github-action@v1
+        with:
+          input: ../../modules/get-started/pages/quick-start.adoc
+          working_directory: redpanda-docs/tests/setup-tests
+          exit_on_fail: true
+          # create a PR/issue only if the workflow wasn't already triggered by a PR
+          create_pr_on_change: true
+          create_issue_on_fail: true
+          token: ${{ env.ACTIONS_BOT_TOKEN }}
+
+      - name: Test Redpanda Self-Managed quickstart
+        if: ${{ needs.setup.outputs.quickstart == 'true' || needs.setup.outputs.console == 'true' }}
+        uses: doc-detective/github-action@v1
+        with:
+          input: ../../modules/get-started/pages/quick-start.adoc
+          working_directory: redpanda-docs/tests/setup-tests
+          exit_on_fail: true
+        env:
+          REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }}
+
+      - name: Upload debug artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-detective-output
+          path: /home/runner/work/_temp/doc-detective-output.json
+        env:
+          REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }}

.github/workflows/check-playbook.yml

@@ -0,0 +1,49 @@
+---
+name: Check playbook branches
+on:
+  pull_request:
+    paths:
+      - local-antora-playbook.yml
+  push:
+    branches: [main]
+    paths:
+      - local-antora-playbook.yml
+
+jobs:
+  check-branches:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for non-standard branch references
+        run: |
+          # Allowed branch patterns in local-antora-playbook.yml.
+          # Any value not matching these is likely a PR branch that
+          # must be reverted before merge.
+          ALLOWED='main|HEAD|v/\*|shared|site-search|!v-end-of-life/\*'
+
+          # Extract all branch values from the playbook
+          BRANCHES=$(grep 'branches:' local-antora-playbook.yml \
+            | sed 's/.*branches:[[:space:]]*//' \
+            | tr -d "[]'" \
+            | tr ',' '\n' \
+            | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+          FAILED=0
+          while IFS= read -r branch; do
+            [ -z "$branch" ] && continue
+            if ! echo "$branch" | grep -qE "^(${ALLOWED})$"; then
+              echo "::error::Non-standard branch reference found: '${branch}'"
+              FAILED=1
+            fi
+          done <<< "$BRANCHES"
+
+          if [ "$FAILED" -eq 1 ]; then
+            echo ""
+            echo "local-antora-playbook.yml contains non-standard branch references."
+            echo "These are used for cross-repo Netlify previews during PR development,"
+            echo "but must be reverted to standard values (e.g., 'main') before merging."
+            exit 1
+          fi
+
+          echo "Playbook OK: all branch references are standard."

.github/workflows/update-extensions.yml

@@ -0,0 +1,59 @@
+---
+name: Update docs tools and extensions
+on:
+  workflow_dispatch:
+  repository_dispatch:
+    types: [trigger-npm-update]
+
+jobs:
+  update-dependency:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+      pull-requests: write
+    strategy:
+      fail-fast: false
+      matrix:
+        branch: [main]
+
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ vars.RP_AWS_CRED_REGION }}
+          role-to-assume: arn:aws:iam::${{ secrets.RP_AWS_CRED_ACCOUNT_ID }}:role/${{ vars.RP_AWS_CRED_BASE_ROLE_NAME }}${{ github.event.repository.name }}
+
+      - uses: aws-actions/aws-secretsmanager-get-secrets@v2
+        with:
+          secret-ids: |
+            ,sdlc/prod/github/actions_bot_token
+          parse-json-secrets: true
+
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ matrix.branch }}
+          token: ${{ env.ACTIONS_BOT_TOKEN }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Update @redpanda-data/docs-extensions-and-macros
+        run: npm update @redpanda-data/docs-extensions-and-macros
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ env.ACTIONS_BOT_TOKEN }}
+          commit-message: "auto-docs: Update @redpanda-data/docs-extensions-and-macros"
+          labels: auto-docs
+          title: "auto-docs: Update @redpanda-data/docs-extensions-and-macros"
+          body: |
+            This PR updates `@redpanda-data/docs-extensions-and-macros` using `npm update`.
+          branch: update/docs-extensions-and-macros-${{ matrix.branch }}
+          base: ${{ matrix.branch }}

README.adoc

@@ -1,49 +1,44 @@
-:product: <product-name>
+:product: Agentic Data Plane
 = {product} Documentation
 :url-playbook: https://github.com/redpanda-data/docs-site
 
 image:https://img.shields.io/badge/slack-purple[Slack, link="https://redpanda.com/slack"]
 image:https://img.shields.io/twitter/follow/redpandadata.svg?style=social&label=Follow[Twitter, link="https://twitter.com/intent/follow?screen_name=redpandadata"]
 
-++++
-<p>
-<a href="https://docs.redpanda.com">
-<object type="image/svg+xml">
-  <img src="https://raw.githubusercontent.com/redpanda-data/docs-ui/main/src/img/redpanda-docs-logo.svg"/>
-</object>
-</p></a>
-++++
-
 This repository hosts the documentation content for Redpanda {product}.
 
-== Contribute
+== About Agentic Data Plane
 
-The Redpanda docs are open source, and we welcome your contributions!
+Redpanda Agentic Data Plane (ADP) provides enterprise-grade infrastructure for building, deploying, and governing AI agents at scale. Key capabilities include:
 
-Before you add or edit content, consult the Redpanda https://github.com/redpanda-data/docs-site/blob/main/meta-docs/STYLE-GUIDE.adoc[Style Guide] for product documentation guidelines.
+* **Model Context Protocol (MCP)** - Tool integration for connecting agents to business systems
+* **AI Gateway** - Centralized routing and governance for multi-agent systems
+* **Declarative Agents** - Build production-ready agents with YAML configuration
+* **Observability & Transcripts** - Compliance-grade audit trails and monitoring
+* **Trust & Governance** - Guardrails, token budgets, and kill switches
 
-To contribute to the Redpanda docs, you have the following options:
+== Content Types
 
-|===
-|Option|Description
+This documentation includes content for both deployment models:
 
-|<<Open an issue>>
-|Suggest a change by opening an issue on GitHub.
+* **Cloud** - Managed ADP on Redpanda Cloud
+* **BYOC** - Bring Your Own Cloud deployment with additional enterprise features
 
-|<<Contribute content>>
-|Make changes directly to the documentation and submit them through a pull request.
+Pages are tagged with `badge:Cloud[]` or `badge:BYOC[]` to indicate which deployment model they apply to. Pages without badges apply to both.
 
-|===
+== Contribute
+
+The Redpanda docs are open source, and we welcome your contributions!
+
+Before you add or edit content, consult the Redpanda https://github.com/redpanda-data/docs-site/blob/main/meta-docs/STYLE-GUIDE.adoc[Style Guide] for product documentation guidelines.
 
 === Open an issue
 
-The Redpanda docs team uses GitHub issues to track, plan, and prioritize tasks. To suggest changes, you can create an issue, which the team will then evaluate:
+The Redpanda docs team uses GitHub issues to track, plan, and prioritize tasks. To suggest changes:
 
-. Verify whether a similar issue already exists in that repository to avoid duplication.
+. Verify whether a similar issue already exists to avoid duplication.
 . Go to **Issues** > **New Issue** to create a new issue.
 
-You have the option to assign the issue to yourself or leave the assignee field blank. The Redpanda docs team triages all new issues and will allocate a writer if one isn't already assigned.
-
 If you are a Redpanda employee, submit doc issues in `redpanda-data/documentation-private`.
 
 === Contribute content
@@ -53,62 +48,58 @@ You have two options to contribute to the documentation:
 . Directly edit a page on GitHub by selecting **Make a contribution** > **Edit on GitHub** located at the bottom of a documentation page.
 . Clone the docs repository to make changes locally on your machine. For a guide, see {url-playbook}/blob/main/meta-docs/CONTRIBUTING.adoc[Submit your first contribution].
 
-Check the open docs issues. If you find an issue you'd like to work on:
-
-- If the issue is already assigned to someone else, please consider another one.
-- If the issue is unassigned, add a comment expressing your interest in working on it.
-
 == Local development
 
-If you want to run the website locally, install and update the packages:
+Build and preview the docs locally:
 
-```bash
+[source,bash]
+----
 npm update
-```
-
-Then, build the docs and start a local web server:
-
-```bash
 npm run start
-```
+----
 
-This command opens a browser window. Most changes are reflected live without having to restart the server.
+This command opens a browser window with live reload enabled. Changes are reflected automatically.
 
 === Build the site
 
-To build the files, run:
+To build static files:
 
-```bash
+[source,bash]
+----
 npm run build
-```
+----
 
-This command generates static content in the `docs` directory and can be served using any hosting service.
+This generates static content in the `docs` directory.
 
-You can serve the static files on a local web server using:
+To serve the static files locally:
 
-```bash
+[source,bash]
+----
 npm run serve
-```
-
-== Versioning
-
-Versioned content is stored in branches that track the version of Redpanda {product}. Production branches use the *v/x.y* naming pattern. For example, branch `v/22.3` hosts the content for version 22.3.x of Redpanda {product}. The `main` branch always contains docs for the latest release.
-
-The production {url-playbook}[docs site playbook] instructs Antora to automatically aggregate content in the following branches:
-
-- `main`: Content for the latest version of Redpanda {product}.
+----
 
 == Repository Structure
 
-The documentation content is stored in the `modules/` directory, where each module represents a top-level label in the documentation nav tree.
-
-Each module has a `pages/` directory that stores the documentation pages in Asciidoc format. Some modules also include a `partials/` directory that contains single-sourced documentation that can be shared and referenced by any documentation pages across any module.
-
-The `shared` module stores the images, attachments, and partials that do not belong to a single module and can be referenced by any documentation pages across any module.
+This repository does NOT use versioning. The `main` branch contains the current documentation.
 
 ....
-modules/shared
-├── attachments
-├── images
-└── partials
+adp-docs/
+├── antora.yml                    # Antora component configuration
+├── local-antora-playbook.yml     # Local development playbook
+├── package.json                  # npm configuration
+├── README.adoc                   # This file
+└── modules/ROOT/
+    ├── nav.adoc                  # Navigation structure
+    ├── pages/                    # AsciiDoc documentation pages
+    ├── partials/                 # Reusable content snippets
+    ├── examples/                 # YAML configurations and examples
+    └── images/                   # Documentation images
 ....
+
+== Related Repositories
+
+* https://github.com/redpanda-data/docs-site[docs-site] - Antora playbook and site build
+* https://github.com/redpanda-data/docs-ui[docs-ui] - UI theme and components
+* https://github.com/redpanda-data/cloud-docs[cloud-docs] - Redpanda Cloud documentation
+* https://github.com/redpanda-data/docs[docs] - Redpanda self-managed documentation
+* https://github.com/redpanda-data/rp-connect-docs[rp-connect-docs] - Redpanda Connect documentation