# transient/ — per-call context

This directory holds call-specific context files that callers drop in *before* sending an althing message to Heid. Codex reads these on demand when the message body references them.

## When to use

Drop a transient context file when:

- The call needs to review a specific diff, contract draft, or hypothesis file — and the file would be larger or more sensitive than belongs in the althing message body.
- The caller has already gathered prior-art (search results, paper abstracts, prior probe data) that Heid should treat as authoritative for this call without re-deriving.
- The call is part of a thread where Heid needs context from earlier turns that aren't in the bus's thread history.

Don't use transient files for:

- Durable context that should live in `CONTEXT.md` / `INVENTORY.md` — extend the durable file instead.
- One-line questions where the message body is sufficient.
- Context that's already in a project repo at a known path — point Heid at the path; she can read the repo.

## Convention

### File naming

`transient/<slug>.md`

`<slug>` is short, kebab-case, distinctive enough that the althing message can reference it unambiguously: `r07-h04-substrate-question`, `sleipnir-pr-42-review`, `worldtree-issue-177-spec-draft`.

If multiple files are needed for the same call, use a directory: `transient/<slug>/{diff.patch, contract-draft.md, prior-art.md}`.

### File format

Plain markdown for prose; raw text / patch format / JSON for non-prose payloads. No required frontmatter. If frontmatter helps the caller organize, the convention is:

```markdown
---
caller: <handle>
call_id: <althing-msg-id-if-known>
shipped_at: <ISO-8601>
expires_after: <call-completion | YYYY-MM-DD | never>
---
```

`expires_after: call-completion` is the default — the caller is responsible for cleanup after Heid replies.

### Referencing from the althing message

In the message body:

```
Load transient context: <slug>
```

Or, more naturally inline:

```
Please review the diff in transient/sleipnir-pr-42-review.md — verdict + must-fix only.
```

Both forms work. Heid looks for the file at the cited path, reads it, treats it as authoritative for the call.

If the message references a transient slug that doesn't exist, Heid surfaces that rather than guessing.

## Cleanup

Transient files are caller-owned. **The caller is responsible for removing the file after Heid replies** — either immediately, after they've consumed the response, or on a TTL.

If transient files accumulate (someone forgot to clean up), the operator may run a cleanup pass. A `.gitignore` on this directory keeps the files out of version control; only this README is tracked.

## What's tracked vs ignored

- `transient/README.md` — this file, version-controlled.
- `transient/*` (everything else) — gitignored.

The directory is a working surface, not a durable archive. If a call produces context that turns out to be durable (a pattern Heid should know about long-term), promote it: extend `CONTEXT.md` / `INVENTORY.md` / one of the role guides, then delete the transient file.