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

package/lib/acde/skills/acde/references/guide/doctor.md

@@ -0,0 +1,144 @@
+# Check the setup
+
+`acde doctor` checks what `acde dev` and `acde test` need on this machine and says how to fix what is wrong; `acde doctor --fix` fixes what acde may fix itself. Run it after installing, in a project you are about to work on, and whenever `acde dev`, `acde test` or the MCP `start` does not come up.
+
+```sh
+acde doctor
+```
+
+```text
+ok     acde: 0.0.9 on Bun 1.4.4 (/Users/me/.acde/versions/0.0.9)
+ok     PATH: acde on PATH is this one (/Users/me/.acde/bin/acde)
+ok     Bun and Node.js: Bun 1.4+ at /Users/me/.bun/bin/bun; Node.js 22.3+ at /opt/homebrew/bin/node
+ok     acdert: acdert 0.0.9 (contract level 1) at /Users/me/.acde/versions/0.0.9/bin/acdert (installed next to acde)
+ok     contract level: level 1 on both sides (acdert 0.0.9, SDK 0.0.9)
+ok     host files: /Users/me/.acde/versions/0.0.9/bin/app/dist
+ok     gpu: Apple M3 Pro (Metal, integrated GPU): drew a test frame in 38 ms
+ok     acde dev sessions: none running
+ok     project: notes, app (acde.config.jsonc): acde check finds nothing wrong
+ok     platform: macos (desktop, standalone) has every required capability
+ok     dependencies: installed with bun (runs on Bun 1.4+), @dopame/acde-api 0.0.9
+ok     git: .acde/ (the build output) is ignored
+ok     agent skill: current in /Users/me/.agents/skills/acde, /Users/me/.claude/skills/acde
+acde doctor: everything acde needs is here
+```
+
+Each line is `<status> <check>: <what it found>`:
+
+| Status | Meaning |
+| --- | --- |
+| `ok` | Fine |
+| `warn` | Works, but something will get in the way; a `fix:` line follows |
+| `error` | `acde dev` or `acde test` will not work; a `fix:` line follows when there is one |
+| `skip` | Not checked: there is no project here, or the check needs one that failed |
+
+The last line counts errors and warnings. The exit code is 1 when any check is an error, else 0. `acde doctor <dir>` checks the project in `<dir>` instead of the current directory (a directory with no acde project is then an error), and `--online` adds whether a newer acde is out.
+
+## What it checks
+
+| Check | What it looks at |
+| --- | --- |
+| `acde` | The version of acde and the JavaScript runtime it runs on |
+| `PATH` | Whether the `acde` on PATH is this one, not another install or checkout |
+| `Bun and Node.js` | Bun 1.4+ and Node.js 22.3+ on PATH; `acde test` and projects that use bun need Bun |
+| `acdert` | The runtime `acde dev` would run (`ACDERT`, else the one installed next to acde, else PATH), and whether it runs |
+| `contract level` | Whether the runtime runs the contract level this acde builds, and whether it is the release this acde pairs with |
+| `host files`, `gpu`, `display` | The runtime's own check, `acdert doctor`: its host files, the GPU (it draws a small frame and reads it back), and on Linux whether a host window can open |
+| `acde dev sessions`, `approval` | The running `acde dev` sessions, and every camera or microphone prompt that waits for an answer |
+| `project` | `acde check` of the project |
+| `platform` | Whether this platform has every capability the project's apps require |
+| `dependencies` | The project's dependencies are installed (also when a workspace keeps them in a parent directory), its runtime is on PATH, and its `@dopame/acde-api` (in `package.json` and installed) is the version this acde is built with; after 0.0.9, an older SDK is reported here once, fixed by `acde sdk update` (followed by the directory when `acde doctor` was given one) |
+| `git` | Whether git ignores `.acde/` |
+| `agent skill` | Whether the acde skill is installed for coding agents and current |
+| `latest release` | With `--online`: whether a newer acde is out |
+
+## Common findings
+
+No runtime:
+
+```text
+error  acdert: acde dev needs the Dopame runtime (acdert) and found none: no /Users/me/.acde/versions/0.0.9/bin/acdert, which the acde installer puts there: run the installer again, set ACDERT to an acdert binary, or put acdert on PATH
+       fix: run the installer again: curl -fsSL https://pkgs.dopame.ai/acde/install.sh | sh (it puts the acdert that pairs with acde next to it)
+```
+
+A runtime that does not start reports why: a missing system library (`it exited with code 127: … error while loading shared libraries: …`), a file that is not executable (`EACCES`), or on macOS a binary that a download left in quarantine, with `xattr -d com.apple.quarantine <path>` as the fix.
+
+A runtime from before `acdert doctor` cannot check its files and the GPU:
+
+```text
+warn   runtime check: acdert 0.0.8 cannot check itself (it has no acdert doctor), so its GPU and host files were not checked
+```
+
+A runtime that cannot draw is an error of the `gpu` check, with the same reason `acde dev` would log at startup after `web layer unavailable:`. On Linux without the GPU's Vulkan driver:
+
+```text
+error  gpu: the system has a GPU (card0, kernel driver xe) but no usable Vulkan driver was found: install the GPU's Vulkan driver (for example vulkan-intel, vulkan-radeon, nvidia-utils) or point VK_DRIVER_FILES at its ICD (wgpu: No suitable graphics adapter found; …)
+```
+
+Install the driver (see [The runtime](../start/install.md#the-runtime)); there is no software fallback. When it works, the line names the GPU, the graphics API and the driver, such as `ok     gpu: Intel(R) Graphics (PTL) (Vulkan, integrated GPU, driver Intel open-source Mesa driver Mesa 26.2.5-arch3.1): drew a test frame in 41 ms`.
+
+On Linux in a shell with no graphical session (over SSH, for example):
+
+```text
+warn   display: neither WAYLAND_DISPLAY nor DISPLAY is set, so acdert app and acdert desktop cannot open a host window here: they would try to start a session on the screen (DRM) instead
+       fix: run acde dev --headless, or run it inside a graphical session
+```
+
+A camera or microphone prompt that waits:
+
+```text
+warn   approval: recorder waits for approval of microphone in acde dev 4242, so its getUserMedia waits until the prompt is answered
+       fix: acde allow (or acde deny): approving is the user's decision
+```
+
+## Fix what it can
+
+`acde doctor --fix` runs the checks, prints them, then fixes what it can and checks again:
+
+| Fix | When | Asks first |
+| --- | --- | --- |
+| `acde skills install` | The acde skill is not installed for any coding agent, or an installed one is outdated or broken | No |
+| Add `.acde/` to the project's `.gitignore` | git does not ignore the build output | No |
+| Remove and make again the sessions directory | It is a link or a file, not a directory | No |
+| Run the installer of this acde version again (`install.sh --version <this version> --no-modify-path`, `install.ps1 -Version … -NoModifyPath` on Windows) | The runtime next to acde is missing, does not run, is of another contract level or release, or lacks its host files; only for an installed acde, and not when `ACDERT` names the runtime | Yes: it downloads the runtime and replaces the install, all or nothing, as the installer always does |
+| The project's install (`bun install`, `npm install`, …) | Its dependencies are not installed | Yes: it downloads packages and runs their install scripts |
+| `acde stop --session <pid>` | A running `acde dev` does not answer | Yes: it ends a process you started |
+
+In a terminal it asks about each fix in the last column. Without a terminal (a script, a coding agent) it skips them and says so, `skipped: … (it asks first: pass --yes to allow it)`, unless it is given `--yes`. A coding agent passes `--yes` only when the user agreed.
+
+It never touches what is the user's to decide: a camera or microphone prompt, a GPU driver or a system library, a binary in macOS quarantine, another acde on PATH, the project's code and config. Those keep their `fix:` line.
+
+```text
+fixing: install the acde skill for the coding agents found here (acde skills install)
+acde: skill linked to /Users/me/.agents/skills/acde (Cline, Codex, …)
+fixed: install the acde skill for the coding agents found here (acde skills install)
+skipped: install the project's dependencies (bun install in /Users/me/notes) (it asks first: pass --yes to allow it)
+acde doctor: after fixing:
+ok     acde: 0.0.9 on Bun 1.4.4 (/Users/me/.acde/versions/0.0.9)
+…
+```
+
+## acde dev points here
+
+When `acde dev` finds no runtime, its error ends with `(acde doctor checks the whole setup)`. When the runtime exits before the session is ready, `acde dev` prints the runtime's log line and then:
+
+```text
+acde: acdert exited (1) before it was ready; acde doctor checks the runtime, the GPU and this setup
+```
+
+## In scripts and agents
+
+`acde doctor --json` prints one object:
+
+```json
+{
+  "ok": false,
+  "checks": [
+    { "id": "acdert", "title": "acdert", "status": "error", "summary": "…", "fix": "…" }
+  ]
+}
+```
+
+`ok` is false when a check is an error. A check that `--fix` can repair carries `"repair": {"action", "target", "ask", "does"}` (`ask` is true for the fixes that ask first), and with `--fix` the object also has `"fixed": [{"repair", "result", "said"}]`, `result` being `fixed`, `failed` or `skipped`; the progress lines then go to stderr. The ids are `acde`, `path`, `runtimes`, `acdert`, `contract`, `runtime` (when the runtime cannot check itself), `runtime.host`, `runtime.gpu`, `runtime.display`, `sessions`, `approval`, `project`, `platform`, `dependencies`, `gitignore`, `skill` and `latest`; `fix` is left out when there is none. The MCP server has the same check as its `doctor` tool, and the fixes that do not ask as `doctor_fix` (it names the others and leaves them to the user); see [MCP](mcp.md).
+
+The runtime's part also runs on its own, `acdert doctor` (or `acdert doctor --json`), with the same exit codes.

package/lib/acde/skills/acde/references/guide/files.md

@@ -0,0 +1,181 @@
+# Files and folders
+
+There are three ways to read and write files:
+
+1. **Standard file pickers**: `showOpenFilePicker`, `showSaveFilePicker`, `showDirectoryPicker`, `<input type="file">`. No capability needed; you get whatever the user picks.
+2. **`acde:fs`**: files by "root": the app's own private folder, the shared folders it names (Downloads, Documents, ...), and folders the user picked. Suited to apps like file managers and editors. Requires the `fs` capability.
+3. **Private storage**: `navigator.storage.getDirectory()` (OPFS), IndexedDB, `localStorage`, for the app's own data.
+
+An app works with handles and root ids, not with absolute paths; only the desktop and its bundled system apps see paths.
+
+## File pickers
+
+They work just like in a browser:
+
+```js
+const [handle] = await window.showOpenFilePicker({
+  types: [{ description: 'Markdown', accept: { 'text/markdown': ['.md'] } }],
+})
+const text = await (await handle.getFile()).text()
+```
+
+- The dialog is the system's own (the open / save panel on macOS, the file dialog on Windows, the portal on Linux).
+- Only this page can read and write the picked file.
+- A folder picked with `showDirectoryPicker()` is also **granted to the app**: it shows up as a root in `acde:fs` (`source: 'granted'`) and is still there on the next launch. The default pick is read-only (the root has `mode: 'read_only'`); `showDirectoryPicker({ mode: 'readwrite' })` gives a writable one. Give it back with `fs.revoke(id)`.
+- When the user cancels, the promise rejects with `AbortError`. A headless session has no dialog: a picker rejects with `AbortError` there too, unless a test answered it in advance (`chooseFiles`, `chooseFolder`, `chooseSaveFile`; see [Testing](testing.md)).
+
+## acde:fs
+
+```jsonc
+{ "capabilities": { "fs": true } }
+```
+
+```js
+import { fs } from 'acde:fs'
+
+const roots = await fs.roots()
+// [{ id: 'private', label: '…', source: 'private', mode: 'writable', reason: null, exists: true }]
+
+await fs.writeFile('private', 'notes/todo.md', '- buy milk\n', { mkdirs: true })
+
+const { entries } = await fs.list('private', 'notes')
+const { text, modifiedMs } = await fs.readText('private', 'notes/todo.md')
+await fs.writeFile('private', 'notes/todo.md', text + '- a new item\n', { ifModifiedMs: modifiedMs })
+```
+
+### Roots
+
+The first argument of every call is a root's **`id`**, and the second is a path under that root. A root's `id` is an opaque name, not a path: `fs.list('/home/me/Downloads')` is rejected.
+
+There are three kinds of root:
+
+| `source` | `id` | What it is | How the app gets it |
+| --- | --- | --- | --- |
+| `private` | `private` | The app's own data folder, created on first use | `"fs": true` (or any `fs` value) |
+| `place` | The place's name, such as `downloads` | A shared folder of the user | Name it in `fs.roots` (see [Shared places](#shared-places)) |
+| `granted` | `folder-` plus 16 hex digits | A folder the user picked | `showDirectoryPicker()` |
+
+`roots()` returns one item per root the app can use now: `{id, label, source, mode, reason, exists}`, plus `place` (the place's name) for a shared place. `label` is a name to show the user (the folder's name for a picked folder). `mode` is `writable`, `read_only` (a folder picked without `mode: 'readwrite'`), or `unavailable`; when it is `unavailable`, `reason` says why (`the folder does not exist`) and `exists` is `false`.
+
+Find a picked folder's root by the handle's name:
+
+```js
+const handle = await window.showDirectoryPicker({ mode: 'readwrite' })
+const picked = (await fs.roots()).find((root) => root.source === 'granted' && root.label === handle.name)
+await fs.writeFile(picked.id, 'export.txt', 'hello')
+```
+
+**Keep working data in `private`.** It needs no declaration beyond `fs` and no picker, it is always writable, and it is not a root of any other app. Use a shared place or a picked folder only for files the user should find outside the app. On disk the private folder is `$XDG_DATA_HOME/acde/files/<app id>/`, which is handy when debugging; the app itself only knows it as `private`.
+
+### Shared places
+
+```jsonc
+{ "capabilities": { "fs": { "roots": ["downloads", "documents"] } } }
+```
+
+`fs.roots` lists shared places by name: `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`. Anything else fails `acde check`: `fs.roots "work" is not a shared place (desktop, documents, downloads, music, pictures, videos); any other folder is one the user picks (showDirectoryPicker() with "fs": true)`, and for a path, `fs.roots "~/Documents" is not a shared place: write "documents", the runtime finds that folder through the system (also when it was moved)`. `private` and picked folders come with every `fs` value and are not listed.
+
+Declaring a place is what gives the app access to it; the user is not asked. Each named place is then in `roots()` as `{ id: 'downloads', source: 'place', place: 'downloads', … }` and its `id` works as the first argument: `fs.list('downloads')`. When the folder does not exist on this machine, the root has `mode: 'unavailable'` and calls on it reject with `ENOENT`.
+
+### Paths
+
+The second argument is a **relative path** under the root, separated by `/`; `''` (or leaving it out in `list`) is the root itself. Absolute paths, and escaping the root with `..` or a symbolic link, are rejected.
+
+### Common calls
+
+| Call | Returns |
+| --- | --- |
+| `roots()` | The roots the app can use now |
+| `list(root, path?, hidden?)` | `{root, path, entries, truncated, skipped?}`: folders first, at most 5000 entries (`truncated`); hidden entries (a leading dot, on Windows also the hidden or system attribute) only with `hidden` `true`; `skipped` counts entries whose names are not valid Unicode |
+| `stat(root, path)` | `{name, kind, size, modifiedMs, version, path}` (does not follow symbolic links) |
+| `readText(root, path)` | `{text, modifiedMs, size, version}`, up to 64 MiB, `EILSEQ` if not UTF-8 |
+| `readBytes(root, path)` | `{data: Uint8Array, modifiedMs, size, version}`, up to 64 MiB |
+| `writeFile(root, path, data, options?)` | Writes text or bytes, up to 64 MiB; returns the entry with its new `version` |
+| `readRange(root, path, offset, length, {ifVersion}?)` | `{data, offset, size, modifiedMs, version}`: part of a file, at most 16 MiB at a time; `size` is the whole file's |
+| `mkdir(root, path, {recursive?})` | Creates a folder |
+| `rename(root, from, to)` | Renames / moves inside one root |
+| `delete(root, path)` | Deletes a file or an empty folder: `{status: 'deleted', path}` |
+| `copy(fromRoot, fromPath, toRoot, toDir)` | Copies a file or a folder into the folder `toDir` of another root (or the same one); returns the new entry and its `path`. A taken name gets a number (`todo 2.md`) |
+| `revoke(id)` | Gives back a folder the user picked |
+
+To bring a file from a shared place or a picked folder into the app's own data, copy it: `await fs.copy('downloads', 'report.txt', 'private', '')`.
+
+### Safe writes
+
+Options for `writeFile`:
+
+- `create`: `'always'` (default, creates the file if missing), `'new'` (`EEXIST` if it already exists), `'never'` (`ENOENT` if it does not exist).
+- `ifVersion`: skips the write and fails with `ECONFLICT` if the file is no longer the one you read. Every read returns a `version` (an opaque string that tells two states of the file apart, even two writes in one millisecond); pass it when you write, and you will never overwrite someone else's changes. `ifModifiedMs` does the same with the modification time; `ifVersion` is the safer of the two. Neither goes with `create: 'new'`.
+- `mkdirs`: creates the parent folders first. Without it, writing into a folder that does not exist fails with `EINVAL`.
+
+A write replacing a file goes to a temporary file in the same folder first, is fsynced, and then replaces the file atomically (keeping its permissions; on Windows its attributes and ACL), so a crash leaves either the old or the new content. When the folder does not let the app create a file, it writes into the original file instead and the returned entry has `inPlace: true`: that write is not crash-safe.
+
+### Large files
+
+The whole-file calls stop at 64 MiB. For larger files use the standard handles: `getFile()` gives a `File` that reads on demand (`slice()`, `stream()`), and `createWritable()` writes at any position into a temporary file that `close()` puts in place atomically. `acde:fs` has the same as calls: `readRange()` above, and `openWrite(root, path, {keepExistingData, create, ifVersion, mkdirs}?)` → `{id, size}`, then `writeChunk(id, offset, data)` (at most 16 MiB a call), `truncateWrite(id, size)`, and `commitWrite(id)` (returns the entry with its `version`) or `abortWrite(id)`. With `ifVersion`, a change by someone else between the open and the commit is `ECONFLICT` and the file stays as it was. A write that is left alone for 10 minutes is given up.
+
+### Errors
+
+On failure the promise rejects with an `Error` that has a `code` and a `status`:
+
+| `code` | `status` | When |
+| --- | --- | --- |
+| `EINVAL` | 400 | Invalid arguments, an absolute path or one that escapes the root, a missing parent folder, wrong type, symbolic link |
+| `EACCES` | 403 | The first argument is not one of the app's roots, the root is read-only, or the system does not allow it |
+| `ENOENT` | 404 | Does not exist |
+| `EEXIST` | 409 | Already exists |
+| `ECONFLICT` | 409 | Changed or deleted by someone else since it was read (`ifVersion`, `ifModifiedMs`) |
+| `ENOTEMPTY` | 409 | Deleting a non-empty folder |
+| `EFBIG` | 413 | Exceeds the size limit |
+| `EILSEQ` | 400 | `readText` read something that is not UTF-8 |
+| `ENOSPC` | 507 | Disk full |
+| `EIO` | 500 | Anything else |
+
+```js
+try {
+  await fs.writeFile(root, path, text, { ifModifiedMs })
+} catch (e) {
+  if (e.code === 'ECONFLICT') askToReload()
+  else throw e
+}
+```
+
+What the common mistakes look like:
+
+| Mistake | Rejection |
+| --- | --- |
+| A path as the root: `fs.list('/tmp')` | `EACCES`: `this app may not use the files of /tmp (not one of its roots)` |
+| A place that is not in `fs.roots`: `fs.list('downloads')` with `"fs": true` | `EACCES`: `this app may not use the files of downloads (not one of its roots)` |
+| An absolute path as the second argument: `fs.readText('private', '/etc/hosts')` | `EINVAL`: `path must be relative to the workspace` |
+| `..` out of the root: `fs.readText('private', '../x')` | `EINVAL`: `path escapes the workspace` |
+| Writing into a folder that does not exist, without `mkdirs` | `EINVAL`: `parent directory is missing or outside the workspace` |
+| Writing to a folder picked without `mode: 'readwrite'` | `EACCES`: `<folder> was picked read-only` |
+| `fs.locate(path)` or `fs.openPath(root, path)` (they turn paths into roots and back) | `EACCES`: `fs.locate() works only in system apps that declare shared places` |
+
+## Dropped files
+
+When files or folders are dragged from the host system into a window, the page receives the standard drag events, ending in `drop`, and `dataTransfer` carries the files the standard way. The page gets no path.
+
+- Each dropped file or folder is an item of `dataTransfer.items` with `kind: 'file'`; `item.getAsFileSystemHandle()` resolves to a **read-only** `FileSystemFileHandle` or `FileSystemDirectoryHandle` (`createWritable()` rejects with `NotAllowedError`).
+- Files up to 64 MiB are also in `dataTransfer.files`. Folders and larger files are not; use their handles.
+- `dataTransfer.types` is `['Files']`; there is no `text/uri-list` or `text/plain` with the paths.
+
+To keep a dropped file, copy its content into `private`:
+
+```js
+import { fs } from 'acde:fs'
+
+addEventListener('dragover', (event) => event.preventDefault())
+addEventListener('drop', async (event) => {
+  event.preventDefault()
+  const items = [...event.dataTransfer.items].filter((item) => item.kind === 'file')
+  const handles = await Promise.all(items.map((item) => item.getAsFileSystemHandle()))
+  for (const handle of handles) {
+    if (handle.kind !== 'file') continue
+    const file = await handle.getFile()
+    await fs.writeFile('private', `inbox/${file.name}`, new Uint8Array(await file.arrayBuffer()), { mkdirs: true })
+  }
+})
+```
+
+A handle (from a drop, a picker, or an open request) can also be handed to another app; see [Opening apps](open.md#files-and-links).

package/lib/acde/skills/acde/references/guide/frameworks.md

@@ -0,0 +1,74 @@
+# Frameworks
+
+acde doesn't ask you to change your framework's config. At build time it recognizes the framework from your dependencies, runs **the framework's own build**, and puts the output into the package. The first match wins:
+
+| Dependency | Build command | Output |
+| --- | --- | --- |
+| `next` | `next build` (standalone) | `.next/standalone` as the backend; static `out/` with `output: 'export'` |
+| `nuxt` (or `nuxt3`) | `nuxt build` (`node-server` preset) | `.output/server/index.mjs` as the backend, `.output/public` |
+| `@sveltejs/kit` | `vite build` | The server is wrapped as the backend; `client` is the static assets |
+| `astro` | `astro build` | `dist/`; a backend if `dist/server/entry.mjs` exists |
+| `@react-router/dev` / `@remix-run/dev` | `react-router build` / `remix vite:build` | A backend if `build/server/index.js` exists |
+| `@angular/core` + `@angular/cli` | `ng build --configuration production --base-href /` | `dist/**/browser`; a backend if `server/server.mjs` exists |
+| `vite` | Calls the project's Vite `build()` in process, reading its `vite.config` | Static pages |
+| `react-scripts` | `react-scripts build` | `build/` |
+| A `build` script in `package.json` | `bun --bun run build` when acde runs on Bun, otherwise `<pm> run build` | The first of `dist` / `build` / `out` / `www` / `.output/public` that contains HTML |
+
+For server-rendered frameworks, pages are generated by the backend, and the manifest's `entry` is `/app/<id>/` (ending in `/`).
+
+If there's no `node_modules`, acde runs `<pm> install` first.
+
+To start a project with one of these frameworks, `acde new --template` has `next`, `nuxt`, `sveltekit` and `astro`, and the Vite templates `react`, `vue`, `svelte`, `solid`, `preact` and `vanilla`; see [First app](../start/first-app.md#create).
+
+## Saving in acde dev
+
+`acde dev` runs the same production build after every save and **reloads the whole page**; it does not use the framework dev server or hot module replacement (HMR). Across the reload, acde restores form values, scroll position, focus and text selection, but **component state is lost**: a React or Preact `useState` counter, Vue `ref`s, Svelte and Solid signals, and any other value held only in memory start over. Keep state you want to survive a reload in `localStorage` or IndexedDB. See [Reloading](dev.md#reloading).
+
+After 0.0.9, pages made by `acde new --template react` (and the other Vite templates) say "save to reload the page" where Vite's own templates say "save to test HMR".
+
+## Detection
+
+Use `framework` in `acde.config.jsonc`:
+
+- `auto` (default): detect using the table above.
+- `next`, `nuxt`, `sveltekit`, `astro`, `react-router`, `remix`, `angular`, `vite`, `cra`, `script`: use this one.
+- `none`: no framework; acde bundles `entry` itself.
+
+When `entry` is set, acde doesn't pick up Vite (the built-in templates depend on Vite only so acde can bundle with it). To build with Vite, remove `entry` or set `"framework": "vite"`.
+
+## Without a framework
+
+When no framework is recognized (or with `"framework": "none"`), acde bundles from `entry`:
+
+- HTML entry: `base` is `/app/<id>/`, `acde:*` imports stay external, `NODE_ENV` is `"production"`, and `import.meta.env` works as in Vite (including `VITE_*` variables).
+- Module entry: bundled into `<name>.js` with its exports kept; the default export is a `WindowApp`.
+
+On Bun it uses `Bun.build`; on Node.js it uses the project's Vite (if it's missing, you're told to `add it with <pm> add -D vite`). The rules are the same on both.
+
+## Vite plugin
+
+If you `import { fs } from 'acde:fs'` in a Vite project, the dev server (`vite dev`, in a regular browser) doesn't know about `acde:` modules. Add the SDK's plugin:
+
+```js
+// vite.config.js
+import acde from '@dopame/acde-api/vite'
+
+export default {
+  plugins: [acde()],
+}
+```
+
+At build time, `acde:*` imports stay external. In the dev server they're replaced with a stub: calls reject with `only there when the app runs in acde`, and `on()` returns a no-op unsubscribe function. That way the same code still opens in a browser.
+
+acde adds this plugin automatically when it builds a project with Vite.
+
+## acde: modules
+
+If the same code needs to run both in a browser and in acde, use `load()`. It returns `null` when the module isn't available:
+
+```js
+import { load } from '@dopame/acde-api'
+
+const fs = await load('fs')
+if (fs) console.log(await fs.roots())
+```

package/lib/acde/skills/acde/references/guide/install.md

@@ -0,0 +1,34 @@
+# Local install
+
+`acde dev` hands your app to the runtime only temporarily. To keep the app in the Dopame desktop on this machine:
+
+```sh
+acde install
+```
+
+This runs `acde build`, then installs the package into `$XDG_DATA_HOME/acde/packages/<id>` (by default `~/.local/share/acde/packages/<id>`, on Windows `%USERPROFILE%\.local\share\acde\packages\<id>`). It copies to a temporary directory first and then swaps the whole directory in, so you never end up with half a package. A handwritten package (no config, with its own `acde` manifest in `package.json`) is installed as a symlink to the project.
+
+Once installed, the next session you start (and `acde dev --desktop dopame`) will see it.
+
+## Package lookup
+
+In this order; for a given id, the first one found wins:
+
+1. Directories in `ACDE_PATH` (this is how `acde dev` hands over its builds);
+2. `$XDG_DATA_HOME/acde/packages/*`;
+3. `$XDG_DATA_DIRS/acde/packages/*` (system-wide installs).
+
+## Uninstall
+
+```sh
+acde uninstall          # the installed packages: id and path
+acde uninstall <id>     # or the project directory it was installed from
+```
+
+It says what it removes and asks first (`--yes` skips the question, and is needed outside a terminal). A copied package's directory is removed; for a handwritten package only the link is removed, never the project. A package that a running `acde dev` session uses is not removed: stop that session first.
+
+The apps' data is kept: under `~/.local/share/acde/` their storage (`storage/app-<id>/`), backend data (`apps/<id>/`) and private files (`files/<id>/`), their folder grants (`~/.local/state/acde/grants/<id>.json`), and their entries in `~/.config/acde/permissions.json` (camera and microphone decisions) and `~/.local/state/acde/windows.json` (window places). After 0.0.9 it is kept unless you ask, and removing it takes all of these (other apps' entries in the shared files stay): in a terminal `acde uninstall` asks whether to remove it too; `--data` removes it and `--keep-data` keeps it without asking. With `--yes` alone it is kept, and the paths are printed. [acde uninstall](../reference/cli.md#acde-uninstall) lists the exit codes.
+
+## Publishing
+
+An app store and `acde publish` are still in the works. For now, distributing an app means distributing the built package directory (`.acde/`); put it in any of the locations above.

package/lib/acde/skills/acde/references/guide/mcp.md

@@ -0,0 +1,64 @@
+# MCP
+
+`acde mcp` is an [MCP](https://modelcontextprotocol.io) server over stdio. It gives AI agents the [debugging tools](tools.md) and more: an agent can start an `acde dev` session itself, look at the screen, click buttons, read the console, and take screenshots, so it can build and verify your app.
+
+Agents can do all of this with the plain [debugging commands](tools.md) too, which need no setup; the [acde skill](agents.md) teaches them how. Use MCP when your agent works better with tools than with a shell.
+
+## Setup
+
+Claude Code:
+
+```sh
+claude mcp add acde -- acde mcp
+```
+
+Other clients: the command is `acde mcp`, with no arguments (add `--session <pid>` to pin a particular session).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `doctor` | Checks this machine for `acde dev`, as [`acde doctor`](doctor.md) does; call it first when `start` fails |
+| `doctor_fix` | Checks, fixes what acde may fix without asking, and checks again, as `acde doctor --fix` does. The fixes that download, install or stop something it only names: the user runs `acde doctor --fix` in a terminal (it asks), or agrees to `acde doctor --fix --yes`. Its `dir` must be inside the working directory |
+| `sessions` | Lists running `acde dev` sessions; can pin one |
+| `start` / `stop` / `logs` | Starts its own `acde dev` session (for the project in the working directory by default), stops it, reads its output. After 0.0.9, when an `acde dev` already runs exactly that (the same projects, `desktop`, `app` and `headless`), `start` uses that session and says so (`attached to acde dev <pid>, which already runs …`); `stop` and `logs` do not reach a session started elsewhere. When one runs those projects some other way, `start` fails and names it (`… which is not what start asked for`): pin it with `sessions {use: <pid>}`, or stop it first. `start {force: true}` starts another one anyway |
+| `webs` | Lists pages, and the camera or microphone prompts that wait |
+| `permissions` / `answer` / `revoke` | Lists the camera and microphone prompts that wait and the decisions made, allows or denies a waiting prompt, takes back a decision; see [Camera and microphone](tools.md#camera-and-microphone) |
+| `snapshot` | The screen as text: windows and the elements of the focused window, each with a ref |
+| `act` / `run` | Performs one action on a ref / several in sequence, and reports what changed |
+| `open` | Opens an app and waits for its window |
+| `query` | Finds elements by CSS selector, hidden ones too; the refs work with `act` |
+| `wait_for` | Waits for some text to appear (or disappear) |
+| `screenshot` | Screenshot of one window or the whole screen |
+| `eval` | Runs JS in a page |
+| `console` / `network` | The pages' logs and requests |
+| `emulate` | Switches light/dark mode |
+| `choose_folder` / `choose_files` / `choose_save_file` | Answers the page's next file picker in advance |
+| `route` / `unroute` | Fakes responses to the page's requests, or makes them fail |
+| `pointer` | Moves the pointer to a screen point, as a real move (hover, screen edges) |
+| `clipboard` | Reads and writes the clipboard |
+| `input` | Sends raw mouse and keyboard events to a page, at page coordinates; `wait` (`ms`) holds a key or button in between (after 0.0.9) |
+| `clock` | Takes over a page's time: installs a fake clock, pauses it, moves it forward |
+| `dialog` | Answers the page's next `alert` / `confirm` / `prompt` in advance, and lists the dialogs it showed |
+| `resize` | Resizes a window so that its page has the given size |
+
+Which session is used: the pinned one; otherwise the one `start` launched; otherwise one picked by the working directory.
+
+Declared capabilities need no answer; only the camera and the microphone ask the user. In 0.0.9 an app that declares one is asked when it starts, and its window waits for the answer; after 0.0.9 the user is asked the first time a page asks for one, and the page waits for the answer. `webs` lists such a prompt as a line, `recorder waits for approval of microphone: the answer tool allows or denies it`. `answer` takes `allow` (true or false). To allow, it must name the `app` and the `capability` that `permissions` lists, so the call states what is granted; to deny, the `prompt` id or the `app` and `capability` will do, and neither is needed when only one prompt waits. It stands in for the user's own answer, so the tool is marked as an action that needs confirmation: allow only what the user asked for or agreed to.
+
+Closing the only window of a session that runs a single app (`act` with `close` on `w1`) ends that session, by design. The call succeeds and its answer says so, `closed w1; acdert exited with it, so acde dev 4242 ended`. The next call fails and says that the session stopped (`the acde dev started here (pid 4242) stopped; last output: …` for a session `start` ran, `acde dev 4242 stopped; no acde dev is running (…)` for one started elsewhere). Run `start` again to go on. Any other action during which the runtime goes away fails with `acdert closed the connection`; so does a `run` whose steps close that window, since the answer to its steps is lost, so close it with `act`.
+
+`input`, `clock`, `dialog` and `resize` do for an agent what `app.mouse` / `app.keyboard`, `app.clock`, `app.answerDialog` and `app.resize` do in a test; see [Time, dialogs and page setup](testing.md#time-dialogs-and-page-setup). `clock` takes `action` (`install`, `pause_at`, `fast_forward`, `run_for`, `resume`, `set_fixed_time`, `set_system_time`, `state`) with a `time` (an ISO string or milliseconds since 1970) or a `duration` (milliseconds, `"mm:ss"` or `"hh:mm:ss"`). `dialog` without `accept` or `text` only lists.
+
+A page's folder, file or save picker can be answered before the page opens it: call `choose_folder` with a `path` (relative paths resolve against the working directory), or with `cancel: true`, then the `act` that opens the picker. Each answer serves the next picker of that kind. In a session started with `start {headless: true}` there is no picker dialog, so a picker that was not answered first fails and the page sees it as cancelled. `choose_files` takes `paths`, `choose_save_file` a `path`.
+
+```json
+{ "name": "choose_folder", "arguments": { "path": "fixtures/project" } }
+{ "name": "act", "arguments": { "ref": "w1.4", "action": "click" } }
+```
+
+On a machine without a display, call `start` with `headless: true`; `screenshot` and `snapshot` work the same. `eval` with `getComputedStyle` or `getBoundingClientRect` checks styles and layout, as in [Styles and layout](tools.md#styles-and-layout).
+
+In a session with windows, `clipboard` touches **your system clipboard**, so the agent must pass `system: true` explicitly, and the tool is marked as an action that needs confirmation. Headless sessions have their own clipboard.
+
+When the server's stdin closes or it receives a signal, it stops the `acde dev` session that `start` launched.

package/lib/acde/skills/acde/references/guide/open.md

@@ -0,0 +1,107 @@
+# Opening apps
+
+## Apps
+
+```jsonc
+{ "capabilities": { "open": ["viewer"] } }
+```
+
+```js
+import { open } from 'acde:open'
+
+const { window } = await open('viewer', { kind: 'show-image', image: '/photos/cat.png' })
+```
+
+The second argument is a **request**: a structured-cloneable object with a `kind`, handed to the other app. `open('viewer')` without a request just opens the app (or brings its window to the front). Setting the `open` capability to `true` allows any app; a list allows only the apps listed.
+
+The app being opened says which kinds of request it accepts in its config, and receives them through the `request` event:
+
+```jsonc
+{ "id": "viewer", "requests": ["show-image"] }
+```
+
+```js
+import { window as self } from 'acde:window'
+
+self.on('request', (request) => {
+  if (request.kind === 'show-image') showImage(request.image)
+})
+```
+
+`requests` lists the app's own request kinds (lowercase words such as `show-image`). The runtime checks only the `kind`; the receiving app checks the rest of the object. An app with no `requests` accepts none.
+
+For a window opened for a request, the request is delivered once, to the first `request` handler only; a request that arrives before any handler is registered is held and delivered when one is. An app that is not `multiple` and already runs gets the request in its existing window.
+
+`open(app, request, { parent, modal })` makes the new window a child of one of your own windows (`parent` is a window id, such as `self.id`), centered over it; `modal: true` keeps input away from the parent until the child closes.
+
+What goes wrong:
+
+| Call | Rejection (`status`, `code`) |
+| --- | --- |
+| `open('mail')` when `open` does not allow `mail` | 403 `forbidden`: `Notes may not use open mail (not in its manifest's capabilities)` |
+| A request without `kind` | 400 `untyped_request`: `a request to viewer needs a kind` |
+| A `kind` that is not in the target's `requests` | 409 `not_accepted`: `viewer does not accept other-kind requests (its manifest's requests)` |
+
+To list the installed apps, use `acde:apps`; its `open` is the same function:
+
+```js
+import { apps } from 'acde:apps'
+
+const installed = await apps.list() // [{ id, label, icon, script }]
+```
+
+## Files and links
+
+An app declares the file types and the link schemes it can open in its config:
+
+```jsonc
+{
+  "id": "notes",
+  "mimeTypes": ["text/markdown", "text/plain"],
+  "schemes": ["mailto"]
+}
+```
+
+When the user double-clicks a `.md` file in the file manager, or another app asks for it to be opened, the system picks an app in this order:
+
+1. The default app the user has set (XDG MIME Applications spec, `mimeapps.list`; on Windows it is remembered per file extension);
+2. The first app whose `mimeTypes` lists the type (an exact type wins over `text/*`);
+3. A native program (Dopame OS / Linux), or the system's default program (the host window on macOS and Windows).
+
+The chosen app receives a **system request**. A file arrives as `{ kind: 'open-file', handle }`, where `handle` is a standard `FileSystemFileHandle` (or a directory handle); a link arrives as `{ kind: 'open-link', url }`. The app gets no path:
+
+```js
+self.on('request', async (request) => {
+  if (request.kind === 'open-file') showText(await (await request.handle.getFile()).text())
+  if (request.kind === 'open-link') compose(request.url)
+})
+```
+
+Apps that request `openFiles` can hand a file or a link to its default app themselves. Leave out the app id and the system picks:
+
+```js
+import { open } from 'acde:open'
+
+await open({ kind: 'open-file', handle }) // a handle from a picker, a drop, or a request
+await open({ kind: 'open-link', url: 'mailto:someone@example.com' })
+```
+
+The same order picks the app, so an app that lists the file's type in `mimeTypes` gets its own file back as a request (unless the user set another default app); there is no way to ask for the system's program instead. On macOS and Windows the system's default program takes only regular files of documents and media: `pdf`, images (`png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `tif`, `tiff`, `heic`, `heif`, `avif`, `ico`), audio and video (`mp3`, `wav`, `ogg`, `oga`, `flac`, `m4a`, `aac`, `opus`, `wma`, `mp4`, `m4v`, `webm`, `mov`, `mkv`, `avi`, `wmv`), `txt`, `md`, `csv`, `log`, `json`, and office documents (`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`). A folder, an `.html` page or any other file is refused, and the promise rejects with a message such as `no app can open this kind of file (text/html): /…/index.html is not handed to the system: only documents and media open in system apps, not .html files`. `http` and `https` links open in the default browser.
+
+With an app id (`open('viewer', { kind: 'open-file', handle })`) the request goes to that app; this needs `open` rather than `openFiles`, and is rejected with 409 `not_accepted` when the target does not declare the file's type in `mimeTypes` or the link's scheme in `schemes`. A read-only handle (from a drop) stays read-only for the receiver.
+
+`acde:openPath` and `acde:handlers` (also `openFiles`) work with a path or a URI instead of a handle:
+
+```js
+import { openPath } from 'acde:openPath'
+import { handlers } from 'acde:handlers'
+
+await openPath('/home/me/Notes/todo.md')
+const { mime, association, handlers: list } = await handlers('/home/me/Notes/todo.md')
+```
+
+They suit the desktop and system apps, which know paths. For an ordinary app the file must be inside one of its `acde:fs` roots, or the call is rejected with 404 `outside_roots`; an app that holds handles uses `open({ kind: 'open-file', handle })`.
+
+Changing the default app for a type is `setDefault(association, app)` from `acde:setDefault`, a shell module for the desktop and system apps (`association` is the value `handlers()` returned).
+
+File types are detected with shared-mime-info, so a dev session on macOS gets the same results as Dopame OS (for example, `.md` is `text/markdown`). On macOS this needs `brew install shared-mime-info`; without it, a one-line warning is printed. On Windows the types are the ones the system has registered for each file extension, and a name it knows no type for has the type `''`.