fix(docs): regenerate bank-template-schema.json and guard drift

.github/workflows/test.yml

@@ -2547,6 +2547,9 @@ jobs:
     - name: Run generate-openapi
       run: ./scripts/generate-openapi.sh
 
+    - name: Run generate-bank-template-schema
+      run: ./scripts/generate-bank-template-schema.sh
+
     - name: Run generate-clients
       run: ./scripts/generate-clients.sh
 
@@ -2566,6 +2569,7 @@ jobs:
           echo ""
           echo "Please run the following commands locally and commit the changes:"
           echo "  ./scripts/generate-openapi.sh"
+          echo "  ./scripts/generate-bank-template-schema.sh"
           echo "  ./scripts/generate-clients.sh"
           echo "  ./scripts/generate-docs-skill.sh"
           echo "  ./scripts/hooks/lint.sh"

hindsight-dev/hindsight_dev/generate_bank_template_schema.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""
+Generate bank template JSON Schema from the Pydantic model.
+
+This script imports BankTemplateManifest and exports its JSON Schema to
+hindsight-docs/static/bank-template-schema.json.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from hindsight_api.api.http import BankTemplateManifest
+
+
+def generate_bank_template_schema(output_path: str | None = None) -> None:
+    """Generate bank template JSON Schema and save to file."""
+    if output_path is None:
+        # Default to hindsight-docs/static/bank-template-schema.json
+        root_dir = Path(__file__).parent.parent.parent
+        output_path = str(root_dir / "hindsight-docs" / "static" / "bank-template-schema.json")
+
+    schema = BankTemplateManifest.model_json_schema()
+
+    output_file = Path(output_path)
+    with open(output_file, "w") as f:
+        json.dump(schema, f, indent=2)
+        f.write("\n")
+
+    print(f"✓ Bank template schema generated: {output_file.absolute()}")
+    print(f"  - Title: {schema['title']}")
+    print(f"  - Definitions: {len(schema['$defs'])}")
+    print(f"  - BankTemplateConfig fields: {len(schema['$defs']['BankTemplateConfig']['properties'])}")
+
+
+def main() -> None:
+    output = sys.argv[1] if len(sys.argv) > 1 else None
+    generate_bank_template_schema(output)
+
+
+if __name__ == "__main__":
+    main()

hindsight-dev/pyproject.toml

@@ -32,6 +32,7 @@ hindsight-api = { workspace = true }
 
 [project.scripts]
 generate-openapi = "hindsight_dev.generate_openapi:generate_openapi_spec"
+generate-bank-template-schema = "hindsight_dev.generate_bank_template_schema:main"
 generate-changelog = "hindsight_dev.generate_changelog:main"
 sync-cookbook = "hindsight_dev.sync_cookbook:main"
 generate-llms-full = "hindsight_dev.generate_llms_full:main"

hindsight-docs/static/bank-template-schema.json

@@ -143,7 +143,8 @@
           "anyOf": [
             {
               "items": {
-                "type": "string"
+                "additionalProperties": true,
+                "type": "object"
               },
               "type": "array"
             },
@@ -167,6 +168,141 @@
           "default": null,
           "description": "Allow entities outside the label vocabulary",
           "title": "Entities Allow Free Form"
+        },
+        "retain_default_strategy": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of the default retain strategy (key into retain_strategies map)",
+          "title": "Retain Default Strategy"
+        },
+        "retain_strategies": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Map of retain strategy name to per-strategy config dict",
+          "title": "Retain Strategies"
+        },
+        "retain_chunk_batch_size": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Max chunks per streaming batch (0 disables batching)",
+          "title": "Retain Chunk Batch Size"
+        },
+        "mcp_enabled_tools": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "MCP tool allowlist for this bank (None = all tools)",
+          "title": "Mcp Enabled Tools"
+        },
+        "consolidation_llm_batch_size": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "LLM batch size for observation consolidation",
+          "title": "Consolidation Llm Batch Size"
+        },
+        "consolidation_source_facts_max_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Max tokens of source facts per consolidation batch",
+          "title": "Consolidation Source Facts Max Tokens"
+        },
+        "consolidation_source_facts_max_tokens_per_observation": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Max tokens of source facts per observation",
+          "title": "Consolidation Source Facts Max Tokens Per Observation"
+        },
+        "max_observations_per_scope": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Max observations to retain per consolidation scope",
+          "title": "Max Observations Per Scope"
+        },
+        "reflect_source_facts_max_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Max tokens of source facts per reflect call",
+          "title": "Reflect Source Facts Max Tokens"
+        },
+        "llm_gemini_safety_settings": {
+          "anyOf": [
+            {
+              "items": {},
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Per-bank Gemini/VertexAI safety filter settings",
+          "title": "Llm Gemini Safety Settings"
         }
       },
       "title": "BankTemplateConfig",
@@ -362,6 +498,45 @@
           "default": null,
           "description": "Compound boolean tag expressions to use during refresh instead of the model's own tags. When set, these tag groups are passed to reflect and the model's flat tags are NOT used for filtering. Supports nested and/or/not expressions for complex tag-based scoping.",
           "title": "Tag Groups"
+        },
+        "include_chunks": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Override whether the internal recall used during refresh returns raw chunk text. None means use the bank/global config default (recall_include_chunks).",
+          "title": "Include Chunks"
+        },
+        "recall_max_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Override the token budget for facts returned by the internal recall during refresh. None means use the bank/global config default (recall_max_tokens).",
+          "title": "Recall Max Tokens"
+        },
+        "recall_chunks_max_tokens": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Override the token budget for raw chunks returned by the internal recall during refresh. None means use the bank/global config default (recall_chunks_max_tokens).",
+          "title": "Recall Chunks Max Tokens"
         }
       },
       "title": "MentalModelTrigger",

scripts/generate-bank-template-schema.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -e
+
+# Regenerate hindsight-docs/static/bank-template-schema.json from the
+# BankTemplateManifest Pydantic model. This file is the source of truth
+# for Ajv validation in hindsight-docs/scripts/check-templates.mjs and
+# is served verbatim at /bank-template-schema.json on the docs site.
+
+cd "$(dirname "$0")/.."
+
+echo "Generating bank template JSON Schema..."
+cd hindsight-dev
+uv run generate-bank-template-schema
+
+echo ""
+echo "Bank template schema generated successfully!"