From 911804f7192aa0ffade946c342696764e4d30ad7 Mon Sep 17 00:00:00 2001
From: Christian Cleberg <hello@cleberg.net>
Date: Sat, 11 Apr 2026 19:41:26 -0500
Subject: chore: update docs

---
 API.md    | 9 ++++-----
 README.md | 4 ++--
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/API.md b/API.md
index eeed574..8d05885 100644
--- a/API.md
+++ b/API.md
@@ -44,8 +44,8 @@ Contribution ranges:
 
 - Contribution read endpoints return zero-filled days, so clients do not need to patch missing dates.
 - Public contribution reads also register the actor for background indexing. A first lookup may therefore return an empty graph while the scheduler catches up.
-- Incremental indexing and historical backfill are separate. An actor can be recently indexed without being fully backfilled yet.
-- The service prioritizes a recent visible history window first, then continues deep-history backfill afterward.
+- Incremental indexing and one-year backfill are separate. An actor can be recently indexed before the retained one-year window is fully filled in.
+- The service only retains and backfills the most recent 365 days of activity.
 
 Background polling:
 
@@ -112,8 +112,7 @@ Behavior notes:
 - This endpoint resolves aliases to a canonical actor before querying data.
 - This endpoint also registers the actor for background indexing and updates the actor's `last_requested_at` timestamp.
 - The response is always immediate; it does not wait for SourceHut polling to finish.
-- Historical backfill runs in bounded background batches and may take multiple scheduler passes to complete.
-- The recent visible window is prioritized before full-history backfill so clients can show a useful graph sooner.
+- One-year backfill runs in bounded background batches and may take multiple scheduler passes to complete.
 
 Example by year:
 
@@ -305,7 +304,7 @@ Response fields:
 Behavior notes:
 
 - Manual polling also updates the actor's indexing metadata.
-- Manual polling also advances historical backfill by one bounded batch per supported service.
+- Manual polling also advances one-year backfill by bounded batches for each supported service.
 - Git polling auto-discovers the actor's owned repositories and unions in any configured tracked repositories.
 
 Possible errors:
diff --git a/README.md b/README.md
index f70f070..656f1c7 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ The current V1 is intentionally narrow and production-oriented:
 
 ## What It Does
 
-The service collects SourceHut activity from one or more sr.ht GraphQL services, turns those records into a canonical event shape, aggregates activity by day, and returns zero-filled calendar ranges so the client never has to patch missing dates. It performs recent incremental polling, prioritizes a recent visible-history window for faster UX, and then continues bounded historical backfill.
+The service collects SourceHut activity from one or more sr.ht GraphQL services, turns those records into a canonical event shape, aggregates activity by day, and returns zero-filled calendar ranges so the client never has to patch missing dates. It performs recent incremental polling, backfills the most recent 365 days for newly requested actors, and prunes older activity from storage.
 
 Example use cases:
 
@@ -165,7 +165,7 @@ Example response:
 }
 ```
 
-Scheduled polling only runs when `ENABLE_SCHEDULER=true`. The scheduler seeds `DEFAULT_ACTOR` as an initial known actor, runs one poll immediately at startup, and public contribution reads register additional actors for later background polling and historical backfill.
+Scheduled polling only runs when `ENABLE_SCHEDULER=true`. The scheduler seeds `DEFAULT_ACTOR` as an initial known actor, runs one poll immediately at startup, and public contribution reads register additional actors for later background polling and one-year backfill.
 
 For `git.sr.ht`, owned repositories are auto-discovered for the actor. `GIT_TRACKED_REPOSITORIES` can still be used to union in extra repositories. Entries may be either:
 
-- 
cgit v1.2.3