Stories row, notifications, offline, LAN¶
Stories row (SPEC §7.4)¶
GET /api/stories → {"stories": [Story]}, one per configured repo that has commits in the last 24 hours (wall clock), newest first:
{"repo": "storefront", "mascot": "otter", "mascot_image": "/assets/mascots/otter.png?v=<mtime>" | null,
"commits": [{"sha": "<full>", "short": "abc1234", "ts": 1700000000, "author": "Alice Archer", "subject": "Fix ...", "files": 3}],
"seen": false}
git log --since=@<now-86400> on the repo ref (via gitq), cached per repo head sha.
- seen is true when every commit sha was already viewed: POST /api/stories/seen {"repo", "shas": [...]} records them (table story_views(repo, sha, seen_at)).
- The web shows a horizontal row of circles (mascot image or initial) at the top of the feed; unseen repos get a colored ring. Tapping opens a full-screen story viewer: one commit per page (subject, author, time, files count, short sha), tap right/left to move, swipe down or ✕ to close; viewing marks shas seen.
Notifications (SPEC §7.5)¶
Table notifications(id, kind, text, card_id, created_at, read_at) (exists). Generated by a server pass (in the learning worker loop, or its own worker) and gittok notify:
- new_cards: "12 new cards from storefront" once per finished run with accepted > 0 (link: feed).
- srs_due: "2 quiz cards are back for another try" when due SRS cards exist and no unread srs_due notification exists. The dedup key is a hash of the sorted due card ids, so it fires once per distinct due set.
- hot_file: at most one per repo per UTC day, from the same commits used for stories. Files touched by ≥3 commits in the last 24 h count; paths under dot-directories (.github/, .claude/) do not. One file gives "auth.py was in 3 commits in the last 24 hours"; several give a digest, "Busy day in storefront: brief.py (11 commits), cli.py (10), api.py (7) and 4 more". Deduplicated on (repo, date).
- new_kind: "A new Spot the Bug from billing/" when a card with story_type spot_the_bug lands (link: card). Only cards created in the last 24 hours count.
- Dedup key per notification so passes are idempotent.
GET /api/notifications?unread=1 → {"notifications": [{"id", "kind", "text", "card_id", "created_at", "read"}], "unread": n}; POST /api/notifications/read {"ids": [...]} | {"all": true}. The web shows a bell with the unread count in the top bar and a /notifications list; tapping one with a card opens /card/{id}.
PWA and offline (SPEC §11)¶
web/static/manifest.webmanifest(name "GitTok", short_name, theme/background colors,display: standalone, icons 192/512 generated as PNG from an SVG at build time or committed), linked fromapp.htmlwithapple-touch-iconandtheme-colormetas.- A hand-written service worker (
web/src/sw.ts, built intosw.jsbyweb/scripts/build-sw.mjsand registered from the layout when'serviceWorker' in navigator): precache the app shell (build assets list) and cache-first for/assets/*images; network-first with cache fallback forGET /api/feed(the last successful batch is served offline) and/api/cards/*; never cachePOSTs; queuePOST /api/eventswhile offline and replay on reconnect (Background Sync when available, else on next load). - An "Offline — showing your last batch" banner when the feed came from cache.
LAN access¶
- LAN serving is on by default (
server.lan: true), because the feed is made for a phone.gittok serveandgittok mcp --uibind0.0.0.0and print the LAN URL(s) (first non-loopback IPv4 of each interface) next to the localhost URL.server.lan: falseinlocal/settings.yaml, or--no-lan, binds127.0.0.1. An explicit--hostis used as given;--lanforces LAN serving. - The feed goes over plain HTTP.
docs/install.md, "Phone access", says what that means on a network you do not trust. - The feed is token-protected. A LAN bind creates (or reuses) a random token in
<data_dir>/lan_token(mode 0600). A paired device holds it in an HttpOnly, SameSite=Lax cookiecs_lan(long expiry). The token is never in a page, a link or a log line. - Pairing is by code only. The page for an unpaired device has a "Pair with a code" button:
POST /pair/codemakes a request in thepair_requeststable, sets an HttpOnly cookiecs_pairwith the request's secret id, and redirects to/pair/wait. That page shows a six-character code (no characters that look alike) and loads again every 3 seconds (/pair.js, a file of the server, because the CSP allows no inline script; a meta refresh when scripts are off). The user tells the agent "pair code ...", and thepair_deviceMCP tool (orgittok pair <code>) approves it in the database. The next load of/pair/waitsetscs_lanand redirects to/. A code lasts 10 minutes and works once; at most 20 codes wait at the same time, and at most 3 for one device address (429 after that). A device that asks again with itscs_paircookie gets its waiting code back. Only a code that the user types approves a request: a device on the network can ask for codes but cannot approve one. An app on the home screen keeps its own cookies and pairs inside the app the same way; the web app's "not paired" message has the same button. - The feed address. The SessionStart line
gittok url --hintgives it at the start of each session, and thefeed_addressMCP tool gives it on request ("pair my phone", "what is the feed address?"): the addresses where the running server answers, from a TCP connect to each one, and thenoticeabout LAN serving. Theset_lanMCP tool writesserver.lan; the server must then start again. - Requests from non-loopback peers need the cookie, except
/pair/code,/pair/wait,/pair.js(the Copy button of the wait page: "pair code XXXX-XX", with anexecCommandfallback because plain HTTP has nonavigator.clipboard) and the app icons and manifest (api.APP_ICON_PATHS: a phone takes the home-screen icon from what it can fetch when the user adds the app, and these files hold no user data). The pairing pages link the icon and the manifest too. Without it,/api/*returns 401 JSON and other paths return a small page with the "Pair with a code" button. Loopback peers never need the cookie. The token is compared in constant time. - The feed server has no MCP endpoint. The MCP server speaks stdio only, to the session that started it.
- Request bodies are limited to 1 MB (413).
POST /api/stories/seentakes at most 100 shas, each 7-40 hex characters.POST /api/eventstakes at most 500 events, and each eventdatamust be 4 KB or less as JSON. - PWA install and offline mode need HTTPS: service workers do not register on plain-HTTP LAN origins. The feed still works in the browser over HTTP. GitTok serves plain HTTP only;
docs/install.md, "HTTPS on a LAN", has two untested recipes with a second program. settings.server.hostis127.0.0.1by default; it is the bind address when LAN serving is off. A non-loopback--host(orserver.hostwithserver.lan: false) is token-protected too: the server makes the token, and devices pair by code as on the LAN.- Host allowlist (DNS rebinding). Every path (
/api/*,/assets/*,/pair, the web app) answers only when theHostheader, with or without a port, is127.0.0.1,localhost,[::1], one of this machine's LAN IPv4 addresses, its host name (also the short name and<short name>.local), or a name insettings.server.allowed_hosts(a list, empty by default; use it for a VPN name or an IPv6 address). Any other or missingHostgets 421. The address list is read again after 30 s, and at most each 2 s when an unknown Host arrives, so a new LAN address works without a restart. - Origin check. A
POST,PUT,PATCHorDELETEwith anOriginheader whose host is not in the same allowlist, or whose scheme and port differ from the request (the Vite dev port 5173 on a loopback name is the one exception; a proxied request is checked by host only), gets 403. A request withoutOriginpasses. - Response headers on every response:
X-Content-Type-Options: nosniff,Referrer-Policy: no-referrer(same-originon the page for an unpaired device and on/pair/wait: withno-referrera browser posts the "Pair with a code" form withOrigin: null, which the Origin check refuses), and aContent-Security-Policy:default-src 'self'; script-src 'self' 'wasm-unsafe-eval' <sha256 of each inline script in the built index.html>; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; worker-src 'self'; manifest-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'. The server computes the script hashes fromindex.html(again when the file changes), so the web build needs no CSP config.'wasm-unsafe-eval'is for the code highlighter's WebAssembly regex engine;'unsafe-inline'styles are for highlighted code and diagrams. - The uvicorn access log shows
/pair?[redacted], never the token.
Characters that carry¶
- Pages:
/persona/<handle>(avatar, name,biofrom personas.yaml or the voice, recent posts, recent comments) and/file/<repo>/<path>(commit count, last touched, top authors, cards that cite the path in sources, visual, depth panels oraccount). API:GET /api/personas/{handle},GET /api/files/{repo}/{path}. - Card headers and comment names link to those pages; a code-account poster links to its file page.
- Follow:
POST /api/follows {repo, path, on}. Follows are stored in theprefstable underfollowed_paths. A follow shapes generation: the brief ranks the leads in the dir of a followed path (the path itself if it has no file extension) higher, bylead_score.followedin reward.yaml. The feed does not reorder cards that exist. - Comments: the card face shows two comments with avatars. On quiz cards a comment is a spoiler
(hidden until answered) unless it sets
spoiler: false. - Cast notes:
get_packetreturnscast_markdown, each packet persona's last 3 hooks or comments (trimmed), at most 800 bytes. Writers call back to running jokes. - Series:
seriesisnullor{key, part, of}. The face shows a "Part n/of" chip. The slotter holds a part back while an earlier part is unseen, orders parts, and spaces themSERIES_GAP(3).