From d3811433fcd41d7381ef4814be3f007d542b317a Mon Sep 17 00:00:00 2001
From: Albert Mavashev <amavashev@k2n.io>
Date: Sat, 16 May 2026 05:19:16 -0400
Subject: [PATCH] chore: migrate installs-cache from `docs` to `cycles-docs`
 after repo rename
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The org repo `runcycles/docs` was renamed to `runcycles/cycles-docs`.
`.vitepress/theme/installs-cache.json` still keyed the cached clones
(count: 16064) and releases (0) under the old name. Without this
migration, the next run of `installs.data.ts` (build-time loader) or
`scripts/update-github-counts.mjs` (scheduled refresh) would have
silently double-counted ~14 days of clone activity on the renamed
repo:

  1. `listOrgRepos()` returns the live list, which now contains
     `cycles-docs` (not `docs`).
  2. For `cycles-docs`, the cache lookup falls back to the default
     `{ count: 0, lastSeenDay: '' }` (or `'1970-01-01'` in the script).
  3. All 14 days in the `/traffic/clones` API window pass the
     `day > cached.lastSeenDay` check, so a fresh `cycles-docs` entry
     is seeded with 14 days of clones in one bulk addition.
  4. The old `docs` key is preserved by `{ ...cachedByRepo }` because
     nothing iterates removed keys. It becomes a zombie entry frozen
     at count=16064.
  5. The aggregate `clones` field = sum of all entries = old `docs`
     count + freshly seeded `cycles-docs` count, double-counting the
     overlapping 14 days.

This patch migrates the keys directly in the cache so the next loader
run reads `cycles-docs` from a populated entry (with the correct
lastSeenDay cursor) and only accumulates new days. No re-seed, no
zombie key, no double-count. The aggregate `clones` field (70541) is
unchanged because the key was renamed, not the value.

The displayed total (`total: 13319`) was not affected by this bug
because clones are explicitly excluded from the displayed total per
installs.data.ts:511. Only the homepage clones counter (cache.clones)
was at risk.

Releases migration is cleanup-only: the cached `docs` value was 0, so
no double-count, but removing the zombie key keeps the file tidy.

## Follow-up consideration

The script has no rename-detection mechanism. If another repo is
renamed in the future, the same bug recurs. Two options worth thinking
about:

1. A `REPO_RENAMES` map in `update-github-counts.mjs` that migrates
   cached entries from old to new names at the start of each run.
   Manual maintenance, but the safest approach.
2. An auto-prune step that drops cached keys not in the current
   `listRepos()` result. Dangerous — a temporary API failure or a
   repo briefly archived could wipe legitimate cached state.

Recommend option 1 if rename frequency increases; for now, a one-off
data migration is sufficient.
---
 .vitepress/theme/installs-cache.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.vitepress/theme/installs-cache.json b/.vitepress/theme/installs-cache.json
index 8efb51b..0e93f76 100644
--- a/.vitepress/theme/installs-cache.json
+++ b/.vitepress/theme/installs-cache.json
@@ -48,7 +48,7 @@
       "count": 1552,
       "lastSeenDay": "2026-05-14"
     },
-    "docs": {
+    "cycles-docs": {
       "count": 16064,
       "lastSeenDay": "2026-05-14"
     },
@@ -90,7 +90,7 @@
     "cycles-agent-action-authority-demo": 0,
     "cycles-openai-agents": 0,
     "cycles-client-python": 0,
-    "docs": 0,
+    "cycles-docs": 0,
     "cycles-client-typescript": 0,
     "cycles-openclaw-budget-guard": 0,
     "cycles-server-events": 0,