Onboarding reference: the seven sections, field by field

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.

​

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. 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. 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.

​

3. Tool stack

Which tool you actually use for each category. See Available integrations & modules 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. 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 for the full purpose, trigger, inputs, and outputs of every module, and Available integrations & 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. Completeness: a recipient is set, and at least one channel entry exists.

​

6. Content

Voice calibration, plus your ICP/goals context that the strategic-monitoring modules read. 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. 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.

​

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.

​

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 — the friendly, narrative walkthrough of this same conversation, plus what happens after you submit
• Self-serve configuration — how the connector and its tools work mechanically, including reconnecting once you’re live
• Agent reference — full detail on every module the modules section above lets you enable
• Available integrations & modules — the current option list for every tool-stack category