From e8a6dcbd595c435066b19a0798fa190372b2d0f4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 16 Sep 2026 14:57:50 +0000
Subject: [PATCH 1/3] Add Context7-ready template configuration

Co-authored-by: palewire <9993+palewire@users.noreply.github.com>
---
 .github/workflows/context7-refresh.yml | 43 ++++++++++++++++++++++++++
 CHANGELOG.md                           |  3 ++
 MANIFEST.in                            |  1 +
 TEMPLATE_SETUP.md                      | 20 ++++++++++++
 context7.json                          |  3 ++
 5 files changed, 70 insertions(+)
 create mode 100644 .github/workflows/context7-refresh.yml
 create mode 100644 context7.json

diff --git a/.github/workflows/context7-refresh.yml b/.github/workflows/context7-refresh.yml
new file mode 100644
index 0000000..b026fdf
--- /dev/null
+++ b/.github/workflows/context7-refresh.yml
@@ -0,0 +1,43 @@
+name: Refresh Context7 index
+
+on:
+  push:
+    paths:
+      - "context7.json"
+      - "README.md"
+      - "docs/**"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: context7-refresh
+  cancel-in-progress: true
+
+jobs:
+  refresh:
+    name: Request library refresh
+    if: >-
+      github.ref_name == github.event.repository.default_branch &&
+      vars.CONTEXT7_REFRESH_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Request Context7 refresh
+        env:
+          CONTEXT7_API_KEY: ${{ secrets.CONTEXT7_API_KEY }}
+          CONTEXT7_LIBRARY_NAME: /${{ github.repository }}
+        run: |
+          if [ -z "$CONTEXT7_API_KEY" ]; then
+            echo "::error::Set the CONTEXT7_API_KEY repository secret."
+            exit 1
+          fi
+          printf -v authorization "Authorization: %s %s" "Bearer" "$CONTEXT7_API_KEY"
+
+          curl --fail-with-body --retry 3 --retry-all-errors \
+            --silent --show-error --max-time 60 \
+            --request POST \
+            --url https://context7.com/api/v1/refresh \
+            --header "$authorization" \
+            --header "Content-Type: application/json" \
+            --data "{\"libraryName\":\"$CONTEXT7_LIBRARY_NAME\"}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9622ea6..40afb76 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- Add project-neutral Context7 configuration, opt-in index refresh automation,
+  and setup guidance for generated projects.
+
 ### Changed
 
 ### Fixed
diff --git a/MANIFEST.in b/MANIFEST.in
index be60802..2009289 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -7,6 +7,7 @@ include .pre-commit-config.yaml
 include .python-version
 include AGENTS.md
 include CHANGELOG.md
+include context7.json
 include LICENSE
 include README.md
 include CODE_OF_CONDUCT.md
diff --git a/TEMPLATE_SETUP.md b/TEMPLATE_SETUP.md
index 621ba68..c5bd0fd 100644
--- a/TEMPLATE_SETUP.md
+++ b/TEMPLATE_SETUP.md
@@ -19,6 +19,26 @@ Complete this checklist before the first release.
 - [ ] Configure S3 deployment through the protected `docs-production`
       environment, AWS OIDC variables, and `DOCS_DEPLOY_ENABLED=true`.
 
+## Context7
+
+The root `context7.json` intentionally specifies only the current schema.
+Context7 can then infer project metadata, follow the default branch, scan the
+whole repository, and apply its built-in exclusions without template-specific
+placeholders.
+
+- [ ] Publish useful documentation, then [submit the public repository to
+      Context7](https://context7.com/add-library).
+- [ ] Claim ownership from the library's Context7 admin page. Add the generated
+      `url` and `public_key` values to `context7.json`, push them to the default
+      branch, and complete the claim.
+- [ ] After claiming, use **Apply for Verification** on the admin page and
+      provide the requested project and documentation details if the automatic
+      quality check does not approve it.
+- [ ] Rely on Context7's usage-based automatic refreshes, refresh manually after
+      important releases, or enable `.github/workflows/context7-refresh.yml` by
+      setting a `CONTEXT7_API_KEY` repository secret and the
+      `CONTEXT7_REFRESH_ENABLED=true` repository variable.
+
 ## Continuous Integration
 
 - [ ] Set the `PACKAGE_IMPORT_NAME` repository variable to the package import
diff --git a/context7.json b/context7.json
new file mode 100644
index 0000000..2ffb2cc
--- /dev/null
+++ b/context7.json
@@ -0,0 +1,3 @@
+{
+  "$schema": "https://context7.com/schema/context7.json"
+}

From e0711db14670a61e680297c01b1ff642f74d18c5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:02:16 +0000
Subject: [PATCH 2/3] Refine generic Context7 indexing defaults

Co-authored-by: palewire <9993+palewire@users.noreply.github.com>
---
 TEMPLATE_SETUP.md |  9 +++++----
 context7.json     | 13 ++++++++++++-
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/TEMPLATE_SETUP.md b/TEMPLATE_SETUP.md
index c5bd0fd..54c061f 100644
--- a/TEMPLATE_SETUP.md
+++ b/TEMPLATE_SETUP.md
@@ -21,10 +21,11 @@ Complete this checklist before the first release.
 
 ## Context7
 
-The root `context7.json` intentionally specifies only the current schema.
-Context7 can then infer project metadata, follow the default branch, scan the
-whole repository, and apply its built-in exclusions without template-specific
-placeholders.
+The root `context7.json` uses the current schema, indexes `docs/` and the
+root-level README, and excludes the template's operational files. It omits
+project metadata, branch names, versions, and usage rules so Context7 can infer
+safe defaults without template-specific placeholders. Adjust its paths if the
+project's user documentation lives elsewhere.
 
 - [ ] Publish useful documentation, then [submit the public repository to
       Context7](https://context7.com/add-library).
diff --git a/context7.json b/context7.json
index 2ffb2cc..bb29c81 100644
--- a/context7.json
+++ b/context7.json
@@ -1,3 +1,14 @@
 {
-  "$schema": "https://context7.com/schema/context7.json"
+  "$schema": "https://context7.com/schema/context7.json",
+  "folders": ["docs"],
+  "excludeFiles": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "RELEASING.md",
+    "SECURITY.md",
+    "TEMPLATE_SETUP.md"
+  ]
 }

From 193d46ac94b3905acc774763a04ebc8df3cf1197 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 24 Sep 2026 10:28:02 +0000
Subject: [PATCH 3/3] Fix remaining Context7 review findings

Co-authored-by: palewire <9993+palewire@users.noreply.github.com>
---
 .github/workflows/context7-refresh.yml |  6 +-----
 TEMPLATE_SETUP.md                      |  8 +++++---
 context7.json                          | 13 ++++++++++++-
 3 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/context7-refresh.yml b/.github/workflows/context7-refresh.yml
index b026fdf..761aa52 100644
--- a/.github/workflows/context7-refresh.yml
+++ b/.github/workflows/context7-refresh.yml
@@ -2,16 +2,12 @@ name: Refresh Context7 index
 
 on:
   push:
-    paths:
-      - "context7.json"
-      - "README.md"
-      - "docs/**"
   workflow_dispatch:
 
 permissions: {}
 
 concurrency:
-  group: context7-refresh
+  group: context7-refresh-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
diff --git a/TEMPLATE_SETUP.md b/TEMPLATE_SETUP.md
index 54c061f..49bcb2a 100644
--- a/TEMPLATE_SETUP.md
+++ b/TEMPLATE_SETUP.md
@@ -36,9 +36,11 @@ project's user documentation lives elsewhere.
       provide the requested project and documentation details if the automatic
       quality check does not approve it.
 - [ ] Rely on Context7's usage-based automatic refreshes, refresh manually after
-      important releases, or enable `.github/workflows/context7-refresh.yml` by
-      setting a `CONTEXT7_API_KEY` repository secret and the
-      `CONTEXT7_REFRESH_ENABLED=true` repository variable.
+      important releases, or enable `.github/workflows/context7-refresh.yml`.
+      Once enabled with a `CONTEXT7_API_KEY` repository secret and the
+      `CONTEXT7_REFRESH_ENABLED=true` repository variable, it refreshes after
+      each default-branch push so moving documentation files or folders in
+      `context7.json` does not silently disable automated refreshes.
 
 ## Continuous Integration
 
diff --git a/context7.json b/context7.json
index bb29c81..e5874d8 100644
--- a/context7.json
+++ b/context7.json
@@ -4,11 +4,22 @@
   "excludeFiles": [
     "AGENTS.md",
     "CHANGELOG.md",
+    "CHANGELOG.mdx",
     "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
     "LICENSE",
+    "LICENSE.md",
     "RELEASING.md",
     "SECURITY.md",
-    "TEMPLATE_SETUP.md"
+    "TEMPLATE_SETUP.md",
+    "agents.md",
+    "changelog.md",
+    "changelog.mdx",
+    "code_of_conduct.md",
+    "contributing.md",
+    "license.md",
+    "releasing.md",
+    "security.md",
+    "template_setup.md"
   ]
 }