# brettschiff.tools — agent guide

Personal mini-tool library by Brett Schiff. Human UI at https://brettschiff.tools/.
This file documents the machine-facing contracts. Deep customization rides in JSON
config files; the site UI stays minimal by design.

## Sift — https://brettschiff.tools/sift

Local-first triage: a deck of cards the user flicks into buckets, one at a time.
ALL data stays on the user's machine (browser storage + local disk). Agents exchange
work with the user through a local folder — never through the network.

### Prepare a task (agent → user)

1. Write a folder anywhere on the user's machine:
     <folder>/sift.json          the manifest (schema below)
     <folder>/...                the files it references (any layout; relative paths)
2. Hand the user this link (Chromium browsers; opened directly, not in an IDE preview):
     https://brettschiff.tools/sift?path=<absolute folder path>
   The page displays the path, copies it for them, and guides them through granting
   folder access with the browser's picker. Fallback for any browser: they can drag
   the folder onto the page.

### Read the results (user → agent)

When the user says they're done, read:
     <folder>/sifted/sift.json
Same schema, with each item's bucket / tags / note filled in. Classification only —
files are not moved, copied, or renamed; src still points at the originals. Item ids
are preserved exactly, so correlate by id.
The user may instead PASTE the sift.json contents directly into the conversation —
Sift has a one-click "Copy sift.json" button. Accept either channel.

### sift.json schema (v1)

{
  "sift": 1,
  "buckets": [                        // optional: preconfigure the sort
    { "label": "Keep", "dir": "right", "color": "#22c55e" },
    { "label": "Toss", "dir": "left" }
  ],                                  // dir ∈ left|right|up|down; one bucket per dir
  "tags": ["favorite", "redo"],       // optional: seed the tag tiles (keys 1–9)
  "options": {                        // optional
    "skip": "down",                   // direction bound to Skip; null = Space only.
                                      // default "down" (yields if a bucket claims it)
    "allowEdits": true,               // inline field editing
    "titleField": "name",             // card headline field
    "visibleFields": ["name", "take"],// fields shown on cards (default: all)
    "groups": {                       // group-compare routing (see below)
      "winners": "Keep",              // bucket label for picked members
      "losers": "Toss"                // bucket label for the rest
    }
  },
  "items": [
    {
      "id": "sfx-001",                // your correlation id — echoed back in results
      "kind": "audio",                // text | image | audio | file
      "src": "takes/sword-1.wav",     // path relative to the folder (media kinds only)
      "fields": { "name": "sword clash — take 1", "effect": "sword clash" },
      "bucket": null,                 // or a bucket label, to pre-sort this item
      "tags": [],
      "note": ""
    }
  ]
}

Deal order = items order (group related items consecutively). Fields are free-form
strings shown on the card. Audio: wav/ogg/mp3. Images: svg/png/jpg/webp/gif.
Buckets can also carry "autoTags": [...] and "set": {"field": "...", "value": "..."}
(applied to items dropped into them).

GROUP-COMPARE: give items a "group" field (a plain field-name convention — works in
any format, including a CSV `group` column). Items sharing a group value deal as ONE
card showing every member side by side; the user picks a winner (arrow keys when the
group has ≤4 members, click always) — winner goes to options.groups.winners, the rest
to options.groups.losers (defaults: first/second bucket). Groups may be any size,
managed entirely by the JSON author. Space skips a whole group; picks are one undo
step. This is the shape for "generate N takes per thing, keep one of each".

### Interaction model (what the user experiences)

One card at a time. Swipes / arrow keys map to the claimed directions (buckets and
Skip); Space always skips (recirculates the card); keys 1–9 toggle tags (on a group
card they tag the whole group); N adds a note. Design pick-one-of-N choices as
GROUPS (the "group" field, above) — that is the intended shape for take-selection
tasks. Plain keep/toss sweeps work best as two direction buckets.

### Other exchange formats

ZIP round trip also works: hand the user a .zip containing sift.json + files (they
drop it on the page); their "Download" returns a .zip of bucket folders + updated
manifest. Use the folder + task-link flow when you can — it needs no downloads.

## Other tools

No public write APIs anywhere on this site. Tools are static pages; the ULC area is
private and auth-gated — do not probe it.