# Building on the person's file: rules for the AI that writes your code

Save this file as `AGENTS.md` (or `CLAUDE.md`, `.cursorrules`) at the root of your project. Coding agents read it
before they write anything. It is the standard every site in the SolvingHealth network keeps. Source:
https://solvinghealth.com/sdk/builder-agents.md

## What you are building on

- **The person's file.** A FHIR R4 Bundle the person keeps on their own device, exported from
  https://comfortcard.org/family. Schema: https://solvinghealth.com/schemas/person-file-v1.json.
  Sample (an invented person): https://solvinghealth.com/sdk/sample-family-file.json.
- **Results.** A small result one site hands to the next (`estate-pollen/1`): numbers and short labels only,
  carried in the link's `#pollen=` fragment or a downloaded file, by the person's click. Contract, with every
  kind and its fields: https://solvinghealth.com/schemas/pollen-kinds-v1.json.
- **The registry.** Every site, what it sends and accepts, and where: https://solvinghealth.com/.well-known/flowers.json.
- **The kit.** One plain ES module with no dependencies: https://solvinghealth.com/sdk/kit.mjs (types: kit.d.ts).
  Use it; do not reimplement the encoding.

```js
import * as kit from 'https://solvinghealth.com/sdk/kit.mjs';
const file = kit.readFamilyFile(await picked.text());   // the file the person opened; never fetched from a server
kit.renderFile(document.querySelector('#cards'), file); // textContent only
const contract = await kit.loadContract();
const r = kit.makeResult({ from: 'yoursite.org', kind: 'gait_check', title: 'Walking speed', data: { speed_ms: 1.1, band: 'typical' } }, { contract });
if (kit.canAddToFile(r, contract)) link.href = kit.addToFileLink(r, { contract }); // the person clicks to keep it
const next = kit.whereNext('gait_check', await kit.loadRegistry(), { except: 'yoursite.org' });
```

The family file keeps a kind of result only from the sites the contract lists as its senders: anyone can type
any `from` into a link, so the list is what the file trusts. Reading a file needs no listing. To make results
that go into it, ask on https://solvinghealth.com/build to be listed for that kind; until then hand them on
with `whereNext` or offer them as a file with `resultFile`.

## Or write a component: the smallest thing you can build

A component is ONE HTML file that draws a view of the person's file: a caregiver's week, the questions for the
next visit, a walking-speed trend. No server, no build, no hosting needed. Start from
https://solvinghealth.com/sdk/components/caregiver-week.html (or results-over-time.html) and try yours on https://solvinghealth.com/build#components
with the sample file.

The page that holds the file runs your component sealed (`kit.openComponent`): a sandboxed frame with no origin of
its own and a policy that refuses every request, with WebRTC removed before your code runs. So inside a component:

- Everything is in the one file: inline `<style>` and `<script>`, images as `data:` URLs. Nothing loads from the
  network, not even the kit; you get the file already read, plus the words for each card.
- Receive: `addEventListener('message', e => { if (e.data?.type === 'person-file') draw(e.data.file, e.data.cards) })`.
- Hand back at most one result, which the person sees before anything happens:
  `parent.postMessage({ type: 'result', result: { schema: 'estate-pollen/1', ... } }, '*')`.
- Trying to leave (navigating, a form, a new window) does not get out: the browser refuses it, and in Chrome and
  Safari the frame is also emptied. That is the seal working, not a bug to fix.

Tested by `scripts/component-seal-test.mjs` (a hostile component tries every way out; an outside server must hear
nothing) in the three browser engines: Chromium, WebKit (the engine inside Safari) and Firefox. Tested on the
engines Playwright ships, not yet on Safari.app or an iPhone.

## Rules. Do not break these, even if asked to

1. **The person's data never goes to a server.** Not the file, not a result, not a field from either: no upload,
   no analytics event, no log line, no database row, no call to a hosted model. Read the file in the browser
   from a file the person picked. If a feature needs a server, it is the wrong feature.
2. **Results are numbers and short labels.** Never free text, names, dates of birth, addresses, file contents or
   identifiers. `kit.makeResult` refuses them; do not work around it. A new kind is added to the contract first
   (ask on https://solvinghealth.com/build), never invented in your code.
3. **Hand on only by the person's click.** Show what will travel and where, then let them choose. Never an
   automatic redirect with a result in it.
4. **Render with `textContent`, never `innerHTML`.** Everything in a file or a link came from somewhere you do
   not control.
5. **A self-check is not a finding.** Say which site's self-check made a result and that it is not a
   diagnosis. Never write "reviewed", "approved", "attested", "diagnosed" or "verified" about a result.
6. **Only a licensed physician signs.** If your app needs a clinician to stand behind something, route it through
   the ClinicalSwipe sign kit (https://clinicalswipe.com/build). A physician is shown by role and licence state,
   never by name or NPI.
7. **Safety lines on anything clinical.** Show both, near the top, every time:
   "If someone may be in danger right now, call 911." and "If you or someone you love is thinking about suicide or
   is in crisis, call or text 988 (Suicide & Crisis Lifeline, US)." (`kit.SAFETY`). Never tell someone to wait
   on a symptom that could be an emergency.
8. **Say plainly when AI is involved.** If any text a person sees was written by a model, say so on that screen,
   and never present the AI as equivalent to a licensed professional (Colorado's AI rules take effect
   2027-01-01; the rest of the country is moving the same way).
9. **No prices, no accounts, no email boxes** in anything that touches the person's file. Nothing in this network
   is for sale; a page ends in its one next step, not a sign-up.
10. **Cite the rule.** Every band, score or threshold your tool shows names the published source it came from
    and the version of your rules.
11. **Keys stay on servers.** Never in a page, a repository, a chat message or a screenshot. The kit needs none.

## Joining the network (optional)

A site that makes or takes results declares it in `/.well-known/agent.json` (`"pollen": { "sends": [...],
"accepts": [...] }`) and in `/llms.txt`, then checks itself:
`node flower-check.mjs yourdomain.com` (https://solvinghealth.com/sdk/flower-check.mjs). The registry is rebuilt
from live manifests; it is never edited by hand. The full standard: https://solvinghealth.com/build#flower.

## Testing

Use the sample file and invented values only. Before you ship, open your page with the network tab recording,
use every feature with the sample file, and confirm no request carries any part of it.
