# AGENTS.md — hipulse.ai

This file is a guide for **AI agents** (Claude, Gemini, ChatGPT, Perplexity,
Ollama, Grok, Cursor, VS Code, etc.) that crawl or connect to Pulse. It
describes how to discover, authenticate, and use Pulse without a browser.

## What Pulse is

Pulse is an **HR Intelligence MCP server** that makes the "people world model"
of an organization legible, continuous, and governed. It replaces the
HRIS-era stack of forms and status meetings with:

- **Ambient signals** pulled from git, calendar, Salesforce, and HRIS.
- **Weekly check-ins + coaching signals** (may be shared with manager and leadership for organizational coordination and resourcing; k-anonymity ≥ 5 on aggregates).
- **Goals that roll up from contribution** — set top-down at the company
level, with department themes emerging bottom-up.
- **An MCP interface**, so any AI agent connects once and carries the team's
context through weekly 1:1s, goal check-ins, and ambient rollups.

## How to connect (MCP)

Pulse speaks MCP over HTTP at `/mcp`. OAuth 2.1 + PKCE is required.

1. Discover: `GET https://hipulse.ai/.well-known/oauth-authorization-server`
2. Register the client (dynamic client registration) or use a pre-provisioned
  `client_id`.
3. Complete the auth flow (Google / Okta SSO / email OTP).
4. Exchange the code for a bearer token and open an MCP session at `/mcp`.

Agents that can't open a browser should instruct the user to copy the
`start_onboarding` prompt rendered on the auth success page.

## Onboarding scripts

The preferred way for an agent to walk a new user through Pulse is to call
the `start_onboarding` MCP tool. It returns a role-appropriate script
(`admin/exec` → organization setup, `os_contributor` → draft proposals, every
other role → team contribution mapping) with an ordered `steps[]` array,
each referencing concrete Pulse tools to call.

- Admin / exec: [/onboarding](https://hipulse.ai/onboarding)
- Team member: [/team-onboarding](https://hipulse.ai/team-onboarding)
- Contributor drafts: [/contributor-onboarding](https://hipulse.ai/contributor-onboarding)

## Canonical tools

- `start_onboarding` — returns the role-aware onboarding script.
- `start_os_onboarding` — step-by-step OS builder (values → principles →
mission → vision → BHAG → painted picture → goals).
- `get_org_framework` — goal-framework guidance for exec onboarding.
- `ingest_org_chart` — push a roster when Pulse isn't connected to a
pull-adapter HRIS (Workday / Google Workspace). Admin only.
- `propose_os_`* — save values, principles, mission, vision, BHAG, etc.
- `save_weekly_check_in` — persist the employee weekly check-in (manager +
leadership can read).
- `list_team_weekly_check_ins` — managers/leaders read weekly cadence sessions.

## Crawling guidance

- Respect `[/robots.txt](https://hipulse.ai/robots.txt)`.
- Start from `[/llms.txt](https://hipulse.ai/llms.txt)` for a concise index.
- Authenticated areas under `/app` (employee hub) and `/app/admin` (workspace) are
not indexable; without a session the site returns an auth redirect.
- Marketing pages (`/`, `/manifesto`, `/security`, `/live-demo`) render
server-agnostic HTML with full semantic structure.

## Contact

- Domain: `hipulse.ai`
- MCP endpoint: `https://hipulse.ai/mcp`
- Security contact: `security@hipulse.ai`