# puppet-show Agent Guide

Base URL: `https://puppet-show.aisloppy.com`

## Purpose
Discussed building an app sort-of based on graphitura - perhaps both should share some shared infrastructure service.

## Standard Endpoints
- `GET /api/health` - Service health check.
- `GET /api/version` - App version.
- `GET /architecture` - Architecture page (typically login-gated).
- `GET /agent-guide.md` - Machine-readable integration guide.
- `GET /agent-guide` - Human-readable rendered guide.

## Authentication
- Endpoints marked as auth-protected require a valid JWT.
- Browser clients should use the app's own sign-in UI.
- API clients should send `Authorization: Bearer <jwt>` unless the app guide documents a different auth mechanism.
- If the app exposes local signup or login endpoints, document those app-local endpoints here instead of pointing agents at third-party auth vendors.

## Integration Rules
- Fail fast on errors; do not silently degrade.
- Read `PORT` from environment.
- Use network APIs between services; no cross-app imports.
- Long-running work must start async jobs and return `202` with a task ID quickly.
- Durable task status belongs on `GET /api/tasks/<task_id>`.
- SSE is optional live transport only; do not make it the sole source of task state.

## Notes For Coding Agents
- Start with `GET /agent-guide.md` for current contract.
- Confirm endpoint auth requirements before calling.
- Include explicit timeouts and propagate errors.