File and API Discipline

Expands the file organization, DocC, and design-smell rules in ../SKILL.md.

What gets its own file

Public API types, internal types with meaningful bodies, private nested types that grew past a tiny helper, type-erased wrappers, and conformance extensions for externally owned types.

A helper can stay with its parent while it is private and trivial (a nested enum for local branching, a one-line private extension). Move it the moment it has lifecycle, state, a protocol conformance, or enough logic to test independently.

DocC quick examples

/// Stores a typed ``CmuxSetting`` value.

/// Reads from `UserDefaults.standard` only when injected by the caller.

Double backticks reference symbols; plain backticks are non-symbol code.

Design smells

// Fake namespace: no instances, no DI, no test seam.
enum Foo {
    static func bar() { ... }
}

Runtime-state singletons (static let shared / standard / default) are constructed at app startup and injected instead. static let stays legal for identifiers, schema entries, and enum cases.

A guard plus assertionFailure plus a fallback usually means the type model is too weak. Encode the invariant in the type system.

A hand-maintained list that mirrors declared items drifts silently. Derive it via reflection or a macro where practical.