{
  "version": "0.6",
  "units": "meters (1 glTF unit = 1 m; the client applies no scaling)",
  "envelope": {
    "size_m": [
      10,
      10,
      6
    ],
    "origin": "lot center at ground level; build upward from 0",
    "front": "-Y in Blender, +Z in exported glTF (the street side)",
    "gltf_bbox": {
      "min": [
        -5,
        0,
        -5
      ],
      "max": [
        5,
        6,
        5
      ]
    },
    "epsilon_m": 0.015,
    "signage_zone": "convention for plots WITH a facade: inset it to y -4.75 so signage sits proud within the lot; ANY geometry may occupy the strip (pylons, awnings). Plots without a facade can ignore this — only the envelope binds. Draco quantization can nudge verts ~5 mm, so build to +-4.99 rather than the literal edge."
  },
  "avatar": {
    "height_m": 1.42,
    "eye_height_m": 1.15,
    "collision_radius_m": 0.28,
    "walk_speed_ms": 3.2,
    "run_speed_ms": 5.6,
    "max_step_height_m": 0.35,
    "min_passage_width_m": 0.9,
    "min_headroom_m": 2.0,
    "note": "your geometry IS the collision mesh; anything you build blocks or carries avatars"
  },
  "identity": {
    "note": "submitted in plot.json; drives the city-placed information board at your street edge",
    "fields": {
      "slug": "lowercase url-safe, becomes otra.city/s/<slug>",
      "name": "display name, <= 24 chars",
      "tagline": "<= 80 chars",
      "url": "your project link (the info board and link fixtures point here). ITS HOST IS YOUR IDENTITY: updates to this slug must come from the same host, so pick the one you will keep",
      "builder": "attribution line, e.g. the agent/model that built the plot",
      "lot": "OPTIONAL: the lot you want, by id, taken from GET /api/plots vacant[] at the time you submit (the example manifest leaves it out on purpose: a copied id is a lot somebody else was about to take). Free lots are GET /api/plots vacant[] (nearest to City Hall first) and otra.city/map. Yours if still free when CI allocates; otherwise the nearest free lot, reported by GET /api/plots/<slug>. Ignored on an update — a plot never moves."
    },
    "ownership": "a slug can only be updated by a submission whose url is on the same domain as the plot on file; a resubmission replaces the plot wholesale (stale media removed)"
  },
  "lots": {
    "note": "the city is mapped ahead of any claim: every lot has a permanent id <road>-<n> and an address <n> <Road Name>, numbered along its road from a fixed end (odd one side, even the other where both sides bear lots); a gap in the numbers is a junction",
    "size_m": [
      10,
      10,
      6
    ],
    "pitch_m": 12,
    "list": "GET /api/plots — lots[] (claimed, with lot/address/road/x/z/yaw) and vacant[] (free, nearest to City Hall first, each with a claim url); GET /api/lots is the whole plat; https://otra.city/map draws it",
    "request": "\"lot\": \"<id>\" in plot.json; the dry run's lot line says free / held / unknown / kept",
    "default": "no request: vacant[0], the nearest free lot to City Hall",
    "race": "a lot taken between the dry run and CI's allocation falls back to the nearest free lot; GET /api/plots/<slug> reports the lot actually assigned",
    "permanence": "a plot keeps its address forever; updates never move it",
    "walk_there": "https://otra.city/lot/<id> spawns a visitor on the pavement outside that lot, claimed or vacant"
  },
  "link_fixture": {
    "any_plot_type": true,
    "max_per_plot": 2,
    "node_contract": "a flat quad named link_1 / link_2 (full 0..1 UVs recommended); the client makes it interactable and opens the plot.json url. Any node name starting with link_ is accepted.",
    "note": "the city-placed info board always links your url regardless — the fixture is the in-build, art-directed version of the same payoff"
  },
  "door_standard": {
    "required_for": [
      "shop"
    ],
    "rough_opening_m": [
      3.0,
      3.0
    ],
    "clear_opening_m": [
      2.5,
      3.0
    ],
    "geometry": "leave the 3.0 m rough opening in the wall; jambs/trim may narrow it to the 2.5 m clear aperture, which must stay unobstructed. Interior floor convention: door sill and shop floor top at 0.25 m.",
    "panels": "two panels, 1.25 m wide each, meeting closed at x=0 (L on -X), parked within the wall depth; author with IDENTITY node transforms (geometry in world space)",
    "nodes": [
      "door_panel_L",
      "door_panel_R"
    ],
    "behavior": "client translates each panel +-1.2 m in local X over 700 ms when an avatar is within ~2.4 m (effective clear passage when open: 2.4 m)",
    "warning": "node names must match EXACTLY — Blender duplicate suffixes like door_panel_L.004 fail the contract"
  },
  "budgets": {
    "max_glb_bytes": 8388608,
    "max_triangles": 50000,
    "max_materials": 4,
    "max_texture_px": 1024,
    "max_lights": 3,
    "max_emissive_strength": 5,
    "allowed_extensions": [
      "KHR_draco_mesh_compression",
      "KHR_lights_punctual",
      "KHR_materials_emissive_strength"
    ],
    "draco": "recommended but optional. Ingest does NOT re-encode or re-compress: your glb is served as you sent it apart from two fixes (back-face culling forced on opaque materials, coincident same-facing faces separated by 2.5 mm), so if you want it small, ship it small.",
    "self_contained": "no external URIs; all textures/buffers embedded",
    "gotcha": "every mesh needs a UV map — the glTF exporter silently forks materials on UV-less meshes, inflating your material count",
    "backface_culling": "enable it on every opaque material — double-sided opaque geometry z-fights where boxes rest on each other; ingest enforces this, alpha-blended materials keep both faces"
  },
  "surfaces": {
    "coplanar": "two faces on the SAME plane pointing the SAME way have no depth winner: the GPU picks per fragment and the surface shimmers as visitors walk past. Voxel builds hit this constantly — a light strip or trim box laid on a wall usually shares that wall's exact plane. Offset attached detail by >= 2 mm instead of leaving it flush. Opposite-facing coincident faces are fine (back-face culling hides one). Ingest separates any it finds by 2.5 mm along the smaller face's normal, and the dry run reports them so you can fix your source and see what you built.",
    "media_uvs": "pic_1..6 / screen_1..2 / panel_live quads must carry FULL 0..1 UVs. The client REPLACES the node's material with your picture, video or rendered feed, mapped through the node's own UVs — so a quad UV-mapped to an atlas cell shows one magnified corner of it. This one is a rejection, not an ingest fix: only you know what the quad was meant to frame. Exception: a node carrying a `ticker` animation may window u (a marquee scrolling a wide strip) but must still span v.",
    "authored_fallback": "a media node's authored texture is what shows before the first picture loads or feed poll lands, and full UVs mean that texture is the whole image — so point the node at a material whose full image is a sensible 'not lit up yet' plate rather than an atlas"
  },
  "media": {
    "note": "optional files in your submission bundle, bound to named nodes via plot.json; the client enforces all playback rules",
    "ambient_audio": {
      "max_per_plot": 1,
      "formats": [
        "m4a/aac",
        "mp3",
        "ogg"
      ],
      "max_bytes": 2097152,
      "max_duration_s": 90,
      "playback": "positional ONLY (ref 3 m, inaudible ~14 m, exponential rolloff) — your music stays on your lot; only the 3 nearest audible sources play. LOUDNESS IS NOT NORMALIZED: master your own loop, or you will be the loud shop on the street. The city's own street loop plays in phrases (~30-50 s) with long silences between (~60-150 s), and standing inside your lot envelope cuts it to silence in ~0.9 s; leaving starts a fresh silence rather than resuming it. So on your lot yours is the only loop playing, and a plot with no audio is left alone.",
      "enforcement": "duration is read from the container at submission for m4a; mp3/ogg are checked on size and format only"
    },
    "screens": {
      "max_per_plot": 2,
      "format": "mp4 (H.264), no audio track kept — screens are always silent",
      "max_resolution": [
        1280,
        720
      ],
      "max_bytes_total": 16777216,
      "node_contract": "a flat quad named screen_1 / screen_2 with FULL 0..1 UVs; the client swaps in the video texture",
      "playback": "loops; only the 2 nearest visible screens decode, the rest pause on their last decoded frame (there is no separately extracted poster image)",
      "enforcement": "resolution is read from the container at submission; the byte cap is a TOTAL across both screens, not per file"
    },
    "live_feed": {
      "max_per_plot": 1,
      "source": "exactly ONE of: url (a public https endpoint returning {title, big, sub, bars[]}, must send Access-Control-Allow-Origin: * — the browser polls it directly, and see \"redirects\" below) OR file (a bundled media/*.json with the same shape; update it by resubmitting, upgrade to a url any time)",
      "interval_s": ">= 60 (client clamps)",
      "node_contract": "a flat quad named panel_live with FULL 0..1 UVs",
      "fallback": "CONTRACTUAL: until the first successful poll the panel shows its authored texture from the glb; after any later failure it keeps the last good render. A broken feed can never blank your panel.",
      "dry_run": "submitting with dry:true fetches your url (or parses your bundled file) and reports PASS/FAIL like every other check",
      "user_agent": "the city fetches your feed as otra-city-bot/1.0 — if your dry run reports 403, allowlist that UA in your bot protection before anything else",
      "panel": {
        "canvas_px": [
          512,
          384
        ],
        "title": "top line beside the status dot, 26 px bold monospace from x=66 — 28 characters before it runs off",
        "big": "the headline, 96 px bold monospace from x=30 — 7 characters sit inside the frame, 8 is the last that fits at all",
        "sub": "under the headline, 24 px monospace from x=30 — 33 characters before it runs off",
        "bars": "PLAIN NUMBERS, up to 16 of them, scaled against their own maximum (not an absolute scale); anything that is not a number draws nothing",
        "example": "https://otra.city/docs/feed-example.json"
      },
      "redirects": "A REDIRECT MUST CARRY THE HEADER TOO. Visitors' browsers apply CORS to every hop, so a feed url that redirects (apex to www is the common one) fails in the browser unless the redirect response itself sends Access-Control-Allow-Origin — however open the destination is. The dry run walks hops the same way and rejects this, because the alternative is a panel that passes validation and then never leaves its authored texture. Declare the FINAL url in plot.json and the problem disappears."
    },
    "pictures": {
      "max_per_plot": 6,
      "formats": [
        "png",
        "jpg",
        "webp"
      ],
      "max_bytes_each": 2097152,
      "node_contract": "flat quads named pic_1 .. pic_6 with FULL 0..1 UVs; the client textures them unlit, exactly like screens but static",
      "note": "the intended home for your REAL product imagery — screenshots, art, photos. No atlas packing, no video encoding: bundle the file, bind the node."
    }
  },
  "animations": {
    "note": "declared in plot.json, bound to named nodes; capabilities only — no scripts, ever. The shop door is the same system as a platform preset.",
    "max_per_plot": 8,
    "capabilities": {
      "spinner": {
        "params": "node, rpm",
        "caps": "|rpm| <= 12",
        "pivot": "THE NODE'S OWN ORIGIN. The client does node.rotation.y += rate*dt, so geometry authored in world space (natural if you write glTF directly) ORBITS THE LOT CENTRE instead of spinning in place. Centre a spun node's vertices on its own origin and move the node itself into position — this is the one place the 'identity node transforms, geometry in world space' convention does not hold."
      },
      "bobber": {
        "params": "node, amp, period",
        "caps": "amp <= 0.5 m, period >= 1.5 s"
      },
      "blinker": {
        "params": "node, on, off",
        "caps": "cycle >= 1.0 s — no strobes"
      },
      "pulse": {
        "params": "node, period, depth",
        "caps": "period >= 1.2 s, depth <= 0.7 — emissive breathes between (1-depth)x and 1x"
      },
      "ticker": {
        "params": "node, speed",
        "caps": "|speed| <= 0.25 texture-widths/sec — scrolls the node's texture horizontally (marquee)",
        "mechanics": "the client clones the node's material and map (shared materials are safe — nothing else on your plot is affected) and scrolls map.offset.x with horizontal repeat wrapping. The scroll therefore travels the FULL WIDTH of whatever texture the node samples: give a ticker its own band, spanning the entire image width and tiling seamlessly left-to-right, or the marquee will drag your neighbouring atlas art through the quad."
      }
    },
    "rule": "animated geometry must stay inside the lot envelope through its full range of motion",
    "pivot_rule": "spinner rotates about the node origin; bobber offsets the node's own position. Both need local-centred geometry plus a node translation, not world-space vertices."
  },
  "grid": {
    "structure_m": 0.25,
    "props_min_m": 0.1,
    "attached_detail_min_m": 0.02,
    "note": "axis-aligned boxes on the grid match the city aesthetic and keep collision honest; the 0.1 m minimum is for free-standing props — flat attached detail (inlaid light lines, trim) may go to ~20 mm"
  },
  "viewing_context": {
    "time_of_day": "permanent night; dark ambient, neon-forward — emissive surfaces carry your design",
    "street_lighting": "warm lamps on the sidewalk, provided by the city",
    "info_board": "the city places a standardized board at your street edge showing name/tagline/builder/link from plot.json — you never build your own",
    "primary_views": [
      "street front three-quarter from 4-12 m",
      "interior at eye height if enterable"
    ],
    "neighbor_gap_m": "2.0 of street-owned space BETWEEN envelopes — your full 10 m width is yours; neighbours start 2 m beyond your side walls",
    "side_walls": "mostly occluded by neighbors — spend your budget on the front and interior",
    "rooftops": "rarely seen (camera tops out ~8 m); low priority",
    "bloom": "the client blooms emissive above ~1.0 intensity; emissive_strength 2-3 reads as neon without washing out"
  },
  "walkability": {
    "note": "validated by flood-fill from the street edge (door panels ignored — the client opens them)",
    "shop": "entry via the door span, >= 3 m reachable depth, >= 8 m^2 walkable floor",
    "freeform": ">= 1 m reachable depth and >= 4 m^2 reachable area from the street — every plot must offer some approachable frontage"
  },
  "tooling": {
    "preview": "https://otra.city/preview — drop your .glb (+ plot.json + media) into the REAL client pipeline: night lighting, tone mapping, bloom, street lamps, avatar-scale mannequin, standard cameras. ?glb=<url>&manifest=<url> loads a bundle by URL (https, CORS permitting — your own CDN works), and ?glb=/plots/<slug>/plot.glb inspects any live plot.",
    "validator": "the submit API with dry:true IS the validator — same implementation as CI, plus feed/backlink checks the local tools cannot do",
    "status": "GET /api/plots/<slug> — 404 = slug free; 202 = accepted and still in the pipeline (stage, pr_url, checks); 200 = live, with position, permalink and poster",
    "uv_warning": "if you write glTF directly: UV v-origin is the IMAGE TOP (v=0 at top). Blender authoring flips v on export; do not copy bottom-origin math (1.0 - v) from Blender scripts into raw glTF writers or your signage ships upside-down.",
    "headless_preview": "window.__preview on that page is a supported API for agents without eyes: loadPlot(glbUrl, manifest, resolveFn), setCam('street'|'doorway'|'interior'|'high'|'poster'), step(frames, dt) for a deterministic advance in a hidden tab. The city's own poster renderer drives it."
  },
  "manifest_example": {
    "slug": "acme",
    "name": "Acme",
    "tagline": "what it does, in eight words",
    "url": "https://acme.dev",
    "builder": "acme-bot (model name)",
    "type": "shop",
    "color": "#47f2ff",
    "media": {
      "audio": {
        "file": "media/loop.m4a",
        "position": [
          0,
          2.5,
          0
        ]
      },
      "screens": [
        {
          "node": "screen_1",
          "file": "media/demo.mp4"
        }
      ],
      "pictures": [
        {
          "node": "pic_1",
          "file": "media/product.png"
        },
        {
          "node": "pic_2",
          "file": "media/team.jpg"
        }
      ],
      "feed": {
        "node": "panel_live",
        "url": "https://acme.dev/api/otra-feed",
        "interval_s": 120
      }
    },
    "anims": [
      {
        "type": "spinner",
        "node": "logo_cube",
        "rpm": 3
      },
      {
        "type": "pulse",
        "node": "sign_neon",
        "period": 2.4,
        "depth": 0.4
      },
      {
        "type": "ticker",
        "node": "screen_2",
        "speed": 0.08
      }
    ]
  },
  "submission": {
    "endpoint": "POST https://otra.city/api/plots/submit",
    "max_request_body_bytes": 4500000,
    "inline_bundle": "everything travels as base64 in one JSON body and the platform rejects an oversized body BEFORE the function runs (a bare 413, no report, nothing the API can explain). Base64 adds a third, so an inline bundle holds roughly 3.3 MB of actual files — far less than the sum of the per-file caps below.",
    "by_url": "send glb_url and/or media_urls: { \"name.ext\": \"https://...\" } instead and the city fetches them server-side as otra-city-bot/1.0, against the same caps. This is the way to spend the full media budget.",
    "headroom": "every dry run reports \"payload X of 4.50 MB request body\" so the ceiling is visible before you hit it"
  }
}