# Public Greenfield Bootstrap Contract

## Scope Statement

- Classification: `staged closure blueprint`
- In scope:
  - define the minimum external environment needed to start `NexusCRM public-core v1`
  - define the baseline bootstrap/startup contract
  - define the first public remote-service success criteria
  - require the first CRM L1 app-pack install/verify path used by the public
    greenfield proof
- Out of scope:
  - broader package lifecycle, including upgrade, uninstall, registry, and
    external tenant onboarding flows
  - private tenant overlay apply
  - business-data onboarding
  - production-grade infra topology choices

## 1. Objective

An external user should be able to:

1. prepare a supported database and runtime env
2. run the public bootstrap path
3. start backend and frontend
4. verify a baseline public service surface

This contract is evaluated against the public-core distribution/workspace, not
against a single monolithic backend package tree. The implementation may be
split across the L0 kernel and public L0 extension modules, but the documented
greenfield path must remain reproducible without private source material.

This flow must work without:

- `NEXUSCRM_APPLY_TENANT_OVERLAY=1`
- `NEXUSCRM_TENANT_OVERLAY_DIR`
- any private payload from `controlplane/tenants/**`

## 2. Baseline Runtime Contract

The public greenfield contract is:

1. build public-core binaries/assets
2. initialize env for a greenfield org
3. run `setup apply`
4. explicitly install the CRM L1 app pack with the CRM-tagged setup command:
   `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup install-pack --source official_repo:salesforce-crm-standard`
5. run `cd backend/distributions && GOWORK=off go run -tags crm ./cmd/setup verify-pack salesforce-crm-standard`
6. run CRM-tagged tenant-agnostic readiness verify after the CRM pack install
7. start backend through the lock-held `setup apply-if-needed` authority. Step 4
   intentionally invalidates the earlier `ApplyAll` marker, so this first auto
   start runs full `ApplyAll`, re-verifies the source-backed pack composition,
   and restores the completed marker before serving
8. start frontend
9. run the minimum smoke suite

The command paths above describe the current-tree startup evidence.
Setup/bootstrap/control-plane/verify and API host code may move from the kernel
package tree into public modules or public repos only when this contract is
updated with replacement commands and the minimum smoke suite is re-proven
before the old path is removed.

## 3. Required Inputs

- supported DB endpoint
- public runtime env template
- backend/kernel binary or `go run` path plus any documented public extension
  module commands needed by the distribution
- frontend build/run path
- standard metadata/bootstrap assets from the public workspace or approved
  public app-pack/dialect repositories

## 4. Forbidden Inputs For The Public Baseline

- tenant overlay directory
- private tenant payload
- private deploy scripts
- PingCAP-specific env defaults

## 5. Minimum Smoke Suite

The public baseline is acceptable only if all of the following pass:

1. describe-global
2. per-object describe for at least one standard CRM object after explicit CRM pack install
3. at least one documented UI API slice
4. frontend bootstrap and first-page load
5. after step 7 has restored the completed marker, a backend restart enters
   `setup apply-if-needed` but does not run full `setup apply`, `apply-packs`,
   repair, or tenant overlay apply while all current completed-marker receipts
   and source revisions remain converged

## 6. Success Criteria

`NexusCRM public-core v1` remote startup is considered successful only if:

1. the system boots from a greenfield state without tenant overlay
2. the public docs are sufficient to reproduce that path
3. the minimum smoke suite passes
4. no private source-of-truth path is required at any step
5. any public module split preserves setup/apply/verify/API-host behavior with
   replacement commands documented before the old path is removed

## 6.1 Modularization Guard

The following surfaces are required public-core capabilities, even if they stop
living inside the L0 kernel package tree:

- setup/bootstrap
- control-plane apply/verify/drift checks required by the public baseline
- API host/runtime composition required to serve the public service surface
- CRM app-pack install/verify commands for the first public L1 distribution

They may be relocated to public modules or public repositories. They may not be
deleted, privatized, or made dependent on tenant payload.

## 7. Repo Evidence Checked

These are current-tree evidence paths. They can be replaced by public modules
only after the replacement path satisfies this contract.

- `backend/cmd/setup/main.go`
  - `apply` and `apply-tenant` are distinct commands
- `backend/internal/controlplane/operations.go`
  - tenant layering is explicit and separate from platform baseline apply
- `infra/runtime/deploy.py` and `backend/cmd/runtime-api/main.go`
  - app-blind substrate initialization and private Runtime serving are separate from L1/L2 installation
- `backend/internal/controlplane/verify.go`
  - public baseline verify is tenant-agnostic
- `docs/open-source/self-hosting/greenfield-bootstrap-runbook.md`
  - current backend + frontend + smoke proof path for public-core v1
- `docs/open-source/self-hosting/backend-greenfield-bootstrap.md`
  - current backend-only bootstrap, verify, and startup proof path