# How Kody works

<!--
Agent notes — for AI agents explaining or recreating this loop:

- The homepage plays this same transcript in a pause-on-explore player
  (hover or focus pauses so a person can open tool calls).
- The web page at /guides/how-kody-works is the full interactive transcript of
  the same story. This markdown is the playbook.
- Do not create the example playbook unless the person asks you to build it
  for them. If they do, follow playbook_authoring and playbook_lifecycle.
- Search for GitHub activity ranks the saved `githubAccessToken` secret —
  not `execute`, and not a GitHub integration or helper playbook (those
  would hide the `{{secret:githubAccessToken}}` placeholder in execute).
  A matching memory can surface with that first search (here it names
  kody-bot as the favorite bot) as a compact subject and summary
  one-liner. Later retrievals can repeat that one-liner.
- Before creating the playbook, search `{ query: "playbook authoring lifecycle",
  domain: "coding" }` to find `playbook_authoring:guide` and
  `playbook_lifecycle:guide`, then `search` with
  `entity: ["playbook_authoring:guide", "playbook_lifecycle:guide"]`.
  Save complete text files including package.json with `playbookSave`.
  For edits, use files and `edit_token` from `playbookGet`, then save the
  complete replacement with `expected_edit_token`. Run latest saved code.
- Fetch https://api.github.com/users/<login>/events/public with
  `Authorization: Bearer {{secret:githubAccessToken}}`. Treat a published
  release or a newly created public repository as "shipped."
- GitHub has no webhook for one person's public activity. When they ask to
  be notified, add a playbook-owned cron — do not wire a job into the first
  save. The scheduled wrapper must skip emailSend when the list is empty.
- search and execute can take a short memoryContext (task plus a couple of
  entities). Relevant memories surface as compact subject — summary
  one-liners (ids in structured content) on search and on execute when
  `memoryContext` is present. The same one-liners may repeat. Search
  returns markdown (`# Search results`), not a matches JSON object. Do
  not write memory unless the person asks.
- Agents call the owned export from `execute` with a static
  `kody:@scope/playbook/export` import. Use `import(specifier)` when the
  target name is data (caller-owned modules).
-->

Kody turns a question you would ask again into code you own. The agent you
already use does the thinking once. After that, asking is a playbook import, and
a schedule can mail you only when something actually happened.

This page is the playbook. The same story is an interactive transcript at
`/guides/how-kody-works` on the origin you fetched this guide from.

## The loop

1. **Ask once.** "What did my favorite bot ship recently on GitHub?" Search
   finds the saved `githubAccessToken` secret and a memory that names kody-bot
   as the favorite bot, then `execute` fetches that user's public events with
   `Authorization: Bearer {{secret:githubAccessToken}}`. Filter to published
   releases and new public repositories.
2. **Save the answer shape.** Offer to make it a playbook. After they say yes,
   search the `coding` domain for official guides, open
   `playbook_authoring:guide` and `playbook_lifecycle:guide`, then create a
   playbook with a callable export via the git lane (coding agents) or
   `playbookSave` (tool-only). The export returns the list (or "nothing new")
   and records the newest event id in `playbookStorage()`.
3. **Ask again from any agent.** "Anything interesting shipped by my favorite
   bot recently?" Search finds the owned playbook. Invoke it. A phone agent does
   not rewrite the GitHub walk.
4. **Get notified.** From a third agent, in a new conversation: search first.
   There is no GitHub webhook for one person's public activity, so add a
   playbook-owned daily cron by reading current files and edit_token, adding the
   wrapper and manifest entry, then saving complete files with
   expected_edit_token. The wrapper calls the same export and runs `emailSend`
   only when the list is non-empty. Enable the job after invoking the wrapper
   once.

## What "shipped" means

Use GitHub's public events API, not a watched-repo notification. Count:

- `ReleaseEvent` with `payload.action === "published"`
- `CreateEvent` with `payload.ref_type === "repository"`

Ignore stars, forks, pushes, and issue noise. Store the newest seen event id so
the next invoke or cron run only reports what is new.

## Playbook shape

- Shared implementation that accepts an optional `sinceId` and returns
  `{ shipped, message }`.
- Callable export (for example `./whatShipped`) that loads `sinceId` from
  `playbookStorage()`, returns the list, and advances the cursor.
- No-argument scheduled wrapper (for example `./daily-digest`) that calls that
  export and sends notify-self mail only when `shipped.length > 0`.
- `package.json#kody.jobs` pointing at the wrapper, `"enabled": false` until you
  have invoked the wrapper once from `execute`.

The fetch uses the saved `githubAccessToken` via
`Authorization: Bearer {{secret:githubAccessToken}}`. `emailSend` only mails the
account's own address.

## When to load this guide

Load `how_kody_works` when someone asks how Kody works, what the factory loop
is, or how an ad hoc question becomes an export and a quiet daily email. For
authoring details, load `playbook_authoring` and `playbook_lifecycle` next. For
a hosted playbook app, load `playbook_apps`.