# @kentcdodds/lineage — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke checks, snippets, and edge cases. Secrets by **name**
only — never paste secret values. Do not disable live webhooks or jobs.

## Secrets / surfaces

| Name | Kind | Notes |
| --- | --- | --- |
| `githubLocWebhookSecret` | user secret | HMAC for `github-push` webhook (`x-hub-signature-256`) |

- Job: `backfill-missing` (cron `*/30 * * * *`, timezone America/Denver) —
  catch-up only; keep enabled.
- Webhook: `github-push` → `./handle-github-webhook` (`responseMode: ack`).
- Hosted app: `https://kentcdodds.kody.run/packages/lineage`
- Dependency: `@kentcdodds/github`

## Import paths

| Export | Import |
| --- | --- |
| overview | `kody:@kentcdodds/lineage` |
| status | `kody:@kentcdodds/lineage/status` |
| series | `kody:@kentcdodds/lineage/series` |
| settings | `kody:@kentcdodds/lineage/settings` |
| backfill | `kody:@kentcdodds/lineage/backfill` |
| backfill-continue | `kody:@kentcdodds/lineage/backfill-continue` |
| ingest-missing | `kody:@kentcdodds/lineage/ingest-missing` |
| handle-github-webhook | `kody:@kentcdodds/lineage/handle-github-webhook` |
| commentary | `kody:@kentcdodds/lineage/commentary` |
| inspect-commit | `kody:@kentcdodds/lineage/inspect-commit` |
| reset-ingest | `kody:@kentcdodds/lineage/reset-ingest` |
| seed-highlights | `kody:@kentcdodds/lineage/seed-highlights` |
| seed-primitive-story | `kody:@kentcdodds/lineage/seed-primitive-story` |
| record-version | `kody:@kentcdodds/lineage/record-version` |

Prefer static `kody:@kentcdodds/lineage/...` imports from `execute`. Do not lead
with `packages.invoke`.

## Smoke test (read-only)

```js
import status from 'kody:@kentcdodds/lineage/status'

export default async function main() {
	return await status()
	// => { repo, ingest, commentaryCount, recentIngest }
}
```

Optional series read (same numbers the UI graphs):

```js
import getSeries from 'kody:@kentcdodds/lineage/series'

export default async function main() {
	return await getSeries({ mode: 'cumulative' })
}
```

## Common snippets

Backfill a batch (writes storage; safe catch-up):

```js
import backfill from 'kody:@kentcdodds/lineage/backfill'

export default async function main() {
	return await backfill({ limit: 50 })
	// Transient GitHub/CF failures may return { deferred: true }
	// Slow listings stop early with { listingComplete: false, done: false }
}
```

Inspect one commit's file classification:

```js
import inspectCommit from 'kody:@kentcdodds/lineage/inspect-commit'

export default async function main() {
	return await inspectCommit({
		sha: '35878a47ef4aa3567eb6f6b5ea4d3d2c753934b5',
	})
}
```

Attach commentary:

```js
import commentary from 'kody:@kentcdodds/lineage/commentary'

export default async function main() {
	return await commentary({
		sha: 'abc123',
		label: 'Worker split',
		narrative:
			'The monolith was carved into the first dedicated worker package.',
	})
}
```

## Edge cases

- Tracked repo is `kentcdodds/kody` (application source), not `use-kody`.
- Generated / Linguist-generated / `@generated` / `DO NOT EDIT` paths are
  skipped even when committed — use `./inspect-commit` to debug empty buckets.
- Prefer the `github-push` webhook for new main commits; keep
  `backfill-missing` enabled as coarse catch-up. Do **not** disable the webhook
  or job.
- `backfill` / `ingest-missing` may return `deferred: true` on transient
  GitHub/Cloudflare failures instead of throwing — retry on the next tick.
  On the webhook path (explicit SHAs) any per-commit fetch failure is listed in
  `errors` and left for `backfill-missing`, so the delivery still succeeds.
- `./reset-ingest` wipes stored commit buckets so a recount can run after
  ignore-rule changes — confirm before calling.
- `./seed-highlights` and `./seed-primitive-story` are safe to re-run; existing
  SHAs keep current commentary.
- `./record-version` after publish with the published commit for the About view.
- Never paste `githubLocWebhookSecret` values into chat or logs.

## Dependency note

Uses `@kentcdodds/github`, which authenticates via `createAuthenticatedFetch` on the `github-bot` / `github-kent` OAuth integrations (not mirrored `github-*AccessToken` user secrets).