> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitygtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding reference: the seven sections, field by field

> A precise, field-by-field reference for the onboarding conversation's seven sections and four tools — exact schema shapes, completeness rules, and known gaps — for anyone who wants the full detail behind the walkthrough.

[Getting started](/agents-lite/getting-started) already walks through the
onboarding conversation in plain English, section
by section. This page is the same seven sections again, but at reference
density: the exact field paths, their types and validation rules, precisely
when a gap is treated as a blocking error versus a warning, and a handful of
known rough edges worth knowing about honestly rather than glossing over.
If you just want to have the conversation, start there — come back here when
you want the precise mechanics behind it, or when you're troubleshooting why
a specific answer wasn't accepted the way you expected.

<Tip>
  Everything below describes the same four tools —
  `get_onboarding_status`, `onboarding_next_step`, `submit_onboarding_answer`,
  `submit_for_review` — introduced in
  [Self-serve configuration](/agents-lite/self-serve-config#the-two-kinds-of-tools).
  You still don't need to know these tool names to use them; your Claude.ai
  or ChatGPT session calls them for you as you talk. This page is for anyone
  who wants to see exactly what's underneath that conversation.
</Tip>

## How your draft is stored

A brand-new deployment starts from one fixed empty shape: an empty team
list, an empty north star, an empty tool stack, no modules enabled, an empty
routing block, no content settings, an empty infra block, and an onboarding
status of `draft`. Every one of the seven sections below is a real, present
(if empty) part of that starting shape — nothing is missing, everything
just starts blank.

Every answer you submit through `submit_onboarding_answer` saves to your
working draft immediately. A **subset** of those edits also durably commit
to your permanent configuration record right away: specifically, replacing
an entire section at once (for example, submitting a whole updated team
list in one call). A single-field edit inside a section (for example, just
your north star's goal, or just one tool-stack category) saves to your
working draft but doesn't get its own durable commit — it rides along with
the next whole-section replacement, or with your final `submit_for_review`,
which always commits everything regardless. In the rare case a commit
itself fails after your answer already saved, you get an explicit warning
saying so — your answer is never silently lost, just not yet durably
recorded.

The seven sections are always presented in the same fixed order, because
later sections build on earlier ones: **team → north star → tool stack →
modules → routing → content → infra**, followed by an eighth, non-fillable
step — **review** — once everything above is complete. Infra sits last on
purpose: every other section is a Gravity-side configuration decision you're
making; infra is the one section actually asking whether you've gone and
done something on your own side, so it deliberately waits until every other
decision is already settled.

## 1. Team

Who's on the team the agents work for.

| Field                                                   | Type            | Notes                                                         |
| ------------------------------------------------------- | --------------- | ------------------------------------------------------------- |
| `id`, `name`, `email`                                   | string          | Required for every team member                                |
| `role`                                                  | string          | Free text                                                     |
| `linkedin_url`                                          | string or null  | Needed before any LinkedIn module can go live for that person |
| `modules_active`                                        | list of strings | Which modules this person is active in                        |
| `is_primary`                                            | boolean         | Exactly one team member must have this set                    |
| `messaging_handle`, `linkedin_urn`, `messaging_user_id` | string or null  | The last two are filled in during provisioning, not by you    |

**Completeness:** at least one team member, with exactly one marked
`is_primary`. Having more than one primary is always treated as an error,
at any stage. Having zero primaries is a soft warning while your draft is
still in progress, but becomes a blocking error once you submit for review.
An empty team list is treated as "nothing to check yet" for this specific
rule, not as its own separate error.

## 2. Your north star

Your actual goal, in your own words.

| Field       | Type                                                            | Notes                                                                          |
| ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `goal`      | string                                                          | A short, specific description of what you're aiming for                        |
| `metrics`   | string                                                          | One sentence on how you'll measure progress — a single description, not a list |
| `timeframe` | one of: `this_month`, `this_quarter`, `this_year`, `multi_year` | The horizon your goal is scoped to                                             |

This comes right after team and before tool stack/modules on purpose — once
set, the modules section echoes your own stated goal back at you while you
decide what to turn on, and Company Clarity reads it directly.

**Completeness:** all three fields must be present and non-blank (and
`timeframe` must be one of the four valid values) before this section
counts as done — treated the same way as team's primary-contact rule: a
warning while your draft is in progress, a blocking error once you submit.

<Note>
  Like the registry-governed fields elsewhere in this walkthrough (tool-stack
  categories, LinkedIn options, module keys) and `content.path` below, an
  invalid `timeframe` value is rejected immediately, the moment you submit
  it — before anything is saved — naming the four valid values in the
  rejection message. This applies whether you set it directly (a
  `north_star.timeframe` answer on its own) or as part of setting the whole
  north star section at once. A blank or missing `timeframe` is a separate
  case, and behaves differently: leaving it unset for now is exactly what
  being in `draft` is for, so that's still a soft warning while you're in
  progress, becoming a blocking error only once you submit for review — see
  Completeness above.
</Note>

## 3. Tool stack

Which tool you actually use for each category. See
[Available integrations & modules](/agents-lite/integrations-and-modules#integrations-by-category)
for the full, current list of valid options per category, build status, and
the "something else" path for a tool that isn't listed yet.

| Category                                                                 | Choice                                  |
| ------------------------------------------------------------------------ | --------------------------------------- |
| Messaging, Email, Calendar                                               | Pick exactly one                        |
| Data Store, CRM, File Storage, Meeting Notes, Programmatic Email Sending | Pick one, or skip the category entirely |
| LinkedIn                                                                 | Pick any number, or none                |

For any category set to "something else," you also need to describe what
the tool actually is in a matching companion field — the walkthrough tells
you this explicitly when it applies, and the description is required
(non-blank) the moment you pick "something else," at any stage.

**Completeness:** there's no single pass/fail flag for this section — the
walkthrough instead looks at which of the eight categories above you've set
anything for at all, and nudges you toward the ones you haven't touched yet.

Four of those eight categories (data store, file storage, meeting notes,
programmatic email sending) are genuinely, deliberately skippable —
programmatic email sending's own guidance is explicit that selecting
nothing is a common, valid choice (it just means outreach stays
Gmail-draft-only by default). Each of these four now has a real,
explicit **"none"** option to submit, the same way CRM already did — so
"I'm intentionally skipping this category" is a normal, first-class answer
rather than something you have to work around by leaving a field blank.
Submit `"none"` for any of the four the moment you know you don't need it,
and the walkthrough's step-by-step guidance stops nudging you toward that
category right away, moving on to the next thing that actually needs your
attention. Your real completeness bar (checked when you submit for review)
still only ever requires a data store or a CRM (and only if you've enabled
at least one module), plus whatever your specific enabled modules need — a
category set to `"none"` never counts toward satisfying that requirement,
exactly as if you'd left it blank; the only thing that changed is that now
there's an explicit way to say so instead of the walkthrough guessing at
your intent from silence.

## 4. Modules

Which agents to actually turn on. See
[Agent reference](/agents-lite/agent-reference) for the full purpose,
trigger, inputs, and outputs of every module, and
[Available integrations & modules](/agents-lite/integrations-and-modules)
for the base-package/add-on breakdown and per-module settings.

Each module you enable is a simple `{enabled: true}` (plus optional
module-specific settings) at `modules.<module key>`. Rather than handing
you a bare technical list, the walkthrough surfaces a plain-English
description of what each available module does — and, since your north
star is already set by this point, echoes your own stated goal back
alongside it, so you can judge fit for yourself rather than guessing from a
feature name.

**Completeness:** at least one module enabled. This doesn't yet check
whether that module's own requirements (a specific tool-stack category, a
LinkedIn connection, and so on) are actually satisfied — that's a separate
check, described next.

**The gap-check, right after modules.** Once you've enabled at least one
module, the walkthrough re-checks your whole draft as if you were
submitting it right now, specifically for gaps your chosen modules created
— a module needing a tool-stack category you skipped, or a LinkedIn
connection you haven't set up. If it finds any, it sends you back to tool
stack momentarily to close exactly that gap before moving on to routing.
Team members who need voice calibration but have no voice source yet are
checked the same forward-looking way, but that specific gap surfaces later,
at the Content section itself, not here — it never sends you back to tool
stack (see Content below).

## 5. Routing

Who gets alerted for what.

| Field                    | Type   | Notes                                                       |
| ------------------------ | ------ | ----------------------------------------------------------- |
| `urgent_alert_recipient` | string | A team member's `id` — who gets alerted for anything urgent |
| `channels`               | object | Arbitrary channel name/id → purpose-string pairs            |

**Completeness:** a recipient is set, and at least one channel entry exists.

<Note>
  If `urgent_alert_recipient` is set, it's cross-checked against your real
  team section — a typo or a stale id (one that doesn't match any current
  team member's `id`) is flagged, naming the id you gave and the real ids it
  could have matched. Treated the same way as the rest of this section's own
  completeness: a soft warning while your draft is still in progress, a
  blocking error once you submit for review. If your team roster is entirely
  empty when you set this, there's nothing yet to check it against, so
  nothing is flagged until you've actually added team members.
</Note>

## 6. Content

Voice calibration, plus your ICP/goals context that the strategic-monitoring
modules read.

| Field                                    | Type                          | Notes                                                                                                                                                                                                                                                                             |
| ---------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`                                   | `corpus` or `interview`       | Which voice-calibration path you're taking — like the registry-governed fields elsewhere in this walkthrough (tool-stack categories, LinkedIn options, module keys), `corpus_files[].type` below, and `north_star.timeframe` above, an invalid value here is rejected immediately |
| `gtm_context_notes`                      | string                        | Free-text ICP/goals context                                                                                                                                                                                                                                                       |
| `corpus_files`                           | list of `{name, type, owner}` | Required if `path` is `corpus`; `type` is one of `cold_email`, `investor_email`, `linkedin_post`, `deck`, `brand_guidelines`, `other`; `owner` (optional) attributes a file to a specific team member's voice                                                                     |
| `interview_scheduled` / `interview_date` | boolean / date or null        | Required if `path` is `interview`                                                                                                                                                                                                                                                 |

**Completeness:** you've either listed at least one corpus file (with
`path: corpus`) or marked an interview as scheduled (with `path:
interview`). If any of your enabled modules need voice calibration, this
section isn't considered done until that's also true — checked as if you
were submitting right now, the same forward-looking check used for the
modules gap-check above. Separately, if a specific team member needs voice
calibration but owns no corpus file, that's flagged as its own gentle,
always-non-blocking reminder — it never stops you from finishing, at any
stage.

## 7. Infra

Whether you've already started on any infrastructure that's on your own
side to create.

| Field                         | Type                                                        | Notes                                                                                                                                                                                        |
| ----------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer_github_repo`        | string or null                                              | Your GitHub org/repo slug (e.g. `acme-corp/agents-light`)                                                                                                                                    |
| `customer_anthropic_org`      | string or null                                              | Your Anthropic org name (e.g. `Acme Corp`)                                                                                                                                                   |
| `hosting_platform`            | one of: `vercel`, `railway`, `aws`, `azure`, `gcp`, `other` | Which hosting platform you've chosen — a registry-governed field, rejected immediately if set to anything else, the same as the other registry-governed fields elsewhere in this walkthrough |
| `customer_deploy_url`         | string or null                                              | Your actual deploy URL, once one exists — a separate, later answer from `hosting_platform`: you can name the platform you've picked well before a real deploy URL exists                     |
| `customer_kv_name`            | string or null                                              | Your own label/name for your KV/Redis database (e.g. `acme-prod-kv`), if you've already created one                                                                                          |
| `hosting_platform_preference` | one of: `vercel`, `railway`, `aws`, `azure`, `gcp`, `other` | A *request*, not a tier change — signals you'd like to self-host, before an operator has decided to flip your hosting tier to customer-managed                                               |

This section only asks about a given component (GitHub, Anthropic, hosting,
KV) if that component's tier is already set to customer-managed — available
when you have a specific reason to own a given piece yourself — **and** you
haven't yet
reported an identifying value for it. It never asks about a component
that's on the Gravity-managed tier instead, since there's nothing on your
side to report for it. Which tier each component is on isn't something you
set in this conversation or through any onboarding tool — that's a decision
already made before onboarding starts, not a choice this section lets you
change.

`hosting_platform_preference` is the one exception to that rule, and
deliberately so: unlike `hosting_platform` (which only appears once your
hosting tier is already customer-managed), this field is offered regardless
of your current tier — it's how you tell Gravity you'd *like* to move to
customer-managed hosting even before an operator has made that call.
Setting it doesn't change your tier by itself; a Gravity operator follows up
to actually flip it and set things up. It stops being surfaced once you've
set a value, or once your hosting tier is already customer-managed (at that
point the real `hosting_platform` field above is what matters).

**Completeness:** infra is the only section that's allowed to stay
completely empty forever without ever blocking `submit_for_review` — a
deployment that's Gravity-managed on all four components has nothing
pending here, ever, and falls straight through to review. For a component
that is on your customer-managed tier, reporting its identifying value is
invited but entirely optional at every stage: skipping it never blocks
submission, and you can report it (or come back and report it later) any
time before go-live.

<Note>
  **Never share an actual password, API key, token, or secret value in any
  of these fields — only names, slugs, or URLs.** A value that looks
  credential-shaped (matching a common API-key/token prefix, a connection
  string with credentials embedded in the URL itself, or containing
  `token=`, `key=`, `secret=`, or `password=`) is rejected immediately, the
  moment you submit it, before anything saves — whether you submit that one
  field on its own, or as part of answering the whole infra section in a
  single call — and checked again, unconditionally, at `submit_for_review`
  regardless of onboarding phase, the one infra-related check that's always
  an error rather than a phase-gated warning. Once you submit your
  configuration, you'll get a secure `/provision-secrets` link to share any
  real credentials — see
  [Security & credentials](/agents-lite/security-and-credentials).
</Note>

## Submitting for review

Once every section above is filled in — infra excepted, since it's allowed
to stay empty (see Infra above) — `submit_for_review` re-validates
your **entire** draft in one pass, checked as if you were submitting right
now (the same forward-looking check used by the two gap-checks described
above). Zero errors flips your status to `submitted`, durably commits your
whole configuration, and hands off to a Gravity operator for provisioning —
this is the one action that always durably commits, regardless of what
kind of edit got you there. Any errors come back as a specific, itemized
list (paired with any non-blocking warnings, so you see the full picture in
one response) — nothing advances silently, and nothing gets left for you to
discover only once it fails for real later.

<Warning>
  **Known gap:** a handful of later-stage prerequisites (values that only
  matter once your infrastructure is actually being provisioned) are
  checked one stage further than what `submit_for_review` itself gates on.
  In practice, that means an outstanding item in this category can appear
  in your submission's warnings, but can never by itself block your
  submission from going through. It's visible, not blocking — a Gravity
  operator still sees it during provisioning.
</Warning>

## What each tool actually returns

For anyone building against these tools directly (or just curious what's
underneath the conversation):

**`get_onboarding_status`** — your current status (`draft` or `submitted`),
a section-by-section completeness summary for all seven sections plus your
checklist progress, and your full current list of validation issues (each
tagged `error` or `warning`, using your **real, current** status to decide
severity — so a north-star or module gap shows as a warning while you're
still in `draft`, and only becomes an error once you're at `submitted`).

**`onboarding_next_step`** — the single next section to work on, a short
summary of what's missing, a few lines of specific guidance, a suggested
field path, and (for the tool-stack section specifically) the real, current
list of valid option keys for whichever category it's pointing you to.
Where this differs from `get_onboarding_status`: a couple of its branches
(the modules gap-check and the content voice-check described above) always
check as if you were at the `submitted` stage, regardless of your real
current status — so it's normal for these two tools to disagree on whether
a given gap is "just a warning" or "a real blocker" for the exact same
underlying issue. Neither is wrong; they're answering slightly different
questions (where you really stand today, versus what still needs to be
true before you can submit).

**`submit_onboarding_answer`** — sets one field to a new value. Rejects
immediately, before saving anything, if: the field path isn't a real one
that exists in your configuration; the value isn't a real, valid option for
a field governed by the current integration/module list (tool stack
categories, LinkedIn accounts, module keys); it's an invalid
`north_star.timeframe` value (see Your north star above — checked the same
way whether you set it directly or as part of the whole north star
section); the value looks credential-shaped for one of the four infra
identifier fields (see Infra above — checked the same way whether you set
one directly or as part of answering the whole infra section at once); it
tries to set one of the 5 operator-managed infra tier fields (`github`,
`anthropic`, `hosting`, `kv`, `deployment_path` — see Infra above, and same
whole-section-or-direct check); or the value doesn't structurally fit that
field's own shape (for example, submitting a whole team list with a member
missing a required email). Once it passes all these checks, it saves to
your draft and tells you whether that particular edit also durably
committed (see "How your draft is stored" above).

**`submit_for_review`** — described above. Returns either
`{submitted: false, error: "not_ready", ...}` with the full issue list, or
`{submitted: true, ...}` with a plain-English confirmation and any
remaining (non-blocking) warnings.

## Known gaps, gathered in one place

For quick reference, everything flagged above as a known rough edge:

1. **A handful of later-stage (provisioning-time) prerequisites can never
   by themselves block `submit_for_review`** — they surface as warnings in
   an otherwise-successful submission, not as errors.
2. **`get_onboarding_status` and `onboarding_next_step` can disagree on
   severity for the same underlying gap** — by design, since one reports
   your real current status and the other previews what submitting right
   now would require.

Previously, this list also carried a fifth gap: four "optional" tool-stack
categories (data store, file storage, meeting notes, programmatic email
sending) had no explicit "I'm skipping this" value, so the walkthrough's
guidance could nudge you toward one even when nothing you'd enabled needed
it. That's fixed — each of the four now has a real `"none"` option, the
same way CRM already did, and the walkthrough stops nudging the moment you
submit it. See the tool-stack section above.

This list previously also carried two more gaps, now both fixed. An invalid
`north_star.timeframe` value used to be accepted at submission time,
caught only later when your status was checked or you submitted for
review — it's now rejected immediately, the same as every other
registry/enum-governed field in this walkthrough (see Your north star
above). And `routing.urgent_alert_recipient` used to have no cross-check
against your real team list at all, so a typo'd or stale id was accepted
cleanly at every stage — it's now cross-checked, phase-gated the same way
as every other completeness rule (see Routing above).

Three further gaps in the infra section specifically, found in review and
now all fixed. First, the credential-shape check on the four infra
identifier fields only fired when you set one of them directly — answering
the whole infra section in a single call (the same shape every other
section already supports) could carry a credential-shaped value straight
past it; the check now covers both shapes identically (see the Infra
section's own Note above). Second, nothing previously stopped a customer
from setting or flipping one of the 5 infra tier fields
(`github`/`anthropic`/`hosting`/`kv`/`deployment_path`) directly, even
though this page always described that decision as the operator's alone —
`submit_onboarding_answer` now rejects any attempt to set one, in either
submission shape, which is what actually makes that guarantee true today.
Third, answering the whole infra section in a single call used to fully
replace it — so reporting just one identifier that way could silently
erase any tier decision the operator had already made for the *other*
components, even though nothing about setting that tier was itself
rejected. Whole-section infra answers now merge with what's already there
instead of replacing it, so reporting one piece never erases another.

None of these block you from completing onboarding — they're honest,
specific rough edges worth knowing about up front rather than discovering
mid-conversation.

## Next steps

* [Getting started](/agents-lite/getting-started) — the friendly, narrative
  walkthrough of this same conversation, plus what happens after you submit
* [Self-serve configuration](/agents-lite/self-serve-config) — how the
  connector and its tools work mechanically, including reconnecting once
  you're live
* [Agent reference](/agents-lite/agent-reference) — full detail on every
  module the modules section above lets you enable
* [Available integrations & modules](/agents-lite/integrations-and-modules) —
  the current option list for every tool-stack category