ci: add automated star history chart

Keep README growth data self-hosted and resilient when detailed GitHub stargazer history is unavailable.

docs/STAR_HISTORY.md

@@ -0,0 +1,57 @@
+# Star History Chart
+
+BookOrbit renders its README star-history chart in the repository instead of
+depending on an external chart service.
+
+## Storage
+
+The `star-history` branch contains two generated files:
+
+- `star-history.json`: validated daily aggregate counts and source metadata
+- `star-history.svg`: the self-contained README chart
+
+The workflow creates normal commits on this branch. It does not force-push, so
+previous chart data remains recoverable without adding automated commits to
+`main`.
+
+The bootstrap snapshot at `scripts/star-history/bootstrap.json` contains the
+initial exact aggregate history. It is used only when the publication branch
+does not exist. Raw stargazer records and GitHub usernames are never stored.
+
+## Refresh behavior
+
+The `Star History` workflow runs daily and can also be dispatched manually.
+It restores the stored series, obtains the current repository star count,
+replaces any existing point for the current UTC date, renders the SVG, and
+publishes the JSON and SVG in one branch commit.
+
+The built-in workflow token is sufficient for daily snapshots. An optional
+`STAR_HISTORY_TOKEN` repository secret belonging to a collaborator enables
+exact-history refreshes from GitHub's timestamped stargazer endpoint. Exact
+refreshes replace the aggregate curve and correct any drift from previous
+snapshots. If the endpoint is unavailable, the workflow retains the stored
+history and falls back to the current count.
+
+The generator refuses malformed series, data for a different repository,
+future points, invalid API responses, and exact histories beyond GitHub's
+pagination limit. A failed run publishes nothing.
+
+## Local commands
+
+Run the focused test suite:
+
+```bash
+pnpm run test:star-history
+```
+
+Generate from a stored series and the current count:
+
+```bash
+GITHUB_TOKEN=... node scripts/star-history/generate.mjs \
+  --repo bookorbit/bookorbit \
+  --series star-history.json \
+  --bootstrap scripts/star-history/bootstrap.json \
+  --out star-history.svg
+```
+
+Set `STAR_HISTORY_TOKEN` as well to attempt a complete exact-history refresh.