# Reviewer demo guide

Use this handoff when a directory reviewer, integration partner, or design
partner needs to test HollyHR without touching a real customer tenant.

The reviewer tenant must be synthetic, resettable, and usable without a manual
signup loop. Do not ask reviewers to complete MFA, SMS verification, email
verification, or customer onboarding before they can test the API/MCP surface.

## Create the tenant

Provision a synthetic tenant and write credentials to an ignored env file:

```bash
HOLLYHR_DATABASE_TARGET_PROOF="postgresql://..." \
HOLLYHR_ALLOW_DEVELOPER_DEMO_LOGIN_LINKS=1 \
pnpm developer:demo:provision -- \
  --create-api-key \
  --create-login-links \
  --login-personas=hrAdmin,manager,directReport \
  --output-json=./demo-tenant.json \
  --output-env=./demo-tenant.env
```

For production reviewer credentials, derive the target proof from a fresh Vercel
Production env pull instead of local `.env`. Use the internal
`docs/runbooks/workos-authkit-mcp-oauth.md` runbook for the exact operator
command. The current hosted reviewer workspace is `https://sandbox.hollyhr.com`.

`demo-tenant.json` is the non-secret reviewer manifest. It includes:

- the concrete API and MCP endpoints;
- the endpoint template for directory forms;
- the seeded scenario name and reset/reseed evidence;
- the reviewer login model and requested personas;
- safe starter prompts for Claude, ChatGPT, and generic MCP hosts;
- commands for TTFC and submission-pack generation.
- the public status page URL for service-health checks during review.

`demo-tenant.env` is secret. It contains the reveal-once API/MCP token and any
single-use reviewer login links. Do not commit it or paste it into model
prompts.

## Prove time to first call

Run the smoke from the generated env file:

```bash
dotenv -e ./demo-tenant.env -- sh -c 'HOLLYHR_TTFC_OUTPUT_PATH=./ttfc-evidence.json pnpm developer:ttfc:smoke'
```

Attach `ttfc-evidence.json` to the internal submission bundle. It proves:

- REST auth, `/me`, people, and metadata;
- MCP protected-resource metadata and unauthenticated challenge discovery;
- authenticated `GET /api/mcp` returning `405 Method Not Allowed`;
- MCP initialize, `tools/list`, and `whoami`;
- request IDs and rate-limit headers where returned by the live endpoint.

## Generate the submission pack

Build the reviewer and partner pack:

```bash
pnpm developer:submission:pack
```

The generated files are local evidence outputs:

```text
dist/developer-platform/submission-pack.json
dist/developer-platform/submission-pack.md
```

They are intentionally not committed. The tracked source of truth is
`docs/api/developer-platform-submission-evidence.json`.

## Host-specific blockers

Server-side Claude API, Cursor, and generic MCP clients can use the
developer-preview bearer-token flow when the token is stored outside prompts and
browser code.

ChatGPT app/connector submission and public connector directories require the
production OAuth path to be live and proven. Do not submit while the protected
resource metadata for the reviewer tenant returns an empty
`authorization_servers` array.

Production MCP writes remain blocked until DPIA/DPO approval, `mcp:write`, the
underlying write scope, `HOLLYHR_MCP_WRITE_MODE=enabled`, and host form
elicitation are all in place.

## Starter prompts

Use these examples when a reviewer asks what to try first. They are written as
human review tasks rather than secret test commands, and each one exercises a
specific safety property of the hosted MCP server.

```text
Open the HollyHR sandbox and list the MCP tools available to this connection.
```

```text
Find the sandbox People team and summarize each person's name, role, and department using only returned fields.
```

```text
Show upcoming time off in the sandbox using HollyHR's generic absence labels.
```

```text
Start a sample leave-request flow and stop at the human approval prompt before committing a write.
```