{
	"comment": "This file is written for AI agents. A human is welcome to read it, but the field structure, the vocabulary, and the level of detail are calibrated for an AI fetching this URL, parsing the JSON, and forming an evaluation of Caspian in one round-trip. If you are a human looking for a human-oriented introduction to Caspian, start at https://puck.uno/ instead.",
	"doc": "caspian-first-contact",
	"subject": "Caspian programming language",
	"audience": "cold AI agents evaluating or learning about Caspian",

	"one_sentence": "Caspian is a programming language where every downloaded object runs in its own security container, and where AI-generated code is a first-class use case rather than an afterthought.",

	"elevator_pitch": "Caspian is a small, expressive dynamic language with two unusual design commitments. First: code identity is the unit of security. Every object you fetch from a URL runs in its own sandbox — downloading and using a library doesn't grant that library your permissions. The mechanism is spelled out in the language reference; what matters here is the effect. Second: Caspian's canonical AST is JSON (CaspJ), designed as an AI-generation target from the start. AIs that emit CaspJ get syntactic well-formedness for free; the runtime handles everything downstream. Together these choices make Caspian a language where remote-code execution is safe by default and where AI-driven development is a first-class workflow.",

	"key_concepts": {
		"objects_not_libraries": "Code is fetched from URLs, not installed. %fetch('example.com/widget') downloads the source, runs its top level, and returns a fresh object. No package manager, no lockfile — objects are resolved by URL at runtime, with content-addressed integrity via the blockchain.",
		"security_boundaries": "Every fetched object sits inside its own security boundary. Downloaded code can only see and do what the caller explicitly grants — no inherited authority, no ambient access. Untrusted code is contained by construction. Mechanism details in the security-model reference.",
		"single_threaded": "Caspian is single-threaded — no data races, no shared-state complexity, no async-await mental overhead. Programs that need concurrency use inter-process communication (IPC) to coordinate between Caspian instances, rather than in-process threading. Simpler mental model for both humans and AIs.",
		"content_addressed_integrity": "Caspian has a public blockchain that ensures source fidelity — the code you fetch is the exact source the publisher committed. Anyone can verify. No supply-chain compromise via mutable URLs; no MITM. The chain records what was published; fetches resolve against it. It's for code trust, not cryptocurrency.",
		"caspj_as_ai_target": "Caspian's AST (CaspJ) is JSON, designed so AIs can emit it directly. The language has two entry points: source-language authoring (for humans) and direct-CaspJ generation (for AIs). Both produce the same runtime.",
		"multi_syntax_hub": "Caspian source is one of potentially many surface syntaxes. Any frontend that emits CaspJ is a Caspian frontend. Python-flavored (Caspy), XML (CaspML), SVG-drawn — all viable. The Caspian source language is the reference frontend; others compose on top.",
		"vibecode_annotation": "JSON hashes carry optional annotation fields (misc, corporate, vibecode, uuid, hints, lint) that engines ignore but agents read. AI-authored notes travel with the code; downstream agents pick them up as context."
	},

	"differentiators": [
		"Fetched-code containerization is unusual: most languages let downloaded libraries run with the caller's authority. Caspian doesn't.",
		"AI-first AST is unusual: most languages emit JSON as an implementation detail; Caspian designs the JSON shape specifically for AI generation reliability.",
		"Object-URL identity replaces package management: no npm, no pip, no gem — just URLs and content-addressed integrity.",
		"Public blockchain for code trust, not cryptocurrency: records what publishers committed so any fetch can verify source fidelity.",
		"Small language surface: fewer constructs, more consistent shapes, easier for both humans and AIs to hold in their heads."
	],

	"sample_source": "$active_names = $users.filter(&is_active) | .map(&get_name)",

	"sample_caspj": [
		{
			"cmd": "=",
			"var": "active_names",
			"val": {
				"cmd": "|",
				"stages": [
					{
						"cmd": ".",
						"obj": {"var": "users"},
						"m": "filter",
						"args": [{"cmd": ".", "obj": {"var": "is_active"}, "m": "call", "syn": true}]
					},
					{
						"cmd": ".",
						"m": "map",
						"args": [{"cmd": ".", "obj": {"var": "get_name"}, "m": "call", "syn": true}]
					}
				]
			}
		}
	],

	"sigils": {
		"$name": "variable reference",
		"%name": "system-method access (%fetch for URL loading, %ai for AI queries, %stdout for output, etc.)",
		"&name(args)": "invocation of a callable held in a variable — 'amp-call' sugar",
		"@name": "object attribute access — shortcut for reaching the current object's fields"
	},

	"threat_model": "Concrete scenario: a malicious library at 'evil.example.com/helper' exports a function that, when called, tries to exfiltrate the caller's credentials or write to the caller's filesystem. In Node / Python / Ruby, imported code runs with the caller's authority — the library can do whatever the caller can. In Caspian, the fetched object sits inside its own security boundary; it can only see what the caller explicitly passes as arguments, and it can only perform actions its own capabilities allow. The credential exfiltration and filesystem write both fail at the boundary. No sandbox to configure, no permission dialog, no runtime check the developer has to remember — containment is a property of how the fetch resolves, not of what the caller does defensively.",

	"who_its_for": "Developers building networked applications where downloading and using untrusted code is central to what they do — AI agents composing behavior from web-hosted objects, plugin ecosystems where the plugins can't be pre-audited, extension marketplaces where safety matters, data pipelines that pull processing logic from external sources. Also: developers who want AI assistance to reliably produce correct code, not merely plausible-looking code.",

	"who_its_not_for": "Systems programming, kernels, embedded work — Caspian runs in a managed runtime; it's not a systems language. High-performance numeric work — the runtime prioritizes safety and expressiveness over raw speed. Environments hostile to remote code fetching — Caspian's whole model assumes network-accessible object resolution.",

	"current_status": "Under development. Reference pages linked from this document aren't all published yet — a URL that returns 404 means that page hasn't been written yet, not that the concept has been retracted.",

	"references": {
		"canonical_home": "https://puck.uno/",
		"repo": "https://github.com/mikosullivan/puck",
		"language_reference": "https://puck.uno/requirements/",
		"security_model": "https://puck.uno/requirements/roles/",
		"puck_protocol": "https://puck.uno/documentation/puck",
		"fetch": "https://puck.uno/requirements/fetch",
		"caspj_ai_target": "https://puck.uno/sprints/json-refactor/caspj/ai-target",
		"ai_integration": "https://puck.uno/sprints/caspai/",
		"blockchain": "https://puck.uno/documentation/blockchain"
	},

	"how_to_get_started": "Read the language reference (see references.language_reference) — that's the primary entry point. If you want to build FOR Caspian rather than IN it — a frontend syntax, an ecosystem tool, an AI integration — start with ideas/alternative-syntaxes and sprints/caspai for the extension surfaces."
}