Company prospect demos

POST /v1/public/demos/{key}/open opens an explicitly provisioned synthetic trial without an email, using {access} from the unguessable scoped share link. The response has the usual session body. The share page is /demo/{key}#access=…; the browser removes the fragment on entry. Your invitation supplies the company key and secret. An unknown key or incorrect secret opens nothing.

Each workspace is isolated, marked demo, opts out of product analytics, and has homeowner messaging disabled. Guest access permits reading the local schedule and crews and creating, moving or cancelling synthetic jobs. It cannot administer users, invite anyone, switch companies, reveal credentials, configure integrations, change company settings, or purchase plans. New endpoints are denied by default. Demo edits are shared only with holders of that company's scoped link. Use sample data. Guest-created jobs strip contact details, replace free-text customer details with synthetic labels, and prohibit import/test-client quota bypasses. Public customer booking is unavailable until email claim. Every manually scheduled job consumes the normal first-50 promotion; generated jobs have no creating user and are excluded. There is no unlimited free-access grant. Job 51 is refused by the existing database promotion enforcement until an explicitly chosen paid plan succeeds.

Trucks, crews, customers, locations, jobs and activity are synthetic. Market names come from company-controlled public evidence recorded in src/prospect-catalog.ts. Map routes use provider road geometry; missing geometry never becomes invented straight-line driving. The server keeps live actors advancing, and separate planning crews have a bounded seven-day pool refreshed daily. The demo never represents the company's actual employees, properties or operations.

POST /v1/demo/claim/start accepts the prospect's name and email and sends a code only after they supply that email. POST /v1/demo/claim/verify accepts the code, activates the same company and owner, and preserves all manually scheduled jobs and their consumed allowance. It revokes every guest session and the share secret, stops simulation, retires only generated sample jobs, and clears simulated GPS. Demo crew names stay explicitly labeled so the owner can configure actual crews. No card, Stripe customer, subscription or charge is created by claiming. The usual billing page is used to choose and explicitly buy a plan when the allowance is exhausted. Reopening the original link cannot recreate the company or allowance. POST /v1/signup with demoKey refuses and directs users to this claim flow. Claim proves receipt of email, not legal ownership of the named business.

An occupied slug whose identity does not match the catalog causes a failure; existing customers are never converted into demos. With an output-file argument, initial share links are written privately with mode 600 and uploaded to the existing private encrypted deployment bucket. Repeat initialization does not rotate links or recreate a claimed company.

Guest access cannot send or accept CrewConnect invitations.

#Configuration-driven provisioning assessment

The existing supported command is tsx src/cli.ts demo-prospects init <private-links-file>. It only creates absent entries from the compiled catalog; it does not accept arbitrary company definitions. The normal admin company-create action alone does not install the prospect lifecycle, synthetic scheduler, share secret or promotion. Do not bypass those invariants with database edits.

For future additions, extend this existing internal CLI with a validated manifest import and a dry-run command; no new public admin UI is needed. A later, separately tested change should persist a versioned, immutable prospect definition bound to its company ID. The API, simulation and road-warmer must all consume that same stored definition rather than separate static lists. The introduction style must also come from validated server metadata instead of a browser slug list. Validate key uniqueness and slug collisions, IANA timezone, coordinates, service/crew counts, normalized logo bytes, source URLs and the global road/roster budget. Assets should be imported as validated bytes, never fetched by the server from arbitrary URLs.

A transaction must bind the definition, company, isolated guest, synthetic roster, promotion and hashed share secret; export share links atomically while preserving prior links. Reject definition replacement for an existing or claimed company. Existing catalog records must remain supported unchanged. Test interrupted imports, duplicate imports, preserved identities/usage, failed claims, synthetic dispatch denial and concurrent imports before enabling the command. This batch uses the established catalog/release path; it does not introduce the dynamic importer.