docs: Align documented behavior with the implementation

[renato-freis]

Summary

Aligns the README and the in-app documentation with what the code actually does, and adds the first dashboard screenshots to the README.

Several documented claims described behavior this repository does not implement. For a sample that readers use as a reference, those are the most costly kind of defect.

Corrected claims

Documented before	Actual behavior
Implementation of the SCTE-130 specification	Implements the ESAM SPE/SPN signal-conditioning exchange (SCTE-130 Part 9)
Rule chaining with short-circuit evaluation	First-match evaluation; only the first matching rule applies
Roles: Admin, Operator, Viewer + per-channel ACLs	Two Cognito groups: admin and user; no per-channel scope
/esam uses Basic Authentication	Basic Authentication is optional, configured per channel
Session state in DynamoDB with TTL-based expiration	One active break per channel, with a calculated expiry; no DynamoDB TTL attribute is written
Asynchronous action execution to avoid processing latency	Actions run inside the ESAM request path; the SPN waits for their timeouts and retries
Support for all SCTE-35 segmentation types	Matching and modification for the documented fields
cdk destroy --all removes everything	Stack-managed resources; runtime-created SSM parameters and log groups need a check

The rule example also used break_duration, which is not a valid modification target. It is now breakDuration, matching ModificationTarget in backend/domain/models/channel.py, and the README documents the supported condition fields, operators, actions and modification targets.

The fallback administrator procedure previously listed only admin-create-user. Without admin-add-user-to-group, the resulting account cannot administer the dashboard.

Removed unsubstantiated performance figures

The in-app documentation advertised ~50 req/s and P95 < 150ms. This repository has no benchmark, so those numbers were not supportable. The Metrics page now explains what the CloudWatch dashboard graphs and what the reader should measure. Publishing real percentiles is deliberately left for a separate change with a reproducible methodology.

Behavior changes

Environment profiles are now wired to the API stack. lib/config/environment.ts declared enableDetailedLogging, enableXRayTracing and throttling limits per environment, but only logRetentionDays reached ApiStack, so the README statement about environment profiles was not true. Verified by synth:

	dev	prod
DataTraceEnabled	true	false
LoggingLevel	INFO	ERROR
Burst / rate	200 / 100	2000 / 1000

This also stops full ESAM XML payloads from being written to CloudWatch in the prod profile.

Opt-in MediaLive permissions. The MediaLive plugin calls BatchUpdateSchedule, but the signal-processing role had no MediaLive permissions, so the feature could not work as deployed. Passing -c mediaLiveChannelArns=<arn>[,<arn>] now grants medialive:BatchUpdateSchedule and medialive:DescribeSchedule scoped to those channels. Without the flag, nothing is granted.

Dashboard screenshots

The repository had no interface images. The README now shows the Channels page, the rule configuration form and the live SCTE-35 feed. The images were rendered from the application's own compiled stylesheet, component markup and lucide icon set, with fictitious sample data and no account identifiers, ARNs, API IDs or credentials.

Request path behavior

New README section describing the failure modes of the synchronous path: the 30-second Lambda timeout, stage throttling, the noop fallback for unknown or disabled channels, the defaultAction fallback on parse failure, fail-open break-state handling, and the fact that encoder behavior on an unreachable POIS is configured on the encoder.

Testing

• pytest --cov: 176 passed, 68.96% coverage (gate 65%)
• ruff check . and black --check .: clean
• npx tsc --noEmit, npm run lint, npm run build (frontend): clean
• npm run build (infrastructure): clean
• npx cdk synth for the dev and prod API stacks, asserting the table above and the scoped MediaLive statement

No functional backend change; LICENSE and CODE_OF_CONDUCT.md are untouched.