app/README.md

# Phast app

Canonical source of truth for Phast app.

> **Connect your tools once. Bring your tool belt anywhere.**

Phast app gives a person one portable MCP plus a programmable Prefab home. Connect `my.phast.app/mcp` to an agent to create and manage Phast apps. A created Phast app has two matching surfaces:

- `user.phast.app` — human / Prefab home
- `user.phast.app/mcp` — the user's portable MCP tool belt

## V0 contract

`phast.json` is deliberately boring. It is mostly:

1. the MCP tool list and provider connections;
2. references to delegated credential authority (Persimmons, never raw secrets);
3. Prefab home/widget settings.

The browser and chat are two editors for the same declaration.

### Browser flow

Home → Edit Home → Add Widget → provider search → connect if necessary → place/configure widget.

### Agent flow

Connect once to `my.phast.app/mcp` → create/manage `user.phast.app` → search providers → add tools/widgets → stream/taste-test Prefab in chat → persist accepted UI to the same `phast.json`.

## Boundaries

- **Phast app composes.** It owns the portable MCP/tool belt and Prefab composition.
- **Oracle discovers.** Provider/MCP/OAuth discovery comes from the capability graph, not a hard-coded Phast app directory.
- **Persimmons holds secrets.** Phast app stores connection/authority references, not secret values.
- **Factory builds/operates.** Provisioning uses bounded deterministic infrastructure routes.
- **Clients are replaceable.** ChatGPT, Claude, Codex, or another MCP client should be able to use the same Phast app without recollecting the user's tools.

V0 is intentionally not arbitrary app generation. Prove the portable-tool-belt + editable-home loop first.

## Naming and copy

Use **Phast app** when naming the product or one of its instances; use
**Phast apps** for the plural. Write “your Phast app,” “create a Phast app,”
and “My Phast app” for the management connector. Existing all-caps display
styles may use “PHAST APP.” Apply this to page titles, metadata, navigation,
buttons, examples, generated homes, MCP display text, and documentation.

Keep deliberate substitutions for “fast”: “make something phast,”
“built phast,” and “make MCP apps phast.” Do not rename literal domains,
URLs, `phast.json`, environment variables, CSS classes, tool names, or
schema keys/values as part of a copy edit. Preserve user-chosen app names.

The public copy lives in `index.html` (phast.app), `my/index.html`
(my.phast.app), and `server.py` (generated personal homes and MCP display
text). `phast.json` supplies the management display name. Review these
surfaces together when changing product naming.

Chair review: the standalone “PHAST.” wordmark and the “My Phast” connector
label could be separate brand treatments. This change proposes “PHAST APP.”
and “My Phast app” consistently; the chair should confirm those treatments.
The phrase “your Phast” names an app instance, so it becomes “your Phast app.”

## Running

Prod since 2026-10-14: Fly app `phast-app` (this `fly.toml`), one machine, volume `phast_data` at `/data`
(`PHAST_DATA_DIR=/data/phast`, `FASTMCP_HOME=/data/fastmcp`). It serves phast.app, my.phast.app and
`*.phast.app`; the two pages are this repo's `index.html` and `my/index.html`, not copies. Sign-in is
Teahub OAuth (app "Phast app" owned by `teahubxyz`, redirect `https://my.phast.app/auth/callback`);
`GITEA_OAUTH_CLIENT_ID`, `GITEA_OAUTH_CLIENT_SECRET` and `JWT_SIGNING_KEY` exist only as Fly secrets.
`ALLOWED_GITEA_USERS` says who may use it.

Deploy: `fly deploy --build-arg SOURCE_SHA=$(git rev-parse HEAD)`; `GET /healthz` reports the SHA.
History before 2026-10-14 is `matcha/phast` from the old factory, merged in.