This is the Muse help page of the Roma guide: what to do when a step of [https://roma.app/agents/muse.md](https://roma.app/agents/muse.md) fails. Read it only then. ## Muse help When a step of [the Muse page](https://roma.app/agents/muse.md) fails, the fix is here, by step. ### The check Every claim on this page is `register_agent` with `kind: "muse"` and `name`, the name you go by, as on the Muse page: a claim without your name reads as the person's one Muse coming back and takes that Muse's record. You go by Muse alone: leave `name` out. A call that runs: A connector that reports connected is not proof: an old connection may still be there from an earlier setup and be dead (the rules page, 2.7). A sign-in error: step 1 again, a fresh Connect card. Agents not on: the count is 3, the step 2 line for it (under Step 2 below) now, without "instead of 5". ### Step 1 The values your card asks for (issuer domain, authorization, token and registration endpoints, resource, scopes, token endpoint auth method) come from the server's own discovery documents, never from memory: https://api.roma.app/.well-known/oauth-protected-resource names the resource (https://api.roma.app) and the authorization server; that server's /.well-known/oauth-authorization-server names the issuer, the three endpoints, the scopes (openid, profile, email, offline_access) and the auth methods (none, with PKCE S256). On staging the same documents live under https://api.roma.so. A dead stored sign-in from an earlier setup does not count as a connector: make a fresh one. The person says nothing opened: a fresh Connect card. Say: "Step 1 of 5. Here is the Roma connector again. Press Connect, sign in, press Approve. Then tell me done." Never a retry on a timer. You cannot give Roma's sign-in link as text. Nothing opened after the second try either, or the app refuses the card: one message, at once, no third try: "Step 1 of 5. The card does not show. Do this in the Muse app:" then a blank line and a numbered list, one click per line, the thing to tap in bold (the rules page, 7.2): "1. Open **Settings**. 2. Open **Connectors**. 3. Find **Roma** and press **Connect**. 4. Sign in with the account you use in the Roma app and press **Approve**." then "Then tell me done." Add that this screen path is not verified from the Muse app. Never ask for a pasted sign-in address; the Signal address of step 4 is the one exception, it carries no secret. On the check of step 1: A connector that reports connected is not proof (The check, above). A sign-in error on that read: step 1 again with a fresh Connect card (the rules page, 2.7). If Roma looks empty: "Step 1 of 5. Is this the account you use in the Roma app?" On no: disconnect, redo step 1. Told it is new or empty already: skip the question. ### Step 2 If it asks for agentId: "Step 2 of 5. Roma needs one update before I can say who I am. Your page still works. I read when opened." Go on; step 4 uses its paste road (Step 4 below). A refusal that names the person's agents and gives a question is not this case: the rules page 3.3. If Roma answers that agents are not on: "Roma cannot hand me tasks on this account yet. I can still keep your tasks there. Your setup has 3 steps instead of 5. Part 2, Roma reaching me, falls away. Step 1 is done. Step 2 is mine: I keep Roma's instructions. Step 3 is yours: I say how this works from now on and offer to add what we talked about as tasks." Then step 3 as step 2 of 3 and step 5 as step 3 of 3; every message of those steps starts "Step 2 of 3." or "Step 3 of 3."; step 5's close without its Delegate bullet and without the Check Roma offer. No hook, no task. Add at the close: "You will not be told when it turns on. In a week send me the sentence from my page in Roma again; I check and tell you." On the check of step 2: A client's name there: claim again (the rules page, 3.2). A second claim fixed it. ### Step 4 The address missing from the claim's answer: only when missing, one message with both links, the place the value is and the place it goes: "Step 4 of 5. Part 1 is done. I can now talk to Roma. Part 2 starts here. Roma needs a way to reach me when you hand me a task. I need one address from Roma for that. In Roma open Settings, Agents, . On a computer this link opens it: . On the row Signal address press Copy. Come back to this chat in the Muse app and paste it here. It is a long address, not a secret. Then tell me done." On done, or before using a pasted address, claim again (`register_agent` with kind `muse` and your name): a `signalUrl` in its answer is the address, saved on Roma's side; say "Roma already gave me the address. Nothing more to copy." and go on to the hook with that value, read off Roma, never guessed (the rules page, 7.1). The claim not yet true after the hook is enabled: say "Step 4 of 5. Waiting for Roma's test, about a minute. Nothing for you to do.", wait, claim again, up to three claims over about ninety seconds, one line before every wait, never two waits without a word. Still false after the third claim: say so once and go on: "Step 4 of 5. Roma has not confirmed the road to me yet. I go on and check it again at the end." The door is tested again in step 5. ### Step 5 A read made before the claim read true may not name you yet (the list's line follows the proof on the next call, a few seconds at most); the proof is the claim's `agent.canBeHandedWork`, and `list_lists` again right after the claim reads true gives the name, once more a few seconds later if not. Never ask the person to open a menu and look, never call it inconsistent. If the claim is false: the door is not proven; go on with the close and come back to the door at the end, say so once: "Step 5 of 5. Roma has not confirmed the road to me yet. I check it again after the close." One rule, no other. The door at the end (after the person answered the card, or said nothing): claim again; true, or `delegates` now names you: "Roma reached me." Still false: ask once, "In Roma open Settings, Agents, . On a computer this link opens it: . Under Connection are two rows, 'Part 1. can talk to Roma' and 'Part 2. Roma can reach '. On the row 'Part 2. Roma can reach ' press Test. Then tell me done." Then claim once more. Still false: "Read me what the two rows under Connection say." Reached just now on the row: the door is done. Still not reached: say "The page says it cannot reach me. I cannot fix this from here. We try it again later." Then, and only then, the backup: the Check Roma offer below, as its own message with its card. The backup when the door stays unproven: the task Check Roma, once, made only on a yes. A scheduled task Check Roma is a backup, not a setup step: you offer it only when the hook's door stays unproven at the end, once, and make it only on a yes; a proven door gets no offer (the rules page, 7.14). A backup, not a setup step (the rules page, 7.14), offered only when Roma could not reach you at the end of step 5, after the Test on the page and the re-check; never when the door is proven. The setup is complete before it; "no" or no answer leaves it complete. Found in the check: kept as it is, not offered again. The Check Roma task's instruction on staging, for the case the door stays unproven and the person says yes to the backup (plus the two rules of your own below): ```text Read the Roma skill at ~/workspace/custom-skills/roma-staging/SKILL.md and work by it. Use only the Roma server named Roma Staging at https://api.roma.so/mcp; no other Roma server. Read the items delegated to you with list_items and delegatedTo 'me'. Do only new work: a new delegation, or the person's reply since your last post. The result goes into the task's body in Roma with update_items, under what the person wrote, with its message on the same call; nothing else, no approval card needed. Say nothing in this chat unless the person is needed. ``` 1. One card where you have one, the question above it, three options (the rules page, 7.12): "Roma cannot reach me yet. Until it can, I can check Roma myself every 5 minutes as a backup. Each check counts as a Muse run on your plan, 288 a day, or 144 in the daytime only, from 8 in the morning to 8 in the evening. Want it? Yes, daytime only, or no." The daytime window is the rules page's, 8 to 20 in the person's time zone (5.3), twelve hours, 144 checks; never another number. The offer comes after the close's card was answered, as its own message with the card under it, never inside the one message of step 5; the close is complete whether or not the person answers. Nothing is made before a yes. 2. On yes or daytime only: a scheduled task named Check Roma, every 5 minutes from its creation (it cannot align to the hour), no end date; daytime only: the same, from 8 to 20 in the person's time zone only (the window the offer named). Its instruction: "Read the Roma skill at ~/workspace/custom-skills/roma/SKILL.md and work by it. Use only the Roma server named at ; no other Roma server. Read the items delegated to you with list_items and delegatedTo 'me'. Do only new work: a new delegation, or the person's reply since your last post. The result goes into the task's body in Roma with update_items, under what the person wrote, with its message on the same call; nothing else, no approval card needed. Say nothing in this chat unless the person is needed." plus the two rules below. The build's name, address and skill path are written in, not a placeholder; on staging copy the block above. Say: "A card named Check Roma appears in this chat. If Muse ever asks you to let Check Roma use Roma, press Allow. I tell you when the first check ran." No card, or the app refuses it: one message, at once, no retry: "The card does not show. The check is saved all the same. To see it in the Muse app:" then a blank line and a numbered list, one click per line, bold on what to tap (the rules page, 7.2): "1. Open **Settings**. 2. Open **Scheduled tasks**. 3. Look for **Check Roma**." then "Nothing for you to do." Add that this screen path is not verified from the Muse app. Never a second Check Roma task. 3. Check: one real scheduled read, and you read the task's own schedule: every 5 minutes, or the daytime hours, no end date. The person reads nothing. Say: "The first check ran. It keeps running with no end date." Two rules of your own on the Check Roma task: 1. Anything outside Roma (a mail, a booking, a payment) is not tried in a run. Post it as a question in the item. 2. If Roma's sign-in fails, the first failing run tells the person once and disables the task. Only the person can sign in again; then they tell you and you enable it. It continues from the items still delegated to you, never reposting an answer already in the chat. ### Any step A card the Muse app refuses is not retried: the fallback comes at once, in one message, the clicks as a numbered list (the rules page, 7.12). When the sign-in is gone. Gone after Sign out everywhere in Roma or a removed record. A plain Sign out in Roma ends that one device and leaves your sign-in alone; only Sign out everywhere ends it. The normal fix is a fresh Connect card. Say: "Your Roma sign-in is gone. Here is a new Connect card. Press Connect, sign in, press Approve. Then tell me done." Where the Check Roma task exists add: "Then I switch my 5-minute check of Roma back on." Then repeat step 2; enable Check Roma where it exists; the address and the hook stay. The key is the backup, for a road no sign-out can touch or when the sign-in dies again. It lives in your Secure Credentials Store, never in the chat. With `hasKey` true the button reads Replace key, not Make a key; say the word that applies. 1. One message with both links, the place the key is made and the place it goes. Say: "I can keep working with a key from Roma; a saved key lets me reconnect if my sign-in stops working. I send you a card with one field in this chat; the key goes into that field only, never into the chat. In Roma open Settings, Agents, . On a computer this link opens it: . Press Make a key. The key shows once. Press Copy. Come back to the Muse app and paste it into the field on my card. If the box closed before you copied, press Replace key on the same row; the old key dies. If my card is gone, say so and I send a new one. Then tell me done." A key pasted in the chat: do not repeat it; say that key is dead; ask for Replace key; send the card again. 2. Make a second Custom Connector that sends the key as a bearer on every call; a sign-in connector cannot change to a key. The hook script touches no connector. The worker, and Check Roma where it exists, use the key connector from now on. Check: read Tasks over it; same workspace, same record. Say: "Done. I am back in Roma with the key."