Agent context single source

.github/workflows/agent-context-ci.yml

@@ -0,0 +1,33 @@
+name: Validate agent context
+
+on:
+  pull_request:
+    paths:
+      - agent-context/**
+      - .github/workflows/agent-context-ci.yml
+      - .github/workflows/sync-agent-context.yml
+  push:
+    branches: [main]
+    paths:
+      - agent-context/**
+      - .github/workflows/agent-context-ci.yml
+      - .github/workflows/sync-agent-context.yml
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - run: npm test
+        working-directory: agent-context
+      - run: npm run check
+        working-directory: agent-context
+      - run: npm run build
+        working-directory: agent-context

.github/workflows/sync-agent-context.yml

@@ -0,0 +1,132 @@
+name: Sync plugin context
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - agent-context/context/**
+      - agent-context/targets/**
+      - agent-context/scripts/**
+      - agent-context/test/**
+      - agent-context/package.json
+      - .github/workflows/sync-agent-context.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-plugin-context
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          package-manager-cache: false
+      - run: npm test
+        working-directory: agent-context
+      - run: npm run check
+        working-directory: agent-context
+
+  sync:
+    needs: validate
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: codex
+            repository: mintlify/codex-plugin
+            repository_name: codex-plugin
+            mcp_file: .mcp.json
+          - target: cursor
+            repository: mintlify/cursor-plugin
+            repository_name: cursor-plugin
+            mcp_file: mcp.json
+          - target: claude
+            repository: mintlify/mintlify-claude-plugin
+            repository_name: mintlify-claude-plugin
+            mcp_file: .mcp.json
+
+    steps:
+      - name: Check out context source
+        uses: actions/checkout@v6
+        with:
+          path: source
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          package-manager-cache: false
+
+      - name: Create target repository token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ vars.CONTEXT_SYNC_APP_CLIENT_ID }}
+          private-key: ${{ secrets.CONTEXT_SYNC_APP_PRIVATE_KEY }}
+          owner: mintlify
+          repositories: ${{ matrix.repository_name }}
+          permission-contents: write
+          permission-pull-requests: write
+
+      - name: Check out target repository
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ matrix.repository }}
+          token: ${{ steps.app-token.outputs.token }}
+          path: target
+
+      - name: Generate target context
+        run: node source/agent-context/scripts/sync-target.mjs "${{ matrix.target }}" target
+
+      - name: Detect changes
+        id: changes
+        working-directory: target
+        run: |
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push sync branch
+        if: steps.changes.outputs.changed == 'true'
+        working-directory: target
+        env:
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+          BRANCH: automation/sync-agent-context
+        run: |
+          git config user.name "${APP_SLUG}[bot]"
+          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"
+          git checkout -B "$BRANCH"
+          git add skills/mintlify .mintlify-agent-context.json "${{ matrix.mcp_file }}"
+          git commit -m "Sync Mintlify agent context"
+          git fetch origin "$BRANCH:refs/remotes/origin/$BRANCH" || true
+          git push --force-with-lease origin "HEAD:$BRANCH"
+
+      - name: Open sync pull request
+        if: steps.changes.outputs.changed == 'true'
+        working-directory: target
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_REPO: ${{ matrix.repository }}
+          BRANCH: automation/sync-agent-context
+          SOURCE_SHA: ${{ github.sha }}
+        run: |
+          BODY="Generated from mintlify/docs at ${SOURCE_SHA} using agent-context. Do not edit generated skill files in this repository."
+          EXISTING_PR="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number')"
+          if [[ -z "$EXISTING_PR" ]]; then
+            gh pr create \
+              --head "$BRANCH" \
+              --base main \
+              --title "Sync Mintlify agent context" \
+              --body "$BODY"
+          else
+            gh pr edit "$EXISTING_PR" --body "$BODY"
+          fi

.mintignore

@@ -0,0 +1,2 @@
+# Internal tooling that compiles context for external agent plugins.
+agent-context/

agent-context/.gitignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+.DS_Store

agent-context/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mintlify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent-context/README.md

@@ -0,0 +1,60 @@
+# Mintlify agent context
+
+Single source of truth, maintained in the Mintlify documentation repository, for the Mintlify skill distributed through the Codex, Cursor, and Claude plugins.
+
+## Repository structure
+
+- `context/skills/mintlify/` contains canonical, client-neutral context.
+- `context/mcp-servers.json` contains canonical MCP names, URLs, and transport settings.
+- `targets/*.json` contains only client packaging differences such as MCP config file and schema names.
+- `scripts/build.mjs` renders self-contained plugin artifacts into `dist/`.
+- `scripts/sync-target.mjs` replaces only `skills/mintlify/` in a target repository.
+- `../.github/workflows/sync-agent-context.yml` opens generated sync pull requests in all three plugin repositories.
+
+Plugin manifests, assets, READMEs, and Cursor rules remain owned by their target repositories. This project generates the shared skill and each client's MCP configuration file.
+
+## Local development
+
+Requires Node.js 22 or newer and has no package dependencies.
+
+```bash
+npm test
+npm run check
+npm run build
+npm run status
+```
+
+Build one target by passing its ID:
+
+```bash
+node scripts/build.mjs codex
+```
+
+Preview a sync into a local checkout:
+
+```bash
+node scripts/sync-target.mjs codex ../../codex-plugin
+git -C ../../codex-plugin diff
+```
+
+The sync command replaces `skills/mintlify/`, writes the client-specific MCP configuration file, and writes `.mintlify-agent-context.json` with the source commit. It does not change any other plugin files.
+
+`npm run status` compares locally checked-out sibling plugin repositories with fresh builds and reports whether each one is current. Pass a workspace root as the final argument if the repositories do not share this repository's parent directory.
+
+## Publishing setup
+
+Create a GitHub App installed on these repositories:
+
+- `mintlify/codex-plugin`
+- `mintlify/cursor-plugin`
+- `mintlify/mintlify-claude-plugin`
+
+Grant the app repository **Contents: read and write** and **Pull requests: read and write** permissions. Add its client ID as the `CONTEXT_SYNC_APP_CLIENT_ID` Actions variable and its private key as the `CONTEXT_SYNC_APP_PRIVATE_KEY` Actions secret in the `mintlify/docs` repository.
+
+Every qualifying push to `main` validates the source and opens or updates the `automation/sync-agent-context` pull request in each repository. The workflow never pushes directly to a target's default branch.
+
+## Editing rules
+
+Edit shared knowledge and MCP definitions in `context/`, not in generated plugin copies. Put a value in `targets/` only when a client requires a different packaging format.
+
+The build rejects retired CLI commands. Tests verify that the skill, detailed references, and MCP definitions remain semantically identical across targets.

agent-context/context/mcp-servers.json

@@ -0,0 +1,10 @@
+{
+  "Mintlify Search": {
+    "type": "http",
+    "url": "https://mintlify.com/docs/mcp"
+  },
+  "Mintlify Admin": {
+    "type": "http",
+    "url": "https://mcp.mintlify.com"
+  }
+}