Importer

Every way in goes through one install pipeline, run by the CLI:

acquire → inspect → sanitize → revendor → customize → place → register → dependencies → gate → serve → open

It is what makes an app from elsewhere safe to have, so never do its work by hand: never unzip a package into place, never copy one's credentials or data, never re-vendor someone else's app yourself. What the pipeline guarantees:

• Nothing from the source runs before the dependencies step, and what runs then is the pipeline of a toolkit installed on this machine, chosen by the id the package records, never by a path it records.
• Credentials, data, runtime state, .git/, node_modules/ and build output are dropped; the app gets a fresh identity, port and credential.
• A step that fails leaves nothing behind. The one exception is the gate: an app that fails it stays installed so it can be fixed, and the result says so.

Every command prints JSON on stdout (diagnostics go to stderr) and exits 0 success, 1 rejected, 2 usage, 3 unreachable. Read the JSON; never scrape the prose.

Which path?

Marketplace

1. Find the id: agent-app catalogue --search "<their words>". Install only an id this returns; never guess one. Each entry says whether it runs here: compatible: true; false with a reason (a Living UI app → Convert, a toolkit not installed here → say which); null when the entry states no requirement. --source <marketplace> reads another marketplace (github:<owner>/<repo>[@<ref>], or a local directory).
2. Confirm with the person: which app, its name, and its customizable fields (offer each default).
3. Install: agent-app install <id> [--set KEY=VALUE]… [--name "<name>"]. The result's trust is catalogued: the app was verified upstream, so nothing more is owed — no walk-verify. Give the person its url.
4. Consent is still theirs. If the app declares integrations (capabilities) or queues work for agents, ask before granting any. Never start a bridge for it (agent-app <dir> bridge start): each task it queues becomes an agent run, a capability a person grants knowingly, for an app they chose.

A zip, a folder, or a git repository

1. Inspect first: agent-app inspect --from <source>. Nothing is installed and nothing from it runs. <source> is:
   • a zip file (any file is read as a zip);
   • a folder (copied, never moved: the folder is left as it was);
   • github:<owner>/<repo>[@<ref>][/<path>], or https://github.com/<owner>/<repo>[/tree/<ref>/<path>];
   • any other git host: git+<url>[#<ref>].
2. Show the person the report, and ask. Say what it is (kind), whether it is installable and why not, what will run on their machine (pipeline: the commands of the toolkit installed here, not the package's), what install removes (strips), whether its system files match its own record (integrity), what it declares (capabilities), and every warnings entry.
3. An installable package: agent-app install --from <source> [--name "<name>"]. Its trust is untrusted, and its next names what is owed: before the app is used for real work, a separate agent — never you, the installer — runs the walk-verify skill against it. Until then, report it as installed and unverified.
   • Not installable because its toolkit is not here: the reason names it. --blueprint <id> re-vendors it from another toolkit installed here, but that toolkit's system files replace the package's, so only with the person's agreement.
   • The person wants the app to stay in its folder: agent-app <dir> import runs the same pipeline in place (untrusted, the same walk-verify owed). It refuses a folder whose app is serving: agent-app <dir> stop first.
4. Not a package: the report's routes say what can be done instead — Convert (convert) or Adopt (adopt), below.

install is the same for both kinds of source: a source that turns out not to be a package stops at inspect, with { ok: false, step: "inspect", kind, reason, routes }. Take it to the route; never force it.

Convert — a rebuild

For a CraftBot Living UI app, or foreign code the person wants rebuilt as an Agent App. Tell the person the cost first: nothing of the original code runs afterward; its behaviour is re-implemented.

1. Scaffold a new app on the blueprint that fits what it does: agent-app <dir> scaffold --blueprint <id>.
2. Keep the original as a read-only reference — the CLI fetches it, from any source, without its credentials, data or build output: agent-app inspect <catalogue id> --keep <dir>/reference/source, or agent-app inspect --from <source> --keep <dir>/reference/source. Read it; never edit it, never run it.
3. Synthesize reference/requirements.md from it — its screens, its data, what each action does — and build it with the creator skill: feature by feature under the ownership rule, agent-app <dir> validate, launch, and a walk-verify by a separate agent before announcing it.

Adopt — run it as it is

For a foreign app that must keep running unchanged: any HTTP app, in any stack. The app runs from upstream/, and the sidecar adapter in front of it serves the A2App surface and forwards each declared operation to one of its own routes.

1. Scaffold on the sidecar blueprint: agent-app <dir> scaffold --blueprint blueprint-sidecar, then read <dir>/reference/blueprint.md — the authoritative, step-by-step adopt guide. What follows is its outline.
2. Place the source unchanged in upstream/. Never edit it. If it cannot run here (a database server, private services, system packages), stop and tell the person exactly what is missing.
3. Declare how it starts in sidecar.json: an argv (never a shell string), "port": "auto" handed over as {port}, its environment, and a health path.
4. Name the modules from the grouping the app already has (OpenAPI tags, route prefixes, controllers), and map its API: one operation per thing an agent should be able to do, in operations.json (what it is: typed params, destructive, readOnly) and sidecar.json (which route it reaches). No server API means no operations: say so; never invent verbs or map database writes.
5. Verify the mapping, not the app: agent-app <dir> validate, agent-app <dir> serve, then invoke every non-destructive operation for real (a2app <dir> <module> <operation> --…); a destructive one is shape-checked (it answers approval_required), never fired. A mapping that does not work does not ship.

Tell the person what adoption gives them: it is operate-only — agents reach the app through the mapped operations (a2app <dir>, then a module, then an operation), with no entities and no data verbs — and the app's own UI stays at its own address; the sidecar's port serves only the protocol and the account page. Changes apply live: edit the declarations, stop, serve.

Export — to share

agent-app <dir> export [--out <file.zip>] writes the app as a package: one folder named after the app, without credentials, data, runtime state, dependencies or build output, and with .a2app/toolkit.json reduced to its id. It never replaces an existing file. It prints { ok, file, sha256, bytes, files }: give the person the file and its sha256. It installs on another machine with agent-app install --from <file.zip>, where it is untrusted and walk-verified.

Afterwards

• An installed or imported app is an ordinary Agent App: operate it with the a2app CLI (the walk: a2app <dir>, then the module, the entity, the operation; records through a2app <dir> data <entity> …), and change it with the modify skill. An adopted app has operations only.
• Never edit an app's system-owned files: the gate hashes them.
• agent-app <dir> toolkit-sync re-vendors from the toolkit the app itself records, path included, so it is for an app that is already yours, after its toolkit was updated. Never use it to bring in an app you were given: install and import re-vendor from a toolkit installed here, chosen by id.
• In a harness with the framework plugin, the same commands are the tools agent_app_catalogue, agent_app_inspect, agent_app_install and agent_app_export, and a manager tab's Marketplace and Import panels run them for the person; what is owed afterwards is the same.