Lessons Learned

What changed once the platform became real.

Last reviewed: April 2026 Focus: trade-offs, not slogans

We started with path-based thinking, but dedicated subdomains made routing, cookies, redirects, and ownership much easier to reason about.

Keeping too much data on a 40 GB host is not observability maturity. Short retention is part of staying healthy.

GitHub-hosted Actions plus SSH deploy proved easier to audit, review, and recover than a local runner would have been for this size of platform.

Runbooks, routing maps, and rollback notes reduce ambiguity later. Documentation is not extra polish once the platform is live.

Incident Patterns

Failures that changed the platform shape.

Trigger: the public landing page loaded with animation-dependent visibility rules while the intended JS path was not guaranteed.

What changed: visibility now defaults to readable content, and animation only enhances the page when the JS path actually succeeds.

Why it matters: the public surface should degrade gracefully instead of treating presentation logic as a hard dependency.

Trigger: a raw tool surface is fine for an operator, but weak for visitors, previews, and no-JS scenarios.

What changed: status.shellr.net now has a static public entry page before the deeper Kuma interface.

Why it matters: operational proof is stronger when the public layer stays readable under reduced client capability.

Trigger: real routing, monitoring, and backup existed, but the public documentation and landing pages initially exposed too much internal jargon.

What changed: the platform now surfaces guided entry points, case studies, and clearer reviewer-facing language.

Why it matters: technical substance only becomes a trust signal when visitors can decode it quickly.