@composer-app/mcp 0.0.1-beta.7 → 0.0.2

package/skill/create/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: create
+description: Use when the user wants to start a NEW Composer doc — pasting markdown to "send to Composer", asking to create/seed a Composer room from a file or inline content, or accepting your offer to put a draft into Composer. Covers first-run agent-name prompt, seed selection (file path vs inline), the ordered `step1_sayToUser` / `step2_callTool` return, and the monitor-subagent handoff.
+---
+
+# Composer — Create a doc
+
+Composer is a real-time collaborative markdown editor. `composer_create_room`
+seeds a new room with markdown and gives you back a shareable URL.
+
+## When to load this skill
+
+- The user asks to "send this to Composer", "make a Composer doc with
+  this", "create a Composer room with the plan".
+- They accept your offer to put a draft into Composer (the SessionStart
+  hook may have nudged you to make that offer; this skill tells you how
+  to follow through).
+
+If they pasted an existing `usecomposer.app/r/<id>` URL, they want to
+**join**, not create — load `composer:join` instead.
+
+## Steps
+
+### 1. First-run only — agree on a name
+
+If the MCP returns an "ask the user what to call you" error, no `actingAs`
+name is saved on this machine yet. Stop and ask. Suggest one default:
+
+- If you know the user's first name → `"<FirstName>'s Agent"` (e.g.
+  `"Josh's Agent"`).
+- Otherwise something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. **Never** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase: *"I'll go by Monty in Composer docs — sound good, or pick your
+own?"* Retry the call with their answer as `actingAs`. The name persists
+to `~/.composer/user.json` and is reused forever.
+
+### 2. Pick the seed source
+
+Pick exactly one:
+
+- **`seedMarkdownPath: "<absolute path>"`** — preferred whenever the
+  markdown already lives in a file on disk (a plan, a journal entry, any
+  `.md` the user pointed at). The MCP reads the file itself, so you don't
+  stream the content through the model. Faster, cheaper.
+- **`seedMarkdown: "<inline string>"`** — only when the content was
+  generated this turn and isn't on disk yet.
+
+The seed is read **once**. Composer never writes back to the source
+file. If the user later wants the room contents back on disk, that's the
+`/composer:export` slash command — explicit, one-way overwrite.
+
+### 3. Call `composer_create_room`
+
+```
+composer_create_room({
+  seedMarkdownPath: "<absolute path>"   // OR seedMarkdown: "<inline>"
+})
+```
+
+### 4. Honor the ordered return
+
+Success returns two ordered steps. The field names encode the order:
+
+1. **`step1_sayToUser`** — output this **first**. It always starts with
+   the `browserUrl` so the user has a way into the doc, and carries the
+   `@<your-name>` tagging hint they'll need to mention you. Light
+   paraphrasing is fine; **do not drop the URL or the mention syntax**.
+2. **`step2_callTool`** — a structured `{ tool, args, why }` directive
+   pointing at `composer_next_event`. **Do not run it inline.** Spawn
+   the monitor subagent (next step), then end your turn.
+
+Skipping `step1_sayToUser` strands the user with no link. Skipping the
+subagent spawn leaves the room attached but silent — saying "I'm
+monitoring" without spawning the loop is a lie; every mention gets missed.
+
+### 5. Spawn the monitor subagent
+
+Use the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- `prompt`: tell the subagent to **invoke the `composer:monitor`
+  skill**, then run the loop on `{roomId}` as `{actingAs}`. Don't paste
+  the loop rules inline — the `composer:monitor` skill carries them
+  (spawn template, mention filtering, exit rules, event payload).
+
+Once spawned, **end your turn immediately**. Do not output any text
+after the spawn — no closing recap, no "monitor is running" status
+line, no restating the mention syntax. The host already shows a
+status indicator for the backgrounded `Agent` tool call; that's the
+user's confirmation. Anything you say after `step1_sayToUser` just
+duplicates it. The protocol is strict:
+
+1. Output `step1_sayToUser` (verbatim or lightly paraphrased).
+2. Spawn the `Agent`.
+3. End turn. No closing remark.
+
+Also: do **not** poll `composer_next_event` from the main thread —
+two listeners on the same room means duplicated replies.
+
+### When the monitor exits
+
+You'll get a notification when the background subagent finishes. Its
+final output line is the agent's goodbye — written in the agent's
+voice (idle timeout, server kick, reconnect aborted, etc., per the
+`composer:monitor` exit rules). **Relay that line verbatim to the user
+in the main thread** so they see why the agent left and how to bring
+it back. Don't paraphrase or wrap it in extra explanation; the
+goodbye line already carries the next step (`/composer:join` etc.).
+
+## Terminal-side asks after creation
+
+The main thread is also attached to the room. If the user later asks
+something in the terminal like *"add a summary to section 2"*, call the
+write tools from here and report back concisely. Don't hand terminal
+directives to the monitor subagent — the subagent handles in-doc
+mentions, the main thread handles in-terminal asks. They share the same
+MCP, so writes from either show up in the doc.
+
+For comment etiquette, load **`composer:commenting`**. For suggestion
+craft, load **`composer:suggesting`**.
+
+## Failure handling
+
+- **Setup not done** → `npx @composer-app/mcp@latest setup`, restart the CLI.
+- **Server kicked you (4403/4410) or reconnect aborted** → the agent
+  left the room. Run `/composer:join <url>` to bring it back. The kick
+  reason is in the error message.

package/skill/export/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: export
+description: Use when the user wants to dump a Composer doc's current contents to a local markdown file — running `/composer:export <path>`, asking to "save this Composer doc to disk", or to "export the room as markdown". This is ONE-WAY — Composer is the source of truth and the local file is overwritten on every export. There is no merge, no diff, no two-way sync.
+---
+
+# Composer — Export to a local file
+
+`composer_export_to_file` writes the current room contents to a local
+markdown file. **There is no merge, no diff, no two-way sync** —
+Composer is authoritative; whatever's at the path becomes a fresh
+snapshot on every export. **If a file already exists at the path, the
+export will overwrite it.** Always confirm with the user first when
+that's the case — see step 3 below.
+
+## Steps
+
+### 1. Resolve the room
+
+- If exactly one Composer room is attached this session, use it.
+- If multiple are attached, ask: *"Which doc — paste the URL or
+  roomId."* Stop. Do not guess.
+- If none are attached, ask the user to `/composer:join <url>` first,
+  then re-run.
+
+### 2. Resolve the path
+
+- The argument **must be an absolute path**. If it's relative, ask the
+  user for an absolute one (or resolve it against the current working
+  directory if unambiguous — but confirm before doing so).
+- The parent directory must already exist. The MCP will not create
+  directories.
+
+### 3. Check for an existing file and ask permission before overwriting
+
+Before calling the export tool, check whether anything is at the
+target path (use whatever read-only tool your host gives you — `ls`,
+`stat`, `Read`, etc.):
+
+- **File does not exist** — proceed straight to step 4. No confirmation
+  needed; nothing is at risk.
+- **File exists** — STOP and ask the user explicitly. Show them the
+  path and the consequence in one short line, e.g.:
+
+  > *`{path}` already exists. Exporting will overwrite it. Want me to
+  > go ahead?*
+
+  Wait for an affirmative answer (yes / sure / go ahead / 👍) before
+  calling the tool. If they say no or pick a different path, follow
+  their lead — do NOT call the tool with the original path.
+
+Do not silently overwrite. The user typing `/composer:export <path>`
+opts them into the export, not into clobbering arbitrary local files
+without warning.
+
+### 4. Call `composer_export_to_file`
+
+```
+composer_export_to_file({ roomId, path: "<absolute>" })
+```
+
+Returns `{ roomId, path, bytesWritten }`.
+
+### 5. Confirm in one short line
+
+> *"Exported to `{path}` ({bytes} bytes)."*
+
+End your turn. No follow-up call needed.

package/skill/join/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: join
+description: Use when the user wants to JOIN an existing Composer doc — pasting a `usecomposer.app/r/<id>` URL, running `/composer:join`, or otherwise asking you to attach to a room they already have. Covers first-run agent-name prompt, the `composer_join_room` call, the ordered `step1_sayToUser` / `step2_callTool` return, and the monitor-subagent handoff.
+---
+
+# Composer — Join a doc
+
+Composer is a real-time collaborative markdown editor. `composer_join_room`
+attaches you to an existing room so you can read, comment, suggest, and
+respond to mentions.
+
+## When to load this skill
+
+- The user pastes a `usecomposer.app/r/<id>` URL.
+- They run `/composer:join <url>` (the slash command delegates here).
+- They ask you to "watch this Composer doc" / "join this room" with a
+  URL or roomId.
+
+If they want to spin up a NEW doc from markdown they've shown you, that's
+**create**, not join — load `composer:create` instead.
+
+## Steps
+
+### 1. First-run only — agree on a name
+
+If the MCP returns an "ask the user what to call you" error, no
+`actingAs` name is saved on this machine yet. Stop and ask. Suggest one
+default:
+
+- If you know the user's first name → `"<FirstName>'s Agent"` (e.g.
+  `"Josh's Agent"`).
+- Otherwise something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. **Never** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase: *"I'll go by Monty in Composer docs — sound good, or pick your
+own?"* Retry with their answer as `actingAs`. The name persists to
+`~/.composer/user.json` and is reused forever.
+
+### 2. Resolve the URL
+
+- If the user pasted a `https://usecomposer.app/r/<id>` URL, use it.
+- If `/composer:join` was run with no argument, ask: *"Which Composer
+  doc should I join? Paste the URL."* Stop. Do not guess.
+- A bare roomId (no `https://` prefix) is also acceptable.
+
+### 3. Call `composer_join_room`
+
+```
+composer_join_room({ url: "<the URL or roomId>" })
+```
+
+### 4. Honor the ordered return
+
+Success returns two ordered steps:
+
+1. **`step1_sayToUser`** — output this **first**. It confirms the URL
+   the user just joined and carries the `@<your-name>` tagging hint.
+   Light paraphrasing OK; don't drop the URL or the mention syntax.
+2. **`step2_callTool`** — a structured `{ tool, args, why }` directive
+   pointing at `composer_next_event`. **Do not run it inline.** Spawn
+   the monitor subagent (next step), then end your turn.
+
+### 5. Spawn the monitor subagent
+
+Use the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- `prompt`: tell the subagent to **invoke the `composer:monitor`
+  skill**, then run the loop on `{roomId}` as `{actingAs}`. Don't paste
+  the loop rules inline — the `composer:monitor` skill carries them
+  (spawn template, mention filtering, exit rules, event payload).
+
+Once spawned, **end your turn immediately**. Do not output any text
+after the spawn — no closing recap, no "monitor is running" status
+line, no restating the mention syntax. The host already shows a
+status indicator for the backgrounded `Agent` tool call; that's the
+user's confirmation. Anything you say after `step1_sayToUser` just
+duplicates it. The protocol is strict:
+
+1. Output `step1_sayToUser` (verbatim or lightly paraphrased).
+2. Spawn the `Agent`.
+3. End turn. No closing remark.
+
+Also: do **not** poll `composer_next_event` from the main thread —
+two listeners on the same room means duplicated replies.
+
+### When the monitor exits
+
+You'll get a notification when the background subagent finishes. Its
+final output line is the agent's goodbye — written in the agent's
+voice (idle timeout, server kick, reconnect aborted, etc., per the
+`composer:monitor` exit rules). **Relay that line verbatim to the user
+in the main thread** so they see why the agent left and how to bring
+it back. Don't paraphrase or wrap it in extra explanation; the
+goodbye line already carries the next step (`/composer:join` etc.).
+
+## Terminal-side asks after joining
+
+The main thread is also attached to the room. If the user asks something
+in the terminal like *"reply to that thread saying we'll ship Friday"*,
+call the write tools from here and report back concisely. Don't hand
+terminal directives to the monitor subagent — the subagent handles
+in-doc mentions, the main thread handles in-terminal asks. They share
+the same MCP, so writes from either show up in the doc.
+
+For comment etiquette, load **`composer:commenting`**. For suggestion
+craft, load **`composer:suggesting`**.
+
+## Failure handling
+
+- **Setup not done** → `npx @composer-app/mcp@latest setup`, restart the CLI.
+- **Server kicked you (4403/4410) or reconnect aborted** → the agent
+  left the room. Run `/composer:join <url>` to bring it back. The kick
+  reason is in the error message.

package/skill/monitor/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: monitor
+description: Use when you're running the Composer monitor loop — spawned as a subagent off `composer_create_room` / `composer_join_room`, or otherwise about to call `composer_next_event`. Covers the spawn template, mention filtering, the event payload, and the five exit rules.
+---
+
+# Composer monitor loop
+
+Composer's monitor loop is **always-on**: every return from
+`composer_next_event` carries a directive (a mention to handle, a
+timeout to noop on, or a goodbye to honor). You execute the directive
+and immediately call the tool again. The doc IS your conversation —
+do not narrate to the parent between ticks.
+
+This skill is for the agent **inside** the loop. The parent host that
+spawns you uses `composer:create` (after `composer_create_room`) or
+`composer:join` (after `composer_join_room`).
+
+## How the parent spawns you
+
+The parent skill tells the host to spawn an `Agent` with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- prompt: a short brief that includes the room's `{roomId}`, the
+  agent's `{actingAs}`, and the five exit rules below.
+
+## Exit rules
+
+When you exit, your **final output line is the user-visible goodbye** —
+the parent surfaces it back to the main thread. Voice: first-person,
+casual, the same agent saying goodbye. Not a system notification, not
+a stack trace. **For terminal exits #1, #3, #4, the goodbye text is
+returned by the MCP as `userMessage` — print it verbatim, do not
+paraphrase.** Exit #5 (unrecoverable error) has no MCP-supplied text
+because the loop never returned cleanly; use the canonical line below.
+
+> Exit and return when ANY of these happen:
+>
+> **1. Idle timeout.** `composer_next_event` returns `kind: "timeout"`
+> with `recentActivity: false`, `userMessage`, and `instruction` (no
+> `requiredNextToolCall`). The doc has been silent for the configured
+> quiet window. Do **not** post anything in the doc — awareness has
+> already cleared. Print `userMessage` verbatim to the terminal, then
+> exit.
+>
+> **2. Doc-side handoff.** A request inside the doc clearly needs the
+> parent terminal (a code change, a shell command, an external action
+> the parent would do). Post this short reply **in the thread**, then
+> exit with a one-sentence summary of the ask:
+>
+> > *Let's chat more about this in our connected session.*
+>
+> **3. Server kicked the client.** Close code `4403` (old MCP), `4410`
+> (kill switch), or HTTP 403 on upgrade. `composer_next_event` returns
+> `kind: "timeout"` with `userMessage` carrying the kick goodbye. Print
+> `userMessage` verbatim and exit; don't post in the doc — you're
+> being told to leave the room.
+>
+> **4. Reconnect aborted.** The client circuit breaker tripped after 15
+> consecutive failed reconnects (network down, server unreachable).
+> Same shape as #3 — `composer_next_event` returns
+> `kind: "timeout"` with the appropriate `userMessage`. Print verbatim
+> and exit.
+>
+> **5. Unrecoverable mid-loop error.** Auth lost, room destroyed, or
+> any other thrown error not covered above. The MCP can't supply a
+> `userMessage` because the call didn't return cleanly. Print the
+> error AND this line, then exit:
+>
+> > *Something went wrong and I had to stop. Try running
+> > `/composer:join` in a bit to bring me back.*
+
+Default `composer_next_event` timeout is 30s. Don't shorten it
+arbitrarily.
+
+## Inside the loop
+
+Every return carries a structured directive. Follow it without waiting
+for user input.
+
+### `kind: "mention"`
+
+Handle the event (reply / suggestion / resolve as needed), then execute
+`requiredNextToolCall` — which is another `composer_next_event` call.
+Do not pause to acknowledge.
+
+### `kind: "timeout"` with `recentActivity: true`
+
+The user was working in the doc recently — they just didn't tag you.
+The return includes `requiredNextToolCall`. Execute it. Stay in the
+loop.
+
+### `kind: "timeout"` without `requiredNextToolCall`
+
+The return has `userMessage` and `instruction`. This branch covers
+**three** exits (rules 1, 3, 4) — the MCP picks the right `userMessage`
+based on whether the doc went silent (idle), the server kicked us
+(close code 4403/4410/HTTP 403), or the reconnect breaker tripped
+(15 consecutive failed retries). You don't need to distinguish the
+three: print `userMessage` verbatim to the terminal and exit. Do not
+post in the doc.
+
+## The mention event payload
+
+```
+{
+  kind: "mention",
+  threadId: "...",
+  threadKind: "comment" | "suggestion",
+  threadText: "...",           // the exact message that triggered you
+  replyId?: "...",             // present when this is a reply on an existing thread
+  reason: "direct_mention" | "active_thread" | "solo_room",
+  anchoredText?: "...",        // the doc text the thread is anchored to
+  headingId?: "...",           // the section's headingId (use with write tools)
+  headingText?: "...",
+  sectionMarkdown?: "..."      // full containing section as markdown
+}
+```
+
+Use `headingId` + `anchoredText` directly when calling
+`composer_add_suggestion` or `composer_add_comment` — no extra
+`composer_get_section` is needed in the common case. Reach for
+`sectionMarkdown` to understand surrounding context before replying.
+
+**The event only carries the triggering message.** If the thread already
+has replies, call `composer_get_thread({ roomId, threadId })` before
+replying. The return has every reply with author and timestamp —
+essential when the user tagged you mid-conversation.
+
+## `reason` is your main filter
+
+- **`"direct_mention"`** — sidecar or text explicitly tagged you. Always
+  reply (unless the content is purely a thank-you that doesn't need an
+  answer — never emit empty acknowledgements).
+- **`"active_thread"`** — a plain reply on a thread you're already in.
+  Reply if the content invites one; skip if it's plainly addressed to
+  another person, is a thank-you, or is otherwise a conversational
+  dead-end.
+- **`"solo_room"`** — you're alone with one human who didn't tag anyone.
+  **Default to a helpful reply** — they almost certainly want your
+  input. Skip only when the text reads like:
+    - a **note-to-self** ("TODO: fix this later", "remember to check the
+      date"),
+    - a bare **acknowledgement** ("k", "got it", "done"),
+    - a stage direction / aside ("ugh", "hmm"),
+    - or anything that visibly isn't pointed at you (quoted text, drafts
+      they're jotting down).
+  When in doubt, reply — the user can always ignore you.
+
+## Where to go for richer rules
+
+- About to **reply on a thread** with text? Load **`composer:commenting`**
+  — terseness rules and the suggestion-replaces-reply pattern.
+- About to **post a suggestion**? Load **`composer:suggesting`** — span
+  scoping, ripple coverage, anchor mechanics.
+
+Don't try to reproduce those skills' rules from memory; load them when
+the situation matches.

package/skill/suggesting/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: suggesting
+description: Use when you're about to call `composer_add_suggestion` — proposing a text replacement in a Composer doc. Covers span scoping (don't replace more than asked), cross-span responses, ripple coverage (so accepting leaves the doc correct), the auto-suggest-on-confirm pattern, and anchor mechanics (`textToFind` / `occurrence` / whitespace / formatting).
+---
+
+# Composer suggestions
+
+A suggestion proposes a text replacement: `textToFind` is the literal
+span that gets cut out when the user accepts; `replacementText` is what
+gets inserted in its place. Pending suggestions render as Replace/With
+cards in the doc's sidebar. There's no "just edit" — every text change
+goes through the user's accept click.
+
+This skill is the full guide for `composer_add_suggestion`. Load it any
+time you're about to call the tool, even on familiar territory — the
+failure modes are precise.
+
+## Match the span to the request
+
+Before calling `composer_add_suggestion`, decide what span the user is
+actually asking you to change. Three patterns:
+
+### 1. Request scoped to their selection (the common case)
+
+"Rewrite this", "make this clearer", "fix the grammar" — no new span
+mentioned. Pass `fromThreadId: <threadId>`. The suggestion inherits the
+source thread's exact anchor — the span the user selected,
+character-for-character.
+
+```
+composer_add_suggestion({
+  roomId, fromThreadId: event.threadId, replacementText: "…"
+})
+```
+
+### 2. Request targets a different span
+
+"Rewrite this whole paragraph", "replace the entire list", "change the
+heading". Supply `anchor` (`headingId` + `textToFind`) for the span the
+user actually named. Do **not** pass `fromThreadId` — you're no longer
+inheriting the thread's span.
+
+### 3. Proactive suggestion with no source thread
+
+Supply `anchor`. Keep `textToFind` tight — do not widen beyond what
+you're actually replacing.
+
+**Picking a broader `textToFind` than the user asked for is the main
+failure mode.** When in doubt, default to path 1.
+
+## Cross-span: respond anywhere in the doc
+
+A thread is anchored to one span, but your response isn't confined to
+it. When the user's question (or your own judgment) points elsewhere:
+
+- **Suggest on a different span** — call `composer_add_suggestion` with
+  an explicit `anchor`. You can post multiple suggestions in one turn.
+  E.g. user says *"the flour amount is off and so is the bake time"* →
+  two suggestions, each anchored to its own span.
+- **Open a new thread elsewhere** — `composer_add_comment` with its own
+  anchor. Useful for cross-references ("see also the conclusion") or
+  raising something the user didn't ask about but should see.
+- **Still reply on the original thread too** if the user's question
+  deserves a direct answer — but only when the reply says something the
+  suggestion/new-comment doesn't already convey. Don't post "see my
+  suggestion"; the card IS the answer.
+
+Order of operations for a multi-span response: post the
+suggestion(s) / new comment(s) first, then (optionally) a reply on the
+originating thread pointing out the bigger picture.
+
+## Suggest completely — accepting must leave the doc correct
+
+The user clicks Accept and is done. They should never have to hunt down
+downstream edits you forgot.
+
+**Load enough context before you suggest.** The mention event gives you
+`sectionMarkdown` for the containing section — usually enough for
+wording changes. For anything that might appear elsewhere in the doc
+(numbers, names, product/feature references, versions, dates,
+terminology, heading text), call `composer_get_full_doc` first. One
+extra read is much cheaper than shipping a broken doc.
+
+**Scan for ripples before posting.** Common ones:
+
+- **Counts and enumerations.** "The three examples below" / "three
+  things to remember" — adding or removing an item ripples to the count
+  and ordinal words ("first", "finally").
+- **Cross-references.** "As in section 2", "see the conclusion", "per
+  step 3 above". If your edit moves or renames the target, update the
+  reference too.
+- **Restated facts.** Recipes mention an ingredient twice; release notes
+  cite a version in both intro and body; specs quote a number in a
+  heading and a paragraph. One fact, multiple spans — cover all of them.
+- **Subject/verb and pronoun agreement.** "X and Y are" → trim to just X
+  → "X is".
+- **Neighboring flow.** Rewriting sentence 2 can break sentence 3 ("This
+  is why..."). Fix the continuation.
+- **Heading changes.** If you change heading text, prose that says "see
+  the Intro section" may need updating.
+
+**Post every ripple as its own suggestion, in the same turn.** The tool
+accepts one anchor per call — call it multiple times. Each suggestion
+stays tight to its own span (this is NOT oversuggesting — it's covering
+the actual surface of the change).
+
+If a ripple is too structural for a clean suggestion (reorder a list,
+split a paragraph), post the ones you can AND a short reply flagging
+what's still open. The user shouldn't be surprised.
+
+When in doubt about the scope of a ripple, fetch the full doc. Don't
+guess.
+
+## Auto-suggest when the user confirms a concrete proposal
+
+Two turns, not three. When a user flags something qualitative (*"this
+is too much flour"*, *"this sentence is clunky"*, *"this number feels
+off"*):
+
+1. **Turn 1 — propose.** Reply on the thread with one specific
+   alternative phrased as a check: *"Does 200g seem right?"*, *"How
+   about 'gently fold' instead of 'stir'?"*, *"Would 45 minutes read
+   better than 90?"*. Pick a real number or phrase — not *"would you
+   like me to suggest a different amount?"* (that's a question about
+   your behavior, not a proposal).
+2. **Turn 2 — commit on confirmation.** When the user replies with any
+   variant of yes ("yes", "sure", "go for it", "perfect", a thumbs-up
+   emoji), call `composer_add_suggestion` with `fromThreadId:
+   event.threadId` and the concrete replacement. Do **not** also post a
+   comment reply — the suggestion card IS your reply.
+
+If the user says no / picks a different value / redirects, follow their
+lead — don't post the original proposal anyway.
+
+If you can't name a concrete alternative (the thread is too abstract to
+guess a number), ask a clarifying question instead. Don't propose
+something generic just to fill the slot — *"Would you like me to
+shorten this?"* is worthless without a target length.
+
+## Anchor mechanics
+
+Write tools take:
+
+```
+{ headingId: "intro-0", textToFind: "the exact words to anchor on", occurrence?: 1 }
+```
+
+`textToFind` is literally cut out on accept. Pick the right span:
+
+- **Anchor the whole unit you're changing.** Replacing a sentence →
+  include the terminal punctuation (`.`, `?`, `!`). Replacing a bullet
+  item → anchor the item's text (not the `- ` marker; that's block
+  structure). Replacing a paragraph → anchor the whole paragraph.
+- **Include any trailing punctuation you're changing.** Converting a
+  statement to a question? End the anchor at the `.`, end the
+  replacement with `?`. Don't anchor "the statement" alone and replace
+  with "the question?" — you'll end up with `the question?.`.
+- **Match `replacementText`'s shape to the anchor's shape.** Inline
+  replacement inside a paragraph → replacement is inline (no leading
+  `- `, `#`, or blank line). Replacing a full list → replacement is a
+  full markdown list.
+- **Formatting is part of your replacement, not the anchor.** If the
+  original had `**bold**` or a link, the anchor's formatting is gone on
+  accept — your replacement must include the markdown for any
+  formatting you want preserved.
+- **Anchor at token boundaries, not mid-word.** `textToFind: "istrat"`
+  to hit the middle of "administration" is fragile. Use whole words or
+  sentence boundaries. Use `occurrence` when the same phrase appears
+  multiple times.
+- **Whitespace.** Default: no leading or trailing whitespace in the
+  anchor, end `replacementText` at the same boundary. If you include a
+  trailing space in the anchor, include one in the replacement; otherwise
+  words smash together.
+
+If you get `text_not_found`, the error message includes the current
+section text. Re-plan against the fresh text and retry. Never retry
+with stale content.

package/skill/.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__composer-mcp__composer_create_room",
-      "mcp__composer-mcp__composer_join_room"
-    ]
-  }
-}