# HiRey: write and publish the owner's Page

> Read this to give your owner a Page on HiRey, or to bring their existing Page up to date. Needs sign-in. You write the Page from everything you have; HiRey checks it, keeps their photo and anything you can't see, and publishes only after the owner's yes.

Every call is `POST https://hi.hirey.ai/v1/capabilities/hi.workspace-workflows/call` with `Authorization: Bearer <api_key>` and a body `{"action":"<operation>","payload":{...}}`; over MCP, the same operation runs through `workspace_workflows` (action, payload and confirmation map one to one). Give each write its own `idempotency_key` and reuse a key only to retry that exact call. Sign-in is in [setup.md](https://hirey.ai/docs/agents/setup.md). When you are setting up everything at once (Page, company, products, Need), [setup.md](https://hirey.ai/docs/agents/setup.md) says how the one preview and the one yes work across them.

<a id="introduce-your-owner"></a>
#### 5. Introduce your owner

Right after sign-in, run checks 1 to 3 below first. If the owner has no Page yet, offer once: "Want me to introduce you on HiRey, so people can find you?" If the owner says no, don't ask again. If they asked you to set up HiRey or their Page, that request is the yes to start: don't offer, just do it. If the owner founded or runs a company, also offer [company-and-products.md](https://hirey.ai/docs/agents/company-and-products.md) once, even if they already have a Page.

A Page has two layers. The top is for people and stays short: name, a one-line headline, a short bio, a few lines on what they are known for and can help with. The layer below is for agents and should be full: up to 150 facts, each one line with its source (roles, companies, dates, projects, education, writing, talks, what they are looking for). Write it from everything you have, not just the last message.

**What to write from.** Use all the material you already have about the owner:

- what they told you, in this conversation and in earlier ones you remember;
- files they point you to on their computer (a resume, a bio, a product brief, notes);
- links they give you, and their own public pages linked from those (personal site, company site, GitHub, LinkedIn, talks, writing). Read public pages only; never sign in to a site to read it.

An AI without HiRey installed (a ChatGPT or Claude chat) can still write the owner's material: the owner copies the prompt from "Fill my Page with my AI" on https://hirey.ai/me (or asks Rey for it), pastes it into that AI, and sends its answer, which starts with `HIREY-PAGE-MATERIAL v1`, to Rey. Rey drafts the Page from it, marked as from the owner's AI rather than their own words, and publishes only after their yes. If you are that AI, answer the prompt in its format; you don't need the calls below.

A page you found yourself by searching their name may be someone else with the same name. Use it only when the owner gave it to you, it is linked from their own material, or they confirm it is them. The same holds for anything a people-data provider matched by name and company: confirm it is this person first.

Never put a phone number, email address or home address on the Page, never guess, and never state something uncertain as fact. Write only about the owner, as themself: never make a Page for someone else here (that is the Connector flow on https://hirey.ai/me).

1. `identity.me` returns the owner's `person_id`, `display_name`, `slug` and `visibility_status`. A `slug` means the owner already has a Page: `public` or `unlisted` is live at `https://hirey.ai/p/<slug>`; anything else was taken down earlier. You update that Page with 4 to 6 below; never make a second one.
2. Only when `identity.me` has no `slug`: `people.find` `{"query":"<the owner's full name>"}`. A result whose `person_id` equals the owner's own `person_id` is already their Page: use 3. If a result with another `person_id` is clearly the owner (same name, and its headline or place matches what you know), a Connector made a Page for them before they signed in. Do not create another. Tell the owner: "You already have a Page at https://hirey.ai/p/<slug>. Ask the Connector shown on that Page for a claim link." Then stop this page (the company, products and Need can still go ahead). If you are not sure, ask the owner whether it is them.
3. `page.mine` `{"owner":true}` returns exactly one row: the owner's own Page. Check it in this order, before any write:
   - `read_status`: anything but `ok` (`owner_draft_ambiguous`, `owner_draft_inconsistent`) means send the owner to https://hirey.ai/me and stop this page.
   - `workspace_id`: the owner's personal workspace, where every Page write below runs. If the row has none, send them to https://hirey.ai/me and stop this page. Call `workspace.focused` `{}`; if its `workspace_id` is different, `workspace.focus` `{"idempotency_key":"...","workspace_id":"<the row's workspace_id>"}` with `"confirmation":{"approved":true,"operation":"workspace.focus"}` now (the owner's request covers it).
   - `page_draft_id`: when set, it is their own draft, with its `current_revision`, `content_json` (their photo, `avatar_media_asset_id`, and every section) and `public_fields` (what is live now). When it is null and `identity.me` had no `slug`, create the draft: `page.create` `{"idempotency_key":"...","content":{"slug":"<slug>","display_name":"<their full name>"}}` (leave out `subject_person_id`: it is the owner's own Page). The slug is lowercase letters, digits and hyphens, usually the full name (`jane-doe`), at least four characters. It returns `page_draft_id` and `revision`. When it is null but they have a `slug`, send them to https://hirey.ai/me and stop this page.
   - A Page that already has an address keeps it: changing `slug` in a draft does not move it. Only when the owner asks for a new address, use `page.change_address` (see `describe`); the old link stops working.
4. Write the Page with HiRey's writing brief. You write; HiRey only checks.
   - `page.compose.brief` `{"page_draft_id":"...","if_revision":<current revision>,"materials":[...]}` returns the brief, its JSON schema and your materials numbered m1, m2 ... in order. Up to 10 materials: `{"text":"...","label":"..."}` for words (what the owner told you, the text of a file they gave you; up to 50,000 characters each), `{"url":"https://..."}` for a public page, `{"media_asset_id":"mas_...","label":"..."}` for a file uploaded as in [photo-with-someone.md](https://hirey.ai/docs/agents/photo-with-someone.md) part 3.
   - Write your answer in that schema, citing the materials as m1, m2. Fill the agent layer (`facts`) fully from the materials; keep the top short.
   - `page.compose.check` with the same `page_draft_id`, `if_revision`, `materials` and your `page` returns `passes` and any problems, and writes nothing.
   - `page.compose` `{"idempotency_key":"...","page_draft_id":"...","if_revision":<current revision>,"materials":[...the same, in the same order],"page":{...}}` saves it as one private revision and returns the Page as written. It starts from the current draft: their photo and any words already there stay (existing words may move into `facts`). `page_compose_checks_failed` lists each problem (`check`, `slot`, `text`, `why`): fix or drop that text and send it again with a new `idempotency_key`. `page_compose_source_unavailable` names a material HiRey can't read now: leave it out and renumber, or tell the owner.
   - For an exact field the owner dictates (a website, a city), use `page.draft` `{"idempotency_key":"...","page_draft_id":"...","if_revision":<current revision>,"content":{...}}`: `content` is the draft's whole `content_json` with only that field replaced; keep every other key as it is. `website_url` is a full `https://` address only.
5. Show the owner the Page exactly as it will be public: `page.mine` `{"owner":true}` again, then show the top (name, headline, bio, the short lists), the photo if there is one, the facts, and its address `https://hirey.ai/p/<slug>`: when `identity.me` has a `slug` (live or taken down), that is the address; the `slug` in the draft is used only for a first Page. For a Page that is already live, say what changes. Ask once whether to publish it (in a full setup, this is part of the one preview in [setup.md](https://hirey.ai/docs/agents/setup.md)). If they ask for changes, make them and show the changed parts again.
6. Only after the owner says yes, run these calls. That one yes covers both; don't ask again, and don't ask about single fields: what you showed is what goes public.
   - `page.authorize` `{"idempotency_key":"...","page_draft_id":"...","draft_revision":<revision>}` with `"confirmation":{"approved":true,"operation":"page.authorize"}`. It returns `authorization_id`.
   - `page.publish` `{"idempotency_key":"...","page_draft_id":"...","draft_revision":<revision>,"authorization_id":"...","visibility_status":"public","public_fields":[...]}` with `"confirmation":{"approved":true,"operation":"page.publish"}`. `public_fields` lists every field the draft has a value for, from `slug`, `display_name`, `headline`, `bio_markdown`, `avatar_media_asset_id`, `location_text`, `website_url` and `page_extension`; always include `slug`. A field left out is not shown: leaving out `avatar_media_asset_id` takes their photo down, and leaving out `page_extension` takes down everything below the bio, the facts included.
   - If `page.publish` refuses a field (for example "website_url must use https"), fix it in the draft with `page.draft` (the whole `content_json`, only that field changed), then `page.authorize` and `page.publish` the new revision. Publish without asking again only when the fix keeps what the owner saw (the same website with `https://` added). Any other change, even inside one field (a different photo, rewritten text, a section removed), is shown to the owner first and published only on their yes. Never drop `avatar_media_asset_id` or `page_extension` to get past a refusal: that takes down the photo or everything below the bio.
7. Share `https://hirey.ai/p/<slug>` only after `page.publish` returns. Its receipt has no URL: call `identity.me` and build it from its `slug`. A slug written in the draft is not the address. Opening the address before publishing can leave a cached "not found" for about a minute.
8. "public Page address is already in use" may mean the owner already has a Page. Don't add a number or suffix to get around it: open `https://hirey.ai/p/<slug>` and search the name again. If it is the owner, follow 2. If it is clearly someone else, ask the owner which address they want. Addresses of one to three characters and reserved words are refused.

Afterwards other people find the owner by name: agents at once with `people.find` (search the full name), and the search on https://hirey.ai/people within about a minute. Later, whenever the owner asks you to update their Page, run 3 to 7 again with what is new.