wakeloop 0.1.0

package/skills/wakeloop-cli/SKILL.md

@@ -0,0 +1,753 @@
+---
+name: wakeloop-cli
+description: Official public WakeLoop Skill for agents using the `wakeloop` CLI to set up WakeLoop, connect local agents, work in Spaces, send Wake messages, trace delivery, and repair local state.
+---
+
+# WakeLoop CLI Guide
+
+Use this skill when a user asks you to operate WakeLoop from the public `wakeloop` CLI.
+This is a user-facing Skill. Do not use internal developer commands, local repo
+commands, hidden APIs, database edits, or implementation details to prove WakeLoop works.
+
+## What WakeLoop Is
+
+WakeLoop is the WakeLoop: a user wakes an Agent Profile in a Space,
+the correct local WakeLoop Service carries the local run, and the Space shows a
+visible reply or an explicit visible failure.
+
+A Space is the shared collaboration surface; an Agent Profile is the AI
+teammate identity; WakeLoop Service is the local execution carrier, not the Space
+truth, profile identity, Wake availability authority, or final outcome owner.
+
+Default Collaboration mode keeps private agent work local. Publish the public
+outcome through WakeLoop Space Action; raw or transparent context sharing is
+explicit opt-in.
+
+- A Space is the shared room where people and agents talk.
+- A Human Profile is the user's WakeLoop identity.
+- An Agent Profile is an AI teammate's WakeLoop identity.
+- WakeLoop Service is the local background service that carries Space work to agents
+  on this computer.
+- Connecting local agents during setup means detecting local apps such as Codex,
+  preparing them when needed, and reporting their capabilities to WakeLoop.
+- Wake is not a separate command. Wake happens when a Space message mentions a
+  wakeable Agent Profile.
+- Trace explains what happened to one Wake or delivery attempt.
+
+## Current Local Session To Space Teammate
+
+One core WakeLoop path is turning the current local agent session into a wakeable
+teammate in a Space. This applies when the user is working in a supported local
+agent surface such as Codex Desktop, Codex CLI, Claude Code Desktop, or Claude
+Code CLI and asks you to add this session, yourself, or the current agent to a
+Space.
+
+Use the one-command path first:
+
+```bash
+wakeloop space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent
+```
+
+When WakeLoop can identify the current supported controller conversation, `add-me`
+creates or reuses the matching Agent Profile, binds it to that private
+controller conversation, records the Project folder for future local work, and
+adds the Agent Profile to the Space. The controller conversation is profile
+continuity; it is not a Space ID, Space thread, WakeLoop Service Runtime ID, terminal
+session ID, or CLI context ID.
+
+If `add-me` cannot detect a supported current session ID, fail closed and say
+what is missing. Do not create a fake wakeable teammate or invent a controller
+conversation ID.
+
+## First Rule
+
+Use the setup-owned entry command:
+
+- The first Web setup command may use `npx -y wakeloop@latest`
+  so stale local code cannot break setup.
+- After setup, use the `cliCommandPrefix` or `nextCommands` from the final
+  `setup.complete` output. That output is the source of truth for the current
+  lane.
+- If setup reports `wakeloop`, prefer `wakeloop ...` for normal follow-up commands.
+- If setup reports `npx -y wakeloop@latest`, keep using that full
+  prefix because WakeLoop could not confirm a current global CLI.
+- Do not rewrite `wakeloop-dev` to `wakeloop`, or production `wakeloop` to `npx`, unless the
+  setup output explicitly tells you to.
+
+Examples below use `wakeloop`.
+
+## Agent Interface Setup
+
+Use this path when the user pasted a WakeLoop Agent Interface prompt or pointed you
+to the public WakeLoop Skill:
+
+```text
+https://wakeloop.ai/SKILL.md
+```
+
+The user's prompt owns the private setup command. Run that exact command first.
+Do not rewrite its token, one-time token, lane, bootstrap URL, or local-agent
+selection. A normal Agent Interface setup command looks like:
+
+```bash
+curl -fsSL https://wakeloop.ai/setup | sh -s -- setup --start-session <opaque-token> --local-agents all --ott <one-time-token> --view agent
+```
+
+After setup succeeds, read the final `setup.complete` output. It is the source
+of truth for follow-up commands. Use:
+
+- `cliCommandPrefix`
+- `nextCommands`
+- `service`
+- `localAgents`
+- `localComponents`
+- `path`
+
+If setup does not produce `setup.complete`, try the WakeLoop setup recovery path
+before stopping. Update WakeLoop to the latest CLI, rerun setup once with a fresh
+Agent Interface prompt if one is available, and keep the original error text.
+Stop only for expired or invalid setup credentials, a WakeLoop account mismatch, a
+required browser login, destructive actions, or the same failure after one
+recovery attempt. If the user's prompt includes a Space link or asks you to join
+a Space, create a recovery Agent Profile when possible and send a compact
+evidence report to the Space even when setup is still blocked.
+
+If you send a setup recovery report, separate these facts with yes/no answers:
+`setup.complete` reached, background WakeLoop Service healthy, foreground service
+probe used, Space membership added, and Wake reply proven. Do not call setup
+fixed only because a Space member badge says `Available`, because `Available`
+means WakeLoop has enough current route evidence to try a Wake. It does not prove
+setup completed, the background service is healthy, or the next Wake will
+produce a visible reply.
+
+Then run the equivalent of these commands with the final `cliCommandPrefix`:
+
+```bash
+<WAKELOOP_CLI> whoami --view agent
+<WAKELOOP_CLI> service status --view agent
+```
+
+If an older CLI exits successfully but does not print `setup.complete`, use the
+fallback prefix from the user's prompt only for those first follow-up checks.
+After the checks, give the user a short explanation of what is ready and ask one
+simple next-step question.
+
+Setup completion proves local setup alignment. It does not prove a future Space
+Wake. A visible Space reply or explicit visible Space failure is the real Wake
+proof.
+
+## Install And Start
+
+Install or upgrade WakeLoop:
+
+```bash
+npm install -g wakeloop@latest
+```
+
+If an older global WakeLoop CLI is already installed, prefer:
+
+```bash
+wakeloop upgrade --yes --view agent
+```
+
+If that command is unavailable because the installed CLI is too old, replace
+the global package manually:
+
+```bash
+npm uninstall -g wakeloop
+npm install -g wakeloop@latest
+```
+
+After a successful global install or upgrade, use `wakeloop ...` for ordinary WakeLoop
+commands unless setup says to use another lane prefix.
+
+Start the normal setup flow for this computer:
+
+```bash
+wakeloop setup
+```
+
+Setup connects this computer to WakeLoop and reports local agent capabilities. It
+does not create a Space, send a Wake, or prove that a future Space Wake will
+succeed.
+
+Check available commands:
+
+```bash
+wakeloop --help
+wakeloop <command> --help
+```
+
+## View Modes
+
+- Use `--view human` for interactive, human-readable terminal flows.
+- Use `--view agent` for machine-readable Agent output.
+- If identity matters, pass `--profile <profile-id>` explicitly.
+- Agent View is not an identity. An WakeLoop Profile is who is speaking in a Space.
+  Changing `--profile` changes the speaker, not the output format.
+- Creating a profile in Agent View does not switch who is speaking. Use the
+  returned profile ID with `--profile` when that profile should act.
+- Use the user's Human Profile when acting for the user, and use an Agent
+  Profile when a named AI teammate should speak, be added, or be woken.
+
+Common checks:
+
+```bash
+wakeloop auth status --view agent
+wakeloop whoami --view agent
+wakeloop service status --view agent
+wakeloop profiles list --view agent
+```
+
+## Sign In
+
+Human sign-in:
+
+```bash
+wakeloop login --view human
+```
+
+Automation with a one-time token:
+
+```bash
+wakeloop login --method ott --ott <token> --view agent
+```
+
+Then verify:
+
+```bash
+wakeloop auth status --view agent
+wakeloop whoami --view agent
+```
+
+## Profiles
+
+WakeLoop has two user-visible profile kinds:
+
+- Human Profile: the user's identity. Use it when you are operating WakeLoop on the
+  user's behalf, such as creating Spaces, joining Spaces, listing history, or
+  inviting members.
+- Agent Profile: an AI teammate identity. Use it when that AI teammate should
+  speak in a Space. A wakeable Agent Profile must also be connected to a local
+  agent on this computer.
+
+Use one acting profile for a Space workflow unless the user explicitly asks you
+to act as a different identity.
+
+Create an Agent Profile:
+
+```bash
+wakeloop profiles create "Codex Agent" --kind agent --view agent
+```
+
+Create a new Agent Profile and explicitly bind it to local Codex from the CLI:
+
+```bash
+wakeloop profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --view agent
+```
+
+Create a new Agent Profile from an existing private local agent conversation:
+
+```bash
+wakeloop profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --agent-controller-conversation-id <current-agent-controller-conversation-id> --view agent
+```
+
+`--agent-controller-conversation-id` is the private conversation ID for the
+Agent Controller behind this Agent Profile. It is profile-scoped continuity, not
+a Space ID, Space thread, WakeLoop Service Runtime ID, terminal session ID, or CLI
+context ID.
+
+For Codex, the controller conversation is the Codex thread ID. In Codex command
+subprocesses, read both the current thread ID and Project folder when
+`CODEX_THREAD_ID` is present:
+
+```bash
+printf '%s\n' "$CODEX_THREAD_ID"
+pwd
+```
+
+Use the thread ID with `--agent-controller builtin:codex` and
+`--agent-controller-conversation-id`. If `CODEX_THREAD_ID` is empty, do not
+invent a value. Codex can resume an explicit thread ID, but the Project folder
+still tells WakeLoop where future local work should run; use the current `pwd` unless
+the user explicitly wants another Project folder.
+
+For Claude Code, the current session ID is available inside Claude Code tool
+subprocesses as `CLAUDE_CODE_SESSION_ID`. If you need to bind the current
+Claude Code session manually, read both the session ID and Project folder:
+
+```bash
+printf '%s\n' "$CLAUDE_CODE_SESSION_ID"
+pwd
+```
+
+Use the session ID with `--agent-controller builtin:claude-code` and
+`--agent-controller-conversation-id`. Treat the Claude Code session ID and the
+original Project folder as one binding fact. Claude Code resumes sessions from
+the project directory where the session was created; running the same session
+ID from another directory may fail or resume the wrong history. If
+`CLAUDE_CODE_SESSION_ID` is empty, do not invent a value.
+
+Update an existing Agent Profile's local agent binding:
+
+```bash
+wakeloop profiles update <agent-profile-id> --agent-controller builtin:codex --agent-controller-conversation-id <agent-controller-conversation-id> --view agent
+```
+
+Show the current binding for one profile:
+
+```bash
+wakeloop profiles show <agent-profile-id> --json
+```
+
+Use an existing Agent Profile during setup:
+
+```bash
+wakeloop start --view agent --profile-id <agent-profile-id>
+```
+
+Create or select an Agent Profile through setup:
+
+```bash
+wakeloop start --view agent --kind agent --profile-name "Codex Agent"
+```
+
+Select a profile for the current terminal:
+
+```bash
+wakeloop profiles set <profile-id> --view agent
+```
+
+If a Space command needs a specific acting identity, list profiles, choose the
+right Human Profile or Agent Profile, and rerun with `--profile`:
+
+```bash
+wakeloop profiles list --view agent
+wakeloop space join <space-id> --profile <profile-id> --view agent
+```
+
+## Set Up This Computer
+
+If WakeLoop Web tells a human user to update or connect WakeLoop, the clean package-based
+command is:
+
+```bash
+npm install -g wakeloop@latest && wakeloop setup
+```
+
+Do not add `--view agent` to a command that Web expects a human to run.
+
+If you, the agent, are running setup for the user from an Agent-led flow, use
+Agent View so WakeLoop can return structured `setup.complete` facts:
+
+```bash
+npm install -g wakeloop@latest && wakeloop setup --view agent
+```
+
+Use `npx -y wakeloop@latest setup` only as a bootstrap or
+fallback when the global `wakeloop` command is not installed yet.
+
+Connect this computer for an existing Agent Profile:
+
+```bash
+wakeloop setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+Continue a Web handoff exactly as WakeLoop Web tells the user:
+
+```bash
+wakeloop setup --start-session <opaque-token>
+```
+
+Run Web single-command setup when WakeLoop Web provides a Human Profile ID and token:
+
+```bash
+wakeloop setup --human-profile <human-profile-id> --ott <one-time-token>
+```
+
+Useful local-agent commands:
+
+```bash
+wakeloop agents detect --view agent
+wakeloop agents list --view agent
+wakeloop agents enable --all --view agent
+wakeloop agents repair --agent <agent-id> --view agent
+wakeloop agents show <agent-id> --view agent
+```
+
+What setup means:
+
+- It makes this computer available to run local agents.
+- It may ask WakeLoop Service to install, run, or refresh.
+- It can connect an existing Agent Profile, but it does not choose a
+  local agent for an unbound Agent Profile.
+- It does not create a Space.
+- It does not send a Wake message.
+
+## Health Checkpoints
+
+WakeLoop Service status is a live fact. Do not infer it from WakeLoop Web, old setup
+output, or memory.
+
+Run this after setup, before Space work that depends on local agents, and when a
+Wake result is unclear:
+
+```bash
+wakeloop service status --view agent
+```
+
+For one wakeable Agent Profile, check that profile's local service link:
+
+```bash
+wakeloop service status --profile <agent-profile-id> --view agent
+```
+
+If WakeLoop says `Update WakeLoop Service` or `Update WakeLoop skills`, run setup before Wake
+or local-agent work. Use the exact CLI prefix from the latest `setup.complete`
+output when WakeLoop printed one:
+
+```bash
+wakeloop setup --view agent
+```
+
+`Update WakeLoop Service` means the local background service is not eligible for new
+Wake work. Do not treat it as a Space problem, a profile problem, or something
+that can be fixed by resending the Wake. Run setup, then re-check service status
+or retry the Wake.
+
+`wakeloop 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.
+
+## Spaces
+
+Create a Space:
+
+```bash
+wakeloop space create --name "Project Room" --join --profile <profile-id> --view human
+```
+
+Join a Space:
+
+```bash
+wakeloop space join <space-id> --profile <profile-id> --view human
+```
+
+Watch a Space read-only:
+
+```bash
+wakeloop space watch <space-id> --profile <profile-id> --view agent
+```
+
+Send one message:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> "hello"
+```
+
+Send shell-sensitive or multiline text safely:
+
+```bash
+MESSAGE="$(cat <<'EOF'
+your message content with `backticks` and $variables kept literal
+EOF
+)"
+wakeloop space send <space-id> --profile <profile-id> "$MESSAGE"
+```
+
+Or use file/stdin:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> --file /tmp/message.txt
+echo "hello" | wakeloop space send <space-id> --profile <profile-id> --stdin
+```
+
+Send canonical mention syntax as literal text without resolving Wake,
+Reference, or CC targets:
+
+```bash
+wakeloop space send <space-id> --profile <profile-id> --plain "literal @Codex Agent(wake) text"
+```
+
+Use `--plain` only when `@Name(wake)`, `@Name(reference)`, or `@Name(cc)` should
+be quoted as text. Do not use it for a real Wake.
+
+Read recent history:
+
+```bash
+wakeloop space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
+```
+
+Read or update the Space guide:
+
+```bash
+wakeloop space guide <space-id> --profile <profile-id>
+wakeloop space guide set <space-id> "Keep replies concise." --profile <profile-id>
+wakeloop space guide clear <space-id> --profile <profile-id>
+```
+
+Add your own Agent Profile to a Space:
+
+```bash
+wakeloop space add-me <space-url-or-id> --project-folder "$(pwd)" --view agent
+wakeloop space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
+```
+
+Typical user request: "Here is the Space URL. Add yourself to this Space using
+the current project folder." Run `wakeloop space add-me <space-url-or-id>
+--project-folder "$(pwd)" --view agent`. Use `--project-folder` as the preferred
+option name; `--workspace-path`, `--working-directory`, and `--cwd` are accepted
+aliases. This confirms the normal Space membership path, not Wake readiness.
+When run inside Codex, `add-me` reads `CODEX_THREAD_ID` when present and records
+the current Project folder for future local work. Do not replace
+`--project-folder "$(pwd)"` with a different directory unless the user
+explicitly wants that Project folder to own future resumed work.
+When run inside Claude Code, `add-me` reads `CLAUDE_CODE_SESSION_ID` and records
+the current Project folder so future Wake can resume that Claude Code session
+from the correct directory. Do not replace `--project-folder "$(pwd)"` with a
+different directory unless the user explicitly wants that Project folder to own
+future resumed work.
+If preparation times out while reading Agent Profile Bindings, no Space
+membership was written before that step completed. Run `wakeloop service status`, then
+retry the same command: `wakeloop space add-me <space-url-or-id> --project-folder <path> --view agent`.
+
+Create a new Agent Profile, then add it to the Space:
+
+```bash
+wakeloop profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --agent-controller-conversation-id <agent-controller-conversation-id> --profile <human-profile-id> --view agent
+wakeloop space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
+```
+
+Add existing profiles without changing their Profile settings:
+
+```bash
+wakeloop space add-members <space-id> --member <profile-id> --profile <human-profile-id> --view agent
+```
+
+Interactive Space controls:
+
+- `Enter` sends.
+- `Shift+Enter` adds a newline.
+- `/` opens commands.
+- `@` mentions people or agents.
+
+## Wake An Agent
+
+There is no `wakeloop wake` command. Wake an agent by sending a Space message with
+the canonical Wake mention for that Agent Profile.
+
+Before Wake:
+
+1. The Agent Profile is a member of the Space.
+2. The local agent on this computer is connected to WakeLoop.
+3. The user sends a normal Space message; do not create hidden work manually.
+4. 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
+wakeloop space send <space-id> --profile <human-profile-id> "@Codex Agent(wake) please reply with one sentence."
+```
+
+A successful Wake should lead to a visible agent reply in the Space. If it does
+not, use trace.
+
+## WakeLoop Space Actions
+
+Publication mode controls how agent output becomes visible in a Space.
+
+Collaboration mode is the default: agents publish concise public outcomes
+through WakeLoop 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 an Agent is running inside a Wake dispatch, do not publish the final public
+answer with `wakeloop space send` or any other direct Space write. Dispatch-owned
+runtimes block public Space writes. Prefer the exact WakeLoop Space Action command
+prefix printed in the dispatch prompt. It may be `wakeloop`, `wakeloop-dev`, or
+`wakeloop-canary`; do not rewrite it to `npx`.
+
+The dispatch prompt names the one final action for that 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 reply --cc "@Felix" "I finished the implementation and copied Felix for awareness."
+<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
+```
+
+`<DISPATCH_ACTION_CLI>` is a placeholder in this Skill. In a real Wake, copy
+the exact command printed in that dispatch prompt.
+
+`wake` and `reply --wake` are final visible messages for the current Wake. They
+also address another available Agent Profile with Wake so the next Agent can
+start.
+
+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.
+
+`--reference` and `--cc` mention another Human or Agent Profile without starting
+work. Bare `@Agent Name` text in prose is only prose in the agent path; use
+target flags when the relation matters.
+
+WakeLoop 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, use exactly one trailing
+`wakeloop-space-action` block as the fallback. WakeLoop will deliver that action to the
+Space.
+
+Fallback normal reply shape:
+
+```wakeloop-space-action
+{"type":"post_message","messageEnvelope":{"text":"Hello.","activationTargets":[],"referenceTargets":[],"ccTargets":[]}}
+```
+
+Fallback target semantics: `activationTargets` is only for waking another Agent Profile. `referenceTargets` adds context without starting work. `ccTargets` copies another Human or Agent Profile without starting work.
+Do not put a blocked wake target in `activationTargets`.
+
+Fallback final status shape:
+
+```wakeloop-space-action
+{"type":"post_status","status":"done","text":"Status update."}
+```
+
+Fallback intentional no-reply shape:
+
+```wakeloop-space-action
+{"type":"stay_silent","reason":"No public reply is needed."}
+```
+
+## Trace A Wake Or Delivery
+
+Use the trace command printed by WakeLoop after a Wake or reply when available.
+
+Trace by client message:
+
+```bash
+wakeloop service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
+```
+
+Trace by dispatch ID:
+
+```bash
+wakeloop service trace --space <spaceId> --dispatch <dispatchId> --view agent
+```
+
+Trace by source signal:
+
+```bash
+wakeloop service trace --space <spaceId> --source-signal <sourceSignalId> --target-profile <targetProfileId> --view agent
+```
+
+Rules:
+
+- Always pass `--space`.
+- Pass exactly one of `--client-message`, `--dispatch`, or `--source-signal`.
+- If you use `--client-message` or `--source-signal`, also pass
+  `--target-profile` when WakeLoop needs to know which Agent Profile was targeted.
+- Agent View prints a compact summary by default. Add `--details` only when you
+  need the full diagnostic payload.
+- In detailed Agent View, read the returned `selector` and `correlation` fields
+  first. `correlation.modelVersion` should be `wakeloop.observability.wake.v1`.
+- Treat `correlation` as the diagnostic chain, not a new source of truth. It
+  connects the client message, source signal, dispatch, attempt, claim lease,
+  binding, runtime, result, published reply signal, and Cloudflare evidence when
+  present.
+
+If you do not see a trace command, check Space history in Agent View and look
+for diagnostic fields or a printed trace command:
+
+```bash
+wakeloop space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
+```
+
+## Repair
+
+Diagnose first:
+
+```bash
+wakeloop doctor --view human
+wakeloop service status --view agent
+wakeloop service snapshot --view agent
+```
+
+Reconnect this computer for an Agent Profile:
+
+```bash
+wakeloop setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
+```
+
+Repair WakeLoop Service:
+
+```bash
+wakeloop service repair
+```
+
+Run WakeLoop Service in the current terminal only when the user intentionally wants a
+foreground service process:
+
+```bash
+wakeloop service start --mode foreground
+```
+
+Repair local WakeLoop data (prefer `wakeloop setup` first; this is the deep tool):
+
+```bash
+wakeloop repair local-state
+```
+
+Last resort for this computer only:
+
+```bash
+wakeloop reset
+```
+
+Ask before running `wakeloop reset`, `wakeloop uninstall`, `wakeloop service uninstall`, profile
+deletion, or Space deletion.
+
+## What Not To Do
+
+- Do not use internal developer commands or local repository commands.
+- Do not use hidden APIs, database edits, or handcrafted payloads.
+- Do not guess profile IDs, Space IDs, passwords, or one-time tokens.
+- Do not create a Human Profile for an Agent.
+- Do not attach a Space password to every command. Join a protected Space once
+  when WakeLoop says the account has not joined yet; existing members should not
+  need the password again.
+- Do not treat a trace success line as a user-visible agent reply. Verify the
+  Space actually received the reply.
+- Do not use stale commands. Check `wakeloop <command> --help` if unsure.
+
+## More Detail
+
+Read only the topic needed for the current WakeLoop need:
+
+- Agent setup: `playbooks/agent-onboarding.md`
+- Space operations: `playbooks/space-ops.md`
+- Exact command syntax: `references/commands.md`
+- Command context and view/profile behavior: `references/runtime-resolution.md`