# Working on Beacon

The canonical `support-beacon` repository owns Beacon's complete source, UI,
integration, migrations and effective component choices. First-party authors,
owner forks and community publishers edit the same authoritative inputs.
`edition.json` selects local components; `sources.lock.json` identifies their
bytes and retains upstream comparison source. The Support family no longer
writes this edition. Read the source-authoring section in README.md before
changing selections or publishing a source release.

The shared product is a cohesive starting point. Owners and community authors
may change core behavior, schema, UI, infrastructure and any other source.
Configuration and hooks are useful conveniences, not limits. Agents choose the
integration method and handle complex merges; verify recorded requirements and
affected data transitions. Useful discoveries can be contributed with tests to
shared source, then deliberately adopted and verified by other editions.

Beacon is the Support family's conversation desk edition for one business.
Incoming conversations can remain at zero cases; operators raise cases explicitly
when needed. Preserve this distinction and the reviewed-reply workflow.
The current widget and reviewed reply pilot is a bounded implementation of the
larger contract, with incomplete clauses recorded in its registry and handover.

Beacon's recorded product policy makes AI assistive: it may summarise, classify,
extract, cite and draft, but may not send customer messages, verify evidence,
approve or execute provider operations, or complete a case. Approval, execution,
reconciliation, notification and completion remain distinct durable states.
Preserve these requirements unless this installation's owner explicitly changes
them; then record the departure and test its replacement. This is Beacon's policy,
not a limit on the owner's authority to customise source.

This repository contains the editable source of the owner's product. Its purpose,
implemented scope and operating instructions are in `README.md`; current coverage
and remaining work are in `HANDOVER.md`. Read those documents, `CONTRACT.md`,
`BASELINE.md`, `seed.json`, and existing customisations before changing behaviour.
Read `.seed/intent.md` where present and treat its recorded owner requirements as
binding until the owner changes them.

## Run Beacon

Use Node 26.8.1 from `.nvmrc` and the pnpm version in `package.json`:

```sh
pnpm install
pnpm run dev
pnpm run verify
```

Follow [README.md](README.md) for exact environment values and the implemented
`pnpm run setup`, `pnpm run bootstrap-operator` and `pnpm run deploy` commands.
Bootstrap only an empty workspace. Setup/deploy support explicit environments
and dry runs. Use `pnpm run setup`, not pnpm's reserved shell-setup command.
Credential-free verification CI does not deploy.

Local sample data requires `BEACON_SAMPLE_DATA=true` and a loopback request host;
local native sign-in delivery does not prove external mail delivery. Configured
provider behaviour needs its real credentials. Provider acceptance is distinct
from delivery; preserve visible ambiguous-send review without automatic resend.

`pnpm run export` and `pnpm run import` implement portable database/storage
archives; read their actual options and empty-target checks before use. Local
restore evidence does not establish a live deployment or accepted Intercom import.
`pnpm run baseline:strict` checks complete or accepted-superseded baseline coverage;
ordinary verification can pass while declared TODOs remain. Read the reports.

## Make it fit

The owner may edit all source, including base code, family domain, modules,
application UI, configuration and tests for new owner requirements. This is a
complete repository; authoring repositories are not runtime services it needs.
Choose the coherent change that minimises total work, cost, elapsed time and
owner attention, including future verification and updates.

Use existing configuration or extension APIs where they help. Core changes are
fully legitimate. Adding or removing capabilities requires handling their data,
dependencies and integrated journeys explicitly. Keep files small, remove dead
code, and preserve server-side authorisation and secret boundaries. Access data
through the product's repository layer and validate inputs at trust boundaries.
Declare new externals and isolate their integration. Never edit released
migrations; add a migration and recovery path for destructive changes.

Record why an intentional departure exists in the edition’s existing requirement
records, with applicable tests that demonstrate the required behaviour.
`.seed/intent.md` is an optional convention, not a required file or format. Do not silently weaken a guarantee
or edit its upstream test to hide a regression. Use the edition's implemented
contract override mechanism with a replacement test. Deliberate changes to
security requirements must reflect and record the owner’s authority; ordinary
fixes that meet existing requirements need no additional confirmation. If tooling is missing, record the gap and
verify the intended behaviour directly without pretending an override passed.

Preserve customisations in every path when integrating upstream changes.
Directories such as `src/ext/`, `.seed/`, `migrations/ext/` and `tests/local/`
are organisational conveniences, not an automatic preservation guarantee.

## Verify and update

Run the edition's documented verification and exercise the affected journeys on
the real local app or a preview. Report uncovered or failing guarantees plainly.
A clean build or passing upstream tests alone does not prove owner intent survived.
No production mocks, hidden failures or semantic fallbacks.

Read the release changes, provenance and recorded intent before updating. Prepare
a candidate away from the live installation. Use update tooling only when the
edition supplies it; choose merge, rebase, reapplication or rewriting as appropriate.
Never regenerate over the owner's fork or discard conflicting work wholesale.
Verify applicable product guarantees, declared overrides and local intent tests
before adoption. Record what changed, what passed and any remaining limitation.

The owner may keep and change the MIT source independently of management services.
Use documented, verified export and restore procedures for data portability;
do not promise a command or recovery capability that has not been implemented.