# Install Page Systems in an eve agent

These are the exact steps for a coding agent adding Page Systems to an existing eve project.
Page Systems lets the agent send the person a small mobile web page (a flight picker, a time picker, a form, ...)
instead of asking in chat. The answer comes back into the same conversation.

Requirements: an eve project (`eve` `>=0.72.0 <0.76.0` in package.json) and Node 24 or newer.

## 1. Install the package

Run in the project root, with the project's package manager:

```bash
npm install @pagesystems/eve
```

## 2. Add the mount file

Create `agent/extensions/pages.ts` with exactly this content:

```ts
export { default } from "@pagesystems/eve";
```

The file name matters: eve prefixes every tool with it, so the tools become `pages__list_page_types`,
`pages__get_page_type_schema`, `pages__create_page`, `pages__get_page_result` and `pages__cancel_page`.

## 3. Ask the human for the API key

You cannot create the key yourself. Stop and ask the human:

> Please sign in at https://app.pagesystems.ai/dashboard/keys, click "Create API key", and paste the key here.
> It starts with `ap_live_` and is shown only once.

Never invent a key and never commit it.

## 4. Set the environment variable

Add the key to `.env.local` (create the file if needed; make sure it is git-ignored):

```bash
PAGE_SYSTEMS_API_KEY=<the key the human gave you>
```

Tell the human to add the same variable to the Vercel project (Settings → Environment Variables),
or run `vercel env add PAGE_SYSTEMS_API_KEY` if the Vercel CLI is linked.

## 5. Only for apps with their own auth middleware

If the eve agent is composed into a Next.js app (`withEve`) that has a `middleware.ts` or `proxy.ts` redirecting
unknown or signed-out requests, add this path to its list of public paths, next to any webhook paths already there:

```
/eve/v1/page-systems/callback
```

Without it, Page Systems' notification is redirected and answers are only available by polling. Standalone eve apps
need nothing here.

## 6. Verify

```bash
npx eve info
```

The output must list:

- tools `pages__list_page_types`, `pages__get_page_type_schema`, `pages__create_page`, `pages__get_page_result`, `pages__cancel_page`
- route `POST /eve/v1/page-systems/callback`

The skill `pages__pages` is not listed: it loads from Page Systems (`GET /v1/skill`) when a session starts.

If `eve info` fails with `Selected module binding "extensions/pages.ts" has no compile or runtime usage.`, the
installed eve version is outside `>=0.72.0 <0.76.0`. Tell the human; do not try to patch the package.

## Notes

- A missing API key does not break the build. The first `create_page` call fails with a message explaining how to set it.
- On Vercel, the callback URL is derived automatically. Locally there is no public URL, so the agent reads answers
  with `get_page_result`; set `PAGE_SYSTEMS_CALLBACK_URL` to a tunnel URL ending in `/eve/v1/page-systems/callback` to get pushes.
- Full reference: the `@pagesystems/eve` README on npm.