# nexo Docs

This directory holds product notes, migration decisions, and operational
documentation that apply to more than one module.

Module-specific instructions stay with the module that owns them.

## Runtime Baseline Index

- Workspace runtime and upstream policy: `../README.md`
- Core compose runtime, deploy loop, smoke checks, remote parity, and secret boundary:
  `../services/core/compose/README.md`
- Core upstream snapshot baseline: `../services/core/UPSTREAM.md`
- Mattermost mobile app upstream snapshot baseline: `../apps/mattermost/UPSTREAM.md`
- Mattermost push-proxy upstream snapshot baseline: `../services/push-proxy/UPSTREAM.md`
- Runtime Image Validation details: `runtime-image-validation.md`
- iOS notification smoke prerequisites and runbook: `ios-notification-test-guide.md`

## Upstream Following Policy

Mattermost upstream repositories are runtime baselines, not the main nexo
product surface. Keep `apps/mattermost`, `services/core`, and
`services/push-proxy` close to their recorded upstream snapshots, and put
nexo-owned behavior in the Flutter SDK, compose/runtime wrappers, docs, or
small explicit compatibility patches.

### Baseline Records

Each upstream snapshot owner keeps an `UPSTREAM.md` file with:

- source repository URL;
- tracked branch and release tag when applicable;
- exact upstream commit SHA;
- snapshot date;
- snapshot source and target path;
- accepted nexo-local patch boundary;
- update gate and smoke evidence expected before a merge request.

When a baseline changes, update the matching `UPSTREAM.md` in the same change
as the snapshot. Do not mix app, core, and push-proxy snapshot updates in one
merge request.

### Snapshot Script Contract

A workspace snapshot helper may automate only the mechanical staging and copy
steps. Its contract is:

- update the external `mattermost/` staging clone for one selected upstream
  repository at a time;
- read the tracked branch from the module's `UPSTREAM.md` or project rules;
- copy the chosen snapshot only to the matching target directory;
- exclude `.git`, dependency caches, build outputs, runtime data, logs, and
  ignored secret-bearing files;
- record the selected upstream commit SHA for the operator to apply to the
  matching `UPSTREAM.md`;
- print the follow-up diff review and smoke checklist.

The helper must not commit, push, update multiple upstream repositories in one
run, promote runtime images, or auto-merge staging pull results into this
workspace. Snapshot diff review and smoke verification remain separate gates.

### Push-Proxy Baseline

Current choice: keep `services/push-proxy` as a source snapshot mirror of
`mattermost-push-proxy`, and build nexo-owned runtime images from that source
when needed. Runtime image tags and digests are deployment evidence, not the
source baseline.

Image-only tracking is allowed only after a separate roadmap decision when no
local source build, patch, config packaging, or smoke diagnosis needs the
source snapshot. If that decision changes, update `services/push-proxy/UPSTREAM.md`
and this section together.

### Release Watch

Check Mattermost server/webapp monthly releases, active ESR updates, security
notices, Mattermost mobile updates used for verification, and push-proxy
releases before opening a baseline update. Security patches are triaged as soon
as they are noticed; normal monthly or ESR refreshes can wait for an explicit
snapshot lane.

The public record for a release watch is the relevant `UPSTREAM.md` plus
sanitized runtime evidence in `runtime-image-validation.md` when images or
compose inputs change. Raw credentials, private endpoints, and environment
values stay out of tracked docs.

### Patch Policy

Webapp branding and feature visibility changes must stay thin: prefer upstream
configuration, feature flags, small compatibility wrappers, or isolated style
patches. Do not rewrite the webapp into a nexo-owned product surface in this
runtime baseline.

Do not apply bulk renames, package-wide reformatting, repository reshaping, or
deep fork changes to upstream-owned server, webapp, app, or push-proxy code
without a separate roadmap decision. Exceptions require an explicit rollback
path and a note explaining why an upstream-compatible wrapper is insufficient.

Classify upstream features during refresh as:

- `keep`: compatible with nexo runtime and low maintenance cost;
- `hide`: available upstream but disabled or hidden by configuration or a thin
  patch;
- `defer`: not adopted until SDK, compose, or app compatibility is ready;
- `remove`: excluded only with a documented compatibility or security reason.