# The shelf

> The shelf is a lightweight, per-workspace jobs board curated with Kin. It holds work that is larger than the current turn's todos: a future rock can stay local for a later session or run on Outpost from its own git br…

The shelf is a lightweight, per-workspace jobs board curated with Kin. It holds
work that is larger than the current turn's todos: a future rock can stay local
for a later session or run on Outpost from its own git branch.

<!-- SOURCE: .gitignore, src/kin/harness/defaults/skills/shelf/SKILL.md, src/kin/harness/defaults/commands/shelf.md, src/kin/harness/shelf.py, src/kin/harness/session/core.py, src/kin/harness/loop.py, src/kin/tui/shelf_watch.py, src/kin/tui/attention.py, src/kin/tui/turn_lifecycle.py, src/kin/tui/app.py, src/kin/harness/settings/, settings.toml.example -->

## Outcome

Park a self-contained job as `.kin/shelf/<slug>.md`, see what is ready or
blocked, and later pick it up from the card alone. Outpost jobs return on
`shelf/<slug>` with their own verified return brief committed into the card.

## Fast path

1. Run `/shelf park <idea>` and review the proposed rock-sized card.
2. Run `/shelf` or `/shelf board` to groom blockers and choose what is ready.
3. Use `/shelf pickup <slug>` for local work, or `/shelf submit <slug>` for an
   Outpost run.
4. When a remote branch returns, use pickup. Kin reads the card on the branch,
   summarizes it in its own words, and verifies git history, the diff, and every
   Done-means item before merging.
5. Use `/shelf recover <slug>` only when a submitted card is overdue.

## Cards are durable cursors

Frontmatter carries `status`, `lane`, `branch`, optional blockers and Outpost
identity. The body records Intent, checkable Done means, durable Context
pointers, and an append-only Trail. The bundled `shelf` skill contains the
canonical template.

For an Outpost lane, the final branch commit must update its own card with
status `done` or `stuck`, the standard Return brief, and verification evidence.
Kin refuses to merge a branch that omits that evidence. Git is the work-product
channel and the completion-notification channel; no GitHub pull request is
required.

## Awareness without polling

On each root turn, Kin sees a compact board hint only when the tracked cards
changed. In the TUI, a background watcher checks the fixed
`refs/heads/shelf/*` refspec every 120 seconds and correlates submitted cards
with the existing 45-second Outpost attention snapshot. It adds no Outpost API
traffic.

A new branch raises one informational toast and a metadata-only reminder. If
Kin is idle, it quietly announces the change and offers pickup; it never starts
the job without you. Branch appearance means only that the remote job believes
it is done—the pickup verification remains mandatory. Delivery is at least once
across TUI restarts, with card status as the durable deduplication cursor.

Set `shelf_enabled = false` (or `KIN_SHELF_ENABLED=0`) to disable board hints
and the watcher. `shelf_watch_interval` / `KIN_SHELF_WATCH_INTERVAL` changes the
git probe cadence with a 30-second minimum; it is read once when the TUI mounts.

## Sharing `.kin/shelf`

Most `.kin/` state is machine-local. Shelf cards are the exception. A repo that
ignores `.kin/` must use:

```gitignore
.kin/*
!.kin/shelf/
```

Git cannot re-include a directory beneath a blanket `.kin/` ignore. Kin proposes
this change during first-time initialization but never makes it silently.

## Reference

- [Beam work to Outpost](/docs/kin/guide/beam/)
- [Skills](/docs/kin/guide/skills/)
- [Slash commands](/docs/kin/guide/slash-commands/)
- [Decision record 0133](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0133-the-shelf.md)