Recommendations and overrides

Last updated Jun 14, 2026

When a founder declares an Intent with goal=start_company, Matter's resolver fills in every Day-0 field with an opinionated default — authorised shares, par value, founder vesting, repurchase window, fiscal year end, registered agent, officer slate, EIN application, 83(b) e-file rail, bank-account processor, indemnification policy, signing mode, and more. Each default is paired with a Recommendation carrying the basis (NVCA standard, DGCL default, IRS safe harbor, community-property law, etc.), a one-paragraph rationale, and the override paths for changing it.

This page is the canonical inventory of the Day-0 recommendations the resolver emits, and the worked examples for the two ICPs at either end of the customisation spectrum: the novice founder who accepts every default, and the technical founder who overrides 12 fields.

The resolution flow

POST /v1/intents
{
  "goal": "start_company",
  "parameters": {
    "proposed_name": "Lattice Labs",
    "founder": { "name": "Jane Doe", "email": "jane@lattice.dev", "home_state": "CA" }
  }
}

Returns:

{
  "id": "int_…",
  "status": "resolved",
  "execution_plan": { "steps": [ … ] },
  "resolved_recommendations": [
    {
      "field": "share_structure.authorized_common",
      "recommended_value": 10000000,
      "basis": "nvca_standard",
      "rationale": "10M authorised common is the NVCA Model Cert default …",
      "override_paths": [
        { "endpoint": "POST /v1/intents", "field": "parameters.share_structure.authorized_common", "context": "intent_parameters" },
        { "endpoint": "POST /v1/entities", "field": "share_structure.authorized_common", "context": "create_entity_body" }
      ],
      "document_merge_fields": [
        { "document_kind": "certificate_of_incorporation", "merge_field": "Authorized Shares" }
      ],
      "confidence": "best_practice",
      "citations": [ { "authority": "NVCA Model Cert v2024 §IV" } ]
    },
    /* … ~45 more entries … */
  ]
}

The resolved_recommendations[] array is the founder-facing audit trail. The dashboard renders each entry as a hover card next to the corresponding form field; the docs render the same content as a "What Matter recommends" table; CI snapshot-tests the full array against three canonical fixture intents (novice-DE-solo, technical-DE-cofounder-CA-community-property, serial-DE-with-portfolio) so changes to the rules table are deliberate.

The Day-0 rules table

Every value Matter recommends, with its basis and citation. Override on POST /v1/intents (parameters.<field>), on PATCH /v1/intents/{id} (parameters.<field>), on POST /v1/entities (request body), or on POST /v1/entities/{id}/formation_packet (request body) — whichever endpoint you're calling. The override_paths[] array on each Recommendation enumerates the valid paths.

Officer-slate derivation

When officer_slate[] is omitted, the resolver derives it from the founder set:

Worked example — novice founder accepts every default

The novice path: pass goal=start_company with the minimum required parameters and let the resolver fill everything else. No overrides; the Day-0 cookbook (Day-0 Delaware C-Corp in one API call) shows the resulting formation_packet payload.

curl https://api.mattermode.com/v1/intents \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Matter-Version: 2026-05-01' \
  -H 'Idempotency-Key: 18a3-…' \
  -d '{
    "goal": "start_company",
    "parameters": {
      "proposed_name": "Lattice Labs",
      "founder": {
        "name": "Jane Doe",
        "email": "jane@lattice.dev",
        "home_state": "CA"
      }
    }
  }'

The resolver returns ~32 resolved_recommendations[] entries (1 per Day-0 default in the table above). The founder reviews them in the dashboard, accepts everything, and posts to POST /intents/{id}/execute to commit. formation_packet cascades; minute book lands.

Worked example — technical founder overrides 12 fields

The technical-founder path: structured Intent with explicit overrides on the values that matter. Recommendations still emit for the un-overridden fields; overrides are honoured directly.

curl https://api.mattermode.com/v1/intents \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Matter-Version: 2026-05-01' \
  -H 'Idempotency-Key: 24f8-…' \
  -d '{
    "goal": "start_company",
    "parameters": {
      "proposed_name": "Meridian Lattice",
      "founder": {
        "name": "Idris Rahman",
        "email": "idris@meridianlattice.dev",
        "home_state": "CA"
      },
      "founding_team": [
        { "name": "Reuben Cho", "email": "reuben@meridianlattice.dev", "home_state": "CA", "equity_basis_points": 4500 }
      ],
      "share_structure": {
        "authorized_common": 12000000,
        "option_pool_reservation_percent": 15
      },
      "founders": [
        {
          "vesting": { "cliff_months": 6, "total_months": 36, "repurchase_option_window_days": 60 },
          "acceleration": { "single_trigger_change_of_control_percent": 50, "double_trigger_change_of_control_percent": 100 }
        }
      ],
      "governance": {
        "board_size": 3,
        "action_by_written_consent_allowed": false,
        "quorum_basis_points": 6700
      },
      "officer_slate": [
        { "stakeholder_id": "stk_idris", "title": "chief_executive_officer", "authority_basis": "board_resolution" },
        { "stakeholder_id": "stk_reuben", "title": "chief_technology_officer", "authority_basis": "board_resolution" },
        { "stakeholder_id": "stk_outside_counsel", "title": "secretary", "authority_basis": "dgcl_142_minimum" }
      ],
      "include_bank_account_application": { "processor": "mercury" }
    }
  }'

Twelve overrides:

1. share_structure.authorized_common — 12M (vs default 10M)
2. share_structure.option_pool_reservation_percent — 15% (vs default 10%)
3. founders[].vesting.cliff_months — 6 (vs default 12)
4. founders[].vesting.total_months — 36 (vs default 48)
5. founders[].vesting.repurchase_option_window_days — 60 (vs default 90)
6. founders[].acceleration.single_trigger_change_of_control_percent — 50 (vs default 0)
7. governance.board_size — 3 (vs default 2 for two-founder)
8. governance.action_by_written_consent_allowed — false (vs default true; tightens governance)
9. governance.quorum_basis_points — 6700 (supermajority vs default 5001)
10. officer_slate[] — explicit non-founder Secretary (outside counsel)
11. include_bank_account_application.processor — mercury (vs default column)
12. (implicit via founding_team) — second founder added with explicit equity_basis_points: 4500

The remaining ~20 fields (par value, fiscal year end, registered agent, EIN application, 83(b) e-file rail, indemnification advancement, signing mode, routine install policy, IP assignment scope, etc.) keep their resolved defaults — each emits a Recommendation in resolved_recommendations[] so the dashboard can show them.

Snapshot-tested fixtures

CI snapshots three canonical Intent fixtures and asserts the resolved_recommendations[] arrays haven't drifted:

• novice-DE-solo — single founder, DE, all defaults, no community-property considerations
• technical-DE-cofounder-CA-community-property — two cofounders, both CA-resident (community property), explicit officer-slate with non-founder Secretary
• serial-DE-with-portfolio — serial entrepreneur using Portfolio resource, prior-practice basis on registered agent and bank-account processor inheritance

Modifying the rules table requires regenerating the snapshots: bun run --filter docs test:recommendations -- --update-snapshots. Reviewers compare the diff and approve deliberately.

Audit table — Ironsides parity

The recommendation engine is sized so that every merge field in every Ironsides Delaware C-Corp template resolves to either a captured spec field or a Recommendation. The Ironsides parity check (apps/docs/scripts/ironsides-parity-check.ts, runs in apps/docs build) walks each .cftemplate, extracts every [BRACKETED] placeholder and (( conditional )) flag, and confirms each maps. Zero unmapped merge fields = pass.

Related

• Day-0 Delaware C-Corp in one API call — the worked formation_packet
• Customize bylaws clauses — clause-toggle flow for the technical-founder bylaws override
• Handle a cofounder departure — sole-director board reconstitution
• Impose retroactive vesting — the share_ledger amend verb