# Toupas for coding agents

Toupas makes the app on the user's computer live, at a link anyone can open. The user isn't expected to know anything about servers or deployment, so don't ask them for deployment details: Toupas works them out.

## Make the app live
Call `toupas_make_live` with `dir`, the absolute path of the app's folder. It signs the user in if needed, works out how to prepare the app, writes `toupas.json`, prepares the app (in Docker for apps with their own server), sends only changed files, waits until the new version is live, and returns the link. Calling it again updates the live app.

The first time, it may stop and return:
- `askUser`: a question only the user can answer (copy local data or start empty; Toupas storage or their own). Ask it in its own words, wait for the answer, then call `toupas_make_live` again with the matching argument (`copyLocalData`, `startEmpty`, `useToupasStorage`, `keepOwnStorage`). Never answer it yourself.
- `agentInstructions`: something for you to do first, e.g. switch the app from SQLite to Postgres (`E_LOCAL_DATA_STORAGE`), or ask the user to install Docker Desktop (`E_DOCKER_MISSING`, then `toupas_setup_docker`).
- A sign-in link (`E_SIGN_IN_REQUIRED`): give it to the user; once they've approved it, call the tool again.
- `status: "in_progress"`: preparing is taking a while. Call `toupas_make_live` again with the same `dir`: it keeps waiting for the same run, it doesn't start over.

## Words to use with the user
Say "make live", "update the live app", "app", "version", "settings". Avoid "deploy", "deployment", "project", "container", "environment variable" unless the user uses them.

## After it's live
- Something wrong: `toupas_get_deployment` (did the latest version go live, and why not) and `toupas_get_logs` (what the app printed).
- Settings and secrets: `toupas_list_env`, `toupas_set_env` (`secret: true` for passwords and keys), `toupas_unset_env`. Don't put secrets in code or in `.env` files that get uploaded; `.env` files never go live.
- Data: `toupas_get_database`, `toupas_db_query`; files: `toupas_get_storage`, `toupas_list_files`.
- Links: `toupas_get_links`, custom names (`toupas_set_subdomain`) and the user's own domains (`toupas_add_domain`). These are paid; the answer then includes a link for the user to pay in their browser.
- Plan and trial: `toupas_get_project`, `toupas_get_usage`, `toupas_activate_project`, `toupas_get_billing`.

## Rules
- Payments always happen in the user's browser. Give them the link; never open it or pay yourself.
- Tools that delete or take things offline take `confirm`. Without it they only describe what would happen: show that to the user, and call again with `confirm: true` only if they agree.
- The same can be done in a shell with `toupas <command> --json`; `toupas help` lists the commands. Long-running things (`toupas db tunnel`, `toupas dev db`, `toupas logs --follow`) are only in the shell.