sema: Instructions file for Codex

AGENTS.md — Sema (Lisp with LLM primitives, in Rust)

Canonical instructions for any coding agent working in this repo. CLAUDE.md just points here.

Shipping invariant — NO dev-checkout assumptions in shipped code (HARD RULE)

A shipped sema (crates.io / cargo install, a cargo-dist archive, the shell installer, or Homebrew) runs on a machine that has none of: this git repo, jake, npm/node/wasm-pack, gitignored-or-generated build artifacts, or the maintainer's absolute paths. Any user-facing behavior that depends on those is a shipped bug, not a dev convenience. This is non-negotiable. It already happened once: sema web shipped telling users to run jake wasm.web-runtime because its runtime assets were gitignored and a build.rs file-existence check silently compiled the feature out. It must never recur. Enforced rules:

• Anything a shipped command needs at runtime MUST be a git-tracked package input embedded at build time (include_str! / include_bytes! / rust_embed over a tracked path). cargo package ships only git-tracked files, so never include_*! a gitignored or build-generated path — the .crate would lack it. If a jake recipe generates the artifact, commit the generated output (don't .gitignore it), and verify it embeds the whole directory (prefer rust_embed/include_dir over a hand-maintained file list that can drift).
• build.rs must NEVER change what compiles based on file existence, an env var, or the network. Path::new(...).exists() gating a rustc-cfg is true in your tree and false from a packaged .crate → a silently reduced binary. Use an unconditional include_*! (a missing input then fails the build loudly) or an explicit, documented Cargo feature — never an implicit file-presence gate.
• No runtime path may point into the source tree. env!("CARGO_MANIFEST_DIR"), env!("OUT_DIR"), and repo-relative reads (examples/, website/, Jakefile, …) are fine in tests/ and build.rs (they run from the checkout) but forbidden in shipped runtime code. Resolve companion binaries via std::env::current_exe(), not repo layout.
• Never emit a user-facing message telling an installed user to run jake, make, cargo build, npm, or otherwise assume they have the repo. If a feature can be absent, degrade with an action the end user can actually take.
• Shelling out to a dev tool (jake, cargo, npm, node, wasm-pack, vercel) from a shipped code path is a bug. git is acceptable only where it is the feature's inherent prerequisite (sema pkg, git stdlib bindings).