AGENTS.md: number rules, errors as feedback, and the working method

AGENTS.md

@@ -58,6 +58,36 @@ cargo insta review                       # Interactive review of pending snapsho
 - Never discard errors.
    - If an error is impossible in practice, the program must still panic if it occurs.
    - When an error is deliberately ignored, a comment must say why.
+- No silent fallback. A parse that yields a default on failure (`parse().unwrap_or(0)`,
+  `as i64` on a float) is a bug: `printf '%d' 0xff` printing `0` is the shape to refuse.
+  Return an error that names the value and the fix.
+
+### Number rules
+
+`$(( ))` is where kaish reads a number in another base and does checked 64-bit integer
+arithmetic. `docs/LANGUAGE.md`, "Arithmetic" is the contract; these are the decisions
+behind it:
+
+- Base spellings are bash's: `0xff` and `base#digits` (base 2 to 36). `0b101` and
+  `0o17` are errors that name `2#101` and `8#17`. Add a spelling only after a model
+  panel shows models writing it.
+- A leading zero is text (`007`, `0644`). Where kaish needs a number — `$(( ))`,
+  `[[ -eq ]]`, `test`, a loop count, a list index — it is an error naming `8#10`,
+  `10`, or `10#$x`. kaish never answers octal or a third number.
+- An integer literal must fit in 64 bits; overflow, division by zero, an unset
+  variable, an empty `$(( ))`, and assignment inside `$(( ))` are errors, never
+  wraps or zeros. A string is a value, never an expression.
+- `fromjson` parses JSON and nothing else; it is also the string-to-number coercion
+  (`fromjson 1e3`). `printf %x` / `%o` format the other direction; `$(random --max N)`
+  replaces `$RANDOM`.
+
+### Test a theory before building it
+
+A claim about what models or users will write is measurable. Before adding syntax, a
+spelling, or a shortcut on their behalf, hand a few cheap kaibo casts or subagents the
+proposed help text and a task list, and count what they produce. Keep one syntax until
+the count says otherwise. The same loop works for an error message: show the message,
+ask for the next command, and see whether it lands.
 
 ### Code style
 
@@ -114,6 +144,10 @@ change, **drawn from the conversation with the user**. The commit message is whe
 the narrative of agent and user can be persisted. A useful commit message will
 remind us how we got to the code it contains. The code can speak for itself.
 
+Write it as a clinical engineering narrative: the problem, the evidence, the decision,
+the rule now in force. Design stories, plans, review transcripts, and model-panel
+results live in agent memory outside the repo, and a commit never references them.
+
 ## Architecture
 
 The kernel is the unit of execution. Multiple frontends can connect to the same kernel:
@@ -232,6 +266,11 @@ Errors that face users, agents, and models must not leak internals. Internal cod
 and references will be unresolvable and should only be exposed for assertions and errors
 that indicate a real problem in kaish.
 
+An error is feedback, not a problem. A model that reads `` write `10#$m` `` gets it right
+next turn; a silent coercion teaches nothing. When the choice is between degrading quietly
+and refusing with the fix named, refuse. Keep the text clinical: the value, the rule in
+a few words, the fix.
+
 ### Published builtin text
 
 A `///` comment on a builtin argument is published to agents. `params_from_clap` copies