@dopame/acde-linux-x64 0.0.0-stage → 0.0.10

package/lib/acde/skills/acde/references/reference/cli.md

@@ -0,0 +1,221 @@
+# CLI
+
+```text
+acde <command> [args]
+```
+
+On error, acde prints one line, `acde: <reason>`, and exits with code 1. A wrong argument (an action `act` does not know, a level `console` does not know, …) is answered with one line that names what is wrong and the `acde <command> --help` to read, such as `acde: console: --level loud: one of log, info, warn, error, debug, errors (acde console --help)`; a wrong option value always reads `acde: <command>: --<option> <value>: <what it takes> (acde <command> --help)`. The full usage is printed only by `acde --help`.
+
+After 0.0.9, exit codes are the same for every command:
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Done (also an empty list, such as `acde console` with no entries) |
+| 1 | An error: a wrong argument, something that failed, or something that stops it (a package in use) |
+| 2 | Nothing done, but not an error: nothing matched (`acde query`, `acde inspect --find`) or nothing to remove (`acde uninstall`) |
+| 3 | Cancelled or not confirmed: Ctrl+C in a question of `acde new` or during `acde sdk update`, a declined `acde uninstall`, or no terminal to ask in and no `--yes` |
+
+What a command found goes to stdout; "nothing found", errors and notes go to stderr with the `acde:` prefix. In 0.0.9 some commands differ: `acde query` prints "nothing in …" on stdout, and `acde uninstall` exits 1 when the package is not installed and 2 when it is in use.
+
+`acde --version` (or `-v`, or `acde version`) prints the version of acde on the first line, then the SDK version and contract level it was built with, and the acdert it finds (`ACDERT`, the one installed next to acde, then PATH) with that runtime's version and contract level. `acde --help` (or `-h`, or `acde help`) prints the usage of every command; `acde <command> --help` and `acde help <command>` print that command only. `acde` with no arguments prints only its version, the three commands that start a project, and a pointer to `acde --help`. An unknown command or argument prints one line that says what is wrong and which `--help` to read, and exits with code 1. Output is colored when it goes to a terminal; `NO_COLOR` (set and not empty) turns color off, and `FORCE_COLOR` (set and not `0` or `false`) turns it on. Only labels are colored: `acde:`, `error:`, `warning:`, the statuses of `acde doctor` and the headings of the help. An error is one line, `acde: <what went wrong>`; with `ACDE_DEBUG=1` its stack trace follows (after 0.0.9).
+
+## Setup
+
+### acde doctor
+
+```text
+acde doctor [dir] [--json] [--online] [--fix [--yes]]
+```
+
+Checks what `acde dev` and `acde test` need on this machine: acde on PATH, Bun and Node.js, acdert (found, runs, runs the contract level this acde builds, is the release this acde pairs with), the runtime's own checks (`acdert doctor`: its host files, the GPU, and on Linux the display), running `acde dev` sessions and the approvals they wait for, the project in `dir` (default: the current directory; `acde check`, this platform, its dependencies, `.acde/` in `.gitignore`), and the acde skill for coding agents. See [Check the setup](../guide/doctor.md).
+
+| Option | Description |
+| --- | --- |
+| `--json` | One JSON object instead of lines: `{"ok": …, "checks": [{"id", "title", "status", "summary", "fix", "repair"}]}`; with `--fix` also `"fixed"` |
+| `--online` | Also ask the acde download site (`ACDE_DIST`) whether a newer acde is out |
+| `--fix` | After the checks, fix what acde can: some fixes right away, the others after asking; then check again. See [Fix what it can](../guide/doctor.md#fix-what-it-can) |
+| `--yes` | With `--fix`: do the fixes that ask first without asking |
+
+It prints one line per check, `<status> <check>: <what it found>`, with `fix: …` on the next line for a problem, and a last line that counts errors and warnings. The status is `ok`, `warn`, `error` or `skip` (not checked: no project here, or an earlier check failed). It exits with code 1 when a check is an error, else 0. A `dir` that holds no acde project is an error.
+
+With `--fix`, after the report it prints `fixing: <what>`, the output of what it runs, and `fixed: <what>` or `failed: <what>: <why>` for each fix, `skipped: <what>` for one that was not allowed, and then `acde doctor: after fixing:` and the checks again; the exit code follows the second run. When nothing can be fixed it says `acde doctor: nothing here it can fix; the fix lines say what to do`. `--yes` without `--fix` is an error.
+
+## Projects
+
+### acde new
+
+```text
+acde new [dir] [--template T] [--id ID] [--label NAME] [--backend] [--install|--no-install] [--git] [--pm PM] [--yes]
+```
+
+Creates a project. In a terminal, it asks for whatever is missing; with `--yes`, or outside a terminal, it asks nothing (then `dir` is required, the template defaults to `html`, the dependencies are installed unless `--no-install` is given, and no repository is created unless `--git` is given).
+
+| Option | Description |
+| --- | --- |
+| `--template` | `html` `desktop` `react` `vue` `svelte` `solid` `preact` `vanilla` `next` `nuxt` `sveltekit` `astro` |
+| `--id` / `--label` | App id and display name |
+| `--backend` | Add `server.ts`, a backend. In 0.0.9, `html` only (the other templates ignore it); after 0.0.9, `html` and the Vite templates, and `next`, `nuxt`, `sveltekit`, `astro` (which have their own server) and `desktop` (which has none) refuse it |
+| `--install` / `--no-install` | Install the dependencies, the SDK included, with the package manager, or do not; without either, `acde new` asks in a terminal and installs them otherwise |
+| `--git` | `git init` and make the first commit (if a git user name and email are configured) |
+| `--pm` | `bun` `npm` `pnpm` `yarn`; decides whether the project runs on Bun or Node.js (default: `bun` when acde runs on Bun, else `npm`; in a terminal with both installed, it asks) |
+
+### acde check
+
+```text
+acde check [dir] [--platform windows|macos|linux]
+```
+
+Checks the config (id, entry, icon, service modules, framework) and the manifest rules of the SDK, or the manifest and entry files of a handwritten package, and the `acde:` imports against the manifest. It prints `error:`, `warning:` and `note:` lines on stderr and exits with code 1 only when there is an error. A `note:` marks an import that the check lets pass but cannot verify, the namespace of a [desktop service](../guide/services.md#call-it) that is not the service's own name: `note: src/main.js:1: app "notes": acde:timer resolves only if the service Notes lists ("clock") provides the "timer" namespace`.
+
+It also checks the app's declared capabilities against what a platform has, once for each way of running an app there (`desktop` and `standalone`, on Linux also `session`). That platform is the one `acde check` runs on, or the one `--platform` names:
+
+- A required capability that the platform lacks is an error: `error: windows (desktop): app "notes" requires network, which this mode lacks`, followed by a hint on making it optional.
+- An optional capability that it lacks is a note, and no error: `note: windows (desktop): app "notes" runs without optional camera, which this mode lacks`.
+- When no required capability is missing, the last line is `ok: linux (session, desktop, standalone): every required capability is there`.
+
+### acde build
+
+```text
+acde build [dir] [--out DIR]
+```
+
+Builds into `DIR` (default `.acde`). A relative `--out` is resolved against the project being built. The `acde:` imports are checked first, as in `acde check` (an error stops the build, a `note:` is printed), and the manifest of the output is checked again.
+
+### acde install
+
+```text
+acde install [dir] [--out DIR]
+```
+
+Builds, then installs into `$XDG_DATA_HOME/acde/packages/<id>`; without `XDG_DATA_HOME`, `~/.local/share/acde/packages/<id>` (on Windows `%USERPROFILE%\.local\share\acde\packages\<id>`). See [Local install](../guide/install.md).
+
+### acde uninstall
+
+```text
+acde uninstall [id|dir] [--yes] [--data | --keep-data]
+```
+
+Removes a package that `acde install` put into the packages directory, found by its id (its directory name there) or by the project directory it was installed from. For a handwritten package, installed as a link, it removes only the link; the project it points at stays. Before removing, it prints what it removes (`acde: removes <id>: <path> ...`) and, in a terminal, asks; `--yes` removes without asking, and outside a terminal nothing is removed without `--yes`. When an `acde dev` session runs the package's desktop or one of its apps, or runs a desktop while the package has apps, it removes nothing and names the session to stop first (`acde stop --session <pid>`). With no argument it lists the installed packages, one per line: the id and the path (for a link, `-> <project>`).
+
+The data of the package's apps and desktops (`storage/app-<id>/`, `storage/desktop-<id>/` and `apps/<id>/` under `$XDG_DATA_HOME/acde`, or under `ACDE_STORAGE` for the storage) is removed with `--data` and kept with `--keep-data` (after 0.0.9; 0.0.9 keeps it); with neither, a terminal is asked and `--yes` keeps it, printing `acde: kept its data (…): <paths>`. Both together is a wrong argument (exit code 1).
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Removed, or listed |
+| 1 | In use by an `acde dev` session, or a wrong argument |
+| 2 | Not installed |
+| 3 | Not confirmed (the question was declined, or no terminal and no `--yes`) |
+
+### acde sdk
+
+```text
+acde sdk [update] [dir]
+```
+
+Shows the project's `@dopame/acde-api` and the SDK version this acde pairs with. `acde sdk update` points the dependency at that version's tarball on `https://pkgs.dopame.ai/acdert/<version>/` and reinstalls with the project's package manager (from its lock file or `packageManager`). With npm 12 or later it also adds `allow-remote=root` to `.npmrc` (in the workspace root for a workspace member, where npm reads it; npm 12 refuses URL dependencies without it; projects `acde new` makes with npm 12 have it already). npm 11 does not need it and gets no `.npmrc`, so a project made with npm 11 needs one `acde sdk update` before npm 12 installs it. If the package manager is not on PATH it changes nothing. If the install fails or is interrupted (Ctrl+C), it puts `package.json`, the lock file and `.npmrc` back as they were and says so, naming any file it could not put back; run the install again to bring `node_modules` back in line. `acde check` also warns when `node_modules` holds another SDK version than `package.json` names. `acde check` and `acde dev` warn when the two differ, for example after upgrading acde.
+
+### acde dev
+
+```text
+acde dev [dir...] [--out DIR] [--app ID] [--desktop ID|DIR] [--headless] [--verbose] [--force]
+```
+
+Builds, starts acdert, and rebuilds and reloads on changes. `--headless` opens no window; use it on a machine without a display. `--verbose` (after 0.0.9) also prints the runtime's own info log; by default the terminal shows what the pages and backends print, what happens to each app, and the runtime's warnings and errors. On Linux without `WAYLAND_DISPLAY` or `DISPLAY`, `acde dev` without `--headless` stops with `acde: no display here (no WAYLAND_DISPLAY or DISPLAY): run acde dev --headless` and exits with code 1. After 0.0.9, only one `acde dev` runs a project at a time, even when two start at the same moment: a second one exits with code 1 before it builds and names the running one (`acde: acde dev <pid> already runs <dir>; stop it first (acde stop --session <pid>), or pass --force to start another`); `--force` starts it anyway. Ctrl+C, SIGINT and SIGTERM end the session and its runtime, and remove its files (in 0.0.9, a SIGINT sent to `acde dev` alone, not through the terminal, is ignored); after 0.0.9, files left by a session that was killed are removed by the next `acde dev` or session command. See [acde dev](../guide/dev.md) and [Without a display](../guide/tools.md#without-a-display).
+
+## Running sessions
+
+These work with a running `acde dev` session, and all of them accept `--session <pid>`. A `<web>` is one page: a web name from `acde webs`, an app id, or `desktop`; a `<ref>` is an element id from `acde inspect` or `acde query`, such as `w1.12`, a window, such as `w1`, or (after 0.0.9) a menu on a window's title bar, such as `w1.m1`, or an item of it, `w1.m1.2`. See [Debugging](../guide/tools.md).
+
+| Command | Description |
+| --- | --- |
+| `acde webs` | Lists pages |
+| `acde eval <web> <code\|->` | Runs code in a page and prints JSON |
+| `acde shot <web> [-o, --output FILE]` | Window screenshot, default `./<web>.png` |
+| `acde screen [-o, --output FILE]` | Full-screen screenshot, default `./screen.png` |
+| `acde pointer <x> <y>` | Moves the pointer to screen coordinates, as a real move |
+| `acde inspect [--window W] [--find TEXT] [--all] [--offscreen]` | The screen as text |
+| `acde query <selector> [--window W] [--ref REF] [--limit N]` | The elements a CSS selector matches, each with a ref |
+| `acde act <ref> <action> [arg]` | Performs an action on a ref |
+| `acde input <web> <events\|->` | Sends a JSON array of raw mouse and keyboard events to a page, in its CSS pixels: `move` / `down` / `up` (`x`, `y`, `button`), `wheel` (`x`, `y`, `dx`, `dy`), `keydown` / `keyup` (`key`), `text` (`text`), `wait` (`ms`, up to 10000). Moves are a frame apart, so moves with the button down draw a path; `keydown`, `wait`, `keyup` holds a key (after 0.0.9). In 0.0.9, `down`, `up` and `wheel` happen where the pointer is, whatever their `x` and `y`: send a `move` there first; after 0.0.9 they move the pointer to their `x` and `y` |
+| `acde console [--web W] [--level L] [--since S] [--follow]` | Page logs and errors; `--since reload` or `--since N` |
+| `acde network [--web W] [--failed] [--since S] [--follow]` | Page requests; `--since reload` or `--since N`. With nothing to show, `console` and `network` print `acde: no console entries` / `acde: no requests` on stderr and exit 0 (after 0.0.9) |
+| `acde choose <folder\|open\|save> [path...] [--cancel]` | (after 0.0.9) Answers the next folder, file or save picker the page opens: one folder, one or more files, or the file to write; `--cancel` answers it as cancelled. Prints `the next folder picker answers <path>`. A headless session shows no picker, so answer it before the action that opens it |
+| `acde drop <web> <file...> [--at X,Y]` | (after 0.0.9) Drops files onto a page as a drag from the system would (`dragenter`, `dragover`, `drop` with the files), at `X,Y` in its CSS pixels or in the middle. Prints `dropped N files onto <web>` |
+| `acde permissions` | The camera and microphone prompts that wait and the decisions made |
+| `acde allow [<prompt id> \| <app> <capability>] [--all]` | Allows a waiting camera or microphone prompt |
+| `acde deny [<prompt id> \| <app> <capability>] [--all]` | Denies a waiting camera or microphone prompt |
+| `acde revoke <app> <capability>` | Takes back a decision |
+| `acde stop` | Ends the session and its acdert; see [Stopping](../guide/dev.md#stopping) |
+| `acde devtools [web]` | Opens the DevTools of Chrome or Edge on a page of the session (a web name, an app id, `desktop`, a window title, or `services` or a service name for the services; default: the focused page) and prints the DevTools address. It looks for Edge, then Chrome on Windows; the Chrome app, then the Edge app on macOS; `google-chrome`, `chrome`, `chromium`, `microsoft-edge` on `PATH` on Linux. The browser runs with a profile of its own in acde's cache directory (`acde/devtools/` under `%LOCALAPPDATA%`, `~/Library/Caches` or `~/.cache`), never your everyday one; it opens no window of its own and no sync prompt, only the DevTools window, and stays running for the next `acde devtools`. `ACDE_BROWSER` names another browser; `ACDE_BROWSER=none` opens nothing. Without a browser, or when it cannot be started or reached, it prints the address and why, to paste into the address bar of Chrome or Edge, and exits 0. Asked again for a page whose DevTools are open, it brings them to the front. F12 in a window of `acde dev` (fn+F12 on a Mac keyboard) does the same for the page in that window, and the page never sees that F12; F12 with a modifier still reaches the page (after 0.0.9) |
+| `acde mcp [--session PID]` | MCP server over stdio; see [MCP](../guide/mcp.md) |
+
+| Option | Description |
+| --- | --- |
+| `--window` | `inspect`, `query`: this window (`w1`) instead of the focused one |
+| `--ref` | `query`: search only under this element (`w1.12`) |
+| `--limit` | `query`: list at most this many elements (1 to 3000, default 600) |
+| `--all` | `inspect`: every window that is not marked `[minimized]`, and elements hidden by `opacity: 0` or `visibility`. `allow`, `deny`: every waiting prompt |
+| `--cancel` | `choose`: answer the picker as cancelled |
+| `--at` | `drop`: where to drop, `X,Y` in the page's CSS pixels |
+
+`acde query` prints `N in <window>:` and one line per element (exit code 0), or `acde: nothing in <window> matches "<selector>"` on stderr (exit code 2; in 0.0.9 on stdout, without `acde: `). `acde inspect --find TEXT` exits with code 2 when no element's name or value contains TEXT. Exit code 2 always means the command worked and found nothing; 1 means an error, such as a window or element that does not exist. `acde act` prints what it did and what changed; when the action was not done it prints the reason on stderr (`acde: act <ref>: <reason>`) and exits with code 1. A ref that no longer exists says `there is no such element (any more); acde inspect --find TEXT gives the current refs`.
+
+`acde permissions` prints two blocks and exits with code 0:
+
+```text
+pending:
+  2  recorder  microphone  (request)
+decisions:
+  recorder  camera  granted
+```
+
+A pending line is `<prompt id>  <app>  <capability>  (<reason>)`; the reason is always `request` (the running app asked: its `getUserMedia()` or `request()` waits for the answer); a decision line is `<app>  <capability>  <granted|denied>`. An empty block is `pending: none` or `decisions: none`.
+
+`acde allow` and `acde deny` answer prompts that wait now. Without arguments they answer the only waiting prompt; when several wait they answer none, list them, and exit with code 1. `<prompt id>` names one prompt, `<app> <capability>` the prompt of that app for that capability, and `--all` every waiting prompt. Each answered prompt prints `allowed <app> <capability> (prompt <id>)` or `denied <app> <capability> (prompt <id>)`. When nothing waits, or nothing matches, they print one line that says so (`acde: no approval prompt is waiting`, `acde: no approval prompt 5 is waiting (waiting: 2)`) and exit with code 1.
+
+`acde revoke <app> <capability>` prints `revoked <app> <capability>`; when there is no such decision it says so and exits with code 1.
+
+While a camera or microphone prompt waits, `acde webs` prints one line per prompt after the table (the app's window is open; its `getUserMedia()` waits): `<app> waits for approval of <capability>: acde allow (or acde deny)`. See [Camera and microphone](../guide/tools.md#camera-and-microphone).
+
+## Coding agents
+
+```text
+acde skills [install|remove|path] [--agent ID,...] [--dir DIR] [--copy]
+```
+
+| Command | Description |
+| --- | --- |
+| `acde skills` | Where the acde skill is installed, and whether each place is current |
+| `acde skills install` | Links the skill into `~/.agents/skills` and the skills directory of every agent found |
+| `acde skills remove` | Removes it from those places, and the directories `install` created that are now empty |
+| `acde skills path` | Prints the skill's directory inside the acde install |
+
+| Option | Description |
+| --- | --- |
+| `--agent` | These agents (comma-separated ids such as `claude-code`, `codex`, `cursor`) instead of the ones found |
+| `--dir` | This skills directory instead; the skill goes into `DIR/acde` |
+| `--copy` | Copy instead of link (`install` only) |
+
+See [Coding agents](../guide/agents.md).
+
+## Testing
+
+```text
+acde test [dir|file...] [--headed] [-t PATTERN] [--desktop ID|DIR] [--timeout MS] [--bail] [--trace] [-u]
+          [--workers N] [--retries N] [--video[=on|failed|off]]
+```
+
+| Option | Description |
+| --- | --- |
+| `--headed` | Open windows (headless by default) |
+| `-t`, `--test-name-pattern` | Run only tests whose names match |
+| `--desktop` | Run the app in this desktop |
+| `--timeout` | Timeout per test, including the start of its session (milliseconds, default 60000) |
+| `--bail` | Stop at the first failure |
+| `--trace` | Leave a `trace.html` for every test |
+| `-u`, `--update-screenshots` | Rewrite screenshot baselines |
+| `--workers` | How many test files run at once (default: half the cores, at most 4; 1 with `--headed` or `--bail`) |
+| `--retries` | Run a failing test again this many times, each on a fresh session; a test that passes later is reported as flaky (default 0) |
+| `--video` | Keep `video.png`, an animated PNG of the screen, for failing tests (the same as `--video=failed`); `--video=on` keeps it for every test, `--video=off` for none (the default) |
+
+The run ends with one line that counts tests and files and names the failing files (after 0.0.9; 0.0.9 prints a line for tests and one for files) (`acde test: 5 tests in 2 files: 4 passed, 1 failed; failed: e2e/notes.e2e.ts`); see [Testing](../guide/testing.md#commands).

package/lib/acde/skills/acde/references/reference/config.md

@@ -0,0 +1,51 @@
+# acde.config.jsonc
+
+The project configuration. The JSON Schema is at `@dopame/acde-api/config.schema.json`, and the TypeScript type is `AcdeConfig`:
+
+```ts
+type AcdeConfig = AppConfig | DesktopConfig
+```
+
+## Common fields
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `$schema` | string | | Path to the JSON Schema |
+| `type` | `"app"` \| `"desktop"` | | Required |
+| `name` | string | `name` from `package.json` | Package name |
+| `version` | string | `version` from `package.json` | |
+| `apiLevel` | integer ≥ 1 | The SDK's `API_LEVEL` (1) | The contract level; `acde build` writes it into the manifest. Leave it out |
+| `public` | string | `"public"` | Directory of static files copied as is |
+
+## AppConfig
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | string | Derived from the package name | `[a-z0-9][a-z0-9-]*` |
+| `label` | string | | Display name |
+| `icon` | icon name \| path | `"app"` | See [Icons](../guide/assets.md#icons) |
+| `entry` | string | `"index.html"` | HTML, or a module whose default export is a `WindowApp`; omit when using a framework |
+| `framework` | `Framework` | `"auto"` | See below |
+| `capabilities` | `Capabilities` | `{}` | System capabilities; see [Manifest](manifest.md#capabilities). A desktop service's name here is an error |
+| `optional` | string[] | `[]` | Names that are also in `capabilities`: the app runs without them and reaches them with `load()` |
+| `services` | string[] | `[]` | Desktop services the app uses, imported as `acde:<name>`; not the name of a system module |
+| `size` | `[number, number]` | `[800, 600]` | Content area in logical pixels, positive integers. When `acde dev` runs the app alone, the size the host window opens at (the app fills it); not applied with `--headless` |
+| `frame` | boolean | `true` | System title bar |
+| `multiple` | boolean | `false` | Allow multiple windows |
+| `mimeTypes` | string[] | `[]` | `type/subtype` or `type/*` |
+| `schemes` | string[] | `[]` | URL schemes of links the app opens: `[a-z][a-z0-9+.-]*`, no colon, not `file` |
+| `requests` | string[] | `[]` | Request kinds the app accepts from `open()`: `[a-z][a-z0-9-]*`, not `open-file` or `open-link` |
+| `heapMb` | number | 256 | JS heap limit per window, ≥ 32 |
+| `backend` | `false` \| `{entry?, port?}` | Detected automatically | See [Backend](../guide/backend.md) |
+
+`Framework`: `auto` `none` `next` `nuxt` `sveltekit` `astro` `react-router` `remix` `angular` `vite` `cra` `script`.
+
+## DesktopConfig
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` / `label` / `description` | string | | |
+| `entry` | string | `"index.html"` | The desktop page |
+| `heapMb` | number | 1024 | |
+| `services` | `Record<string, string \| ServiceConfig>` | | Service name → module path, or `{ module, modules? }`: the module path and the shell modules the service gets from `ctx.import()`; see [Services](../guide/services.md#shell-modules-in-a-service) |
+| `apps` | `WindowAppConfig[]` | | Bundled apps (system apps): the `AppConfig` fields except `framework`; `id` and `entry` are required, and `capabilities` may name shell modules |

package/lib/acde/skills/acde/references/reference/env.md

@@ -0,0 +1,44 @@
+# Environment variables
+
+## acde
+
+| Variable | Effect |
+| --- | --- |
+| `ACDE_INSTALL` | Install directory, default `~/.acde` |
+| `ACDE_DIST` | Where the installers download acde and its runtime from, where `acde new` and `acde sdk update` point the SDK dependency, and where `acde doctor --online` looks for a newer one; default `https://pkgs.dopame.ai/acde` |
+| `ACDERT` | The acdert binary `acde dev` and `acde test` run: a path, or a name on PATH. Unset: the acdert the installer put next to acde, then `acdert` on PATH |
+| `ACDE_BUNDLER=vite` | Bundle with Vite on Bun too |
+| `ACDE_DEBUG=1` | An error also prints its stack trace (normally only the one-line message) (after 0.0.9) |
+| `ACDE_BROWSER` | The browser `acde devtools` and F12 in `acde dev` open DevTools in: a path, or `none` to open nothing and only print the address. Unset: Edge, then Chrome on Windows; Chrome, then Edge on macOS; Chrome, Chromium or Edge on `PATH` on Linux (after 0.0.9) |
+| `CI` | When set, `toHaveScreenshot` does not write new baselines; a missing baseline fails right away |
+| `NO_COLOR` | Set and not empty: no color in acde's output |
+| `FORCE_COLOR` | Set and not `0` or `false`: color even when the output is not a terminal |
+
+## Runtime (acdert)
+
+`acde dev` and `acde test` set what is needed for you. To adjust things by hand:
+
+| Variable | Effect |
+| --- | --- |
+| `ACDE_PATH` | Extra package directories (separated by `;` on Windows) |
+| `ACDE_DESKTOP` | Default desktop |
+| `ACDE_HEADLESS=1` | Don't open a window |
+| `ACDE_SIZE` | Screen size, such as `1280x800` |
+| `ACDE_SCALE` | Scale factor when headless (0.5–4) |
+| `ACDE_COLOR_SCHEME` | `light` / `dark` |
+| `ACDE_STORAGE` | Root directory for web storage; set it to empty to keep storage in memory only |
+| `ACDE_AUTOSTART` | Autostart items run by default only in a Dopame OS session: `1` runs them in the host window too, `0` skips them |
+| `ACDE_AUDIO=null` | No sound |
+| `ACDE_CAPTURE=fake` | A fake camera and microphone (`Fake camera`, `Fake microphone`) in place of the system's devices, for `getUserMedia()` |
+| `ACDE_FRAME_STYLE` | Title bar style: `mac` (traffic lights) or `windows` (Windows buttons). Unset: `windows` in the host window on Windows, else `mac` |
+
+## App backends
+
+| Variable | What it is |
+| --- | --- |
+| `ACDE_APP_ID` | The app id |
+| `ACDE_APP_DATA` | The app's data directory (also its working directory) |
+| `ACDE_APP_SOCKETS` | The app's socket directory. Not set for a Node.js backend on Windows, which gets `ACDE_APP_CHANNEL=fd` instead; see [Backend](../guide/backend.md#on-windows) |
+| `PORT` | The configured port |
+| `NODE_ENV` | `production` |
+| `http_proxy`, `https_proxy`, `all_proxy`, `no_proxy` | The session's proxy variables, or else the system's manual proxy (Windows, macOS) with its exceptions plus `localhost,127.0.0.1,::1` in `no_proxy`; upper-case names on Windows, both cases elsewhere. See [Backends](../guide/backend.md#running) |

package/lib/acde/skills/acde/references/reference/manifest.md

@@ -0,0 +1,92 @@
+# Manifest
+
+The runtime only understands **packages**: a directory whose `package.json` has an `acde` field holding the manifest. `acde build` generates it from your config; you can also write it by hand.
+
+```json
+{
+  "name": "my-pkg",
+  "acde": {
+    "apiLevel": 1,
+    "desktops": [{ "id": "dopame", "name": "Dopame", "entry": "desktop/index.html", "services": ["assistant"] }],
+    "apps": [{ "id": "term", "label": "Terminal", "icon": "term", "entry": "/app/term/index.html", "capabilities": { "terminal": true } }],
+    "assets": { "/app/term/": ["apps/term/web"], "/desktop/dopame/": ["desktop"] },
+    "services": [{ "name": "assistant", "module": "services/assistant.js" }]
+  }
+}
+```
+
+There is a single manifest validator: the runtime and `acde check` / `acde build` run the same code (`@dopame/acde-api/manifest`). `acde check <dir>` checks a handwritten package.
+
+## PackageManifest
+
+| Field | Description |
+| --- | --- |
+| `apiLevel` | The contract level the package is built for, a positive integer; required. See [Contract level](#contract-level) |
+| `desktops` | List of desktops |
+| `apps` | List of apps. In a package that has a desktop they are system apps |
+| `assets` | Same-origin URL prefix (`/…/`) → list of directories in the package |
+| `services` | `{name, module}`: service name and module file. A name cannot be that of a system module or capability |
+
+## Contract level
+
+`apiLevel` says which version of the contract between packages and the runtime a package follows. The current level is 1 (`API_LEVEL` in `@dopame/acde-api`; `acde --version` and `acdert --version` print theirs). The runtime loads only packages of its own level:
+
+| Package | What the runtime and `acde check` say |
+| --- | --- |
+| No `apiLevel` (built before contract levels) | `no acde.apiLevel: a package built before contract levels; rebuild it with the current acde (level 1)` |
+| Another level | `acde.apiLevel 2: needs level 2, runtime is level 1` |
+
+A package the runtime refuses is not in the app list or the desktop list. Rebuild it with the current `acde`.
+
+## DesktopManifest
+
+| Field | Description |
+| --- | --- |
+| `id` / `name` / `description` | |
+| `entry` | The desktop page: the path of an HTML file in the package (`desktop/index.html`), not a URL |
+| `services` | The services it uses: a name, or `{name, modules}` where `modules` lists the shell modules the service may get from `ctx.import()` (see [Service API](service.md)) |
+| `heapMb` | Defaults to 1024, minimum 32 |
+
+## AppManifest
+
+| Field | Description |
+| --- | --- |
+| `id` | `[\w-]+`, required. The runtime accepts this; a config only allows `[a-z0-9][a-z0-9-]*` (see [acde.config.jsonc](config.md#appconfig)), so the looser rule matters only for a handwritten package |
+| `label` | Required |
+| `icon` | An icon name, or a URL under assets ending in `.svg` / `.png`; required |
+| `entry` | A URL starting with `/`, required. HTML or a module; a trailing `/` means the page is rendered by the backend (requires `backend`) |
+| `capabilities` | System capabilities; see below |
+| `optional` | Names from `capabilities` the app can run without |
+| `services` | Names of the desktop services the app uses |
+| `heapMb` | Defaults to 256, minimum 32 |
+| `size` | `[width, height]`, defaults to 800 × 600 |
+| `multiple` | Defaults to `false` |
+| `frame` | Defaults to `true` |
+| `mimeTypes` | File types the app can open: `type/subtype` or `type/*` |
+| `schemes` | URL schemes of the links the app can open: lowercase, without the colon, not `file` |
+| `requests` | Request kinds the app accepts from other apps: lowercase words, not `open-file` or `open-link` |
+| `backend` | `{entry, port?}`: `entry` is a `.js` / `.mjs` URL under assets; `port` defaults to 3000 |
+
+## Capabilities
+
+| Key | Value | Grants | Asks the user |
+| --- | --- | --- | --- |
+| `fs` | `true` \| `{roots: string[]}` | `acde:fs`: the private folder and picked folders; `roots` names shared places (`desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`) | |
+| `terminal` | `true` | `acde:terminal` | |
+| `network` | `true` | `acde:network` | |
+| `office` | `true` | `acde:office` | |
+| `launch` | `true` | `start` in `acde:launch` | |
+| `slots` | `true` | `embed` in `acde:launch`: native programs embedded in the app's window | |
+| `open` | `true` \| `string[]` | Opening (these) apps with `acde:open` | |
+| `openFiles` | `true` | `acde:openPath`, `acde:handlers`, and `open(request)` without a target app | |
+| `camera` / `microphone` | `true` | `getUserMedia()` video / audio | Yes. In 0.0.9, a required one when the app starts, an optional one on first use; after 0.0.9, both on first use |
+| `windows` `packages` `session` `desktops` `inspect` `desktop` `setDefault` `permissions` | `true` | The shell module of that name. System apps only: an error in any other package | |
+
+Any other key is an error: desktop services go in `services`. System apps are never asked for approval.
+
+Everything in `capabilities` and `services` is required unless `optional` lists it (`optional` takes names from `capabilities` only). An app with a required item that is missing here (unsupported on the platform, service not running) is left out of the app list and refuses to start: `Notes needs "network" (not available on macOS host windows); list it in "optional" to run without it` (404 `unsupported_app`; the place is `Windows host windows`, `Linux host windows` or `Linux sessions`), or `Notes needs "clock" (service not running)` (503 `service_not_running`). Declaring a capability grants it; only the camera and the microphone ask the user (see [Capabilities](../guide/capabilities.md#camera-and-microphone)).
+
+## URLs
+
+- Pages have the origin `http://acde.local`.
+- An app's files are served at `/app/<id>/` and also mounted at `/`; a desktop is at `/desktop/<id>/`.