# Working on Orbit

Orbit is a self-contained Sales edition for account selling guided by customer evidence. The owner may edit any source. Preserve their recorded intent and verify the running result; a clean merge or passing upstream suite alone is insufficient.

Read `README.md`, `HANDOVER.md`, `CONTRACT.md`, `BASELINE.md`, `DIVERGENCE.md`, `seed.json`, and any `.seed/intent.md` before changing product behavior. The handover distinguishes implemented behavior from the remaining contract work. Do not infer complete release acceptance from the focused test suite.

## Run and deploy

Use Node 26.8.1 and the package-manager version in `package.json`.

```sh
pnpm install --frozen-lockfile
pnpm local:migrate
pnpm bootstrap:owner --local --file /absolute/path/to/owner.json
pnpm dev
```

Ordinary development does not seed customer records. Native sign-in requires configured mail; no development login bypass exists. Test fixtures live under `tests/fixtures` and must not enter application code.

For a fresh Cloudflare deployment, follow `SETUP.md` to provide the ignored deployment configuration, an external owner JSON file, Cloudflare credentials, and `SENDGRID_API_KEY`/`MAIL_FROM` environment variables. Then:

```sh
pnpm run deploy -- --owner-file /absolute/path/to/owner.json
```

This provisions D1, preserves an existing initial owner/workspace, builds the emitted Worker, deploys with a private temporary secret file, and checks health. Never commit actual resource IDs, owner configuration, tokens or secret files. No automatic production deployment is implied by pushing Git.

## Implementation boundaries

- One Cloudflare Worker serves Hono HTTP routes and TanStack Start documents. Preserve native session checks on HTTP, documents and generated functions.
- `src/core/features` owns Orbit records, signals, scoring, recommendations and reviewed outreach. Database access belongs in repositories; validate external inputs in routes.
- `src/family/sales` and `src/modules/sendgrid-email` contain selected component source owned by this edition. Edit it directly; origins support comparison and never override local changes. Independently sourced modules may cross family boundaries with explicit integration and verification.
- `src/ext/config.ts` owns the public identity plate. Keep real behavior and failed states visible; add no mocks, semantic fallbacks or invented AI output.
- Signals retain source, event identity, occurred/received time and immutable evidence. Stage, owner, score, queue and provider delivery state stay independent.
- Every customer send requires review of exact saved content. Preserve revision/staleness checks, recipient permission, one-attempt submission and truthful ambiguous outcomes. No signal or background action approves mail.
- Preserve already-applied migration history; use new migrations for core or extension schema changes. Prefer small files and direct responsibility boundaries.

Run `pnpm verify` after changes and exercise the affected real workflow. It covers implemented D1 behavior, composition, deployment command handling, browsers and the emitted Worker. Record any unverified product or baseline clauses explicitly. For updates, choose the Git or integration method that preserves all owner intent; conflicts are the agent's work.

## Recommended defaults and shared improvements

The maintained edition defaults save integration and verification work. Configuration
and hooks are conveniences; editing domain internals, core schema, UI, framework
or infrastructure is ordinary authoring too. Choose the change that serves the
owner's outcome, without a required sequence of extension mechanisms. Complex
merges and adaptation are the agent's work. Preserve the owner's actual requirements
wherever recorded: `CONTRACT.md`, `DIVERGENCE.md`, owner instructions and optional
`.seed/intent.md`; no particular intent file or registry is required.

Feed useful mechanisms, defaults and verification cases back into shared source
when they would save work in another edition. Their natural home may be this
edition, a family, Base or an independent repository; no separate repository per
module or universal compatibility interface is required. Verify adoption against
the receiving product's requirements, including deliberate local differences.