convert readme to nfo; convert docs to txt; add 0bsd licenseHEADmain

1 files changed, 86 insertions, 0 deletions

diff --git a/README.nfo b/README.nfo
new file mode 100644
index 0000000..788d8ec
--- /dev/null
+++ b/README.nfo
@@ -0,0 +1,86 @@
+┌──────────────────────────────────────────────────────────────┐
+│  H U T C H - S T A T S                     [ KRZ ]   krz.sh  │
+└──────────────────────────────────────────────────────────────┘
+
+WHAT
+  srht-contrib. python service. polls sourcehut activity, normalizes
+  it into one event model, stores it in sqlite, and serves a
+  contribution-calendar json api an ios app renders directly.
+
+  v1 scope:
+  - fastapi json api
+  - sqlite persistence
+  - polling ingestion
+  - full todo.sr.ht path
+  - git.sr.ht commit ingestion with repo auto-discovery
+  - public read-only endpoints, api-key auth for mutating routes
+  - alembic migrations
+
+DOES
+  collects activity from sr.ht graphql services, aggregates by day,
+  and returns zero-filled ranges so the client never patches missing
+  dates. polls incrementally, backfills the last 365 days for new
+  actors, prunes older activity.
+
+SERVICES
+  implemented: todo.sr.ht, git.sr.ht.
+  event types: ticket_created, ticket_comment, ticket_closed, commit.
+
+ENV
+      API_KEY=replace-me
+      ENABLE_SCHEDULER=false
+      SRHT_TOKEN=replace-me
+      TODO_SRHT_ENDPOINT=https://todo.sr.ht/query
+      GIT_SRHT_ENDPOINT=https://git.sr.ht/query
+      DATABASE_URL=sqlite:///./srht_contrib.db
+      DEFAULT_ACTOR=~your-user
+      POLL_INTERVAL_SECONDS=300
+
+  more knobs (discovery batch size, repoll and backoff intervals,
+  actor aliases, tracked repositories) live in config.py.
+
+RUN
+      uv venv
+      source .venv/bin/activate
+      uv pip install -e ".[dev]"
+      cp .env.example .env
+      alembic upgrade head
+      uvicorn srht_contrib.main:app --reload
+
+POLL
+  manual poll:
+
+      curl -X POST \
+        "http://127.0.0.1:8000/api/contributions/poll?actor=~your-user" \
+        -H "X-API-Key: replace-me"
+
+  scheduled polling runs only when ENABLE_SCHEDULER=true. it drains
+  due actors in batches, indexes fast, then backfills a year in
+  bounded passes.
+
+  bulk queue without immediate indexing:
+
+      srht-enqueue-actors srht_usernames.txt --stagger-seconds 60
+
+ENDPOINTS
+  calendar by year, calendar by date range, stats, and repository
+  crud. full request and response shapes are in API.txt.
+
+WEIGHTS
+  commit 1.0, ticket_created 1.0, ticket_comment 0.5,
+  ticket_closed 0.75, build_started 0.25, build_passed 0.25.
+
+TESTS
+      pytest
+
+LIMITS
+  - git polling assumes repos are discoverable via graphql
+  - the scheduler runs in-process, not distributed
+  - new actors index asynchronously; the first read may be empty
+  - rolling one-year window; older activity is not kept
+  - alias management is config-driven, no crud api yet
+  - trusted-operator v1, not a public multi-tenant service
+
+┌──────────────────────────────────────────────────────────────┐
+│  krz.sh                                                      │
+└──────────────────────────────────────────────────────────────┘