Lookup index auto-invalidates on KB updates + manual rebuild flag

Diego asked: does the persisted ``archcenter-refs-index.json`` auto-
update when the KB is updated? Partially — mtime on the cache root
catches add/remove of subdirs (POSIX), but NOT changes to files
INSIDE existing subdirs (description.md added, .drawio replaced).

Two fixes:

1. Both KB-update tools now ``touch`` ``kb/diagram/assets/archcenter-refs``
   when they finish a run that produced changes:
   - ``archcenter_description_fetcher.py`` after fetched > 0
   - ``archcenter_zip_downloader.py`` after downloaded / extract /
     overwrite events
   The touch bumps the parent mtime, which the next lookup detects
   and uses to rebuild its persisted index. Closes the silent-drift
   case where description.md fetches landed but the index didn't
   notice.

2. ``archcenter_pattern_lookup.py --rebuild-index`` flag — escape
   hatch for manual KB edits (someone replaces a cached .drawio by
   hand) where neither tool ran. Removes the stale index file before
   the lookup, forcing a cold rebuild.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

kb/diagram/assets/archcenter-refs-index.json

@@ -1,5 +1,5 @@
 {
-  "cache_dir_mtime": 1777161774.8360987,
+  "cache_dir_mtime": 1777171058.9167857,
   "entries": {
     "active-data-guard-far-sync-dba-oracle": {
       "drawio": "kb/diagram/assets/archcenter-refs/active-data-guard-far-sync-dba-oracle/active-data-guard-far-sync-dba.drawio",

tools/archcenter_description_fetcher.py

@@ -169,6 +169,16 @@ def main() -> None:
         print(f"  {s:25s}  {n}", file=sys.stderr)
     print(f"\nReport: {args.report.relative_to(PROJECT_ROOT)}", file=sys.stderr)
 
+    # Bump CACHE_DIR mtime so archcenter_pattern_lookup invalidates its
+    # persisted JSON index — POSIX doesn't propagate child-file changes
+    # (e.g. new _description.md inside an existing slug) to the parent
+    # dir's mtime, so we touch it explicitly.
+    if counts.get("fetched"):
+        try:
+            CACHE_DIR.touch(exist_ok=True)
+        except OSError:
+            pass
+
 
 if __name__ == "__main__":
     main()

tools/archcenter_pattern_lookup.py

@@ -402,7 +402,15 @@ def main() -> None:
                         "before scoring (opt-in; requires "
                         "ANTHROPIC_API_KEY). Useful for natural-language "
                         "queries the synonym table doesn't cover.")
+    parser.add_argument("--rebuild-index", action="store_true",
+                        help="Force-rebuild the cached archcenter-refs "
+                        "index (kb/diagram/assets/archcenter-refs-index.json). "
+                        "Use after a manual KB edit if mtime didn't bump.")
     args = parser.parse_args()
+    if args.rebuild_index and CACHE_INDEX_FILE.exists():
+        CACHE_INDEX_FILE.unlink()
+        print(f"[lookup] removed stale index at {CACHE_INDEX_FILE.relative_to(PROJECT_ROOT)}",
+              file=sys.stderr)
 
     queries: list[str] = list(args.queries)
     if args.query:

tools/archcenter_zip_downloader.py

@@ -211,6 +211,16 @@ def main() -> None:
         print(f"  {status:30s}  {n}", file=sys.stderr)
     print(f"\nReport: {args.report.relative_to(PROJECT_ROOT)}", file=sys.stderr)
 
+    # Bump cache-dir mtime so the pattern-lookup index invalidates.
+    # New downloads create new subdirs (POSIX bumps the parent mtime),
+    # but re-downloads or unzip-overwrites of existing slugs do not —
+    # so we touch explicitly.
+    if any(counts.get(k) for k in ("downloaded", "zip_error", "no_drawio_after_extract")):
+        try:
+            args.cache_dir.touch(exist_ok=True)
+        except OSError:
+            pass
+
 
 if __name__ == "__main__":
     main()