Island manifest (theme)

An island is laid out and painted from one declarative file. It is the same manifest a self-hosted island serves signed at https://<domain>/.well-known/acre-island.json (signing and the other fields), version 0.3, with a theme block. For an island on ACRE, its hosts apply it unsigned: in Island settings → Theme, or with the island_manifest_apply MCP tool (with your agent).

The server renders deterministically from the manifest and its seed. There is no model and no image generation. Images come only from the addresses (or inline PNGs) in the manifest: each is read once through ACRE’s network guard (https only, public addresses only, every redirect checked), painted again as pixel art under the brand limits, and kept by its content hash.

The JSON Schema is served at /schemas/acre-island.json ($id: https://useacre.dev/schemas/acre-island.json). Validation names every problem by its JSON path, for example /theme/landmark must be one of: server-tower, rocket-pad, ….

Top level

Field	Required	Rule
`$schema`	no	`https://useacre.dev/schemas/acre-island.json`
`acre`	yes	`"0.3"`
`name`	no	Up to 60 characters. Read from a self-hosted island’s manifest; an island on ACRE keeps its own name.
`oneLiner`	no	Up to 140 characters
`skin`	no	`{ "color", "logo", "banner" }`: the brand colour and images. `theme.logo` wins over `skin.logo`.
`theme`	no	How the island is laid out and painted (below). No other fields are allowed in it.

The theme block

Land

Field	Values	Notes
`shape`	`classic`, `valley`, `crescent`, `twin`, `archipelago`, `peak`, `atoll`	The silhouette. Classic is round; valley is long with a river and lake; crescent has a bay and falls; twin is two isles and a bridge; archipelago is three islets; peak is a terraced plateau with cliffs; atoll is a ring round a lagoon.
`size`	`small`, `medium`, `large` (`xl` for a Pro team island)	Capped by the plan: a venture’s tier, and the classic shape is Medium only. A size over the cap is refused with a warning and the island keeps its size.
`seed`	0 to 2147483647	The same shape, size and seed always lay out the same land.
`water`	`auto`, `none`, `river`, `lake`, `falls`, `lagoon`, `canals`	When no `shape` is named, picks one: river or lake → valley, falls → crescent, lagoon → atoll, canals → archipelago, none → classic.
`elevation`	`auto`, `flat`, `hills`, `cliffs`, `terraced`	When no `shape` is named: cliffs or terraced → peak, flat → classic.
`streets`	`winding`, `grid`, `radial`, `boardwalk`	Winding dirt paths; a paved grid town; a radial plaza ring round the camp; planks.

A new shape or size never removes anything placed. Anything that would end up in the water, off the island or in someone’s way moves to the nearest lot that holds it, by the same rule a placement is judged by, and the apply says how many moved. If something has nowhere at all to stand, the land change is refused (the rest of the theme still applies).

Look

Field	Values	Notes
`biome`	`meadow`, `autumn`, `blossom`, `frost`, `dunes`, `volcanic`, `swamp`, `canyon`, `crystal`, `skygarden`, `neon`, `forest`	The base ramps and what grows. `neon` is a night city, `dunes` a desert.
`palette`	`{ primary, accent, ground, water, roof, path }`, each a hex colour	Each becomes a hand-shaded ramp that replaces the biome’s own (shadows lean blue, lights lean gold), never a hue rotate. Each is clamped into the range pixel art reads in and snapped to 4-bit channels; paths are pushed apart from the ground until they read (1.6:1). Leave any out to keep the biome’s.
`vegetation`	`auto`, `oak`, `pine`, `palm`, `cactus`, `crystal`, `cherry`, `birch`, `none`	What stands on the tree spots.
`landmark`	`server-tower`, `rocket-pad`, `vault`, `lab-dome`, `studio`, `observatory`, `greenhouse`, `factory`, `lighthouse`, `arcade`	One signature building at the plaza, drawn in pixel art in your colours.
`decor`	`none`, `lanterns`, `market`, `garden`, `rocks`, `tech`, `neon`	A loose ring of pieces round the plaza.
`tagline`	up to 80 characters	Shown with the island’s name.

Logo and images

Field	Rule
`logo`	An `https://` address of a PNG, or `data:image/png;base64,…`. At most 256 KB. Never SVG (JPEG and WebP are not read: publish a PNG). Painted again as 16, 32 and 64 px tiles.
`banner`	The same rules; painted to fit 64 × 32.
`flag`	The same rules; painted to fit 24 × 16 as the dock flag’s cloth. Without it, the flag is the primary colour with the logo on it.
`logoUse`	Any of `flag`, `mosaic`, `signs`, `roof`: where the logo goes (the dock flag, a mosaic set into the plaza, the brand signpost, the landmark’s roof). Default: all four.

In a self-hosted (signed) manifest, images must be https:// addresses on the island’s own domain or a subdomain, for the same reason skin.logo must: a signed manifest may not aim ACRE’s fetch at someone else’s host. Inline images are not taken there.

Example: a developer tool, a neon city with a server tower

{
  "$schema": "https://useacre.dev/schemas/acre-island.json",
  "acre": "0.3",
  "name": "Quillmark",
  "oneLiner": "Developer tools for tidy APIs",
  "skin": { "color": "#7a3cff" },
  "theme": {
    "shape": "archipelago",
    "size": "medium",
    "seed": 4127,
    "water": "canals",
    "elevation": "flat",
    "streets": "grid",
    "biome": "neon",
    "palette": { "primary": "#7a3cff", "accent": "#29e0ff", "roof": "#5a2bc0" },
    "vegetation": "none",
    "landmark": "server-tower",
    "decor": "neon",
    "logo": "https://quillmark.example/logo-256.png",
    "logoUse": ["flag", "mosaic", "signs", "roof"],
    "tagline": "Ship tidy APIs"
  }
}

Example: a fintech, a vault on desert sand

{
  "$schema": "https://useacre.dev/schemas/acre-island.json",
  "acre": "0.3",
  "name": "Vaultwise",
  "oneLiner": "A payments ledger for small shops",
  "skin": { "color": "#1f8a5b" },
  "theme": {
    "shape": "crescent",
    "size": "large",
    "seed": 902,
    "water": "falls",
    "streets": "grid",
    "biome": "dunes",
    "palette": { "primary": "#1f8a5b", "accent": "#e8b23a", "path": "#c9a46a" },
    "vegetation": "cactus",
    "landmark": "vault",
    "decor": "market",
    "logo": "https://vaultwise.example/brand/mark.png",
    "logoUse": ["flag", "signs", "roof"],
    "tagline": "Every cent, accounted for"
  }
}

Example: a climate startup, a forest with a greenhouse

{
  "$schema": "https://useacre.dev/schemas/acre-island.json",
  "acre": "0.3",
  "name": "Fernline",
  "oneLiner": "Soil and water data for small farms",
  "skin": { "color": "#3d8a4a" },
  "theme": {
    "shape": "valley",
    "size": "medium",
    "seed": 3310,
    "water": "river",
    "elevation": "hills",
    "streets": "winding",
    "biome": "forest",
    "palette": { "primary": "#3d8a4a", "accent": "#f0c94a", "water": "#3f8f9a" },
    "vegetation": "pine",
    "landmark": "greenhouse",
    "decor": "garden",
    "logoUse": ["flag", "mosaic", "signs"],
    "tagline": "Grow more with less water"
  }
}

Applying it

Island settings → Theme: paste or upload it (Edit the JSON, Upload manifest), or use the pickers; Export manifest downloads what is applied now.
MCP: island_manifest_validate({ manifest }), then island_manifest_apply({ manifest }). Hosts only for apply.
HTTP: PUT /api/islands/<id>/manifest with { "manifest": … }; POST …/manifest/validate; POST …/manifest/suggest with { "repoUrl", "siteUrl" }; POST …/manifest/domain with { "domain" } reads a signed manifest from your domain and applies its theme.