Bee Box documentation · directory: https://beebox.run/docs/concepts/ · index: https://beebox.run/docs/concepts/index.md · root: https://beebox.run/llms.txt

# Triage

**Status:** current operational guide. The earlier design exploration, including
superseded artifact shapes and unbuilt proposals, is preserved as
triage design history.

The intake → triage → handle pipeline sorts items arriving in
`_content/inbox/`. Each stage is observable in the filesystem and can be run
independently.

## Pipeline

1. `bbx intake` prepares top-level inbox items, including filename
   normalization, then moves ready items through `_content/inbox/intake/` to
   `_content/inbox/staged/`.
2. `bbx triage` classifies each staged item from the box's triage destinations
   and moves it into `_content/inbox/triaged/<category>/`.
3. `bbx handle` runs each category's procedure over that category's bucket. The
   procedure decides the item's final location or action.

These commands are not automatically chained by wakeup. Run the stage required
for the work at hand; an item left between stages remains available to the next
run.

## Define a category

A triage category is a landmark card whose `destinations` frontmatter contains
an entry with `for: [triage]`. That entry supplies the category rules and its
handler procedure. Triage discovers these landmark entries across the box; it
does not use a separate central registry.

```yaml
destinations:
  - for: [triage]
    rules: Receipts and purchase confirmations.
    procedure:
      ref: /_config/procedures/file-receipts.procedure.card
```

The holding-bucket category name is derived from the landmark directory's last
path segment, sanitized to safe filename characters. The box root uses `root`;
later collisions gain a parent-directory prefix. It is not derived from the
destination's card type. The older `<triage-destination>` and `<navigation>`
XML shapes are not current.

## Confidence and review

The triage agent assigns exactly one confidence level:

- `confident` routes the item to its category bucket with no review marker.
- `probable` routes the item to the bucket and writes a `.probable.txt` marker
  beside it for spot-checking.
- `guess` leaves the category unset, moves the item to
  `_content/inbox/triaged/_unsure/`, and creates a question card. The question
  carries both the immediate placement directive and, when known, the durable
  learning proposal.

There is no numeric confidence score and no `wrong` level. Question batching,
a generated decision tree, and automatic updates to category rules are not
implemented.

## Handler contract

`bbx handle` invokes a category's procedure once for its bucket. The current
implementation attempts to put the box-relative item paths in the
`TRIAGE_ITEMS` environment variable separated by NUL bytes. Environment
variables cannot transport embedded NUL bytes, so this contract is currently
broken for a live multi-item procedure invocation. Do not write a handler that
depends on parsing this value until the runtime transport is fixed. This guide
records the defect rather than presenting the intended shell recipe as usable.

A handler moves or removes every item it successfully finishes. Leaving an item
in the bucket keeps it visible for a later run.

The command reports its worst bucket outcome:

- exit `1` when a handler procedure fails;
- exit `3` when work completed but review reached no verdict, with an
  `Inconclusive: handle <category> — …` line on stderr;
- exit `0` only when every bucket that ran was judged.

## Implementation owners

- `src/core/intake.ts` — intake paths and advancement
- `src/core/triage/index.ts` and `src/core/triage/routing.ts` — category
  discovery, classification, routing, markers, and guess questions
- `src/core/handle.ts` — handler invocation and exit semantics
- `src/core/docs-gen/triage.ts` — the corresponding guide shipped to box agents