ADR-006: Profile default and exposure policy

• Status: superseded by ADR-011

Context

At the time of this decision, the server defaulted to the experimental feature profile for compatibility. That profile enables the full experimental surface, including advanced upload, SMUGGLE, NOTE, WebSocket notes, upload clearing, and note clearing.

The analysis for the 2026-06 implementation plan recommended a safer new-user path before changing runtime defaults or promoting distribution/API tracks. The project also has explicit deployment guidance for localhost, controlled environments, and external exposure, but the profile default, reverse-proxy semantics, Docker status, and compatibility expectations need one recorded decision.

Decision

The supported profile direction is:

Profile	First path
serve	Read-only sharing and inspection when uploads or mutations are not needed.
workspace	Normal file workspace with ordinary uploads and single-file deletes; this is the default for new users after STAGE-004.
experimental	Explicit opt-in for experiments and compatibility with scripts that need advanced upload, SMUGGLE, NOTE, WebSocket notes, or clear operations.

STAGE-004 changed the runtime default to workspace. Documentation and release notes must tell operators to pin --profile experimental for scripts that rely on implicit experimental behavior. The experimental profile and the deprecated --advanced-upload alias remain available as compatibility paths; the default migration must not remove those capabilities.

External exposure is not a supported safe default. Binding to a public interface, enabling TLS, or enabling Basic Auth is not enough on its own for arbitrary internet exposure. Operators exposing the service outside localhost or a controlled environment must provide the external-exposure baseline documented in SECURITY.md, including real TLS, strong credentials, firewall allowlists where possible, exact browser-origin policy, resource limits, monitoring, and reverse-proxy request controls.

Reverse-proxy and client-identity policy is defined in ADR-008. In short, the maintained boundary remains the direct TCP peer from the accepted socket, and reverse-proxy deployments must enforce proxy-side per-client throttling and request-size limits until a dedicated trusted-proxy design exists.

The checked-in Dockerfile and examples/docker/docker-compose.yml remain operator-owned deployment examples for local builds and topology experiments. Tagged releases can still publish Python and container artifacts, but that distribution surface does not change the safe-default exposure policy or the fact that deployment topology, profile choice, proxy controls, and rollback remain operator responsibilities.

Consequences

Positive

• New users now get the safer workspace default while the compatibility path remains explicit.
• Existing automation has an explicit compatibility path: pass --profile experimental when experimental methods are required.
• Reverse-proxy deployments cannot accidentally treat forwarded headers as a trusted client identity boundary.
• Docker examples and published artifacts can coexist without changing the operator-owned deployment boundary.

Negative

• Scripts that rely on implicit experimental behavior need an explicit profile flag after the default migration.
• Operators behind a reverse proxy must configure per-client controls in the proxy as described in ADR-008 until trusted-proxy support exists in the application.

Follow-up

• STAGE-003 can centralize capability policy around this profile boundary.
• STAGE-004 changed the CLI default after compatibility notes were in place and tests proved --profile experimental preserves the legacy surface.
• Future artifact/distribution policy should stay consistent with this operator-owned deployment boundary.