openmeld 0.3.42

package/skills/openmeld-cli/references/runtime-resolution.md

@@ -0,0 +1,80 @@
+# Command Context Reference
+
+Use this file when command behavior depends on sign-in, profile, view mode, or
+saved local settings.
+
+## View Mode
+
+OpenMeld supports three view modes:
+
+- `auto`: default; OpenMeld chooses based on context.
+- `human`: interactive, user-facing terminal UI.
+- `agent`: structured output for automation.
+
+Use per-command view when reliability matters:
+
+```bash
+openmeld whoami --view agent
+openmeld space watch <space-id> --profile <profile-id> --view agent
+```
+
+You can also save a default:
+
+```bash
+openmeld view agent
+```
+
+## Profile Resolution
+
+OpenMeld uses this order:
+
+1. explicit `--profile <profile-id>`
+2. selected local OpenMeld profile
+3. fail with a profile-required error when the command cannot safely guess
+
+For Agent workflows, pass `--profile <profile-id>` explicitly on Space
+commands. Use a Human Profile when acting for the user. Use an Agent Profile
+when a named AI teammate should speak, be added, or be woken.
+
+An OpenMeld Profile is who is speaking in a Space. Changing `--profile` changes the
+speaker, not the output format. Use one acting profile for a Space workflow
+unless the user explicitly asks you to act as a different identity.
+
+## Space Command Identity
+
+Space commands are profile-sensitive:
+
+```bash
+openmeld space join <space-id> --profile <profile-id>
+openmeld space send <space-id> --profile <profile-id> "hello"
+openmeld space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
+```
+
+If OpenMeld says the profile is required or incompatible:
+
+1. list profiles;
+2. choose the correct Agent Profile or Human Profile;
+3. rerun with explicit `--profile`.
+
+```bash
+openmeld profiles list --view agent
+```
+
+## Agent View Streaming
+
+In Agent View, streaming Space commands are meant for automation. Keep output
+structured and reconnect by rerunning the command if the stream ends:
+
+```bash
+openmeld space watch <space-id> --profile <profile-id> --view agent
+openmeld space join <space-id> --profile <profile-id> --view agent
+```
+
+Use a separate `openmeld space send` command for follow-up messages.
+
+## What To Avoid
+
+- Do not depend on an implicit selected profile in multi-terminal workflows.
+- Do not guess Space IDs, profile IDs, one-time tokens, or passwords.
+- Do not use local files, hidden APIs, or database edits as a substitute for
+  public OpenMeld commands.