sky: Instructions file for Codex

AGENTS.md

Agent-agnostic guide for AI tools (Claude, Copilot, Cursor, Codex, …) working in the Sky repository. It is the source of truth; tool-specific files layer on top of it (Claude Code reads CLAUDE.md, which imports this file and adds Claude-Code-only operational rules).

Progressive disclosure. This file is deliberately lean. It teaches the language, the app-building decisions, and the non-negotiable rules, then points you at two authoritative, always-current sources for depth:

• sky doc <Module> — the live stdlib API (typed signatures + summaries + examples), generated from the stdlib source, so it never drifts. Prefer it over any hand-copied API table. sky doc --list enumerates every module; sky doc --serve opens a browsable server.
• docs/ — deep dives (architecture, Sky.Live, Std.Db, Std.Ui, auth, tooling). The map is in the Deep dives table below.

What Sky is

Sky is an Elm-family, purely-functional language that compiles to typed Go. One language for the whole stack: web UIs (Sky.Live), HTTP/JSON APIs, CLIs, TUIs, desktop apps, background jobs. The design goal is "if it compiles, it works" — no user-written FFI, no nulls, no silent wrong answers, and no runtime panic from well-typed code, clear errors, batteries-included stdlib.

The one honest carve-out: partial arithmetic primitives fail LOUDLY, never silently. A well-typed 10.0 / 0.0 has no answer Sky can represent (there is no Inf/NaN shape), so it raises a classified DivisionByZero — recovered per-request to a 500 in a server, or exit(1) + a structured log in a CLI — and is caught by the whole-app panic net (docs/architecture/sky-stdlib-correctness.md §2.9; classifyPanic in runtime-go/rt/panic_recover.go names the eleven panic classes). It is never a silent wrong value (integer ///% by zero are total and return 0, matching Elm). Json.Encode.encode of a NaN or infinite Float fails the same way, as a classified JsonEncodeFailure, never an empty string, and Decimal.toInt / toMinor / Money.toMinor past the 64-bit Int range (or Decimal.toFloat past the Float range) fails as a classified NumericOverflow, never a wrapped number. Code that divides by a value it does not control should zero-guard the divisor; a fallible Maybe-returning division is an offered convenience, not a soundness requirement. "No runtime panic" therefore means no UNCLASSIFIED panic and no silent corruption — the property a service actually needs.