# aosaas Agent Guide

Base URL: `https://aosaas.com`

## Purpose
AoSaaS explains Agent-Oriented Software as a Service: coding agents compose focused products from a network of specialized, API-first services. The public marketing page documents the approach and links to the live Stack proof of concept and its service network.

The concrete workflow starts with the MIT-licensed [`workon`](https://github.com/QualityCopperShovel/workon) script on a laptop, connects to a Platform 2040-managed VPS, and uses Claude Code or OpenAI Codex to compose shared APIs into a deployed app.

The primary proof link opens Stack's public, read-only Puppet Sprites demo at `https://stack.aisloppy.com/demo`; using or changing Stack still requires an account.
The marketing page models Puppet Sprites, GenLibrary, Wordle with a Timer, SimpleSprite, Hyperblues, Whiteboard, Toolong, and YouTubeSurf as pure consumer endpoints around a complete eleven-node service mesh: Stack, Option Table, Software Atlas, PriorityNode, AuthReturn, BrightWrapper, GridGlance, Favicon Generator, Domain Gen, Text Handling Service, and Platform 2040. The local `workon` script sits outside the mesh as the bridge from the coding agent to the VPS.

## Public Surface
- `GET /` - AoSaaS marketing page and system overview.
- `GET /api/health` - Service health.
- `GET /api/version` - Current release version.

## Standard Endpoints
- `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.