List builtin and custom YAA\F platform profiles (hosted, local-hybrid, local, …).

Switch active platform profile (hosted | local-hybrid | local | custom id). Clears session if OIDC issuer changes.

Export active profile as shell environment values for the active YAA\F client.

Save or update a custom platform profile in the active YAA\F client state directory.

Validate platform profile, OIDC discovery, auth session, and service reachability.

Open browser PKCE login against the active platform OIDC authority and persist tokens.

Headless/CI device-code login (Keycloak device grant + PKCE S256). Returns verification_uri and user_code immediately (status=pending) by default so the agent can show them before MCP tool timeouts; background-polls until authorized. Pass wait=true to block until complete. Requires oauth2.device.authorization.grant.enabled on the active OIDC client.

Clear the local YAA\F client session. Optionally open Keycloak end_session.

Return current profile, auth session, tenant name/id, and RBAC identity.

List tenants for the signed-in user (normalized: id, name, slug, is_last, is_selected).

Set active tenant by UUID, name, or slug; activates on the server.

One-shot: validate platform/OIDC, refresh or login, auto-select tenant (last/single/default), return ready state.

List skills in the tenant catalog.

Get one skill by id (via catalog list ?ids=).

Get in-memory skill runtime status for the tenant.

List the tenant skill files tree (Advanced Skills workspace).

Read a skill pack file from the tenant skills tree.

Create a skill pack in YAA\F (writes SKILL.md + skill_configs).

Create or update a skill pack file under the tenant skills tree.

Enable or disable a skill in skill_configs.

Replace agent→skill mappings (bulk). Prefer yaaif_skill_map_agents_merge to avoid wiping existing skills.

Merge skill_ids into agents (fetch current mappings, union, then bulk replace). Safe default for plan execution.

Validate one skill or the catalog.

Re-discover skill files into the catalog.

Reload in-memory skill runtime for agents.

List agent definitions in the tenant (chat and workflow).

Get one agent definition by id (includes skill_ids).

List ambient agent configs in the tenant.

Get one ambient agent config by id.

Create a chat or workflow agent definition.

Update an existing agent (PUT). agent_type is immutable — omit it. skill_ids replaces mappings if provided.

Create an ambient agent config linked to a workflow agent.

Install an ambient workflow graph under an ambient agent. Omit workflow_graph to seed from the Agent Spec workflow_design segment when spec_id or a bound ambient agent is available.

Get an ambient workflow by id.

List ambient workflows.

Update an ambient workflow graph / metadata, including ambient agent assignment.

Fire a test signal against an ambient workflow.

List ambient workflow runs.

Get one ambient run by id.

Scaffold a new MCP server from official YAA\F templates into the workspace.

Idempotently link/create an external MCP tool in the tenant catalog.

Refresh tools from a registered external MCP server.

List external MCP tools in the tenant catalog.

Get one external MCP tool by id.

List registered external MCP servers in the tenant catalog.

Get one external MCP server (and its tools) by id.

Read-only snapshot of the current tenant: agents, skills, MCP tools/servers/deployments, desktop tool packages, API keys, deployment settings status, ambient agents/workflows, local tools, file registry lifecycle (paginated summaries).

Read tenant deployment-service settings (default method, compose/k8s/gitops knobs). Read-only — configure GitOps/kube in Admin UI.

Preflight deployment-service health (docker / kubernetes / gitops / agent / api-server). Call before kubernetes_gitops deploy; require gitops healthy.

Create an MCP deployment (docker_compose or kubernetes_gitops). transport_type must be STREAMABLE_HTTP or SSE. For k8s prefer endpoint_mode=docker_name (auto Service DNS); use custom + endpoint_host only when needed. Prefer API key secret_env over platform S2S.

Update an MCP deployment (image/env/secret_env/endpoint/…). GETs current record, merges patches, PUTs. Call yaaif_mcp_deployment_redeploy afterward for rollout.

Deploy an MCP deployment by id (compose up, or GitOps overlay write/push for kubernetes_gitops).

Roll out an existing MCP deployment (compose recreate or k8s restart/GitOps sync). Use after update or secret_env bind.

Stop an MCP deployment (compose stop or k8s scale-down via GitOps).

Delete an MCP deployment. cascade_agent=true (default) also removes the linked agent-service MCP server/tools.

Register a deployed MCP server into the agent-service tool catalog.

Get MCP deployment status (phase, status_stages, generated_endpoint, kubernetes_namespace, overlay/compose paths).

Fetch MCP deployment logs. Routes automatically: docker_compose → /logs; kubernetes_gitops → /k8s/logs.

Kubernetes runtime introspection for a kubernetes_gitops deployment (pod + Deployment status). Returns clear error if K8s integration is disabled.

List MCP deployments (api-server / deployment-service).

List tenant API keys (scoped ymp- credentials for MCP/downstream → platform APIs). Returns known scopes vocabulary.

Get one tenant API key by id (metadata only; plaintext is never retrievable).

Create a scoped API key for MCP/downstream platform access. Plaintext is returned once — bind via yaaif_api_key_bind_deployment or skill field_map; do not inject platform S2S into MCP pods. Prefer least-privilege scopes (e.g. context_store:read/write).

Update API key name, scopes, allowlists, or enabled flag.

Rotate an API key. Keeps the same Credentials credential_id (bindings stay valid). Plaintext returned once; previous hash remains valid for a short grace window.

Delete (revoke) an API key and its linked Credentials record when present.

Bind an API key Credentials record to an MCP deployment secret_env as YAAIF_MCP_PLATFORM_API_KEY (process fallback for ambient/desktop). Optionally redeploy so the pod picks up the env. Prefer this over putting platform S2S into MCP pods.

List tenant RBAC role names (ADMIN, EDITOR, DEVELOPER, VIEWER, CHAT_USER, plus custom roles). Requires users:read.

List tenant users (name, email, role, active). Requires users:read. Admins use this before yaaif_user_role_set.

Get one tenant user by id or email. Requires users:read.

Create a Keycloak email/password user, generate a one-time password that must be reset on first login, then save the YAAIF tenant user. Returns temporary_password once. Requires users:write. Granting ADMIN additionally requires the caller to be ADMIN and confirm_admin_grant=true. Downstream systems can call the same POST /api/users contract with a ymp- key scoped to users:write.

Change a tenant user's platform role (ADMIN, EDITOR, DEVELOPER, VIEWER, CHAT_USER, or a custom role from yaaif_roles_list). Requires users:write. Granting ADMIN additionally requires the caller to be ADMIN and confirm_admin_grant=true.

List desktop workers in the tenant (control-plane).

List desktop worker↔skill mappings (control-plane).

Replace worker ids mapped to a desktop skill (control-plane PUT). Optionally trace this external dependency to a Scenario slot; attach evidence/attestation before activation.

Delete desktop worker↔skill mapping for a skill id.

List command-based MCP tool packages in the tenant Package Registry (api-server /api/desktop/tool-packages).

Get one desktop tool package by id (UUID) or tool_key (e.g. sap-gui.mcp).

Inspect a local command/stdio MCP codebase and propose Package Registry metadata + archive plan. Does not upload. Reads optional yaaif-tool-package.json.

Add or update a Package Registry entry from a local command/stdio MCP codebase: infer launch contract, zip source or wrap dist exe, create/update the package, upload the platform artifact. Use mode=add (fail if exists), update (fail if missing), or upsert (default).

Update Package Registry metadata for an existing command MCP package (no local codebase required). To refresh the archive from source, use yaaif_desktop_tool_package_publish mode=update.

Remove a command-based MCP tool package (and its platform archives) from the Package Registry.

Install or reinstall a Package Registry archive onto one or more desktop workers (control-plane POST .../install). Re-running on a worker that already has the tool upgrades it to the current package version. Platform is optional — control-plane uses the worker's OS when omitted.

Upgrade a command MCP already installed on desktop worker(s) to the current Package Registry version. Same control-plane install dispatch as yaaif_desktop_tool_package_install (worker upserts the local tool).

Remove an installed command MCP from desktop worker(s) (control-plane POST .../remove). Does not delete the Package Registry entry — use yaaif_desktop_tool_package_delete for that.

Show install/upgrade/remove state of a Package Registry tool on desktop workers (from control-plane tool_install and tool_remove runs). Use before install or uninstall.

List approval strategies (approval-service).

Get one approval strategy by id.

Create an approval strategy (draft). Optionally publish version 1. Use for ambient Linear+approval graphs.

Publish an approval strategy version (required before ambient graphs resolve it).

Diff expected plan components (agent/skill/workflow/MCP/local-tool names) against the live tenant catalog.

Dry-run an execution plan: echo intended tool calls without mutating the tenant. Optionally check catalog refs.

Persist a plan execution checklist (step statuses + result ids) in the active YAA\F client state directory for resume.

Load a saved plan execution by slug.

List saved plan executions.

Update one step status/result_ids on a saved plan execution (call after each mutate).

Refresh Scenario readiness/version before returning the next pending step. Halt for unresolved sync conflicts or failed verification evidence rather than repeating mutations.

Read the tenant Scenario enforcement mode. New tenants default to observe.

Promote the active tenant from observe to warn or require after adoption inventory review.

Inventory untracked catalog objects discovered in observe/warn mode. Map selected objects explicitly before adoption; never auto-create a Scenario.

Create a tenant Scenario (Agent Spec): requirement segments + architecture slots. Admin UI calls this a scenario. Pass the returned spec_id on later create tools.

Delete an empty Scenario (Agent Spec). Allowed only when it has no current catalog bindings, is not active, and is not a required release dependency of another scenario.

Export the portable Scenario tenant policy document for review or promotion across environments.

Import a reviewed version-1 Scenario tenant policy document. This controls enforcement, evidence TTL, and high-assurance override approval.

Explicitly close an untracked inventory item as ignored or adopted. Adoption requires the Scenario id after its mapped bindings were reviewed.

Run a non-destructive Scenario drift scan. It records readiness conflicts only; use sync preview/apply to resolve them.

Read observe/warn/require rollout metrics: untracked mutations, readiness failures, overrides, sync conflicts, and verification failures.

List Scenarios (Agent Specs) for the active tenant.

Load one Scenario (Agent Spec) by id or slug, including segments, slots, bindings, and workflow_design.

Update Scenario identity or segments using the version returned from its last read. Requirement and slot replacement is only allowed with replace_all=true; prefer granular tools.

Update one Scenario segment (overview, architecture, workflow_design, benefits, …).

Explicitly replace every architecture slot. Prefer yaaif_agent_spec_upsert_slot for normal edits.

Bind a live catalog entity to a Scenario architecture slot. Default source is agent_spec (created/maintained from this scenario).

Copy bound ambient workflow graphs into the Scenario workflow_design segment. This is an explicit adopt of live graphs. Prefer yaaif_agent_spec_sync_to_objects to apply Scenario-owned workflow_design onto catalog objects.

Adopt live catalog objects into the Scenario (explicit). Overwrites Scenario-owned names and workflow graphs. Preview with yaaif_agent_spec_sync_preview (from_objects), then apply. Not the default finish step after create/bind.

Apply Scenario-owned names and workflow_design onto bound catalog objects. Preview with yaaif_agent_spec_sync_preview (to_objects), then apply. Skill pack files are not overwritten.

Apply a previously reviewed adoption preview. Existing authored Scenario prose is preserved and a baseline revision is published.

Publish an immutable semantic Scenario release. Use patch for corrections, minor for compatible capability additions, and major for breaking architecture or requirement changes.

List immutable Scenario releases with SemVer, parent revision, content hash, change summary, and author.

Compare two immutable Scenario releases at the identity, segment, requirement, and slot level before restoring or promoting a change.

Restore an immutable Scenario release into a new draft. Historical releases are never altered; review and publish the restored draft as a new semantic release.

Promote a verified Scenario release candidate to its stable SemVer release. Promotion creates a fresh immutable stable record and never rewrites the candidate.

Request the configured approval-service review for a major Scenario release, a release-candidate promotion, or a restore. This is inactive unless tenant policy v2 explicitly enables release governance.

List immutable-draft release approval requests and their latest recorded approval-service status.

Refresh one Scenario release approval from approval-service before attempting the governed action.

Record build, isolated verification, artifact, SBOM, or deployment provenance for one immutable Scenario release. A release candidate needs passing verification provenance before promotion.

List build/test/artifact/SBOM/deployment provenance attached to immutable Scenario releases.

Export a signed-by-hash Scenario release manifest suitable for committing to Git, review, and disaster recovery.

Import a reviewed, hash-verified Scenario release manifest from Git as a new draft. It preserves bound slot identities and never changes release history.

Preview legacy release metadata normalization. This is read-only and never runs automatically for any tenant.

Apply a reviewed legacy-release backfill with the exact preview hash. This is an explicit operator action, not tenant rollout automation.

Preview declared dependent-Scenario compatibility with a proposed provider semantic release; policy may optionally block required incompatibilities.

Declare that this consumer Scenario depends on a provider Scenario release range. The update is version-protected and explicit.

List explicit provider Scenario version constraints declared by this consumer Scenario.

Remove one explicit Scenario provider dependency using the current optimistic draft version.

Return machine-readable activation/publish blockers, requirement coverage, stale evidence, and pending sync conflicts.

Return the Scenario dependency graph for change-impact analysis: requirements, slots, bound objects, and evidence.

Create or update one typed requirement with acceptance criteria; preserves every other requirement and slot.

Delete one unreferenced requirement. Remove it from its slots first.

Create or update one architecture slot and its requirement links without replacing the slot list.

Delete one unbound architecture slot.

Preview apply (to_objects: spec → catalog) or adopt (from_objects: catalog → spec). Read-only; must precede sync apply.

Apply a reviewed preview: to_objects writes the Scenario onto bound catalog objects; from_objects adopts live catalog drift into the Scenario.

List unresolved field-level Scenario/catalog conflicts, including severity and the two competing values.

Resolve one conflict: accept_object copies the live field into the Scenario, keep_spec retains the Scenario value, and merge sets merged_value.

Record requirement-level verification evidence from a passed agent test, ambient smoke run, or audited manual attestation.

Transition a Scenario lifecycle state. Active is rejected until readiness passes; use a separately authorized override only for exceptional cases.

Exceptional activation only. Requires the dedicated permission and a durable reason recorded in the Scenario audit log.

Preview the selected existing bindings, their current live baseline, and authored fields preserved by adoption.

Check Scenario slot coverage against the live tenant catalog.

Get Scenario processing / lifecycle status (revisions, sync, attribution).

Query telemetry metrics attributed to a Scenario (sessions, tokens, tools).

Pause an ambient run (agent-service).

Resume a paused ambient run.

Approve an ambient run gate (agent-service). If managed by approval-service, use yaaif_approval_task_decide instead.

Reject an ambient run gate (agent-service).

Stop an ambient run.

List approval inbox tasks (approval-service).

Claim an approval inbox task.

Decide an approval task (approve|reject|request_clarification|send_back).

READ-ONLY: correlate session_id / ambient_run_id / desktop_run_id / request_id into one incident graph with failure summaries.

READ-ONLY: one-shot incident analysis — correlate IDs, rank failures, and return next_steps. When an ambient run is linked, also includes run_path (coverage/path/current step/canvas URL). Prefer this first; then yaaif_ops_telemetry for drill-down.

READ-ONLY: LLM/flow session metrics detail + derived failure findings for a session_id.

READ-ONLY: ambient workflow run detail + diagnostic failures for a run_id, plus run_path (coverage/path/current step/canvas URL).

READ-ONLY: desktop worker run detail + failure findings for a run_id.

READ-ONLY: list desktop runs for a session_id (optional status filter).

READ-ONLY: unified telemetry drill-down via agent-service /api/ops (proxies telemetry-service). resource=messages|events|flow_events|insights|desktop_logs|ambient_logs. Prefer after yaaif_ops_analyze.

READ-ONLY: LLM transcript messages. Alias of yaaif_ops_telemetry resource=messages.

READ-ONLY: LLM session events. Alias of yaaif_ops_telemetry resource=events.

READ-ONLY: flow-events by request_id. Alias of yaaif_ops_telemetry resource=flow_events.

READ-ONLY: desktop worker logs. Alias of yaaif_ops_telemetry resource=desktop_logs.

READ-ONLY: ambient worker logs. Alias of yaaif_ops_telemetry resource=ambient_logs.

READ-ONLY: flow-session insights. Alias of yaaif_ops_telemetry resource=insights.

READ-ONLY: list prior confirmed ops diagnoses (newest first). Provide exactly one of ambient_run_id, session_id, or desktop_run_id. Call before yaaif_ops_analyze so prior findings inform triage.

READ-ONLY: fetch one confirmed ops diagnosis by id.

Write a confirmed OpsDiagnosisRecord back to YAAIF (append-only). Requires confirm=true after presenting the full draft to the user. Does not pause/stop/approve/retry runs. Requires ops.support.write.

List agent-service built-in local tools (skill lifecycle, files, ambient trigger, state, approvals). Use when authoring SKILL.md tools: lists.

Get one local tool definition (name, description, input_schema, family).

Counts of local tools by family plus recommended skill-authoring tools.

Invoke an agent-service built-in local tool (not external MCP). Prefer for skill_validate_module, skill_develop, files_list, list_ambient_workflows, etc. High-impact tools require allow_mutating=true.

Create or reuse a Cursor authoring chat session for files_* / session_state_* local tools. Auto-picks default skills agent when agent_id omitted. Persists ids in /root/.yaaif/cursor/session.json.

Verify skill frontmatter tools / allowed-tools (or an explicit tools list) exist in local tools or external MCP catalog. Server wildcards such as sap-odata:* are accepted. Also use allowed-prompts / allowed-resources from markdown. Run before skill create.

Validate a skill module via platform local tool skill_validate_module.

Run platform skill_develop local tool.

Create a guided skill draft via skill_create_guided_draft.

List MCP tools for skill linking (skill_mcp_tool_catalog).

Create/update/delete skill module files via skill_update_module_files.

Edit a SKILL.md section via skill_edit_section.

List ambient workflows via platform local tool.

Trigger an ambient workflow via platform local tool.

List ingested files for the active authoring session (includes artifact_name/version when present). Call yaaif_dev_session_ensure first.

Search uploaded files by name/preview via files_search. Call yaaif_dev_session_ensure first.

Load extracted text via file_load_context. file_id may be a durable UUID or ADK artifact filename; pass version for a historical revision.

ADK-aligned artifact helper: list session/user: artifacts or load by filename/file_id (optional version). Prefer for human-readable names.

Mint a short-lived signed URL via file_share_link (when share links are enabled on the platform).

Create a downloadable file in the session via generate_file (returns file_id / artifact_name).

List every version of an ADK artifact name (session-scoped or user:-prefixed). Uses GET /api/files/artifacts/versions. Pass session_id (or call yaaif_dev_session_ensure first).

Delete one artifact version (?version=N) or every version (omit version) via DELETE /api/files/artifacts. Requires confirm=true.

Fetch extracted text via GET /api/files/extracted. file_id may be a durable UUID or an ADK artifact filename; version selects a historical revision (omit/0 = latest).

List session files via GET /api/files (REST). Set latest_only=true to return one row per artifact_name (latest version). Prefer yaaif_files_list / yaaif_load_artifacts for skill authoring.

End-to-end health narrative: profile, OIDC discovery, TLS, auth, tenant, catalog ping. Prefer before create/plan work.

Get anonymous local telemetry opt-in state and counters from the active YAA\F client state directory.

Enable/disable anonymous local success/fail counters (no network, no tokens).