ref-output-serialization-conventions

This skill is the hub for project conventions on how values are serialized into user-facing output. New rules accrete here rather than spawning sibling skills.

Enum value casing

Pick the right enum accessor at definition time; never normalize casing at the call site.

The two categories

Categorical labels — kind, type, classification, identifier-like tokens. Emit StrEnum.value. Lowercase by convention.

• type: SystemType.COMMUNITY.value → "community"
• origin: SessionOrigin.STATIC.value → "static"
• system: lowercase system name
• phase: InitializationPhase.COMPLETED.value → "completed"
• launch_method: "docker" / "python"

Runtime state — current liveness, status that changes over the session's lifetime. Emit .name. UPPERCASE.

• liveness_status: ResourceLivenessStatus.ONLINE.name → "ONLINE"

Discriminator when a field mutates: a lifecycle value that belongs to a documented protocol vocabulary — echoed in docs, filters, and agent retry logic — is categorical even though it changes over time (phase progresses not_started → completed and emits .value). Runtime state is a point-in-time health probe with no protocol vocabulary (liveness_status).

Canonical implementations:

• Categorical: resource_manager/_manager.py (SessionManager.to_dict) reads self.system_type.value and self.origin.value.
• Runtime state: mcp_systems_server/_tools/session.py (_get_session_liveness_info) reads status.name.

The call-site rule

Never call .upper() or .lower() on an enum value at the call site. If a value's casing feels wrong, fix the enum definition — or recognize a vocabulary mismatch that needs a deeper fix, not a transform.

# Good — the enum's chosen accessor is what ships
{"type": mgr.system_type.value, "liveness_status": status.name}

# Bad — call-site normalization
{"type": mgr.system_type.name.lower(), "origin": mgr.origin.name.lower()}

CLI human-mode column headers