zcode: freeFirst, the plain model spends the account's gift first

packages/zcode/README.md

@@ -134,6 +134,44 @@ plan's own in-flight cap (3008/3009) does not: such a request is asked
 again instead (see [A few at once](#a-few-at-once)). A stream's body is
 never read or buffered on the way.
 
+**Free first.** Picking `-Trial` by hand keeps the choice the user's,
+but an agent that always asks the plain model never sees the gift.
+`freeFirst` turns the preference around: the plain model spends the
+account's own live gift first, and falls back to the coding plan when
+the gift cannot serve it — a bucket that is spent, a model the gift
+does not serve, no ZCode session, or the minute's rest a refusal just
+earned. Turn it on for the whole plugin in magpie's Plugins › Options
+
+```json
+{ "freeFirst": true }
+```
+
+or on the provider alone, under `provider.zcode.options` in the config
+magpie hands its plugins — a key only `plugins.json`'s `config` carries,
+so the plugin's own options are the ones magpie's Plugins › Options
+edits. Where both say something, the provider's word stands. An account
+with a coding plan and a gift spends the gift until it is spent, then
+the plan; a gift-only account already goes to the gift by its plain
+names, so the option changes nothing there. Across the accounts magpie
+rotates, each spends its own gift before its own plan — which is the
+point: free allowance is spent before subscribed quota, on every
+account, with no per-account naming to keep up.
+
+Two boundaries worth knowing. The gift is judged before the request is
+sent, from the balance read the plugin keeps for ten minutes: a gift
+that runs out between that read and the send has its refusal answered
+from the plan in the same request — any gift failure is, its own
+waited-out busy cap included, and the replay waits out the plan's busy
+cap as any plan request does — and a spent answer or a block page rests
+the model a minute and drops the route's balance read, so the requests
+behind it go straight to the plan. A gift that cannot be asked at all —
+the network, the host — is answered from the plan the same way, the
+route read dropped for the next request, while a caller's own abort
+stays an abort. The agent sees the plan's answer
+either way. And the `-Trial` entries keep their own strict semantics —
+asking one is still an explicit pick of the gift alone, never the plan;
+a spent one answers 429 with freeFirst on, as it does without it.
+
 ## A few at once
 
 A plan serves one account a few requests at a time; past that, ZCode