---
narrative:
  status: enriched
id: SCI-CRM-ENT-006
title: Create Organization
design: SCR-CRM-ENT-006
prompt: SVP-CRM-ENT-002
product_area: crm
module: entities
revision: 1
status: draft
product_intent: proposed
implementation_evidence: observed
implementation_state: implemented
conformance: not-verified
source_sha:
  rhythm-v2-docs: 7deec3d3d1bfde6660cc7ff1be66184644f0dfcb
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
route:
  pattern: '/console/{tenantId}/crm/organizations/new'
  parameters:
    - 'tenantId: workspace identity from the console shell'
  registration: >-
    react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
    react-console:lib/routes/definitions.ts (crm.organizations.new)
  parent_layout: Console workspace shell; Page content uses its existing responsive console padding.
  navigation: >-
    The record list’s primary action opens the chooser; Continue opens the type form and creation
    opens the saved record.
  guards:
    - RequirePermission checks permissions.crm.organizations.create
    - >-
      Duplicate override availability follows the evaluated organization
      create-despite-duplicate-block grant
  deep_links:
    - '?type=<typeId> opens the selected type’s effective form'
    - '?selected=<typeId> returns to the chooser with that selection'
source:
  repository: react-console
  files:
    - 'app/(console)/console/[tenantId]/crm/organizations/new/page.tsx'
    - components/records/create/create-record-screen.tsx
    - components/records/create/record-type-chooser.tsx
    - components/records/create/chosen-type.tsx
    - components/records/create/use-create-form.ts
    - components/organization-editor/organization-editor.tsx
    - components/organization-editor/options.ts
    - components/forms/form-renderer.tsx
    - lib/organizations/create.ts
    - lib/routes/definitions.ts
    - components/forms/registry/fields.tsx
    - components/contact-editor/fields/entity-pickers.tsx
  entry_component: CreateRecordScreen with OrganizationEditor
  modules:
    - lib/authz evaluated grants
    - lib/routes registered navigation
    - Platform metadata and effective form resolution
    - lib/drafts sign-in recovery
  pull_requests: []
  commits:
    - baf6dae382d6f41dce976c7f848667ccc37e076f
components:
  - CMI-CRM-ENT-008
data:
  reads:
    - listOrganizationTypes supplies active type choices
    - getEffectiveDefinitions and Platform definition/metadata reads supply the organization form
    - Region choices and bound record pickers supply the form’s reference values
  writes:
    - createOrganization with a stable client create identity and optional duplicate override reason
  binding: >-
    The expanded form determines bound scalar, collection and custom-value write keys. The chosen
    type is supplied independently of whether the definition displays that binding. Generic record
    fields may select the parent organization where the effective form includes it.
  server_state: >-
    The create-form and description reads establish the form. The create response identifies the new
    organization; there is no general organization edit path in this component.
  local_state: >-
    The editor holds form values, issues, duplicate-block details, submission state and one create
    intent. A restored draft overlays the definition defaults.
  errors: >-
    Unreadable or invalid definitions produce explicit problem content. Server field errors join the
    form issue list and focus the first issue; another refusal is reported in a toast. Duplicate
    blocks use their dedicated refusal panel.
  loading: >-
    Loading Organization Fields waits for the description and create definition. The chooser has its
    own type-loading and retry state.
  cache_invalidation: >-
    A successful create discards its draft and navigates to the returned organization. A changed
    form clears outdated server and duplicate issues.
  persistence: >-
    The editor holds dirty values through the shared sign-in draft hooks and offers explicit
    restored-draft discard. Cancel navigates directly; this component contains no dirty-navigation
    confirmation guard.
actions:
  - design_label: Create
    operation_id: createOrganization
    as_built: >-
      A valid attempt submits through createOrganization with the held create identity and opens
      Organization 360 after success.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Create Anyway (with a reason)
    operation_id: createOrganization
    as_built: >-
      The duplicate refusal exposes the authorized override with a reason and resubmits the same
      create intent; changing the draft clears the old block.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Cancel
    operation_id: 'none: local interaction'
    as_built: >-
      Cancel navigates directly to the chooser when a type was chosen, otherwise to Organizations;
      no dirty confirmation guard is attached here.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Review field issues
    operation_id: 'none: local interaction'
    as_built: The issue popover selects an issue and asks FormRenderer to reveal and focus its control.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Continue from type choice
    operation_id: 'none: local interaction'
    as_built: >-
      The chooser keeps a selected card and Continue writes the chosen type into the route query,
      opening its form.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Retry form loading
    operation_id: 'none: local interaction'
    as_built: >-
      Retry repeats the failed definition/type read; an unreadable configured form is not replaced
      by an invented default.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
  - design_label: Save & New
    operation_id: 'none: local interaction'
    as_built: >-
      Unavailable: the action bar supplies no Save & New callback and every successful creation
      navigates to its record.
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/organization-editor/organization-editor.tsx
authorization:
  frontend_guards:
    - RequirePermission checks permissions.crm.organizations.create
    - >-
      Duplicate override availability follows the evaluated organization
      create-despite-duplicate-block grant
  backend:
    - >-
      createOrganization requires crm.organizations.create; duplicate override separately requires
      crm.organizations.create-despite-duplicate-block
    - 'Organization type, region and bound record reads retain their own permissions'
observability:
  logs: >-
    No dedicated screen logging is established in the listed components; shared request and service
    logging remains outside this screen’s telemetry claim.
  metrics: No screen-specific metric emission is established by the inspected source.
  events: >-
    Navigation and request state drive the screen. Record creation uses service-owned change
    capture; no separate screen domain-event emitter is established.
  errors: >-
    Unreadable or invalid definitions produce explicit problem content. Server field errors join the
    form issue list and focus the first issue; another refusal is reported in a toast. Duplicate
    blocks use their dedicated refusal panel.
fidelity:
  - difference: >-
      The design lists Save & New, but OrganizationEditor supplies no onSaveAndNew or repeat-create
      action. Cancel goes directly to the chooser for a chosen type or to the list without
      dirty-draft confirmation. The action is documented as unavailable rather than silently
      attributed to Create.
    kind: open
    reference: FND-CRM-ENT-148
    provenance: observed
    source: >-
      react-console:components/records/create/create-record-screen.tsx;
      rhythm-v2-docs:specs/crm/entities/design/screens/SCR-CRM-ENT-006-create-organization.md
verification:
  component_tests: []
  screen_acceptance:
    - TST-CRM-ENT-775
    - TST-CRM-ENT-785
  integration:
    - TST-CRM-ENT-786
    - TST-CRM-ENT-789
    - TST-CRM-ENT-795
  feature_acceptance:
    - FAS-CRM-ENT-02
  accessibility: >-
    not-verified; observed labels, focus helpers and semantic controls do not establish a complete
    keyboard/screen-reader audit (FND-CRM-ENT-079)
  deployment: >-
    No deployment of the pinned commit is verified by this authoring job; documented captures are
    fixtures and the live suites retain not-run.
screenshots:
  - state: organization chooser desktop
    viewport: 1440 × 1000 pixels (image dimensions; full-page images and element crops may differ from the browser viewport)
    path: SCI-CRM-ENT-006/organization-chooser-desktop.png
    sha256: 9b518fafa51cbad76349adc64750f2dfb7498ca6d72a9b473eff1f776442ea8b
    captured_at: '2026-10-17T20:58:13-04:00'
    captured_from: >-
      react-console:docs/screenshots/record-creation/organization-chooser-desktop.png at
      baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live
      deployment
  - state: organization form
    viewport: 1440 × 1000 pixels (image dimensions; full-page images and element crops may differ from the browser viewport)
    path: SCI-CRM-ENT-006/organization-form.png
    sha256: de510d93f400dd3108c541bb901f36390a6ac5369f360df6e4bc50c3a25ab075
    captured_at: '2026-10-17T20:58:13-04:00'
    captured_from: >-
      react-console:docs/screenshots/record-creation/organization-form.png at
      baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live
      deployment
evidence:
  - 'react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx'
  - 'react-console:components/records/create/create-record-screen.tsx'
  - 'react-console:components/records/create/record-type-chooser.tsx'
  - 'react-console:components/records/create/chosen-type.tsx'
  - 'react-console:components/records/create/use-create-form.ts'
  - 'react-console:components/organization-editor/organization-editor.tsx'
  - 'react-console:components/organization-editor/options.ts'
  - 'react-console:components/forms/form-renderer.tsx'
  - 'react-console:lib/organizations/create.ts'
  - 'react-console:lib/routes/definitions.ts'
  - 'services-crm:modules/entities/aws/api/organizations.routes.ts'
  - 'react-console:docs/affiliations/screens-v2/README.md'
  - >-
    react-console:docs/screenshots/record-creation/organization-chooser-desktop.png at
    baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live
    deployment
  - >-
    react-console:docs/screenshots/record-creation/organization-form.png at
    baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live
    deployment
  - 'rhythm-v2-docs:specs/crm/AUTHORIZATION.md'
  - 'rhythm-v2-docs:specs/crm/entities/design/screens/SCR-CRM-ENT-006-create-organization.md'
narrative_sources:
  - section: What Was Built
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Routing
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Source
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Components
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Data Integration
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Actions as Implemented
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Authorization
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Observability
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Design Fidelity
    provenance: observed
    source: >-
      react-console:app/(console)/console/[tenantId]/crm/organizations/new/page.tsx;
      react-console:components/records/create/create-record-screen.tsx;
      react-console:components/records/create/record-type-chooser.tsx;
      react-console:components/records/create/chosen-type.tsx;
      react-console:components/records/create/use-create-form.ts;
      react-console:components/organization-editor/organization-editor.tsx;
      react-console:components/organization-editor/options.ts;
      react-console:components/forms/form-renderer.tsx; react-console:lib/organizations/create.ts;
      react-console:lib/routes/definitions.ts
  - section: Verification
    provenance: test
    source: TST-CRM-ENT-775; TST-CRM-ENT-785; TST-CRM-ENT-786; TST-CRM-ENT-789; TST-CRM-ENT-795
  - section: Design Fidelity
    provenance: documented
    source: FND-CRM-ENT-145
    note: >-
      The missing design fields and Screen Acceptance Specification are documented gaps; matching an
      observed action does not approve its product intent.
---

# Create Organization

## What Was Built

Create Organization asks for a type before opening the organization form. A type-specific definition or workspace default supplies the fields, with a built-in definition used only where resolution permits it. The form binds supported values and submits the chosen type with a stable creation identity. Success opens Organization 360. The built action bar has Create Organization and Cancel, with no Save & New.

## Routing

The static new page takes precedence over the record-id route. The type query chooses the form; an absent type lets CreateRecordScreen read the active catalogue and decide whether to show the chooser. A single choice is preselected rather than created automatically. With no active choices the permitted built-in form opens without a classification. The page checks creation permission before either step.

## Source

CreateRecordScreen with OrganizationEditor owns the coordination described here. The source manifest identifies its page, presentation collaborators and request adapters at the pinned console commit. Service route evidence identifies the authoritative operation names and permission declarations. No pull-request attribution or earlier implementation date is inferred from the current checkout.

## Components

The configured organization form uses the registered Organization Selector variant for organization-valued fields such as hierarchy selection. It reaches that variant through the shared form field registry. This does not imply use of the contact-specific affiliation drawer or contact collection editors. Platform owns the form engine and common input scaffolding; the ownership finding in Console shell remains open. The generic organization form is responsible for its own draft and submit lifecycle.

## Data Integration

The expanded form determines bound scalar, collection and custom-value write keys. The chosen type is supplied independently of whether the definition displays that binding. Generic record fields may select the parent organization where the effective form includes it.

The create-form and description reads establish the form. The create response identifies the new organization; there is no general organization edit path in this component. The editor holds form values, issues, duplicate-block details, submission state and one create intent. A restored draft overlays the definition defaults.

Loading Organization Fields waits for the description and create definition. The chooser has its own type-loading and retry state. Unreadable or invalid definitions produce explicit problem content. Server field errors join the form issue list and focus the first issue; another refusal is reported in a toast. Duplicate blocks use their dedicated refusal panel.

A successful create discards its draft and navigates to the returned organization. A changed form clears outdated server and duplicate issues. The editor holds dirty values through the shared sign-in draft hooks and offers explicit restored-draft discard. Cancel navigates directly; this component contains no dirty-navigation confirmation guard.

## Actions as Implemented

The inventory below follows every action of the protected design. These designs have no permanent action ids; the exact design label identifies each comparison until the design retrofit allocates them. Draft interactions are distinguished from requests that persist a record.

| Design action | Operation or boundary | Built behavior | Provenance | Source |
|---|---|---|---|---|
| Create | createOrganization | A valid attempt submits through createOrganization with the held create identity and opens Organization 360 after success. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Create Anyway (with a reason) | createOrganization | The duplicate refusal exposes the authorized override with a reason and resubmits the same create intent; changing the draft clears the old block. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Cancel | none: local interaction | Cancel navigates directly to the chooser when a type was chosen, otherwise to Organizations; no dirty confirmation guard is attached here. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Review field issues | none: local interaction | The issue popover selects an issue and asks FormRenderer to reveal and focus its control. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Continue from type choice | none: local interaction | The chooser keeps a selected card and Continue writes the chosen type into the route query, opening its form. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Retry form loading | none: local interaction | Retry repeats the failed definition/type read; an unreadable configured form is not replaced by an invented default. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |
| Save & New | none: local interaction | Unavailable: the action bar supplies no Save & New callback and every successful creation navigates to its record. | observed | react-console:components/records/create/create-record-screen.tsx; react-console:components/organization-editor/organization-editor.tsx |

## Authorization

RequirePermission checks permissions.crm.organizations.create. Duplicate override availability follows the evaluated organization create-despite-duplicate-block grant. createOrganization requires crm.organizations.create; duplicate override separately requires crm.organizations.create-despite-duplicate-block. Organization type, region and bound record reads retain their own permissions.

The authorization inventory in frontmatter records the actual service requirements. Browser filtering is presentation; the service is authoritative for scope, version and record restrictions. Nothing in this source review makes a business role an authorization role or certifies shell identity and application access beyond the recorded dependency.

## Observability

Navigation and request state drive the screen. Record creation uses service-owned change capture; no separate screen domain-event emitter is established. No dedicated screen logging is established in the listed components; shared request and service logging remains outside this screen’s telemetry claim. No screen-specific metric emission is established by the inspected source.

Unreadable or invalid definitions produce explicit problem content. Server field errors join the form issue list and focus the first issue; another refusal is reported in a toast. Duplicate blocks use their dedicated refusal panel. These visible failure surfaces are evidence of feedback, not evidence that every request reached a deployed service or every wider audit integration completed.

## Design Fidelity

The design lists Save & New, but OrganizationEditor supplies no onSaveAndNew or repeat-create action. Cancel goes directly to the chooser for a chosen type or to the list without dirty-draft confirmation. The action is documented as unavailable rather than silently attributed to Create.

All twelve designs still require their standard retrofit: feature, user goals, scope, navigation, layout mode, dependency list, field details, action ids, registered components, acceptance criteria and open questions are incomplete. A Screen Acceptance Specification is also absent for this screen. The implementation preserves those gaps as findings and does not manufacture acceptance ids or change the protected design.

## Verification

Organization acceptance joins the typed form to an independently read saved organization and parent context. Fixture record-creation checks exercise the chooser and visible form but cannot establish a persisted organization. General organization correction remains outside this create-only screen.

The frontmatter names the relevant existing registers and feature suite; none is reported as executed here. API and aggregate integration prove their declared service boundaries, not assembled-screen accessibility. No dedicated registered component-test group or complete screen acceptance document exists for this screen. Accessibility and deployment remain not-verified.

## Screenshots

The retained images are copied byte for byte from the console’s documentation at the pinned commit. The recorded dimensions describe the image, including full-page captures and element crops; they are not substituted for the browser viewport. The timestamp is the last modifying commit date of the source image, not an inferred shutter time. These fixture captures show historical presentation; they do not establish that the pinned live deployment renders every state identically.

| State | Image dimensions | Capture source |
|---|---|---|
| organization chooser desktop | 1440 × 1000 pixels (image dimensions; full-page images and element crops may differ from the browser viewport) | [organization-chooser-desktop.png](SCI-CRM-ENT-006/organization-chooser-desktop.png); react-console:docs/screenshots/record-creation/organization-chooser-desktop.png at baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live deployment |
| organization form | 1440 × 1000 pixels (image dimensions; full-page images and element crops may differ from the browser viewport) | [organization-form.png](SCI-CRM-ENT-006/organization-form.png); react-console:docs/screenshots/record-creation/organization-form.png at baf6dae382d6f41dce976c7f848667ccc37e076f; documented fixture capture, not a verified live deployment |