The app folder.

The layout

my-app/
  app/                 the app — packed and sent to devices
    index.html         required: the app's first page
    manifest.json      optional: datasets, settings, files needed at boot, partition choices
    …                  every script, style, image and font the app uses
  gui/                 optional: the app's own settings page in the portal (never sent to a device)
    gui.json
    settings/index.html
  marketplace/         optional: the marketplace listing (never sent to a device)
  seed/                desk only: fake records for a local run, seed/<dataset>.json
  arda.dev.json        desk only: how the player runs on your desk — never packed

  state/  data/  storage/  config.adb  player.adb  files.adb
                       written by the player on your desk — keep them out of git

app/ is the whole app

• The player serves app/ and only app/, as the root of a local web server: /index.html, /app.js. Synced files are served beside it under /storage/ (Files).
• The player never writes into app/. What is in it is yours byte for byte, and it is exactly what ArdaForm packs.
• Any toolchain works (Vite, esbuild, a Makefile): point the connector at the folder that holds the built index.html. ArdaForm never runs a build; it packs files.
• State that belongs to the screen (a draft, a remembered tab) is yours: use localStorage. The player keeps no document store for the app. Data that must reach ArdaForm goes through Arda.db.push.

What is packed

When you push to a connected branch, ArdaForm packs the connector's folder (usually app) into a sealed container. Nothing in the repository is executed on the way.

• Never packed: dotfiles, .env*, .git, .github, arda.dev.json.
• A symbolic link anywhere in the folder fails the pack.
• At most 4096 files and 64 MiB.
• When the app folder is the repository root, gui/ and marketplace/ inside it are left out of the device's pack.
• A commit that changes only gui/ or marketplace/ does not update any device.

The container format and how a device checks it: Package format.

marketplace/ is the listing

One flat folder at the root of the repository, read when you publish the app on its project's Marketplace tab. The app's name is the project's, and the price is set on the tab.

• Required: description.md, terms.md, licence.md, icon.svg or icon.png, and image.webp, .png or .jpg.
• Optional: api.md and api.json, shown under the description as the app's API. api.json must be an OpenAPI 3 document; buyers can download it and open it in Postman, Insomnia or Bruno.
• Markdown and pictures only (md, svg, png, jpg, webp), plus api.json. At most 20 files and 4 MiB; a Markdown file up to 200 KiB, api.json up to 512 KiB. Anything else, or an api.json that is not OpenAPI 3, and the tab says why the folder cannot be used.
• Buyers see the folder as it was when you last saved the tab: push a change, then save again.

Desk-only files

• arda.dev.json — window size, pretend hardware, settings and webhooks for a local run (Developer mode). It may be committed: it is never packed. Outside developer mode the player refuses to start if it finds one, and a container carrying one does not open.
• seed/<dataset>.json — records loaded into an empty local dataset (Datasets on a desk).
• state/, data/, storage/ and the .adb files — the player's stores for this folder. Once the folder is a real device, state/ holds its private key. Keep all of them out of git:

state/
data/
storage/
*.adb

An encrypted app

A device holds the app as one sealed container (app/app.arda) rather than loose files. Developer mode refuses a container: on your desk you always run the loose folder.

Checked: the packing rules are as stated by the package format page and the deployment guide; the desk files and the refusal of arda.dev.json outside -dev are from the player's source (cmd/ardaplayer/devconfig.go, internal/apppkg).