# Connect an AI Agent to AppsPonds

AppsPonds lets a user publish web apps into their pond. An AI agent can connect
through browser-approved integration access, inspect visible ponds and apps, and
publish an AppsPonds package when the user has publishing access.

## Tell the User

Use this prompt when a user asks you to connect to AppsPonds:

> I can connect to AppsPonds using browser approval. I will ask AppsPonds for
> the minimum scopes I need, open an approval link for you, and wait for you to
> approve it while signed in. For publishing I need `apps:create` or
> `apps:publish`; read-only browsing only needs `ponds:read` and
> `apps:read`.

If the user wants to publish, also tell them:

> AppsPonds may require early publishing access or owner/App Manager approval.
> If approval is required, I can stage the candidate version and report that it
> is pending approval instead of claiming it is live.

## Discovery

- Human page: https://admin.appsponds.com/agents
- Markdown: https://admin.appsponds.com/agents.md
- llms.txt: https://admin.appsponds.com/llms.txt
- Full agent context: https://admin.appsponds.com/llms-full.txt
- API catalog: https://admin.appsponds.com/.well-known/api-catalog
- OpenAPI: https://admin.appsponds.com/openapi.json
- Package manifest schema: https://admin.appsponds.com/schemas/appsponds-package.schema.json
- Agent manifest: https://admin.appsponds.com/.well-known/appsponds-agent.json

## Browser-Approved Connection Flow

1. Start authorization with `POST /api/integrations/authorize/start`.
2. Request only the scopes needed for the user's task.
3. Open `approvalUrl` in the user's browser. If you are connecting through a
   tunnel or alternate origin, use the same-origin approval URL returned by the
   local companion when available.
4. Poll `POST /api/integrations/authorize/poll` with `requestId` and
   `deviceCode` until a token is returned or the request expires.
5. Store the token only in the agent session or configured secure credential
   store. Do not print it or commit it to a project.

Authorization requests expire quickly. Issued integration tokens are scoped,
revocable, audited, and expire by default.

## Scopes

- `ponds:read`: list ponds the user can see.
- `apps:read`: list apps visible to the user.
- `apps:create`: create a new app from a package. Ask only when creating.
- `apps:publish`: publish a package to an existing app. Ask only when publishing.

Default authorization is read-only: `ponds:read` and `apps:read`.

## Agent API

All agent API requests use `Authorization: Bearer <token>`.

- `GET /api/agent/ponds`: list visible ponds.
- `GET /api/agent/apps`: list visible apps.
- `POST /api/agent/apps`: create an app from a zip artifact.
- `POST /api/agent/apps/{slug}/publish`: publish a zip artifact over an owned app.

Use the OpenAPI document at `/openapi.json` for request and response shapes.

## Publishing Rules

- A user may need early access before publishing. If a publish endpoint rejects
  the request because publishing access is unavailable, tell the user to open
  AppsPonds and request access from the publish workflow.
- Creating a new app requires a target pond. If the user started from a specific
  pond, use that pond and do not ask again.
- Publishing an existing app is owner-only in this v1 API.
- If AppsPonds says the publish is pending approval, tell the user the candidate
  version is staged and waiting for an Owner or Apps Manager to approve it.
- Do not claim a version is live until AppsPonds reports it as deployed/current.
- For package uploads, prefer a generated `appsponds-package.json` manifest so
  AppsPonds can validate the app kind, source type, health check, resources, and
  static path before deployment.

## Package Format

Packages are zip archives. A package can include `appsponds-package.json` at
the archive root:

```json
{
  "schemaVersion": 1,
  "app": { "kind": "server", "sourceType": "docker-zip" },
  "deployment": {
    "dockerfilePath": "Dockerfile",
    "healthCheckPath": "/health"
  }
}
```

Static apps use `"kind": "static"`, `"sourceType": "static"`, and may set
`deployment.staticPath` when `index.html` is inside a build directory.

Server apps must listen on `0.0.0.0:3000` or `process.env.PORT`. Multi-
container apps, background-only workers, arbitrary public ports, and dedicated
per-app Postgres are not part of v1.

## Optional Resources

AppsPonds never provisions resources unless the package requests them.

- External Postgres: `resources.postgres.mode = "external"`; the app must use
  the configured env var, normally `DATABASE_URL`.
- AppsPonds shared Postgres: `resources.postgres.mode = "appsponds-shared"`.
- SQLite: request `resources.sqlite`; AppsPonds provides a durable
  `sqlite:////data/app.sqlite` URL by default.
- Mounted storage: request `resources.storage.mountPath`, normally `/data`.

Agents should inspect dependencies, env examples, migrations, ORM config, and
database files. If no database is required, do not add database resources.

## Local Companion and MCP

When working from this repository, the local companion can expose deterministic
packaging and MCP tools:

```powershell
npm run agent -- serve
npm run agent -- mcp
```

The MCP server exposes tools to inspect a folder, package a folder, start and
poll browser approval, list visible apps, create an app, and publish an existing
app. Hosted agents that do not have the local companion can call the HTTP API
directly using the OpenAPI document.

## Safety Requirements for Agents

- Request the narrowest scope needed.
- Do not ask for write scopes until the user wants to create or publish.
- Do not persist returned log output, tokens, app env values, or generated
  packages unless the user asks for a local artifact.
- Do not upload secret-like files such as `.env`, private keys, certificates,
  or npm credentials.
- Verify package contents and health checks before reporting success.
- Treat redaction as best-effort; never intentionally print secrets into app
  logs or package summaries.