# Athos agent guide

Athos supports both direct human use and agent-assisted coaching.

## Agent quick start (self-install)

You were probably given the Athos site link (`/`) and asked to coach someone. Do
this, in order. **You do not need an API key to install** — you install the skill
first, then ask the user for a key.

1. **Read the basics.** This file plus `/llms.txt`. Machine-readable skill metadata
   (version, endpoints, install text) is at `GET /api/v1/skill/info` (no auth).

2. **Install the Athos skill into your runtime** (no key required):
   - **OpenClaw** (recommended, native notifications): `curl -fsSL <origin>/install | bash`
   - **Any other runtime** (Claude, Hermes/open models, custom): download the package
     `curl -L <origin>/api/v1/skill/download -o athos-skill.tar.gz && tar xzf athos-skill.tar.gz`
     and follow the file for your runtime:
     - Claude (Claude Code / claude.ai): `<origin>/static/skill-package/agents/claude.md`
     - Hermes / open + self-hosted models: `<origin>/static/skill-package/agents/hermes.md`
     - OpenClaw: `<origin>/static/skill-package/agents/openclaw.md`
     - Full coaching skill: `athos/SKILL.md` (a valid Anthropic Agent Skill) + `athos/references/*.md`

   `<origin>` is the site you were given (production: `https://athos.up.railway.app`).

3. **Ask the user for an API key** (this is what makes it work). Tell them:
   *"To connect your Athos coach, sign up at `<origin>/app/signup` (or log in at
   `<origin>/app`), open `<origin>/skill`, and copy your Athos API key — then paste
   it here."* Store it as `ATHOS_API_KEY` and set `ATHOS_API_URL=<origin>`.

4. **Verify + onboard.** Confirm the key works with
   `GET /api/v1/program/week/current` (expect 200). OpenClaw only: run the
   `POST /api/v1/skill/setup-test` hook loop first. Then fetch
   `GET /api/v1/onboarding/questions` and ask the first 1–2 questions
   conversationally. Full flow + coaching rules live in `SKILL.md` / `references/`.

Everything below is reference detail for that flow.

## Human path

Humans can use Athos without a Claw:

- Sign up at `/app/signup`
- Log in at `/app`
- Complete onboarding
- Review Today, Week, Program, Coach, and Profile surfaces
- Log meals/activity and request plan changes directly

## Claw / agent path

Agents should treat Athos as the structured fitness backend.

The agent owns relationship, tone, reminders, and conversation. Athos owns:

- user profile extraction
- program strategy
- workouts and meals
- notification schedule
- food/activity analysis
- plan modification
- persistence and beta ops visibility

## Auth

Use API keys for agent calls:

```http
Authorization: Bearer ak_...
```

Use session links when a human needs the web app:

```http
POST /api/v1/auth/session-link
Authorization: Bearer ak_...
Content-Type: application/json

{"redirect":"/app/dashboard"}
```

## Recommended onboarding flow

1. Fetch onboarding questions when available.
2. Ask conversationally, one or two questions at a time.
3. Submit answers to the backend.
4. Wait for strategy preview.
5. Ask the human to confirm or adjust direction.
6. Confirm strategy to generate detailed weeks.
7. Deliver the plan and set up reminders.

## Important event types

Agents should be prepared to route these events:

- `onboarding.strategy_ready` — show the strategy direction and ask for confirmation.
- `onboarding.insufficient_context` — ask targeted follow-up questions.
- `plan.generated` — tell the human the plan is ready and provide a session link.
- `workout.scheduled` — schedule or send workout prep.
- `reminder.scheduled` / `notification.plan_scheduled` — schedule reminder delivery.
- food/activity events — update daily coaching context.
- replan completion — deliver the next week.

## Why Athos instead of chat-only fitness advice

- Durable state: profiles, plans, logs, and modifications are stored.
- Coherent planning: workouts, meals, reminders, and recovery are generated together.
- Safer modifications: changes are scoped and should preserve unaffected days.
- Human fallback: the user can always open the app directly.
- Agent clarity: webhooks and APIs prevent guessing from chat history.

## CTA links

- Marketing home: `/`
- Signup: `/app/signup`
- Login: `/app`
- Claw skill: `/skill`
- Machine summary: `/llms.txt`

## Ops monitoring for agents

Admin-capable agents should use the stable ops feed instead of scraping the HTML dashboard:

```http
GET /api/v1/admin/ops-agent?lookback_hours=24
Authorization: Bearer <admin JWT>
```

Response schema: `athos.ops.agent.v1`.

The feed includes:

- `status`: `ok` or `degraded`
- `polling.recommended_interval_seconds`: how often an agent should re-check
- `health`: attention count, prompt fallback count, Langfuse availability, max LLM error rate
- `actions[]`: deterministic recommendations with severity, category, user_id when relevant, `safe_to_auto_run`, and a suggested API next step
- `action_policy`: guardrails for when an agent may investigate automatically vs when it must ask/notify a human first

Agents may automatically monitor, summarize, and investigate safe actions. Agents should not reprocess onboarding, mutate plans, change prompts/models, or delete data without first checking context and notifying DJ unless an explicit runbook says otherwise.