olares-cli shared rules

Read this thin front door before a runtime skill. It supplies the active-profile model, platform entry points and the auth proceed/stop rule — what a task needs once it knows which skill it belongs to. Load detailed references only when the current task triggers them.

• Suite map: which skill owns which task, and how to install olares-cli when it is not on PATH. Read it when the task has not been routed to a skill yet; a task that has been does not need it again.

Reading the answer

Every profile-backed tree spells machine-readable output the same way: -o json (--json is the same request, kept for older scripts). A verb that fails under it answers on stderr with {"error":{"code","message","retryable","action"}}, and stderr carries nothing else, so it parses whole.

.error.code is worth branching on where it is set, and today that is the failures whose recovery differs from every other failure's: auth_no_profile, auth_not_logged_in, auth_token_expired, auth_token_invalidated and timeout, plus whatever Router reports from upstream. Everything else arrives as unclassified with the whole story in .message. So read the code first, and fall back to the message rather than assuming a code you did not get means something. retryable and action are present only when the failure knows them — their absence means unknown, not "no".

Some trees also carry their own result document (Market's lifecycle verbs report .status and .finalState); where they do, that is the one to read.

Platform entry points

• Olares platform model: userspace storage, uid/gid 1000, protected Home directories, app/namespace networking, system middleware and Olares version semantics. Read it for files, chart, cluster or settings tasks that touch those concepts.
• Application state machine: lifecycle transitions, allowed operations, backend timeouts, serialized downloads, running semantics and unreliable progress. Read it for market operations or runtime diagnosis.
• Profile and authentication: login/import flows, profile statuses, token storage and refresh behavior. Read it only for profile work or auth recovery.