# index/

Per-entity state pointers, fetched by sessions at session-start per
METHODOLOGY.md "Session lifecycle". Path convention:

```
index/<kind>/<id>.md
```

where `<kind>` is one of `equipment`, `customer`, `property`, `personal`, `meta`
(per the five-field opener in METHODOLOGY.md), and `<id>` matches the entity's
canonical id used elsewhere in the repo (e.g. `lt180`, `seadoo-gtx-di-2001`).

## Purpose

The index file is the **session-start summary** — what a fresh chat needs to
know to resume work without rederiving context. It is **not** a handoff block
(those live at `handoff-blocks/<id>-<date>.md` and capture per-session
narrative state). The index is higher-level: it points at the most recent
handoff, the current guide version, and the open items.

When a session ends, two things update:

1. A handoff block lands at `handoff-blocks/<id>-<date>.md` (per session, immutable).
2. The index file at `index/<kind>/<id>.md` updates to point at the new
   handoff, bump the guide version if applicable, and reflect open items.

The handoff is the snapshot; the index is the cursor. Sessions read the index
to know which handoff to fetch.

## Format

```markdown
---
id: <entity-id>
kind: <equipment | customer | property | personal | meta>
display_name: <human-readable name>
current_guide: <relative path, or "none">
current_guide_version: <integer, or 0 if not rendered>
guide_status: <verified | in-progress | not-started | deprecated>
last_session: <YYYY-MM-DD, or "none">
latest_handoff: <relative path, or "none">
---

# <display_name>

## Current state

<One paragraph. What is known, what stage the work is at, what was last
done. Should let a fresh session know whether to dive into open work or
catch up on prior decisions first.>

## Open items

<Bulleted list. Pending parts, pending verification, awaiting third-party
input, etc. Empty if none.>

## Pointers

- Latest guide: `<path or "none">`
- Versioned guides: `guides/<id>/` (browse for history)
- Handoff blocks: `handoff-blocks/<id>-*.md` (most recent linked above)
- Diagnostic logs: `guides/<id>/diagnostic-logs/` (DHLs, if any)
- Architecture: `architecture/pending/` (open DRs touching this entity)
```

## Update cadence

Sessions update their index file as the last step of session-end, alongside
or just after committing the new handoff block. If a session ends without
producing a handoff (early termination, no substantive work), the index
should still update `last_session` so the cursor isn't stale.

## Why this exists

Without an index, a fresh session has to discover state by listing the
handoff-blocks directory, sorting by date, fetching the most recent, and
inferring the guide version from the latest filename in `guides/<id>/`.
Each of those is a fetch the session has to perform before it knows what
it's working on. The index collapses that to one fetch.