Concepts

Gills defines compact, plain-text App views shared by browser and terminal hosts. It owns the row wire format, Gill declarations, bounded requests and responses, and an authenticated-fetch client. Your host owns admission, navigation and read-method admission.

Core concepts

• A declaration records the Gill’s App-local identity, source read method, optional placement parameters and their options read methods, change feed and desktop sizes. Agar generates it from the backend; Puffball includes it in the Release digest.
• A request contains a view ID, placement parameters and optional source cursor. The host admits the method and Computer before invoking the App.
• A response is an empty page, a full page of text rows, or an error. A request with options: <parameter key> returns a choice page instead. decodeDeclaredGillResponse rejects another view’s identity.
• A row carries display text and optional navigation parameters. The host opens the Gill’s own App; that App interprets the parameters. Rows cannot name a different App, a URL, or a Session-specific target. Navigation values retain up to 4,096 characters, including a Computer file path; display shortening never changes navigation values.
• Optional row.status carries the App’s plain label and semantic tone for a compact status indicator. The App maps its state; the host does not infer it.
• An error can offer recovery: { kind: "configure", param: "computer" } or recovery: { kind: "open" }. Configure must name a declared parameter and opens that placement’s existing picker. Open uses the host’s launcher for the same App. Neither form contains an App ID, URL or command. App names and icons remain host directory presentation, outside this wire.