# @kody/lineage ## Intent Give Kent (and anyone who forks it) an interactive, commit-level look at countable lines in a GitHub repo — by default `kody-hq/kody`, not `use-kody`, which has no application source. The app should ignore generated output even when that output is committed (Wrangler types, lockfiles, `generated/` trees, Linguist-generated paths, and `@generated` / `DO NOT EDIT` headers), store the series in this package's storage, and stay useful offline as an installable PWA. Success is a graph you can slice by time, language, and type (source / tests / docs), with linked commits and short labels that open a longer narrative. ## What it does - Hosted chart app with cumulative, added/removed, and net-per-commit modes - Backfill and ingest helpers write commit buckets into `packageStorage()` - GitHub push webhook fills new `main` commits as they land - Commentary helpers attach short labels and longer narratives to commits - Status / series / inspect helpers for agents and the UI to share the same numbers ## Prerequisites / setup 1. Tracked repo defaults to `kody-hq/kody` on `main` (override via `./settings` without republishing). 2. The `github-push` webhook uses package-owned HMAC (`x-hub-signature-256`): Kody stores the signing secret on the minted webhook URL, and `webhookUrlApply` writes it into the GitHub hook. No user secret to create. 3. Depends on `@kody/github` for GitHub API access used by ingest / backfill. 4. Prefer event-driven webhook ingest; the `backfill-missing` cron (every 30m, America/Denver) is catch-up only — do not disable live webhooks or jobs. 5. Hosted app: https://lineage--kody.kody.run/ 6. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths and smoke checks. ## Commits or dates on the x axis The **X axis** control under the chart switches between **Commits** (the default: every commit gets the same width) and **Date** (a linear time scale, so busy days spread out and quiet stretches show as gaps). Link the date view with `?xaxis=date`, e.g. . It combines with `?labels=off`. ## Hiding the labels The **Labels** toggle under the chart hides the story markers and their text (the chart data stays the same). Labels are on by default. To link or screenshot the chart without them, add `?labels=off` to the app URL, e.g. . ## Make it yours (forking) Lineage works for any GitHub repository the GitHub connection can read. Kent's copy keeps charting `kody-hq/kody`; a fork changes a few settings. **What to change** — everything owner-specific is in one file, `src/config.ts`: - **Repository** — `defaultRepo` (owner, repo, branch). You can also switch repos later without republishing by calling the `settings` export; a stored setting always wins over the default. - **GitHub account** — `@kody/github` has one `github` credential slot. Map it to a read-only GitHub connection (a bot account is enough) with a default credential mapping on this package. - **Branding** — app name, description, and theme colours under `branding`. The icons and preview image live in `src/ui/art/`. - **Hosted address fallback** — `fallbackHostedOrigin` / `fallbackAppBasePath`, only used if Kody does not provide them. - **Story annotations** — `src/annotations.ts` holds the labelled kody milestones. They only match commits in `kody-hq/kody`, so empty or replace the list for your repo, or add your own labels later with `commentary`. **Credentials you need** - A **GitHub connection** (OAuth) through your own fork of the public `@kody/github` package. Read-only access to the repo is enough. Kody packages can't import across accounts, so fork that package too and point Lineage's import and `kody.dependencies` at your copy. - No webhook secret to create: the `github-push` webhook uses package-owned HMAC that Kody stores when you mint the webhook URL. **Point it at your repo** 1. Fork this package (and `@kody/github` if you are outside the kody org), then edit `src/config.ts`. 2. Publish your fork and mint its `github-push` webhook URL. 3. In your GitHub repo, add a webhook for **push** events pointing at your fork's `github-push` webhook URL with its signing secret (`webhookUrlApply` does both without showing either), then click Approve to turn it on. 4. Run a backfill once (or wait for the 30-minute catch-up job) and open your fork's hosted app. ## Done when - Hosted app loads and shows a countable series for the tracked repo (`kody-hq/kody` for Kent) - `./status` reports stored commits; webhook or backfill fills gaps - Generated files stay out of countable totals; commentaries open from chart labels