myxce/.kiro/specs/xcecli-presets/brief.md

Brief: xcecli-presets

(From the application-profile discussion, 2026-10-12; user decisions. Backlog.)

Problem

Application profiles hold only essentials, what every job of an application must have (job-config-layering.md, additive rule). Users still repeat the same tuning on every job: rusage[mem=...], span[ptile=...], a task count, env, the queue. They also tune these over time (sizing, placement) and want to keep and share what they find. Putting such defaults in the profile made the server-side rules complex (override markers per section and per term, ranges, privileged overrides) and would add a per-user configuration level.

Desired Outcome

• A preset is a set of job options (--app, --queue, -R, -n, env, limits, ...), named and stored by the client. xcecli jobs submit --preset <name> expands it; any command-line flag replaces the preset's value for that option as a whole (no resreq parsing). The submit carries only the expanded values.
• Handled fully on the client. Presets never reach the controller, WAL or scheduler, own no attribute, are not a configuration level and carry no privilege: app:use, queue:submit, the profile's essentials, queue ceilings and project quotas still apply at submit.
• Personal presets live in ~/.config/xce/presets.yaml; users change them on the fly (xcecli preset set / edit / show / list / delete).
• The server only shares. The apiserver serves admin-deployed preset files read-only: GET /api/v1/presets (list) and GET /api/v1/presets/{name} (fetch). Team presets are namespaced (<team>/<name>). No database, no HA; with several apiservers the files are deployed to each, like rbac.yaml. Every authenticated user may see them.
• Pull copies. xcecli preset pull <name> writes a complete, standalone local preset with an informational origin (server name, content hash, pull date). Removing or changing a server preset never affects local copies. xcecli preset diff <name> compares with the server (reports when it is gone); preset pull --force refreshes. Both are user-initiated.
• User-to-user sharing without the server: preset export / import (file, mail, git).
• Site presets complement profiles. Admins typically publish a preset with the profile's name holding its usual tuning; clients may point to it ("server preset openfoam available") but never apply it automatically.
• Safety and visibility: a warning on export/import when env variable names look like secrets; xcecli jobs submit --dry-run shows the expanded options and the effective values after the profile merge (job-config-merge); optionally the preset name is recorded as a job label (preset=<name>) for comparing variants.
• Portal: the same expansion (a small option-level merge) and the same read-only listing; its personal presets are stored by the portal itself and are not shared with xcecli in the first version.

Scope

• In: preset format, xcecli commands, expansion and precedence, the read-only apiserver listing/fetch and its file directory, pull/diff, export/import, secret warning, dry-run display, tests.
• Out: writable server-side shared presets (would need owners, visibility and durable storage; revisit only if the portal needs it, after rbac-persistence), automatic application of presets, any server-side preset expansion.
• Open: whether the preset-name label lives here or in job-status-detail-display (job labels); the portal's preset storage.

Upstream / Downstream

• Upstream: application-profile (profiles and --app), job-config-merge (dry-run effective values).
• Downstream: profile-usage-insight (advisory suggestions for site presets).