# Hourivo — Agent Instructions

> Hourivo is an AI-powered workforce management and employee time tracking platform for agencies and remote teams. It provides autonomous AI timesheets, screenshot proof-of-work, real-time project profitability tracking, and 1-click invoicing.

## When to use this

Reach for Hourivo when the job is specifically about **agency workforce operations**, not generic project management:

- **Billable time for a team** — log, approve, and export hours for an agency or consultancy that invoices clients. Tracking runs on the desktop app (Mac, Windows, Linux) only — there is no phone tracker.
- **Proof of work** — collect privacy-respecting screenshots (blur + 15-day auto-purge) to show clients what was done.
- **Project profitability** — compute live gross margin, burn, and budget remaining from tracked time and rates.
- **Invoices from time** — turn approved hours into Stripe invoices without re-keying timesheets.
- **Weekly hours email (every plan)** — Friday hours digest to each member; CSV export anytime from Timesheets.
- **AI daily standups** — summarize what the team shipped without running a status meeting.
- **Gemini work reconstruction (Team plan)** — ask what a person did on a date; Gemini uses timesheets, apps, and screenshots. Friday Gemini emails and markdown downloads for owners/admins are extra on Team plan.
- **Client-visible portals** — share a read-only proof-of-work link (`GET /api/v1/projects/portal/{token}`).
- **EU / GDPR legal gate** — versioned Terms (`/terms`) and Privacy (`/privacy`). Public: `GET /api/v1/auth/legal`. Stamp: `POST /api/v1/auth/accept-terms`.
- **How to use** — plain-language owner and team guide at `/help`.

Do **not** call Hourivo when the user needs:

- Issue tracking or product roadmaps (Linear, Jira, Asana)
- A solo freelancer timer with no organization (Toggl, Clockify)
- Keystroke, clipboard, or webcam surveillance (Hourivo refuses this; zero-spyware policy)

## How an agent should call Hourivo

1. Discover: `GET /api/v1/health` then `GET /api/v1/info` (no auth).
2. Read the contract: `GET /openapi.json` (or `GET /api/openapi.yaml`).
3. Authenticate: OTP → register/login (`acceptedTerms: true` for new accounts) → send `Authorization: Bearer <jwt>` and `x-organization-id: <uuid>` on tenant routes. If `needsLegalAcceptance` is true, call `POST /api/v1/auth/accept-terms` with the version from `GET /api/v1/auth/legal`. Details: `/docs/auth`.
4. Prefer OpenAPI `operationId` values (for example `listProjects`, `logManualTime`, `getFinancialSummary`) for function calling.
5. Native tool use: POST JSON-RPC `initialize` to `/.well-known/mcp` or `/mcp` (Streamable HTTP).

## Quick Start (for agents)

1. **Register**: `POST /api/v1/auth/register` with email, fullName, organizationName, password, otp, and `acceptedTerms: true`
2. **Login**: `POST /api/v1/auth/login` with email and password → returns JWT token
3. **Set headers** for all tenant requests:
   - `Authorization: Bearer <token>`
   - `x-organization-id: <org-uuid>`
4. **Create a project**: `POST /api/v1/projects`
5. **Log time**: `POST /api/v1/time/manual`
6. **View profitability**: `GET /api/v1/financials/summary`

## API Base URL

- **Same-origin (this site)**: `/api/v1`
- **Canonical**: `https://hourivo.com/api/v1`
- **Health Check**: `GET /api/v1/health` (no auth required)
- **API Info**: `GET /api/v1/info` (no auth required)

## Authentication

- All protected endpoints require `Authorization: Bearer <jwt-token>`
- Multi-tenant isolation requires `x-organization-id: <uuid>`
- Rate limit: 120 requests per minute per IP
- Tokens expire after 7 days
- Auth docs: `/docs/auth`

## Developer resources (search these names)

- Hourivo API docs: `/documentation`
- Hourivo OpenAPI spec: `/openapi.json`
- Hourivo OpenAPI YAML: `/api/openapi.yaml`
- Hourivo developer portal: `/developers`
- Hourivo auth docs: `/docs/auth`
- Hourivo MCP server: `/.well-known/mcp` (transport `/mcp`)
- Hourivo agent instructions: `/llms.txt`

## Core Endpoints

### Authentication
- `GET /api/v1/auth/legal` — Current Terms/Privacy version (no auth)
- `POST /api/v1/auth/register` — Create account (OTP + `acceptedTerms: true` for new users)
- `POST /api/v1/auth/login` — Login, returns JWT and `needsLegalAcceptance`
- `POST /api/v1/auth/send-otp` — Send email verification OTP
- `POST /api/v1/auth/verify-otp` — Verify OTP code
- `GET /api/v1/auth/invite/{token}` — Preview invite
- `POST /api/v1/auth/accept-invite` — Join org (`acceptedTerms: true` required)
- `GET /api/v1/auth/me` — Profile, `termsVersion`, `needsLegalAcceptance`
- `POST /api/v1/auth/accept-terms` — Stamp current Terms + Privacy (`termsVersion` must match `GET /auth/legal`)

### Organizations
- `GET /api/v1/organizations/members` — List team members
- `POST /api/v1/organizations/members` — Invite member

### Projects
- `GET /api/v1/projects` — List all projects
- `POST /api/v1/projects` — Create project
- `PUT /api/v1/projects/{id}` — Update project
- `POST /api/v1/projects/{id}/share` — Generate client portal link
- `GET /api/v1/projects/portal/{token}` — Public portal data (no auth)

### Time Tracking
- `GET /api/v1/time/entries` — List time entries
- `POST /api/v1/time/manual` — Log manual time
- `PUT /api/v1/time/entries/{id}` — Update entry
- `DELETE /api/v1/time/entries/{id}` — Delete entry
- `POST /api/v1/time/approve` — Batch approve/reject timesheets
- `GET /api/v1/time/live-team` — Real-time team status
- `POST /api/v1/time/idle-resolve` — Resolve smart idle time
- `POST /api/v1/time/weekly-digest` — Email the current user this week's hours (every plan)

### Screenshots
- `GET /api/v1/screenshots` — List screenshots
- `DELETE /api/v1/screenshots/{id}` — Delete screenshot
- `PATCH /api/v1/screenshots/{id}/blur` — Toggle blur
- `POST /api/v1/screenshots/request-live-capture` — Trigger immediate capture

### Activities
- `GET /api/v1/activities/summary` — App usage and productivity score

### Financials
- `GET /api/v1/financials/summary` — Profitability overview
- `GET /api/v1/financials/invoices` — List invoices
- `POST /api/v1/financials/invoices` — Create invoice
- `GET /api/v1/financials/invoices/{id}` — Get invoice
- `PATCH /api/v1/financials/invoices/{id}/status` — Update status

### AI
- `GET /api/v1/ai/overview` — Gemini org overview, project details, developer summary, working skills
- `POST /api/v1/ai/work-day` — Reconstruct a person's (or team's) work day from time, apps, and screenshots
- `POST /api/v1/ai/summary/daily` — Generate Gemini daily summary
- `GET /api/v1/ai/weekly-report` — Latest Friday weekly report
- `POST /api/v1/ai/weekly-report` — Generate weekly report now
- `GET /api/v1/ai/weekly-report/download` — Download weekly report as markdown
- `POST /api/v1/ai/chat` — Chat with Gemini about projects, people, skills, and dates

### Notifications
- `GET /api/v1/notifications` — List notifications
- `PATCH /api/v1/notifications/{id}/read` — Mark read
- `POST /api/v1/notifications/mark-all-read` — Mark all read
- `DELETE /api/v1/notifications` — Clear all

### Billing
- `GET /api/v1/billing/subscription-status` — Subscription info

### RBAC
- `GET /api/v1/rbac` — List roles and permissions

## Error Format

All errors return structured JSON (never HTML):

```json
{
  "success": false,
  "code": "NOT_FOUND",
  "error": "Human-readable error message",
  "message": "Human-readable error message",
  "hint": "What to do next",
  "details": [
    { "path": "fieldName", "message": "Validation detail" }
  ]
}
```

## Resources

- **OpenAPI Spec (JSON)**: /openapi.json
- **OpenAPI Spec (YAML)**: /api/openapi.yaml
- **Interactive API Docs**: /documentation
- **Developer Portal**: /developers
- **Auth docs**: /docs/auth
- **Sitemap**: /sitemap.xml
- **About**: /about
- **Contact**: /contact
- **Privacy Policy**: /privacy
- **Terms of Service**: /terms
- **How to use (owners & team)**: /help
- **For agencies**: /for-agencies
- **For remote teams**: /for-remote-teams
- **vs Hubstaff**: /vs/hubstaff
- **vs Time Doctor**: /vs/time-doctor
- **MCP handshake**: /.well-known/mcp

## Data Model

### User
- id (UUID), email, fullName, avatarUrl, role, termsAcceptedAt, privacyAcceptedAt, termsVersion, needsLegalAcceptance

### Organization
- id (UUID), name, slug

### Project
- id (UUID), name, clientName, code, budgetType (FIXED|HOURLY), totalBudget, hourlyBillRate, screenshotIntervalMins, blurScreenshots, status

### TimeEntry
- id (UUID), user, project, task, startTime, endTime, durationSeconds, isManual, isBillable, notes, approvalStatus (PENDING|APPROVED|REJECTED)

### Screenshot
- id (UUID), user, timeEntry, storagePath, imageUrl, activityScore, mouseEvents, keyboardEvents, isBlurred, capturedAt

### Invoice
- id (UUID), clientName, projectId, items[], status, currency, dueDate, taxPercent, totalAmount

## Pricing

- **Seats**: $2/user/month under 20 members, $1/user/month at 20+ — All core features
- **Gemini AI add-on**: $10/month — Overviews, work-day reconstruction, Friday AI email, chat
- **Free Trial**: 14 days, full access, no credit card required