# Deploying a Widget to Modyo

Deployment is **not an MCP operation**. The MCP's widget flow ends at validation (`widgets-validate`) plus a served smoke test (`npm run dev`). Getting the widget onto a Modyo site happens outside the MCP, through one of two paths:

1. **CI from the widget's repository (the standard path).** `widgets-scaffold` initializes the project as a git repository and, when git has a user identity configured, creates an initial commit. The developer pushes the repository to their forge, and a CI workflow runs the push with credentials from the repository's CI secrets. Every deploy is traceable to a commit.
2. **Manual push (the explicit developer path).** The developer runs `npm run push` in their own shell, inside the widget directory.

**The agent never pushes.** There is no MCP tool for it, and the agent does not run the CLI itself. The MCP uses its own `MODYO_TOKEN` only for its own API calls: it does not pass it to the processes it starts (`widgets-scaffold` removes every `MODYO_*` variable from their environment), and token material never enters the chat. If the operator asks the agent to deploy, the answer is to point at these two paths.

## Push scripts of the canonical template

| Script | What it does |
|--------|--------------|
| `npm run push` | Builds the widget and runs the Modyo CLI `push` (uploads it as a draft) |
| `npm run push:publish` | Same, with `--publish` |
| `npm run push:debug` | Same as `push`, with diagnostic logging |

The scripts pin the Modyo CLI version they run.

## Configuration

The CLI reads its configuration from a `.modyo` file next to `package.json` (recommended), from `.env` (supported, deprecated in the CLI), or from environment variables (what CI uses). The template ships `.modyo.example` and `.env.example` with placeholder values; copy one, fill it in for local use, and keep it out of git. In CI, set the variables as secrets.

| Variable | Required | Description |
|----------|----------|-------------|
| `MODYO_ACCOUNT_URL` | yes | Your Modyo account URL, e.g. `https://my-company.modyo.cloud` |
| `MODYO_TOKEN` | yes | Access token of a team member, generated in that user's profile (Settings → Team → the user → API Access → New Access Token). Settings → API Access only registers the application the token belongs to |
| `MODYO_WIDGET_NAME` | yes | Name of the widget on the platform |
| `MODYO_SITE_HOST` | one of the two | Host of the target site |
| `MODYO_SITE_ID` | one of the two | Numeric id of the target site |

`.modyo.example` lists the optional variables (build directory, build command, exclusions, preview settings, logging).

## Draft and publish

`npm run push` uploads the widget as a **draft**; the operator publishes it from the admin when ready. Pushing is a development-time operation: a wrong widget is overwritten by the next push. Publishing affects the site's users and is the operator's decision. `npm run push:publish` pushes and publishes in one step — a decision for the repository's CI workflow, never the agent.

## Credentials policy (for the agent)

- **`MODYO_TOKEN` never enters the chat.** Do not read it — from `.env`, `.modyo`, or the shell environment — into your own context for any purpose.
- **Do not call the Modyo CLI or the admin API with the operator's token.** Deploy questions get answered with the two paths above, not with an execution.
- **Do not resolve the target site yourself.** If the operator's configuration is ambiguous (both `MODYO_SITE_HOST` and `MODYO_SITE_ID`, or neither), say so and let them fix it.

## Troubleshooting

| Symptom | Cause and fix |
|---------|---------------|
| The CLI is denied access to the site | The token's owner needs a site role that allows using the CLI, such as **Site Developer CLI** (`site_developer_cli`), on the target site. **Site Developer** has the same permissions without CLI access. Publishing requires its own permission, which developer roles do not include |
