feat: index storage backend (cache default, PR opt-in)

action.yml

@@ -73,6 +73,10 @@ inputs:
     description: 'Path to a Markdown style configuration file (.md) containing documentation style guidelines. If not set, auto-detects .code-to-docs/style.md in the repository root.'
     required: false
     default: ''
+  index-storage:
+    description: 'How to persist semantic indexes: "cache" (Actions cache, default), "pr" (open a PR to main), or "none" (no persistence)'
+    required: false
+    default: 'cache'
 
 outputs:
   status:
@@ -104,3 +108,4 @@ runs:
     GOOGLE_SA_KEY: ${{ inputs.google-sa-key }}
     MAX_CONTEXT_CHARS: ${{ inputs.max-context-chars }}
     STYLE_CONFIG_PATH: ${{ inputs.style-config-path }}
+    INDEX_STORAGE: ${{ inputs.index-storage }}

src/doc_index.py

@@ -814,19 +814,59 @@ def update_indexes_if_needed():
     return updated_folders
 
 
+_CACHE_MANIFEST_PATH = "/tmp/code-to-docs-index-cache"
+
+
+def save_indexes_to_cache():
+    """Save indexes to a well-known path for Actions cache restore."""
+    docs_root = get_docs_root().resolve()
+    index_path = docs_root / INDEX_DIR
+    if not index_path.exists():
+        print("No indexes to cache")
+        return False
+    cache_dir = Path(_CACHE_MANIFEST_PATH)
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+    shutil.copytree(index_path, cache_dir)
+    print(f"Indexes saved to cache path: {_CACHE_MANIFEST_PATH}")
+    return True
+
+
+def restore_indexes_from_cache():
+    """Restore indexes from the Actions cache path if available."""
+    cache_dir = Path(_CACHE_MANIFEST_PATH)
+    if not cache_dir.exists():
+        return False
+    docs_root = get_docs_root().resolve()
+    index_path = docs_root / INDEX_DIR
+    if index_path.exists():
+        shutil.rmtree(index_path)
+    shutil.copytree(cache_dir, index_path)
+    print(f"Indexes restored from cache ({_CACHE_MANIFEST_PATH})")
+    return True
+
+
 def commit_indexes_to_repo(content_type="indexes"):
     """
-    Commit the .doc-index folder and open a PR to the base branch.
+    Persist the .doc-index folder using the configured storage backend.
 
-    Instead of pushing directly to main (which bypasses branch protection),
-    this pushes to a persistent branch and creates/updates a PR.
+    The INDEX_STORAGE env var controls the backend:
+    - "pr" (default): push to a branch and open a PR
+    - "cache": save to a well-known path for Actions cache
+    - "none": skip persistence
 
     Args:
         content_type: What's being committed - "indexes", "summaries", or both
 
     Returns:
-        bool: True if content was committed and PR created/updated, False otherwise
+        bool: True if content was persisted, False otherwise
     """
+    storage = os.environ.get("INDEX_STORAGE", "pr").lower()
+    if storage == "none":
+        print(f"Index storage disabled (INDEX_STORAGE=none), skipping {content_type} persistence")
+        return False
+    if storage == "cache":
+        return save_indexes_to_cache()
     docs_root = get_docs_root().resolve()
     index_path = docs_root / INDEX_DIR
 
@@ -1244,14 +1284,17 @@ def checkout_docs_from_base_branch():
 
 def fetch_indexes_from_main():
     """
-    Fetch indexes and summaries from the main/base branch.
+    Fetch indexes and summaries from cache or the main/base branch.
 
-    This ensures PRs can benefit from cached indexes and summaries on main,
-    even if they were generated by previous PR runs.
+    Tries the Actions cache path first (when INDEX_STORAGE=cache), then
+    falls back to fetching from the git branch.
 
     Returns:
         bool: True if indexes/summaries were fetched, False otherwise
     """
+    if restore_indexes_from_cache():
+        return True
+
     docs_root = get_docs_root().resolve()
 
     # Determine target directory and relative path