@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.4

package/.build-stamp

@@ -1 +1 @@
-91f5ad2ee63550b2ce4eee3fe99b7d2f064b37381641718bf796f2f31987b905
+b129370a860bac06e3d96a976bd13d89caf64cc7a00d87d4adde5461f7179cf5

package/guidelines/agentRule/agentRule.instruction.md

@@ -121,6 +121,24 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   reader produced**, not on the file that was picked: a reader that uploads and answers a `url` has already paid
   what the ceiling exists for, so refusing its 6 MB photo would refuse it for a cost it does not incur. Only the
   built-in path checks the source size, and there the file itself is the carrier.
+- **An app may also build attachments itself and hand them to `session.send([{ role: "user", text, attachments }])`**,
+  which is why `MessageAttachment` is exported from `akanjs/ui` — the composer's path is typed by the `AttachReader`
+  callback, that one is not, and an object assembled with no nameable type is the one that gets a field wrong.
+  Nothing downstream trusts the result: an attachment whose `mimeType` is not a string is noted like any other
+  unreadable one, and its chip renders its name with no preview, because the host wrote the object and the declared
+  type is a claim rather than a check. A field that arrives wrong costs that attachment, never the turn.
+- **A `url` carrier is an address the *provider* fetches, so a reader that uploads has to know its storage is
+  reachable.** This is the one way an attachment fails with nobody reporting it: the default storage backend
+  serves a path only the app can resolve, the adaptor hands it over as written, and the model answers about a
+  picture it never saw. Answer `data` when the provider cannot reach the URL — the choice is the reader's,
+  because the reader is what chose to upload.
+- **An image type the provider has no block for is refused at the adaptor, not upstream.** `accepts.image` is one
+  boolean, so `AgentService.readable` passes every `image/*` through, and the built-in composer reader base64s
+  every `image/*` as well — an `AttachReader` answering `null` means "not mine" and falls through to it, so an app
+  cannot gate one either. Both shipped vision adaptors therefore match an exact set (`jpeg`, `png`, `gif`, `webp`)
+  and name the rest in the text. It matters because an unsupported type is not one unread attachment: it is a
+  block the API refuses, so the **whole turn** dies on a vendor 400 — and `image/heic`, the iPhone camera default,
+  is the likeliest one an app meets.
 - **`MessageAttachment.ref` is the host's own handle on the file — carried, never read.** A file id, a storage key,
   whatever turns the attachment back into something a tool can be handed. The framework only moves it: the model is
   never shown one, and a tool the app publishes (`useFileFieldTool` below) is what spends it. Without it a host that

package/guidelines/conventions/conventions.instruction.md

@@ -727,6 +727,7 @@ what every developer must know even when not building one.
 - Put display and predicate logic on the `Light<Model>` class rather than in a util module — see Module File Playbook.
 - Defaults are a literal for scalars and a thunk for anything constructed. Arrays are `field([T])`; optional is the postfix `.optional()`.
 - **`field.visual(T)` is a field the page renders and an agent never sees** — a blur placeholder, a rendered HTML body, a serialized geometry. It stays an ordinary stored `property` (persistence, search, forms and the page response untouched) and is stripped wherever a value is masked for an AI caller: every in-page-agent read and every MCP result, along with the MCP readable schema. Unlike `hidden`/`secret` it is cost, not secrecy — nothing is refused over one. Reach for it whenever a field is bulky and useless to a model; that is cheaper than every tool learning to avoid it.
+- **A `field.hidden` / `field.secret` value reads `null` on the client, and the type still declares it.** `SignalContext.resolveReturn` skips both field types while it builds an endpoint's response, and hydration writes `null` over the key rather than leaving it absent — the first branch of the loop in `constant/getDefault.ts`, ahead of the field's own default. So the value is a deliberate `null` behind a type promising a `string`, every use of it typechecks, and the failure lands wherever it is finally dereferenced instead of where it was read. **Guard with `??` or `== null`**: `=== undefined`, a destructuring default and an optional parameter default all catch only a missing key and sail straight past this one. A projection (`pickById(id, { secret: true })`) widens the *server's* read, never the response. If a screen needs the value, the field is neither hidden nor secret; if it only needs to be cheap for a model rather than unseen, that is `field.visual`.
 
 ### Scalar & Field Type Reference
 

package/guidelines/fieldRule/fieldRule.instruction.md

@@ -9,6 +9,7 @@ Use this whenever generating constants or scalar constants. It defines the curre
 - `field(Type).optional()` marks a nullable or optional business value when absence is valid.
 - `field.hidden(Type).optional()` is for internal state that should not be treated as a normal public field.
 - `field.secret(Type).optional()` is for sensitive values that should not be selected by default.
+- Neither survives an endpoint response: both are stripped on the way out and hydration writes `null` over the key, while the generated type still declares the field — so a client holds a deliberate `null` behind a type that promises a value, and only `??` / `== null` catch it. A field a browser has to read is neither.
 - `field([Type])` defines arrays; provide empty array defaults when the app expects list operations.
 
 ## Current Akan Patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -33,7 +33,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.2",
+    "akanjs": "3.0.0-beta.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",