# Profile fields

> Every field of a HUMANS.md 0.3 profile, each closed value and the sentence it produces for an agent.

Validated against app `ae3b0ef2` and Collector `0.9.0` (`54621da`), 11 November 2026.

Generated from `humanload/vendor/humans-core/spec/schema/humans.schema.json`, `humanload/vendor/humans-core/spec/schema/instructions.json`. This page changes only when that code changes.

A profile is a HUMANS.md file, format version `0.3`. Every field is optional except the four the last table marks.
Each closed value produces one fixed English sentence: the instruction line an agent receives with the profile.
Below, each value is followed by its sentence.

## How to write to me: `reading`

### reading.lead_with

What the first line holds.

- `tldr`: Open with a brief summary.
- `decision_needed`: Open with the decision you need from the recipient.
- `context`: Open with the context needed to understand the message.
- `question`: Open with the question you need answered.
- `next_action`: Open with the next action the recipient should take.

### reading.length

- `minimal`: Keep the complete message to the bare essentials, at most five lines; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.
- `short`: Keep the complete message short, at most one screen; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.
- `standard`: Give enough detail to understand the main point.
- `thorough`: Explain the reasoning and relevant details thoroughly.

### reading.max_words

Cap on the entire message, including an appendix, tables and code; never bypass via an unsolicited thread or extra message.

A whole number from 20 to 2000.

An agent is told: Keep the complete message, including any appendix, within reading.max_words words; put first any failure, skipped or unverified step, risk to data or security, change beyond the request or decision the recipient must make; if you left items out, say how many.

### reading.structure

- `bullets`: Organize the message as bullet points.
- `prose`: Write in connected paragraphs.
- `mixed`: Combine short paragraphs with lists where useful.
- `numbered`: Number steps and questions so the recipient can answer by number.

### reading.visual

Preferred forms, most wanted first.

A list of at most 5 values, without repeats.

- `table`: Prefer a table where one fits.
- `diagram`: Prefer a diagram where one fits.
- `chart`: Prefer a chart where one fits.
- `example`: Prefer an example where one fits.
- `text`: Prefer plain text.

### reading.technical_depth

- `non_technical`: Explain the practical meaning in everyday language.
- `balanced`: Balance technical detail with a plain-language explanation.
- `expert`: Use precise technical detail suited to an expert.

### reading.jargon

- `avoid`: Use familiar words rather than jargon.
- `define`: Explain each specialist term once, in a short phrase.
- `ok`: Use specialist terms where they make the explanation precise.

### reading.tone

- `direct`: State the point directly.
- `neutral`: Use a neutral tone.
- `warm`: Use a warm, considerate tone.

### reading.evidence

- `numbers_and_sources`: Back claims with numbers and their source; leave a placeholder rather than invent a figure.
- `key_numbers`: Include the key numbers that support the point.
- `light`: Keep supporting evidence brief while staying accurate.

### reading.uncertainty

flag_explicitly: say what was checked and what was assumed.

- `flag_explicitly`: Say explicitly what you checked and what you assumed.
- `inline`: State uncertainty next to the claim it qualifies.

### reading.close_with

What the last line holds; never invent an action or a question to fill it.

- `next_action`: End with one small, concrete action the recipient can take right away, if there is one; it follows deciding.out_of_scope_steps.
- `one_question`: End with the single most useful open question, if there is one; it counts toward deciding.asks_per_message.
- `nothing`: End when the content ends, with no closing offer, question or next step.

### reading.appendix_depth (groups only)

Not a field you can set. It appears only in the merged preferences of a group (`get_audience_profile`), when its members ask for different values of `reading.technical_depth`.

- `balanced`: In an appendix or details given on request, balance technical detail with plain language, within the same word cap.
- `expert`: In an appendix or details given on request, add precise technical detail, within the same word cap.

## How to put a decision to me: `deciding`

### deciding.reversible

Only for actions the agent is already allowed to take. Never grants a permission.

- `decide_and_report`: For a reversible choice you are already allowed to make, decide and report it; this grants no permission.
- `ask`: Ask before settling a reversible choice within the task.

### deciding.batch_questions

- `end_of_task`: Gather non-blocking questions at the end of the task.
- `as_they_come`: Raise questions as they arise.

### deciding.default_answer

- `always`: Give a recommended answer with each question, unless deciding.format is options_only.
- `when_obvious`: Give a recommended answer when the choice is clear, unless deciding.format is options_only.

### deciding.asks_per_message

- `one`: Limit each message to one question or request.
- `few`: Keep each message to a few questions or requests.
- `any`: Include as many questions or requests as the message needs.

### deciding.format

- `recommendation_first`: State your recommendation before the alternatives.
- `options_then_recommendation`: Present the options, then your recommendation.
- `options_only`: Present the options without a recommendation.

### deciding.question_style

How each question is phrased; yes_confirms_recommendation falls back to multiple_choice without a recommendation.

- `open`: Ask open questions that the recipient answers in their own words.
- `multiple_choice`: Offer short labelled options so the recipient can answer with a label; with no options to offer, ask openly.
- `yes_confirms_recommendation`: Phrase each question so that a plain yes accepts your recommendation; without one, offer short labelled options; with no options to offer, ask openly.

### deciding.challenge

- `welcome_early`: Raise disagreements early.
- `after_draft`: Present a draft before raising disagreements.
- `on_request`: Raise disagreements only when asked.

### deciding.out_of_scope_steps

- `omit_unless_blocking`: In closing lines, do not list next steps outside the task, such as merge or deploy, unless one blocks it.
- `list`: In closing lines, list relevant next steps outside the task as suggestions, not as permission.

## When to interrupt me: `interrupting`

### interrupting.interrupt_for

- `blocking_only`: Interrupt only when you are blocked.
- `blocking_or_risky`: Interrupt when you are blocked or a significant risk needs attention.
- `anything`: Interrupt whenever an update is relevant.

### interrupting.group_by

- `project`: Group updates by project.
- `none`: Present updates without grouping them by project.

### interrupting.when_focused

Stored but inactive; omitted from projections and group merges.

Values: `summary_later`, `urgent_only`, `as_usual`. No instruction sentence: the value is stored and not served.

### interrupting.channel_hint

- `async_written`: For a complex topic, suggest a written, asynchronous exchange.
- `sync_call`: For a complex topic, suggest a live conversation.
- `either`: For a complex topic, written and live exchanges are equally suitable.

### interrupting.progress_updates

How a long task reports where it stands in its own conversation; never a reason to message elsewhere.

- `every_message`: During a long task, state in each message where the work stands, such as step 3 of 5.
- `phase_changes`: During a long task, state where the work stands only when a phase starts or ends.
- `end_only`: During a long task, report progress once, at the end.

### interrupting.quiet_hours

When agents do not interrupt the owner, in the owner's time zone. Times only, never a reason. from and to must differ (SPEC § 3.5). Omitted from groups and stored variants.

- `time_zone`: one of the 419 time zone names of the format.
- `from`: matches `^(?:[01][0-9]|2[0-3]):(?:00|30)$`. Start of the daily quiet range, HH:MM on the hour or half hour, inclusive.
- `to`: matches `^(?:[01][0-9]|2[0-3]):(?:00|30)$`. End of the daily quiet range, exclusive; earlier than from means the range crosses midnight.
- `all_day`: a list of at most 7 values out of `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Weekdays that are quiet all day. An empty list means none, like every optional list (SPEC § 3.2); projections omit it.

An agent is told: Do not interrupt during interrupting.quiet_hours, read in its time zone; hold what can wait until they end, or say so to the person you work for.

## What to leave out: `avoid`

- `walls_of_text`: Break up dense passages.
- `filler_intro`: Start with useful information, without a filler introduction.
- `filler_outro`: End after the useful information, without a filler conclusion.
- `hedging`: Use precise wording without needless hedging, while keeping real uncertainty.
- `emoji`: Leave emoji out.
- `rhetorical_questions`: State the point without rhetorical questions.
- `multiple_asks`: Keep the message to one ask.
- `unexplained_acronyms`: Expand acronyms at first use.
- `passive_voice`: Use the active voice.
- `exclamation`: Use periods rather than exclamation marks.
- `long_preamble`: Keep any preamble brief.
- `nested_bullets`: Use flat lists without nested bullets.
- `sarcasm`: Use literal language without sarcasm.
- `recap`: Do not restate at the end what the message or the work already showed.
- `idioms`: Use literal words rather than idioms or stock phrases.

## Languages: `languages`

A list of at most 10 language codes, the first one first, out of the 183 two-letter codes of the format (`aa` to `zu`).

An agent is told: Write to the recipient in the first language listed in languages, even when they write in another; task content such as documents, code or site copy keeps the language its task or repository sets.

## Remit: `context`

Served as data, without an instruction sentence. The server's instructions tell an agent to hold a request whose kind is not in `context.decides`.

### context.role

One value.

`software-engineer`, `senior-engineer`, `staff-engineer`, `principal-engineer`, `tech-lead`, `architect`, `engineering-manager`, `director-of-engineering`, `vp-engineering`, `cto`, `sre`, `devops-engineer`, `security-engineer`, `qa-engineer`, `data-engineer`, `data-scientist`, `ml-engineer`, `product-manager`, `product-owner`, `designer`, `ux-researcher`, `technical-writer`, `founder`, `ceo`, `coo`, `cfo`, `operations`, `marketing`, `sales`, `customer-support`, `legal`, `finance`, `people-ops`, `researcher`, `student`

### context.knows_well

A list of at most 15 values.

`javascript`, `typescript`, `python`, `php`, `ruby`, `go`, `rust`, `java`, `kotlin`, `swift`, `c-cpp`, `csharp-dotnet`, `elixir`, `scala`, `sql`, `shell`, `react`, `vue`, `svelte`, `angular`, `node`, `symfony`, `laravel`, `rails`, `django`, `spring`, `frontend`, `backend`, `mobile`, `apis`, `distributed-systems`, `databases`, `postgres`, `mysql`, `mongodb`, `redis`, `search`, `caching`, `messaging`, `data-pipelines`, `analytics`, `machine-learning`, `llm-agents`, `infrastructure`, `kubernetes`, `docker`, `terraform`, `ci-cd`, `observability`, `incident-response`, `performance`, `security`, `identity-auth`, `networking`, `cloud-aws`, `cloud-gcp`, `cloud-azure`, `cloudflare`, `cloud-costs`, `testing`, `accessibility`, `design-systems`, `ux-research`, `product-strategy`, `roadmap`, `pricing`, `billing-payments`, `growth`, `seo`, `marketing`, `sales`, `customer-support`, `compliance`, `privacy-gdpr`, `legal`, `finance`, `hiring`, `people-management`, `project-management`, `documentation`, `open-source`

### context.knows_little

A list of at most 15 values, from the same list as `context.knows_well`.

### context.decides

A list of at most 10 values.

`architecture`, `schema-changes`, `api-contracts`, `dependencies`, `infra-budget`, `vendor-choice`, `security-exceptions`, `data-access`, `release-scope`, `release-timing`, `roadmap-priority`, `pricing`, `design`, `copy-and-content`, `hiring`, `team-organization`, `incident-escalation`, `legal-review`, `spending`

## Who reads it: `visibility`

Values: `org`, `anyone_with_file`, `private`.

The format's own description of this field:

> private: owner only. org: authenticated members of the owner's organization. anyone_with_file: any reader who has the file; the consumer checks nothing, so where the file is stored controls access. Omission means org for draft compatibility. New-profile compilers should propose explicit private; preserve existing scope unless the owner approves a change. Enforced from trusted context. A reader maps public in a "0.2" profile to anyone_with_file; in "0.3", public is unknown and makes the profile absent.

On this service, a profile whose `visibility` is `org` or `anyone_with_file` is read by the members of your Teams, and by nobody else. [How to ask me](/how-to-ask-me.md#choose-who-reads-it) explains each value.

## Other fields of the file

| Field | Required | What the format says |
|---|---|---|
| `humans` | yes | The format version: `0.3`. |
| `id` | yes | Unique within its directory. Equals the basename without .md in every directory, except a file named exactly HUMANS.md or an explicitly reported draft validation mode. |
| `name` | yes | Used for resolution only, never served. |
| `updated` | yes | Gregorian calendar date string, years 0000–9999; quoting recommended. No year-0–99 remapping. |
| `aliases` | no | Used for resolution only, never served. |
| `identities` | no | Claims, never proof: resolution goes through the organization directory (SPEC § 7). |
| `states` | no | Stored variants only. Inactive in this draft; no caller state selection and no projection or application of overrides (SPEC § 3.7). |
| `notes` | no | Free text of at most 280 characters. This service stores it and serves it to no agent. |
