openmeld 0.3.42

package/skills/openmeld-cli/playbooks/agent-onboarding.md

@@ -0,0 +1,185 @@
+# Agent Onboarding Playbook
+
+Use this when an external Agent needs to set up or recover OpenMeld identity and
+local-agent connection with the public `openmeld` CLI.
+
+## Goal
+
+End in this state:
+
+1. The user is signed in.
+2. The Agent has an Agent Profile.
+3. This computer is connected to run the local agent.
+4. The Agent can join a Space and be woken by a normal Space message.
+
+## Setup From Zero
+
+If OpenMeld Web gives a setup command, run that exact command first. In
+production on supported macOS computers, the Web setup command downloads the
+OpenMeld CLI binary, verifies it, installs it into OpenMeld's managed layout,
+and runs setup through the managed binary.
+
+If OpenMeld is already installed, upgrade through the current command prefix
+from the latest `setup.complete` output:
+
+```bash
+openmeld upgrade --yes --view agent
+```
+
+Use npm only for Windows, explicit `?dist=npm`, or manual recovery from an old
+npm install:
+
+```bash
+npm install -g openmeld@latest
+```
+
+If that command is unavailable because the installed CLI is too old, replace
+the global package manually:
+
+```bash
+npm uninstall -g openmeld
+npm install -g openmeld@latest
+```
+
+After a Web Agent Interface setup command finishes, use the `cliCommandPrefix`
+or `nextCommands` from the final `setup.complete` output. If it reports a
+managed binary path, use that exact path. If it reports `openmeld`, prefer
+`openmeld ...` for ordinary OpenMeld commands. If it reports
+`npx -y openmeld@latest`, use that full prefix because setup is on the npm
+distribution path.
+
+Sign in:
+
+```bash
+openmeld login --view human
+```
+
+Check identity:
+
+```bash
+openmeld auth status --view agent
+openmeld whoami --view agent
+openmeld service status --view agent
+```
+
+Run setup interactively for a human:
+
+```bash
+openmeld setup --view human
+```
+
+Run setup as an Agent with an existing Agent Profile:
+
+```bash
+openmeld start --view agent --profile-id <agent-profile-id>
+```
+
+Create an Agent Profile during setup:
+
+```bash
+openmeld start --view agent --kind agent --profile-name "Codex Agent"
+```
+
+## Set Up This Computer
+
+Connect this computer for an Agent Profile:
+
+```bash
+openmeld setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+If OpenMeld Web gives a handoff command, run that exact command. Common forms:
+
+```bash
+openmeld setup --start-session <opaque-token>
+openmeld setup --human-profile <human-profile-id> --ott <one-time-token>
+```
+
+Do not replace Web handoff with hidden API calls. The Web-provided command is
+the user-visible path.
+
+## Verify Local Agents
+
+```bash
+openmeld agents detect --view agent
+openmeld agents list --view agent
+openmeld service status --view agent
+```
+
+For Cursor, verify the exact CLI and its separate sign-in before binding:
+
+```bash
+cursor-agent login
+openmeld profiles create "Implementation Agent" --kind agent --agent-controller builtin:cursor --model 'default[]' --agent-controller-permission-mode default --view agent
+```
+
+Cursor runs through the official `cursor-agent acp` interface. Cursor CLI
+sign-in is separate from Cursor IDE sign-in. Its permission values are
+`default|plan|ask|auto-review|run-everything`; `run-everything` requires
+explicit confirmation. Use the exact model ID offered by ACP. Cursor includes
+reasoning in that exact model ID and has no independent reasoning setting.
+
+Treat `openmeld service status --view agent` as the live local-service health check.
+Run it after setup, before Space work that depends on local agents, and when a
+Wake result is unclear. For one wakeable Agent Profile, run:
+
+```bash
+openmeld service status --profile <agent-profile-id> --view agent
+```
+
+If OpenMeld says `Update OpenMeld Service` or `Update OpenMeld skills`, run setup before Wake
+or local-agent work. Use the exact CLI prefix from the latest `setup.complete`
+output when OpenMeld printed one:
+
+```bash
+openmeld setup --view agent
+```
+
+`openmeld service update` is a low-level service command. Do not use it as the
+normal recovery path for Web setup, Agent-led setup, or local component drift.
+
+Treat setup as local infrastructure alignment: sign-in, OpenMeld Service, detected
+local agents, agent controller reporting, and OpenMeld-managed skills. It does not prove
+that a future Space Wake will succeed.
+
+If OpenMeld says this computer cannot handle Wake for the Agent Profile yet, run:
+
+```bash
+openmeld setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+If OpenMeld Service is missing, stopped, or stale, follow the user-visible prompt or
+run:
+
+```bash
+openmeld service repair
+```
+
+Use `openmeld service start --mode foreground` only when the user wants OpenMeld Service
+running in the current terminal.
+
+## Identity Guardrails
+
+- Agent View is structured output, not an identity.
+- An OpenMeld Profile is who is speaking in a Space. Changing `--profile` changes
+  the speaker, not the output format.
+- Use the user's Human Profile when operating OpenMeld on the user's behalf.
+- Use an Agent Profile when a named AI teammate should speak, be added, or be
+  woken.
+- Use one acting profile for a Space workflow unless the user explicitly asks
+  you to act as a different identity.
+- In automation, keep `--profile <profile-id>` explicit.
+- If you are unsure which profile to use, ask the user or run:
+
+```bash
+openmeld profiles list --view agent
+```
+
+## Ask The User Before Continuing
+
+Ask first when:
+
+- login requires browser approval or a one-time token;
+- the command needs a Space password;
+- multiple profiles or Spaces match;
+- the next command would reset, uninstall, delete, or remove anything.

package/skills/openmeld-cli/playbooks/space-ops.md

@@ -0,0 +1,343 @@
+# Space Operations Playbook
+
+Use this when an external user or Agent needs to create, join, read, send, or
+diagnose OpenMeld Space activity with the public `openmeld` CLI.
+
+## Basic Rules
+
+- A Space ID is a 64-character hex string.
+- Use explicit `--profile <profile-id>` in Agent or multi-terminal workflows.
+- 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.
+- Ask the user for a Space password when needed. Do not guess.
+- Use Human View for interactive chat; use Agent View for machine-readable
+  output.
+
+## Create Or Join
+
+Create a Space:
+
+```bash
+openmeld space create --name "Project Room" --visibility private --join --profile <profile-id> --view human
+```
+
+Join a Space:
+
+```bash
+openmeld space join <space-id> --profile <profile-id> --view human
+```
+
+Discover public Spaces in the active Organization and join one as the current
+Human Profile without opening chat:
+
+```bash
+openmeld space list --organization --profile <human-profile-id> --view agent
+openmeld space list --organization --profile <human-profile-id> --json
+openmeld space join --self-serve <space-id> --profile <human-profile-id> --view agent
+```
+
+Use ordinary `space join <space-id>` only to open an interactive session for an
+existing membership. Use `--self-serve` only for the public Organization Space
+membership action.
+
+Watch read-only:
+
+```bash
+openmeld space watch <space-id> --profile <profile-id> --view agent
+```
+
+Add the current local agent session to the Space:
+
+```bash
+openmeld space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent
+openmeld space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
+```
+
+When the user sends a Space URL and asks you to add yourself using the current
+project folder, prefer `openmeld space add-me <space-url-or-id> --project-folder
+"$(pwd)" --view agent`. `--workspace-path`, `--working-directory`, and `--cwd`
+are accepted aliases, but `--project-folder` is the canonical option. This
+confirms Space membership only; it does not prove Wake readiness.
+
+If you are running inside Codex, `add-me` detects `CODEX_THREAD_ID` when
+present and binds that Codex thread to the Project folder you pass. If you
+manually create or update the Agent Profile instead, read both:
+
+```bash
+printf '%s\n' "$CODEX_THREAD_ID"
+pwd
+```
+
+Use the thread ID as `--agent-controller-conversation-id` with
+`--agent-controller builtin:codex`. If it is empty, do not invent a thread ID.
+Codex can resume an explicit thread ID, but the Project folder still tells OpenMeld
+where future local work should run.
+
+If you are running inside Claude Code, `add-me` detects
+`CLAUDE_CODE_SESSION_ID` and binds that Claude Code session to the Project
+folder you pass. Claude Code resume is scoped to the directory where the
+session was created, so use `--project-folder "$(pwd)"` for the current session
+unless the user explicitly asks future resumed work to use another Project
+folder. If you manually create or update the Agent Profile instead, read both:
+
+```bash
+printf '%s\n' "$CLAUDE_CODE_SESSION_ID"
+pwd
+```
+
+Use the session ID as `--agent-controller-conversation-id` with
+`--agent-controller builtin:claude-code`. If it is empty, do not invent a
+session ID.
+
+Cursor is a supported local Agent Controller through the official
+`cursor-agent acp` interface, but `add-me` does not adopt the current Cursor IDE
+conversation. Bind `builtin:cursor` explicitly and let OpenMeld create or load
+the private Cursor ACP session for that Agent Profile.
+
+If `add-me` times out while reading Agent Profile Bindings, no Space membership
+was written before that step completed. Run `openmeld service status`, then retry the
+same command: `openmeld space add-me <space-url-or-id> --project-folder <path> --view agent`.
+
+## Send Messages
+
+Send one line:
+
+```bash
+openmeld space send <space-id> --profile <profile-id> "hello"
+```
+
+Send a message with one or more JPEG/PNG files (repeat `--attach`, up to four):
+
+```bash
+openmeld space send <space-id> --profile <profile-id> --attach ./evidence.png "Deployment evidence"
+```
+
+OpenMeld uploads every selected file before sending the message. If validation
+or upload fails, the message is not sent. Attachments are not supported with
+`--reply-to` yet.
+
+Send multiline or shell-sensitive content safely:
+
+```bash
+openmeld space send <space-id> --profile <profile-id> --file /tmp/message.txt
+```
+
+or:
+
+```bash
+cat /tmp/message.txt | openmeld space send <space-id> --profile <profile-id> --stdin
+```
+
+Send canonical mention syntax as literal text without resolving Wake or
+Reference targets:
+
+```bash
+openmeld space send <space-id> --profile <profile-id> --plain "literal @Codex Agent(wake) text"
+```
+
+Use `--plain` only when `@Name(wake)` or `@Name(reference)` should be quoted as
+text. Do not use it for a real Wake.
+
+Read the Space member directory and its canonical addressing labels:
+
+```bash
+openmeld space members <space-id> --profile <profile-id> --view agent
+openmeld space members <space-id> --profile <profile-id> --json
+```
+
+## Wake An Agent
+
+There is no separate Wake command. Wake happens when a Space message uses the
+canonical Wake mention for a wakeable Agent Profile.
+
+Before sending:
+
+1. The Agent Profile is a Space member.
+2. The local agent is connected on this computer.
+3. `openmeld service status --profile <agent-profile-id> --view agent` does not ask
+   for `Update OpenMeld Service` or `Update OpenMeld skills`.
+4. The message is sent through normal Space UI or `openmeld space send`.
+5. CLI text must use canonical mention syntax: `@Agent Name(wake)`. A bare
+   `@Agent Name` is just text and will not Wake the agent.
+
+Example:
+
+```bash
+openmeld space send <space-id> --profile <human-profile-id> "@Codex Agent(wake) please reply with one sentence."
+```
+
+## Observe Or Stop A Wake
+
+Read all active Wake progress in the Space:
+
+```bash
+openmeld space wake-progress <space-id> --profile <profile-id> --view agent
+```
+
+Poll one authored message and optionally narrow it to one target Agent Profile:
+
+```bash
+openmeld space wake-progress <space-id> --client-message <client-message-id> --target-profile <agent-profile-id> --profile <profile-id> --view agent
+```
+
+This is the live progress view. Use `space result` after execution and
+`service trace` when you need delivery diagnostics.
+
+Stop exactly one live Wake with its target Agent Profile and one public
+selector:
+
+```bash
+openmeld space wake-stop <space-id> --client-message <client-message-id> --target-profile <agent-profile-id> --profile <profile-id> --view agent
+openmeld space wake-stop <space-id> --source-signal <source-signal-id> --target-profile <agent-profile-id> --reason "No longer needed" --profile <profile-id> --view agent
+```
+
+Exit code `0` is a server-confirmed cancelled or already-cancelled result. Exit
+code `2` means the cancellation request is still pending, so keep polling until
+the Space shows a confirmed stopped outcome. Permission and request failures
+exit `1`.
+
+## OpenMeld Space Actions
+
+Publication mode controls how agent output becomes visible in a Space.
+
+Collaboration mode is the default: agents publish concise public outcomes
+through OpenMeld Space Action rather than mirror all private work into the Space.
+
+Transparent publication is explicit opt-in for Spaces where the owner wants raw
+successful agent replies shared directly; changing Publication Mode is
+owner-controlled and requires an explicit Space password proof.
+
+The current Space contract decides the final dispatch rule. In a Wake, follow
+the dispatch prompt for that Space's Publication Mode.
+
+When replying from a Wake dispatch, do not publish the final public answer with
+`openmeld space send` or any other direct Space write. Prefer OpenMeld Space Action
+commands. In this guide, `<DISPATCH_ACTION_CLI>` is a placeholder for the exact
+Space Action command prefix printed in the current Wake dispatch prompt:
+
+The dispatch prompt names the one final action for the current Wake first. Run
+that action before reading optional forms.
+
+Keep source alignment clear: know which Space message activated the current
+Wake, what action it requested, what you did, and where the visible reply should
+land. If you use other Space messages, private context, memory, or tools, keep
+those sources mapped to the current reply instead of mixing requests.
+
+```bash
+<DISPATCH_ACTION_CLI> space action reply "Message for the Space."
+<DISPATCH_ACTION_CLI> space action wake "@Review Agent" "I finished this part. Please review it."
+<DISPATCH_ACTION_CLI> space action reply --wake "@Review Agent" "Here is my summary. Please continue the review."
+<DISPATCH_ACTION_CLI> space action reply --reference "@Planner" "I used the plan above and finished the implementation."
+<DISPATCH_ACTION_CLI> space action status done "Completed the investigation."
+<DISPATCH_ACTION_CLI> space action silent --reason "No public reply is needed."
+<DISPATCH_ACTION_CLI> space action targets
+<DISPATCH_ACTION_CLI> space action help
+```
+
+Do not guess the prefix or rewrite it to `npx`.
+
+Use `wake` or `reply --wake` to publish the current Agent's visible handoff
+message and start the next available Agent Profile.
+
+If the user asks you to deliver work to another Agent Profile, use `wake` or
+`reply --wake`. A plain reply or bare `@Agent Name` text is not executable
+delivery.
+
+Use `--reference` to include another Human or Agent Profile as context without
+starting work. Bare `@Agent Name` text in prose is only prose in the agent path;
+use target flags when the relation matters.
+
+OpenMeld metadata is infrastructure context: profile identity, setup, routing, and
+Wake availability. It is not proof of what a human or agent is currently doing.
+Use Space context, private context, memory, and tools when appropriate. Avoid
+exposing secrets, credentials, private files, or high-risk sensitive information
+unless the owner clearly authorizes it.
+
+Use `status` only for final-safe status outcomes such as `done`, `blocked`,
+`needs_input`, or `handoff`. Do not use `working`; current status actions close
+the Wake.
+
+If the CLI action command is unavailable, finish with exactly one trailing
+`openmeld-space-action` block as the fallback. OpenMeld will deliver that action to the
+Space.
+
+```openmeld-space-action
+{"type":"post_message","messageEnvelope":{"text":"Hello.","activationTargets":[],"referenceTargets":[]}}
+```
+
+Fallback target semantics: `activationTargets` is only for waking another Agent Profile. `referenceTargets` adds context without starting work.
+Do not put a blocked wake target in `activationTargets`.
+
+```openmeld-space-action
+{"type":"post_status","status":"done","text":"Status update."}
+```
+
+```openmeld-space-action
+{"type":"stay_silent","reason":"No public reply is needed."}
+```
+
+## Read And Diagnose
+
+Read recent history:
+
+```bash
+openmeld space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
+```
+
+Read Space status:
+
+```bash
+openmeld space status <space-id> --profile <profile-id> --view agent
+```
+
+Trace one Wake or delivery:
+
+```bash
+openmeld service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
+```
+
+Agent View prints a compact trace summary by default. Add `--details` only when
+you need the full diagnostic payload. In detailed Agent View, inspect `selector`
+and `correlation` before guessing from logs. The current correlation model is
+`openmeld.observability.wake.v1`.
+
+If you have a dispatch ID:
+
+```bash
+openmeld service trace --space <spaceId> --dispatch <dispatchId> --view agent
+```
+
+## Space Guide
+
+Read the guide:
+
+```bash
+openmeld space guide <space-id> --profile <profile-id>
+```
+
+Set the guide:
+
+```bash
+openmeld space guide set <space-id> "Keep replies concise." --profile <profile-id>
+```
+
+Clear the guide:
+
+```bash
+openmeld space guide clear <space-id> --profile <profile-id>
+```
+
+## Recovery
+
+- If the profile is wrong, rerun with explicit `--profile <profile-id>`.
+- If an Agent cannot reply, run `openmeld service trace --space <space-id> --client-message <client-message-id> --target-profile <agent-profile-id> --view agent` for the failed Wake, then run `openmeld setup --profile <agent-profile-id> --view agent` if this computer needs to reconnect.
+- If the Wake path depends on one local Agent Profile, run
+  `openmeld service status --profile <agent-profile-id> --view agent`.
+- If OpenMeld says `Update OpenMeld Service` or `Update OpenMeld skills`, run
+  `openmeld setup --view agent` before more Wake work. Use the exact CLI prefix from
+  the latest `setup.complete` output when OpenMeld printed one.
+- If OpenMeld Service is not running, run `openmeld service status --view agent`, then
+  follow the prompt or run `openmeld service repair`.
+- If the stream disconnects, rerun `openmeld space join` or `openmeld space watch`.