// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
=
UX Standards - E-Grade Launcher Specification
:toc:
:toclevels: 3

== Overview

This directory contains UX standards for application launchers in the hyperpolymath ecosystem.
The **E-Grade Launcher Standard** defines requirements for elite, efficient, elegant, and easy-to-use launchers.

== E-Grade Principles

E-Grade launchers must adhere to these principles:

Elite:: Only essential functionality, no bloat or unnecessary features
Efficient:: Fast startup, minimal dependencies, optimized performance
Elegant:: Clean code, proper error handling, consistent interface
Easy:: Simple to use, clear feedback, intuitive operation
Self-Healing:: Automatic recovery from common issues
Self-Diagnostic:: Built-in troubleshooting and status reporting
Soft-Attach:: Graceful degradation when dependencies are missing

== Standard Launcher Templates

Two reference implementations are available:

1. **E-Grade Template**: link:e-grade-launcher-template.sh[e-grade-launcher-template.sh] - 
   Original specification with elite/efficient/elegant/easy principles

2. **Comprehensive Template**: link:comprehensive-launcher-template.sh[comprehensive-launcher-template.sh] - 
   Full implementation with robust process management, error handling, and troubleshooting

Launchers should either:

1. Use one of these templates with appropriate customization, or
2. Implement equivalent functionality following the same patterns

For detailed implementation guidance, see link:launcher-standard.adoc[Comprehensive Launcher Standard].

== Dustfile Specification

When launchers fail, **Dustfiles** provide targeted, automated repair. See:

* link:DUSTFILE-SPECIFICATION.adoc[Dustfile Specification] - Complete specification
* link:dustfile-template.sh[Dustfile Template] - Reference implementation

Dustfiles are self-diagnostic, self-healing scripts that:
- Detect specific problems
- Provide automated fixes
- Integrate with feedback-o-tron for telemetry
- Support exhausted users via Hypatia integration

== Requirements for Desktop Launchers

=== NO Terminal Wrapping
Desktop launchers for GUI/web applications MUST NOT wrap commands in terminal emulators
(konsole, gnome-terminal, etc.) unless:
- The application is inherently a CLI tool
- Terminal interaction is explicitly required
- The user has opted into terminal mode

Rationale: Terminal wrapping causes "black window" syndrome and prevents proper browser launching.

=== Direct Execution
Desktop `.desktop` files must use direct execution:
[source,ini]
----
Exec=/path/to/launcher.sh --mode
Terminal=false
----

NOT:
[source,ini]
----
Exec=konsole -e /path/to/launcher.sh --mode
Terminal=true
----

=== Process Management
Launchers must properly manage background processes:
- Use `nohup` to prevent process termination
- Implement active waiting for server readiness
- Provide clear feedback about process state
- Clean up orphaned processes

=== Error Handling
Launchers must handle errors gracefully:
- Catch and report browser launch failures
- Provide manual fallback instructions
- Log errors to predictable locations
- Never silently fail

=== User Feedback
Launchers must provide clear, actionable feedback:
- Success: "Server started at URL"
- Waiting: "Waiting for server..."
- Failure: "Failed to start - check log at PATH"
- Action: "Please manually open: URL"

== Implementation Checklist

[ ] Remove all konsole/terminal wrapping from desktop files
[ ] Set `Terminal=false` for GUI/web applications
[ ] Implement `nohup` for background processes
[ ] Add `wait_for_server()` function with timeout
[ ] Implement `run_diagnostics()` function
[ ] Add proper error handling for browser launching
[ ] Provide clear user feedback at each step
[ ] Log to predictable locations (`/tmp/app-name.log`)
[ ] Handle missing dependencies gracefully
[ ] Provide manual fallback instructions

== Compliance

All new launchers must comply with this standard. Existing launchers should be
migrated to E-Grade compliance as part of regular maintenance.

== Feedback Integration

E-Grade launchers should integrate with the feedback-o-tron system for:
- Automatic error reporting
- Usage analytics (opt-in)
- User satisfaction metrics
- Continuous improvement loops

== Complete Standards Suite

This UX standards directory provides a comprehensive suite:

**Core Standards:**
- link:launcher-standard.adoc[Comprehensive Launcher Standard] - Main launcher specification
- link:DUSTFILE-SPECIFICATION.adoc[Dustfile Specification] - Automated repair standard
- link:LM-LA-LIFECYCLE-STANDARD.adoc[LM/LA Lifecycle Standard] - Complete lifecycle management
- link:FACE-IDENTITY-KIT.adoc[Face Identity Kit Standard] - Naming and community-home design standard for language faces
- link:CAPPAUSCRIPTO-FACE-IDENTITY-CARD.adoc[CappauScripto Face Identity Card] - CoffeeScript-facing face identity card (draft)
- link:CAPPAUSCRIPTO-RELEASE-GATE-TRACKER.adoc[CappauScripto Release Gate Tracker] - Launch readiness tracker with tests/fixtures/bench gates
- link:CAPPAUSCRIPTO-COMPATIBILITY-MATRIX.adoc[CappauScripto Compatibility Matrix] - CoffeeScript idiom support matrix
- link:CAPPAUSCRIPTO-MIGRATION-SPEC.adoc[CappauScripto Migration Spec] - `cappa migrate` transform and warning contract

**Templates:**
- link:e-grade-launcher-template.sh[E-Grade Template] - Minimal launcher
- link:comprehensive-launcher-template.sh[Comprehensive Template] - Full-featured launcher
- link:dustfile-template.sh[Dustfile Template] - Automated repair script

**Integration:**
- link:verify-desktop-integrity.sh[Integrity Verifier] - Tamper-proof hash checking

== Related Standards

- link:https://github.com/metadatastician/consent-aware-web[Consent-Aware Web] ⇗ - Privacy-compliant telemetry
- link:../../groove-protocol/[Groove Protocol] - Soft-attach patterns
- link:../../hypatia-rules/[Hypatia Rules] - LLM integration guidelines
- link:../../component-readiness-grades/[Component Readiness Grades] - Quality assessment
