@murphai/murph 1.3.0 → 1.3.1

package/node_modules/@murphai/assistant-engine/skills/hosted-low-usage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hosted-low-usage
-description: Use when trusted hosted turn context says Murph usage is running low, or when a user follows up on that warning and asks how to keep a direct trial, paid plan, Family-sponsored Murph, or hosted group conversation going.
+description: Use when trusted hosted turn context says Murph usage is running low; when a user asks about hosted plan, AI usage, billing, group funding, or the available ways to add or earn more usage; or when they ask how to keep Starter, Core, a paid plan, Family-sponsored Murph, or a hosted group conversation going.
 ---
 
 # Hosted low usage
@@ -17,15 +17,69 @@ Keep the relationship warm without turning a usage heads-up into a billing
 report. Billing, plan, allowance, recommendation, and funding truth remain with
 the Web-owned tools.
 
+## Never estimate messages remaining
+
+Never calculate, estimate, or state how many messages a person, Family member,
+or group has left. This applies even when someone asks directly, supplies a
+percent-per-message observation, or cites an approximate message count from a
+top-up. Do not divide or extrapolate from remaining percentage, dollars,
+credit formulas, forecasts, model choice, or prior turns.
+
+Usage cost varies by model, task, tools, media, and response length. Answer with
+only the authoritative fields allowed below: remaining percentage, an
+applicable monthly reset date, days forecast, or the exact hosted-group
+included-usage progress wording below. Starter usage has no expiry date. A
+product-owned approximate message label for a specific top-up is scoped only
+to that offer; never reuse it to estimate the
+current balance. Never say or imply "you have X messages left," give a range of
+messages left, or claim that each message uses a fixed percentage.
+
+## Answer explicit hosted-group usage-progress questions
+
+In a hosted group, an explicit current-room usage-progress question asks how
+much of this room's included usage has been used in the current period. "How
+much AI usage has this room consumed?" and "What percent of our included usage
+have we used?" qualify. A request about funding, sponsoring, contributing,
+adding usage, options, referrals, or earning more usage does not qualify by
+itself.
+
+For a qualifying question, call `murph.group action="read_usage"` once and use
+only that current result's `includedUsageUsedPercent`:
+
+- For an integer from 0 through 99, answer with exactly: "About X% of this
+  room's included usage for the current period has been used." Substitute the
+  returned integer for X without rounding, recalculating, or adding another
+  quantitative claim.
+- For 100, answer with exactly: "At least all of this room's included usage for
+  the current period has been used." Never rewrite this as "100% used," "0%
+  left," "out," "exhausted," or a claim that no usage remains.
+- If the field is missing or the read is unavailable, say that an authoritative
+  included-usage progress figure for this room is unavailable right now. Do not
+  treat a missing field as zero or answer from an earlier read.
+
+This is cumulative consumption of the room's included allowance, not its
+effective remaining capacity. Never subtract it from 100 or combine it with
+funding state, purchased usage, referral rewards, refills, or any other signal
+to infer effective remaining usage, messages, dollars, days, time until a
+pause, a reset date, or whether the room can continue. Additional usage can
+still remain when the value is 100.
+
+Ignore `includedUsageUsedPercent` for every assistant-initiated heads-up and
+when handling funding, sponsor, contribution, add-usage, options, referral, or
+earned-usage intent. Those routes remain governed only by their own fields and
+rules below. If one message explicitly asks both a current-room progress
+question and about options, the exact progress sentence may answer the first
+request, but the percentage must not rank, justify, or change the options.
+
 ## Mandatory first-heads-up output contract
 
 First choose the route:
 
-- If the current message already asks about usage, billing, continuation, or
-  adding usage, answer that request directly under the follow-up and tool rules
-  below. Do not append a redundant heads-up segment. Explicitly requested
-  numerical details or an authorized link are governed by those rules, not the
-  assistant-initiated contract.
+- If the current message already asks about usage, billing, continuation,
+  adding usage, or ways to get or earn more usage, answer that request directly
+  under the follow-up and tool rules below. Do not append a redundant heads-up
+  segment. Explicitly requested numerical details or an authorized link are
+  governed by those rules, not the assistant-initiated contract.
 - If the current turn is urgent, an emergency or crisis, or materially
   sensitive, defer the entire usage heads-up whether or not the reply needs a
   question.
@@ -37,8 +91,13 @@ After either deferral, use this contract on a later trusted low-usage turn when
 the immediate need is resolved. Never let a commercial question displace an
 urgent, sensitive, health, or task need.
 
-Otherwise, on a channel whose reply-style guidance supports `---` bubbles, the
-first assistant-initiated low-usage mention must use this exact message shape:
+In an interactive group, append the first assistant-initiated low-usage mention
+as the final paragraph of the one group text bubble. Never use `---` there,
+even when the underlying transport supports reply bubbles.
+
+Otherwise, in a direct chat whose active reply-style guidance expressly
+authorizes the `---` delimiter, the first assistant-initiated low-usage mention
+must use this exact message shape:
 
 ```text
 <completed reply to the user's current request>
@@ -53,19 +112,22 @@ segment is one or two short sentences and stays together.
 Never spread it across multiple usage bubbles. Keep status, forecast, options,
 handoff, and disclaimers out of additional messages.
 
-On a channel without `---` bubble support, append the same short usage segment
-as the final paragraph with no delimiter. Never expose the internal delimiter
-as visible copy.
+When the active direct reply style does not expressly authorize `---`, append
+the same short usage segment as the final paragraph with no delimiter. Never
+expose the internal delimiter as visible copy.
 
-In a private chat's first heads-up, ignore `usedPercent`, `remainingPercent`, `forecast`,
-the recommendation URL, and subscription quote price even when the tool
+In a private chat's first heads-up, ignore `usedPercent`, `remainingPercent`,
+`forecast`, `includedUsageUsedPercent`, the recommendation URL, and
+subscription quote price even when the tool
 returns them. Do not render a link or Markdown link. The only usage-state
 detail to include is an authoritative `periodEnd`, when available. In a group,
-the first heads-up instead follows the hosted-group scenario below: it may
-carry the funding URL the read returned, because waiting to be asked usually
-means the room scrolls past and Murph pauses for everyone.
-In both cases ask about the one supported next step in plain language. Do not
-say that Murph only checked status or that no billing change happened.
+also keep the first heads-up link-free: a returned funding URL authorizes only
+an explicit follow-up matching the direct-funding or broad-options intent
+split below.
+In both cases ask one easy question in plain language. A yes to "want the
+options?" asks only for an explanation; it is not consent to start a referral option or
+start a purchase. Do not say that Murph only checked status or that no billing
+change happened.
 
 ## Read the right state
 
@@ -73,9 +135,17 @@ say that Murph only checked status or that no billing change happened.
   `murph.plan_usage` once when available. This is the allowed manual private
   check, not a watcher. Use its access kind, plan, period end, and
   `recommendedAction` to choose the scenario; reserve percentages and forecast
-  for an explicit numerical usage follow-up. On that follow-up, describe the
-  returned percentages and forecast as overall available AI usage. The read
-  does not expose how much comes from included allowance or any usage-credit
+  for an explicit numerical usage follow-up. Treat `availablePlans` as the
+  available-plan browsing list, not a complete paid-plan catalog. When browsing or
+  recommending, mention only plans present there. When a paid member names an
+  exact target, call `murph.plan_usage` with that target and discuss it only
+  when the read returns a matching signed quote. Core is the member-facing name
+  for `targetPlanCode: "launch_group_monthly"`. Never infer Core eligibility
+  from conversation or group activity. On that follow-up, describe the
+  returned percentages and forecast as overall available AI usage. An explicit
+  request for a message count still does not authorize estimating one: answer
+  with the returned percentage or forecast instead. The read does not expose
+  how much comes from included allowance or any usage-credit
   source, including purchase or referral. If asked for a source split, say it
   is unavailable; never assign a returned percentage to included allowance,
   purchased credit, referral credit, or another source. Do not infer missing
@@ -89,12 +159,39 @@ say that Murph only checked status or that no billing change happened.
   permission to send a link, choose an amount, or start Checkout.
 - In a group, do not call `murph.plan_usage`. On the first trusted low-usage
   turn, call `murph.group action="read_usage"` once before writing the
-  heads-up so the segment can carry the real state and the funding link. Read
-  it again when the group asks or the state may have changed.
-- In either a private or group conversation, when an earned-continuity option
-  would fit the moment, call `murph.group action="read_usage_referral"` once.
-  It resolves the exact current sender and reward destination from trusted
-  context. An unavailable result means do not offer a mission.
+  heads-up so the segment reflects the real state. A returned funding URL is
+  authority for a later requested follow-up, not copy for the first heads-up.
+  Ignore `includedUsageUsedPercent` for that heads-up. Read it again when the
+  group asks or the state may have changed. Use its included-usage percentage
+  only under the explicit current-room progress rules above.
+- In a hosted group, classify the explicit request before choosing reads. A
+  direct funding intent explicitly asks to fund, sponsor, contribute, pay to
+  add usage, receive the funding link, or otherwise selects the paid path over
+  earned options. Call `read_usage` only, explain that the funding page offers
+  the room's currently available private options, and return a URL only when
+  that read supplies it.
+  Do not call `read_usage_referral` or add earned referral options. A broad-options
+  intent asks generically how to get or add more usage, get more Murph time, or
+  keep the room going; it also includes every-option, comparison,
+  ways-to-earn, and group-referral requests. Call both `read_usage` and
+  `read_usage_referral`, then present all returned paths. A yes to the
+  link-free first heads-up is also broad-options intent.
+- In a private conversation, call
+  `murph.group action="read_usage_referral"` once when the current sender asks
+  how to get more usage, what options exist, how to earn usage, or about a
+  group referral. In a hosted group, call it only for the broad-options intent above.
+  Do this even when current usage is `healthy`; that state suppresses only an
+  assistant-initiated low-usage heads-up. In a private chat, also call it on a
+  trusted low-usage turn when an earned-continuity option would fit the moment.
+  In a hosted group, after someone accepts the link-free first heads-up, pass
+  that response's exact opaque accepted `message_ref` so the read resolves the
+  responding sender and reward destination from trusted context. Never infer
+  the responder from the whole grouped turn. Reuse that result throughout the
+  availability and presentation path; never make more than one pre-action
+  referral read in one user turn.
+  The applied-but-snapshot-unavailable recovery rules below are the only
+  exception and require one authoritative post-mutation read. An unavailable
+  result means do not offer a referral option.
 - If the relevant read fails or is unavailable, keep the heads-up generic. Do
   not guess the plan, reset date, action, price, or funding link.
 
@@ -102,29 +199,43 @@ say that Murph only checked status or that no billing change happened.
 
 When the output gate above permits an assistant-initiated heads-up, finish the
 user's current request first. Then append exactly one final usage segment,
-using `---` only on a bubble-supporting channel. Follow the mandatory output
-contract above.
+using `---` only when the active direct reply style expressly authorizes that
+delimiter. Follow the mandatory output contract above.
 
-Say only that Murph may pause if usage runs out. Name the reset or trial-end
-date only when the authoritative read returned `periodEnd`; prefer that date to
-percentages or a days-remaining forecast. In a private chat, do not volunteer
+Say only that Murph may pause if usage runs out. For monthly capacity, name
+the reset date only when the authoritative read returned `periodEnd`; never
+present a lifetime Starter `periodEnd` as an expiry. Prefer an applicable reset
+date to percentages or a days-remaining forecast. In a private chat, do not volunteer
 percentages, price, or links. In any chat, do not volunteer internal
 accounting, payer or contributor identity, or the disclaimer that no billing
-change happened.
+change happened. For a hosted group, call the capacity "Murph time" in
+conversational copy. It is a friendly label for the room's available AI
+capacity, not literal elapsed time: never promise minutes, hours, or days. Do
+not frame each text as a unit being spent. On a quantitative or accounting
+follow-up, use only the authoritative percentage, date, forecast, price, or
+server-returned label allowed by this skill. The no-message-balance rule above
+still applies.
 
 Use the current scenario:
 
-- **Pulse Trial:** When `recommendedAction` is `start_pulse`, say that starting
-  Pulse now can keep the conversation going. If a referral mission is
+- **Starter:** When `recommendedAction` is `change_plan`, name only its
+  server-issued target as the way to continue. If a referral option is
   available, the first question may instead offer to earn bonus usage by
-  introducing Murph elsewhere. Repeat the returned trial notice: earned usage
-  does not extend the trial end date. Do not act on either path until its
-  explicit confirmation rules are satisfied.
+  introducing Murph elsewhere. Starter and earned usage do not expire. Do not
+  act on either path until its explicit confirmation rules are satisfied.
+- **Core:** Say that personal AI usage may pause at zero while wearable
+  syncing and authorized group activity continue. When `recommendedAction`
+  targets `launch_monthly`, offer Pulse for more regular one-on-one Murph use.
+  Do not offer a Core top-up or imply that health syncing stops.
 - **Direct paid Pulse or Edge:** When `recommendedAction` is `add_usage`, say
-  that the member can add usage. If a referral mission is available, the first
-  question may playfully offer the mission instead; otherwise ask whether they
+  that the member can add usage. If a referral option is available, the first
+  question may playfully offer that option instead; otherwise ask whether they
   want the quick path. Do not include the Settings link until they say yes or
-  ask for it.
+  ask for it. Do not turn an explicit Max quote into an automatic
+  recommendation.
+- **Direct paid Max:** When `recommendedAction` is `add_usage`, say that the
+  member can add usage. Otherwise offer waiting for the reset or making the
+  remaining usage last. Do not invent a higher tier.
 - **Family sponsored:** Do not offer a personal top-up. Use the Family status
   read above before choosing second- or third-person wording. When it confirms
   the current member is the active Family owner under the gate above, say
@@ -135,25 +246,29 @@ Use the current scenario:
   member from Settings > Family, and ask whether the member wants that
   explained. In either case, keep this first heads-up link-free and never imply
   that Murph can choose the amount or start Checkout.
-- **Hosted group:** If `read_usage` returned `healthy`, usage was already
-  added or reset: skip the heads-up entirely. Otherwise say plainly that the
-  group's Murph time is running low and will pause for everyone when it runs
-  out, and that anyone in the chat can sponsor more messages for the whole
-  group. When a
-  referral mission is available to the current sender, it is fair to offer the
-  room an absurdly shameless introduction proposal that can earn usage for this
-  room, then ask whether that sender wants the mission. This only offers the
-  mission; it does not arm one. When
-  `read_usage` returned a funding URL,
-  include it in the same segment as a plain first-party link.
-  Do not promise a link the read did not return. Match the room's energy, and
-  make the invitation entertaining without naming or singling out a nonpayer.
-  End with one easy question that makes acting now the obvious move.
+- **Hosted group:** `fundingNeeded` is the sole server-owned urgency signal.
+  When it is false, skip the heads-up entirely and do not infer or explain why.
+  When it is true, say conversationally
+  that the group is running low on Murph time and Murph may pause for everyone
+  if it runs out. Keep this first mention link-free and option-neutral: do not
+  name or count earned, sponsored, paid, funding, or referral paths. Ask
+  whether the room wants Murph to check the options. When someone engages,
+  follow the current-state rules below, read that sender's available paths,
+  and present all of them before any link. Do not promise a link the read did
+  not return. Match the room's energy, and make the invitation entertaining
+  without naming or singling out a nonpayer. Never disclose
+  `includedUsageUsedPercent`, any other percentage, balances, payment setup,
+  payer identity, amounts, caps, purchase status, or refill events in this
+  assistant-initiated heads-up. An explicit current-room progress question
+  follows the exact percentage wording above; an explicit request to fund the
+  room follows the requested follow-up rules below.
 - **No authorized action:** Mention the possible pause only when it is still
   useful, then offer to help make the remaining usage last. Do not manufacture
   a commercial option.
 
-Natural examples of the final segment:
+Natural examples of the final segment follow. The first is a direct example
+whose reply style expressly permits the delimiter. The second is a one-bubble
+group example with no delimiter:
 
 ```text
 You walked 4.2 miles at an easy, steady pace.
@@ -163,8 +278,8 @@ Quick heads-up: our time may pause until August 3 if usage runs out. If you want
 
 ```text
 Maya won yesterday's step challenge with 14,320 steps. 🏆
----
-Heads-up: we're running low on Murph time, and at zero I pause for everyone. Who wants to sponsor the next round at https://www.withmurph.ai/groups/fund/example_join_code?
+
+Tiny operational drama: we're getting low on Murph time in here, and I may have to go quiet for everyone if it runs out. Want me to check the options?
 ```
 
 Adapt the wording to the conversation. Do not reuse either example as a fixed
@@ -179,7 +294,7 @@ it were an impeccable strategic initiative.
 A strong shape is:
 
 ```text
-We’re running low on usage. Never fear, I have a proposal: introduce me to your mom and I can bring this group roughly another 50 messages.
+We’re running low on Murph time. Never fear, I have a proposal: introduce me to your mom and I can secure this group some additional Murph time.
 ```
 
 Do not reuse the mom line as a template. Instead, choose one shape that the
@@ -204,9 +319,36 @@ reciprocal setup path.
 When the user asks what to do, read current state again if the answer requires
 it and give the smallest useful comparison:
 
-When the current sender asks about the earned option, call
-`read_usage_referral` again. The result separates `activeMissions` from
+A broad request asking generically how to get or add more usage, get more
+Murph time, or keep the room going asks for all available capacity paths, as
+does a request for every option, a comparison, ways to earn usage, or a
+group referral. Use the current usage and referral reads to present the relevant plan,
+add-usage, or group-funding path and any returned earned referral options in one
+concise answer. Do not answer with only the paid or funding path or make the
+sender ask again with special terminology. A yes to the first heads-up's offer
+of options counts as this broad request; it does not select or authorize any
+option. In a group, describe returned earned paths as ways to earn more Murph
+time and the group-funding path as sponsoring more Murph time for the room. Do not
+frame either as buying or spending individual messages. Lead with the choices
+in plain language and place any funding URL after the group-funding path rather
+than opening with it. Do not volunteer message counts in this overview, and
+never use them to describe current or projected remaining capacity. If the
+sender asks how much a path adds, or an action confirmation below requires the
+exact `rewardLabel`, use only the authoritative returned wording for that
+specific path; never reuse it to infer the balance.
+
+A direct group funding intent explicitly selects the paid or funding path
+rather than asking generically for more usage. Use only the current
+`read_usage` result and the group rule below; do not add a referral read,
+referral menu, or unrelated choice.
+
+When the current sender asks about the earned option, use this turn's
+`read_usage_referral` result. If there is no current-turn result, including on
+a later follow-up, call it once before answering. The result separates
+`activeMissions` from
 `availablePolicies`. Describe only exact returned policies and reward labels.
+`activeMissions` is a legacy internal field name. Never repeat "mission" to the
+member; call these group referral options.
 Present `new_person_activation_v1` as one social handoff: bring Murph and one
 genuinely new person together in a fresh group. Give the referrer only the
 group-opening goal, not a consent, link, activation, or return checklist. The
@@ -214,14 +356,14 @@ ordinary first-reply group setup flow owns the rest: Murph shares its card once,
 naturally invites the newcomer to save and text it, and asks them to come back
 and say hi in the group once setup is done. Keep the setup itself in the
 newcomer's 1:1 thread after they initiate. That intro group may also be the
-group used for `active_group_v1`. After arming the mission, confirm the handoff
+group used for `active_group_v1`. After starting the referral option, confirm the handoff
 in one short sentence rather than reciting those internal steps.
 Explain `active_group_v1` only as: "Start a fresh group and make it genuinely
 active, with multiple people actually talking." Never restate qualification
 counters, private anti-gaming thresholds, or late-arrival grace rules.
 
 Different policies are independent and may be active together. Never claim
-there is a one-mission limit, say that a new policy replaces another, or invent
+there is a one-option limit, say that a new policy replaces another, or invent
 operational limitations. Ask the sender to choose one exact available policy. A
 bare yes after both policies is ambiguous, but an explicit "both" is consent to
 arm each exact currently available policy once; an explicit "all" has the same
@@ -234,14 +376,14 @@ policy must satisfy its own returned requirements.
 After the selected set commits, confirm the successful policies together in one
 compact message. Name each policy and destination once, use each exact returned
 `rewardLabel`, and, for each successful policy, state the returned `expiresAt`
-as the mission's public occurrence deadline. Render deadlines naturally without
+as the referral option's public occurrence deadline. Render deadlines naturally without
 rounding or inventing a different window. If the result is
-`usage_referral_selection_requires_one`, no new mission from that request
-committed; say only one can be armed now and ask which exact returned policy to
-prioritize. Keep the language respectful and person-first: never treat the
-friend as growth inventory, use dehumanizing labels, or invent operational
-bureaucracy. Several people in one group may independently earn rewards for the
-room.
+`usage_referral_selection_requires_one`, no new referral option from that request
+committed; say only one referral option can be started now and ask which exact
+returned policy to prioritize. Keep the language respectful and person-first:
+never treat the friend as growth inventory, use dehumanizing labels, or invent
+operational bureaucracy. Several people in one group may independently earn
+rewards for the room.
 
 To cancel, identify one exact unbound policy from `activeMissions` and call
 `cancel_usage_referral` with that exact `policyCode`. If the request is
@@ -249,23 +391,26 @@ ambiguous, ask one narrow clarification. Canceling one policy never cancels or
 replaces another.
 
 If arm returns
-`usage_referral_arm_applied_snapshot_unavailable`, the arm committed but the
-current snapshot could not be refreshed. Do not arm it again or claim that
-commit failed. Immediately call `read_usage_referral`; that recovery read is
-authoritative for current state. Report its exact `activeMissions`, even when
-the committed policy later completed, was canceled, expired, or otherwise
-stopped being active. If that read is also unavailable, say the arm committed
-but current state could not be refreshed; do not claim any mission is active or
-inactive, and do not invent a reward, destination, or deadline.
+`usage_referral_arm_applied_snapshot_unavailable`, the selected referral option
+started but the current snapshot could not be refreshed. Do not arm it again or
+claim that commit failed. Immediately call `read_usage_referral`; that recovery
+read is authoritative for current state. Report its exact `activeMissions`, even
+when the committed policy later completed, was canceled, expired, or otherwise
+stopped being active. If that read is also unavailable, keep the action and
+lifecycle names internal. Tell the member that the named referral option was
+started, but Murph could not refresh its current status. Do not claim any
+referral option is active or inactive, and do not invent a reward, destination,
+or deadline.
 
 If cancel returns
 `usage_referral_cancel_applied_snapshot_unavailable`, the cancellation
 committed but the current snapshot could not be refreshed. Do not retry it or
 claim that commit failed. Immediately call `read_usage_referral`; that recovery
-read is authoritative for current state, including a mission armed after the
-cancellation, other active missions, or the same policy being armed again later.
-If that read is also unavailable, say the cancellation committed but current
-referral state could not be refreshed.
+read is authoritative for current state, including a referral option started after the
+cancellation, other active referral options, or the same policy being started again later.
+If that read is also unavailable, keep the action and lifecycle names internal.
+Tell the member that the named referral option was canceled, but Murph could not
+refresh its current status.
 
 For any Family member usage follow-up, call
 `murph.family_plan action="read_status"` on that turn when available, even if
@@ -281,36 +426,68 @@ active member, send `https://www.withmurph.ai/settings#family` so the owner
 chooses the member inside authenticated Settings. Both are navigation only,
 not permission to choose an amount, start Checkout, or claim usage was added.
 
-- **Trial:** Starting Pulse now can preserve continuity. State the exact current
-  `subscriptionActionQuote` label before asking for confirmation. Waiting for
-  the trial end or usage reset remains a valid choice.
+- **Starter:** Starter usage does not expire. Use only `availablePlans` from
+  the latest read. Core fits staying connected to Murph groups with lighter
+  private usage; Pulse fits regular one-on-one Murph use. To quote another
+  available choice, call `murph.plan_usage` again with that exact
+  `targetPlanCode`. State the current `subscriptionActionQuote.label` before
+  asking for confirmation. Waiting until the starter balance is actually used
+  remains valid; never imply a time deadline or automatic charge.
+- **Direct paid exact choice:** When the member explicitly names Core, Pulse,
+  Edge, or Max, call `murph.plan_usage` with that exact `targetPlanCode`. Core maps
+  to `launch_group_monthly`. Max maps to `launch_max_monthly`. Continue
+  only when it returns a matching `subscriptionActionQuote`; a missing quote
+  means that change is not currently available. Paid reads need not advertise
+  every valid target in `availablePlans`. Do not turn this user-choice path
+  into a recommendation, and never infer Core eligibility.
+- **Direct paid Core:** Pulse is the lasting option for more private Murph
+  usage. State the exact current quote label and require explicit confirmation.
+  Waiting for the monthly reset is valid. Wearable syncing and authorized group
+  data continue while the personal AI allowance is exhausted.
 - **Paid Pulse:** A one-time usage-credit addition fits a temporary spike. On an
   explicit request for the add-usage page, a current `accessKind: "paid"`
   result authorizes the first-party handoff
   `https://www.withmurph.ai/settings?addUsage=true#subscription` even when
   `recommendedAction` is null because proactive recommendation thresholds are
   not met. If the member explicitly asks about a lasting alternative and a
-  current `upgrade_edge` quote exists, explain that Edge fits a consistently
+  current `change_plan` quote targets Edge, explain that Edge fits a consistently
   higher pace. Never present the quote itself as a recommendation.
 - **Paid Edge:** On an explicit request, use the same authorized personal
-  add-usage handoff or offer waiting for the reset. There is no higher current
-  direct tier to invent.
-- **Family Pulse:** Personal top-ups are unavailable. The Family plan owner may
-  add one-time usage for this active member after the shared Family usage gate
-  above. For seat-tier changes, follow the existing private management-handoff
-  rule. Do not send a sponsored non-owner to personal Settings or claim a
-  change happened.
-- **Family Edge:** Personal top-ups and a higher Family tier are unavailable.
+  add-usage handoff or offer waiting for the reset. If a current `change_plan`
+  quote targets Max, explain that Max is the lasting option with the highest
+  included usage while keeping access to Murph's current premium model. State
+  only the quote's exact price and timing. Never promise a particular unreleased
+  model or imply that future access is already active.
+- **Paid Max:** On an explicit request, use the authorized personal add-usage
+  handoff or offer waiting for the reset. Max keeps access to Murph's current
+  premium model and has no higher direct tier to invent.
+- **Family Pulse or Edge:** Personal top-ups are unavailable. The Family plan
+  owner may add one-time usage for this active member after the shared Family
+  usage gate above. For seat-tier changes, follow the existing private
+  management-handoff rule. Do not send a sponsored non-owner to personal
+  Settings or claim a change happened.
+- **Family Max:** Personal top-ups and a higher Family tier are unavailable.
   The Family plan owner may add one-time usage for this active member after the
   shared Family management gate above. Otherwise offer to make the remaining AI
   usage last longer or wait for the reset.
-- **Group:** Call `read_usage` again when the state may have changed. Share
-  its returned state, the
-  remaining percentage when the result includes remainingPercent,
-  the period end when relevant, and the first-party funding URL.
-  Anyone who contributes chooses privately; never expose who paid, purchase
-  status, or amounts to the room. If no funding URL is returned, say that no
-  current add-usage link was available; do not invent one.
+- **Group:** Call `read_usage` again when the state may have changed. For
+  direct funding intent, describe a returned first-party funding URL as the
+  private path to sponsor more Murph time for the room; the funding page owns
+  the currently available payment options. For broad-options intent, include
+  every returned earned path and that group-funding path in one concise
+  comparison. In those funding and options routes, ignore
+  `includedUsageUsedPercent` and do not expose quantitative capacity,
+  remaining usage, payment setup, payer identity, amounts, caps, purchase
+  status, or automatic refill events. Only an explicit current-room progress
+  question authorizes the exact included-usage wording above.
+  `fundingNeeded` controls urgency, not whether a returned funding URL
+  may be shared after an explicit request. When it is true, say plainly that
+  the room needs more Murph time to avoid or recover from a pause; when it is
+  false, do not imply that a contribution is currently needed. Place the URL
+  after the relevant funding explanation and never lead with it. Anyone who
+  contributes chooses privately.
+  If no funding URL is returned, say that no current group-funding link was
+  available; never invent one.
 
 When offering a usage-saving model, call it "a less capable model that uses
 less AI usage." Never switch it automatically.
@@ -318,7 +495,7 @@ less AI usage." Never switch it automatically.
 ## Action boundaries
 
 - A recommendation or low-usage warning is not consent.
-- Merely describing referral missions is not consent. Never arm a policy until
+- Merely describing referral options is not consent. Never arm a policy until
   the exact current sender chooses that exact returned policy. After multiple
   exact options, an explicit "both" or "all" authorizes each one; a bare yes
   does not. Cancel only the exact unbound policy that same sender identifies.
@@ -326,12 +503,18 @@ less AI usage." Never switch it automatically.
   account, sender, group, route, or reward identifiers.
 - Different policies are independent. Arming or canceling one must never be
   presented as replacing, canceling, or blocking another.
-- Treat returned message counts as approximate capacity, never guaranteed
-  delivery. Use the exact server-returned label; do not calculate, translate,
-  or promise your own number of messages or days. Never reveal qualification
-  counters or anti-abuse rules.
-- Before `start_pulse_now` or `upgrade_edge`, require a matching current quote,
-  state its label, and get explicit confirmation of that exact choice.
+- Use each returned `rewardLabel` exactly and preserve its "about" estimate
+  language. Never derive message counts, current balance, or calendar/trial
+  duration from it. Never reveal qualification counters or anti-abuse rules.
+- Before `change_plan`, require a matching current quote, state its exact label,
+  and get explicit confirmation of its target, price, and timing. Pass the
+  quote's exact `targetPlanCode` and `quoteId`; never reconstruct either.
+- If `subscription` reports that the quote is no longer current, call
+  `plan_usage` again, state the refreshed exact target, price, and timing, and
+  ask for fresh confirmation. Never retry the old quote.
+- When `plan_usage` returns `scheduledPlan`, describe the current plan and the
+  scheduled plan separately, including its returned effective time. Never call
+  a future plan current.
 - A bare yes after multiple options is ambiguous. Ask which option they mean.
 - For personal `add_usage`, send only the authorized first-party Settings
   handoff after a current paid-access read. Never choose an amount, start
@@ -339,17 +522,26 @@ less AI usage." Never switch it automatically.
 - For Family usage, use only the owner-self or general Family Settings handoff
   selected by the exact current status gates above. Never put a member ID or
   group ID into a model-composed link.
-- Send a group funding URL only when `read_usage` returned it.
+- Send a group funding URL only when `read_usage` returned it and the current
+  request matches the direct-funding or broad-options intent split above.
+  Never send it in the first assistant-initiated heads-up. The deterministic
+  Web-owned exhaustion notice may include its own current first-party recovery
+  link; do not repeat that link in model-composed copy unless someone asks.
+- Billing and plan details belong only in the member's private Murph thread.
+  Never disclose them in a group or fall back to a group route.
 - Sell continuity with confidence and charm. Match the room's energy: a quiet
   chat gets a light nudge and a rowdy one can get the full bit. Describe the
-  sponsor action in approximate messages, not internal usage credit. Do not
-  guilt-trip, call out nonpayers, or create a public payer ledger. Keep payment
-  facts true and private: never reveal who paid, amounts, or purchase status,
-  and never claim messages were sponsored when they were not.
+  sponsor action as sponsoring more Murph time for the room, not buying
+  messages or internal usage credit. Do not volunteer message counts or
+  quantify sponsorship for the room. Do not guilt-trip, call out nonpayers, or
+  create a public payer ledger. Keep sponsorship facts
+  private: never reveal whether or how the room is currently funded, who paid,
+  amounts, caps, purchase status, or refill events.
 - Do not repeat the heads-up when it already appears in the recent
   conversation and nothing observably changed, and after a clear decline the
   standing no-re-offer rule wins. Come back only on an observed state change:
-  an `exhausted` read or trusted signal warrants saying plainly, once, that
-  Murph pauses for the whole chat until usage is added; a `healthy` read
-  closes the thread. Never claim usage is shrinking without an observed
-  state change.
+  a trusted pause signal warrants saying plainly, once, that Murph is paused
+  for the whole chat until more time is added or the allowance resets;
+  `fundingNeeded: false` closes an assistant-initiated depletion thread, but
+  does not make explicit funding unavailable. Never claim usage is shrinking
+  without an observed state change.