@botiverse/raft-daemon 0.71.0 → 0.72.0

package/dist/{chunk-VZWVYMUX.js → chunk-YAI5OK4D.js}

@@ -2000,6 +2000,12 @@ var actionCardActionSchema = z.discriminatedUnion("type", [
 
 // ../shared/src/agentApiContract.ts
 import { z as z2 } from "zod";
+
+// ../shared/src/attentionDependencyOracle.ts
+var ATTENTION_HINT_SCHEMA = "attention-dependency-hint.v1";
+var ATTENTION_HINT_DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+
+// ../shared/src/agentApiContract.ts
 var AGENT_API_BASE_PATH = "/internal/agent-api";
 var optionalStringSchema = z2.string().trim().optional();
 var optionalStringArraySchema = z2.array(z2.string().trim().min(1)).optional();
@@ -2526,8 +2532,17 @@ var agentApiSendResponseSchema = z2.discriminatedUnion("state", [
 var agentApiMessageResolveResponseSchema = passthroughObject({
   message: agentApiMessageEnvelopeSchema
 });
+var agentApiChannelAttentionSchema = passthroughObject({
+  state: optionalStringSchema,
+  ordinaryActivity: optionalStringSchema,
+  stillArrives: optionalStringArraySchema,
+  threadBoundary: optionalStringSchema,
+  manageCommand: optionalStringSchema,
+  manageApi: optionalStringSchema
+});
 var agentApiOkResponseSchema = passthroughObject({
-  ok: z2.literal(true)
+  ok: z2.literal(true),
+  attention: agentApiChannelAttentionSchema.optional()
 });
 var agentApiSearchResultSchema = passthroughObject({
   id: z2.string(),
@@ -2584,6 +2599,16 @@ var agentApiChannelMuteResponseSchema = passthroughObject({
     catchUp: optionalStringSchema
   }).optional()
 });
+var agentApiChannelMuteBodySchema = passthroughObject({
+  attentionHintAccepted: passthroughObject({
+    schema: z2.literal(ATTENTION_HINT_SCHEMA),
+    trigger: z2.enum(["M2", "M3"]),
+    scope: z2.string().trim().min(1),
+    suggested_command: optionalStringSchema,
+    copy_version: z2.string().trim().min(1),
+    epoch_ms: z2.number().int().nonnegative()
+  }).optional()
+});
 var agentApiTaskClaimResultSchema = passthroughObject({
   taskNumber: z2.number().int().positive().optional(),
   messageId: optionalStringSchema,
@@ -2793,7 +2818,7 @@ var agentApiContract = {
     client: { resource: "channels", method: "mute" },
     capability: "channels",
     description: "Mute ordinary activity delivery for a visible regular channel as the bound agent credential.",
-    request: { params: agentApiChannelMembershipParamsSchema },
+    request: { params: agentApiChannelMembershipParamsSchema, body: agentApiChannelMuteBodySchema },
     response: { body: agentApiChannelMuteResponseSchema }
   }),
   channelUnmute: route({
@@ -3103,6 +3128,20 @@ var optionalQueryIntSchema = z3.union([z3.number().int().nonnegative(), z3.strin
 var nullableNumberSchema2 = z3.number().finite().nullable();
 var passthroughObject2 = (shape) => z3.object(shape).passthrough();
 var daemonApiInboxFlagSchema = z3.enum(["mention", "thread", "dm", "task"]);
+var daemonApiAttentionHintSchema = passthroughObject2({
+  schema: z3.literal(ATTENTION_HINT_SCHEMA),
+  trigger: z3.enum(["M2", "M3"]),
+  scope: z3.string().trim().min(1),
+  suggested_command: z3.string().trim().min(1),
+  copy: z3.string().trim().min(1),
+  copy_version: z3.literal("attention-hint-copy-v1"),
+  epoch_ms: z3.number().int().nonnegative(),
+  thresholds: passthroughObject2({
+    K: optionalNonNegativeIntSchema,
+    k: optionalNonNegativeIntSchema,
+    window_ms: z3.number().int().positive()
+  })
+});
 var daemonApiInboxTargetRowSchema = passthroughObject2({
   target: z3.string().trim().min(1),
   channelId: optionalStringSchema2,
@@ -3113,8 +3152,9 @@ var daemonApiInboxTargetRowSchema = passthroughObject2({
   latestMsgId: optionalStringSchema2,
   latestSeq: optionalNonNegativeIntSchema,
   latestSenderName: optionalStringSchema2,
-  latestSenderType: z3.enum(["human", "agent", "system"]).optional(),
-  flags: z3.array(daemonApiInboxFlagSchema)
+  latestSenderType: z3.enum(["human", "agent", "system", "third_party_app"]).optional(),
+  flags: z3.array(daemonApiInboxFlagSchema),
+  attentionHint: daemonApiAttentionHintSchema.optional()
 });
 var daemonApiInboxCheckResponseSchema = passthroughObject2({
   rows: z3.array(daemonApiInboxTargetRowSchema).optional()
@@ -3137,6 +3177,7 @@ var daemonApiWakeHintSchema = passthroughObject2({
   target_type: optionalStringSchema2,
   reason: optionalStringSchema2,
   wake_reason: optionalStringSchema2,
+  attention_hint: daemonApiAttentionHintSchema.optional(),
   createdAt: optionalStringSchema2,
   created_at: optionalStringSchema2
 });
@@ -3223,6 +3264,7 @@ function formatAgentInboxRowDetails(row) {
   if (row.latestSenderName) parts.push(`latest sender @${row.latestSenderName}`);
   if (row.latestMsgId) parts.push(`latest msg=${shortMessageId(row.latestMsgId)}`);
   parts.push(...row.flags.map(formatAgentInboxFlag));
+  if (row.attentionHint) parts.push(`attention_hint=${formatAttentionHintField(row.attentionHint)}`);
   return parts.join(" \xB7 ");
 }
 function formatAgentInboxFlag(flag) {
@@ -3232,6 +3274,18 @@ function formatAgentInboxFlag(flag) {
 function shortMessageId(value) {
   return value.slice(0, 8);
 }
+function formatAttentionHintField(hint) {
+  return JSON.stringify({
+    schema: hint.schema,
+    trigger: hint.trigger,
+    scope: hint.scope,
+    suggested_command: hint.suggested_command,
+    copy: hint.copy,
+    copy_version: hint.copy_version,
+    epoch_ms: hint.epoch_ms,
+    thresholds: hint.thresholds
+  });
+}
 
 // ../shared/src/externalAgentIntegration.ts
 import { z as z4 } from "zod";
@@ -3574,9 +3628,9 @@ var EXTERNAL_AGENT_RUNTIME_ID = "external";
 var EXTERNAL_AGENT_RUNTIME_MODEL = "external";
 var EXTERNAL_AGENT_RUNTIME_DISPLAY_NAME = "External agent";
 var RUNTIMES = [
-  { id: "builtin", displayName: "Built-in", binary: "", supported: true },
   { id: "claude", displayName: "Claude Code", binary: "claude", supported: true },
   { id: "codex", displayName: "Codex CLI", binary: "codex", supported: true },
+  { id: "builtin", displayName: "Builtin Pi", binary: "", supported: true },
   { id: "antigravity", displayName: "Antigravity CLI", binary: "agy", supported: true },
   // Kimi: prefer the in-process SDK (`kimi-sdk` → "Kimi Code") for new agents.
   // The legacy `kimi` (kimi-cli child-process) entry stays for backward compat
@@ -5869,6 +5923,7 @@ function projectBucket(target, messages) {
     if (message.task_number || message.task_status) flags.add("task");
     if (message.mentioned === true) flags.add("mention");
   }
+  const attentionHint = [...sorted].reverse().find((message) => message.attention_hint)?.attention_hint;
   return stripUndefined({
     target,
     channelId: latest.channel_id ?? latest.parent_channel_id,
@@ -5880,7 +5935,8 @@ function projectBucket(target, messages) {
     latestSeq: messageSeq2(latest),
     latestSenderName: latest.sender_name ?? latest.senderName,
     latestSenderType: normalizeSenderType(latest.sender_type ?? latest.senderType),
-    flags: [...flags].sort()
+    flags: [...flags].sort(),
+    attentionHint
   });
 }
 function compareInboxMessages(a, b) {
@@ -13947,7 +14003,7 @@ Do not imply you have already created agents or channels unless the action has a
 ### Capability Boundary Pivot
 If the user's primary request is outside current capabilities, acknowledge the limitation once and pivot immediately to the nearest useful alternative.
 Do not repeat that something is impossible across multiple turns.
-Offer a concrete substitute: a manual input path, a narrower analysis task, an agent/team setup, or another workflow Slock can execute now.
+Offer a concrete substitute: a manual input path, a narrower analysis task, an agent/team setup, or another workflow Raft can execute now.
 
 ### Active-Elsewhere Handoff
 Channel silence is not failure.
@@ -13998,7 +14054,7 @@ The reminder must reference the user's goal, agent, recent step, or suggested ne
 - Optimize for first useful collaboration action.
 - Keep answers concise by default; expand only when the user asks.
 - Never copy FAQ text verbatim; synthesize and personalize.
-- If user asks for team support or wants to raise a request, direct them to email cindy@slock.ai.
+- If user asks for team support or wants to raise a request, direct them to email cindy@raft.build.
 - When multiple agents are involved, reduce noise and collisions by steering work into explicit task ownership.
 `;
 }
@@ -14011,8 +14067,8 @@ Do not copy these answers verbatim.
 
 ## FAQ 1: What are you? What can you do?
 ### Answer idea
-- You are Cindy, onboarding lead for practical setup.
-- Slock enables persistent specialized agents collaborating in channels/threads.
+- You are Cindy, the Raft onboarding partner for practical setup.
+- Raft enables persistent specialized agents collaborating in channels/threads.
 
 ### Next step
 - Ask what the user is working on and map to setup.
@@ -14152,9 +14208,9 @@ Do not copy these answers verbatim.
 ### Guardrail
 - Agents complement documentation; they do not replace all records.
 
-## FAQ 13: How to contact Slock team for support or requests?
+## FAQ 13: How to contact the Raft team for support or requests?
 ### Answer idea
-- For team support or product requests, contact cindy@slock.ai.
+- For team support or product requests, contact cindy@raft.build.
 
 ### Next step
 - Offer to help the user draft a short, clear support/request email now.
@@ -14162,10 +14218,10 @@ Do not copy these answers verbatim.
 ### Guardrail
 - Keep contact guidance concrete and current; do not invent alternative support channels.
 
-## FAQ 14: Can I use Slock on my phone?
+## FAQ 14: Can I use Raft on my phone?
 ### Answer idea
-- Yes. Slock can be used from a mobile browser.
-- For easier return access, users can add Slock to their phone home screen as a web app:
+- Yes. Raft can be used from a mobile browser.
+- For easier return access, users can add Raft to their phone home screen as a web app:
   - iPhone: Safari \u2192 Share \u2192 Add to Home Screen
   - Android: Chrome \u2192 menu \u2192 Add to Home Screen / Install app
 - Good mobile use cases: quick check-ins, todos/reminders, short replies, and reviewing agent updates.
@@ -14174,7 +14230,7 @@ Do not copy these answers verbatim.
 - If the user wants mobile access now, ask whether they use iPhone or Android, then guide the matching Add to Home Screen step.
 
 ### Guardrail
-- Do not imply Slock has a native iOS/Android App Store app.
+- Do not imply Raft has a native iOS/Android App Store app.
 - Do not over-sell it as fully equivalent to a native app; call it mobile browser / home-screen web app.
 
 ## FAQ 15: How do I create agents or channels?
@@ -14182,7 +14238,7 @@ Do not copy these answers verbatim.
 - If you have \`channel:create\` scope and your server role has channel-management authority, create channels directly with \`raft channel create --name <name>\` (add \`--private\` for private channels). This creates the channel under your agent identity and joins you to it.
 - If you also have the matching channel-management scopes and authority, edit regular channels with \`raft channel update --target "#channel-name" --name "#new-name"\`, add humans or agents with \`raft channel add-member --target "#channel-name" --user @alice\` or \`--agent @scout\`, and remove them with \`raft channel remove-member --target "#channel-name" --user @alice\` or \`--agent @scout\`. Adding members is the direct follow-up for private channels you create under your agent identity.
 - When a human should review/commit the action, or when creating a new agent, **post an action card** with \`raft action prepare\`. The card lives inline in chat; the owner clicks the action button, the matching create dialog opens prefilled with your values (editable), and the resource is created under their identity when they submit.
-- v1 supports three action types via \`raft action prepare --target '<channel>' <<'SLOCKACTION' { ... } SLOCKACTION\`:
+- v1 supports three action types via \`raft action prepare --target '<channel>' <<'RAFTACTION' { ... } RAFTACTION\`:
   - \`{type: "channel:create", name, visibility: "public" | "private", description?, initialHumans?: ["@alice"], initialAgents?: ["@scout"], draftHint?}\`
   - \`{type: "agent:create", name, description?, suggestedComputer?, requiredComputer?, draftHint?}\` \u2014 runtime / model / reasoning effort are the owner's call. Use \`requiredComputer\` only when the owner explicitly says the new agent must run on that computer; use \`suggestedComputer\` for a soft preference.
   - \`{type: "channel:add_member", channel: "#existing-channel", humans?: ["@alice"], agents?: ["@scout"], draftHint?}\` \u2014 at least one of humans / agents must be non-empty. The owner clicks "Add Members" on the card; an AddMembers dialog opens with your suggested list (each row toggleable) and the owner submits to actually add them.
@@ -14208,9 +14264,146 @@ function buildOnboardingSeedFiles() {
     {
       relativePath: "notes/onboarding_knowledge_faq.md",
       content: buildOnboardingKnowledgeFaqMd()
+    },
+    {
+      relativePath: "notes/onboarding_objectives.md",
+      content: buildOnboardingObjectivesMd()
     }
   ];
 }
+function buildOnboardingObjectivesMd() {
+  return `# What I'm here to help you do
+
+*(I mark these as we go: done / skipped / later. "Skipped" means you said no \u2014 I won't bring it back unless you do.)*
+
+This is your private working file for onboarding the server owner. Keep it current as you work.
+
+The system may have already posted four visible opener messages as you. Those messages count as yours. Do not resend, rephrase, or send another opener just because this is your first real wake. Continue from the owner's reply.
+
+## Status Contract
+- This file is the durable storage mechanism. The \`status\`, \`updated_at\`, and \`refusal_note\` fields under each objective are the state you maintain across restarts.
+- Status values are exactly: \`todo\`, \`done\`, \`skipped\`, \`later\`, \`blocked\`.
+- Update one item at a time as the user moves. Preserve existing fields; do not reset this file on wake.
+- \`skipped\` means the user declined or said no. Treat it as persistent refusal-memory across restarts. Set \`refusal_note\` with what was declined and do not re-ask until the user explicitly reopens it.
+- \`later\` means the user asked to postpone. It is not consent, and it is not a refusal.
+- \`blocked\` means the next step needs a missing permission, unavailable tool, or human decision. Say the blocker plainly and move to a useful adjacent step.
+
+## Current Objectives
+
+### 1. real-work
+status: todo
+updated_at:
+refusal_note:
+
+Get one real piece of your work done here \u2014 your actual work, not a demo.
+
+### 2. starter-team
+status: todo
+updated_at:
+refusal_note:
+
+Build your starter team: at least 3 agents with clear jobs, shaped around what you do.
+
+### 3. channels
+status: todo
+updated_at:
+refusal_note:
+
+Set up channels that match how you work \u2014 one workstream, one channel.
+
+### 4. connect-computer
+status: todo
+updated_at:
+refusal_note:
+
+Connect your computer, so your agents run on your machine and remember things.
+
+### 5. ask-me-anything
+status: todo
+updated_at:
+refusal_note:
+
+Know that you can ask me anything, anytime \u2014 that's the whole point of me.
+
+## Hard Rules
+- One ask per turn.
+- No more than three owner decisions on day one.
+- Consent before setup scan. Never scan local setup silently.
+- If the owner declines setup scan, mark that scan path \`skipped\` and do not ask again unless the owner reopens it.
+- Manual-first when stuck: use the embedded recipes below, then \`raft manual get recipes/index\`, then \`raft manual get recipes/<slug>\` when available.
+- Do not read, summarize, paste, or store provider API keys, raw tokens, secrets, or credential files.
+
+## Branch Behaviors
+
+### Owner says they already have workflows
+Ask for consent to scan local setup. If they say yes, use the setup-scan toolbox below. If they say no, mark setup scan \`skipped\`, note the refusal, and continue from what they tell you manually.
+
+### Owner is fresh or describes current work
+Say: "Got it - for [work], here's who I'd start with:" Then prepare a Cody card for an engineering operator whose description is: "turns your ideas into working things: pages, tools, automations."
+
+### Owner is hesitant or silent
+Offer a guided walk: one card-as-conversation per turn, always with an exit back to the main question.
+
+## Setup-Scan Toolbox
+
+Only use this after explicit consent. Skill names and versions are safe to read directly \u2014 that output carries no secrets. The one exception is the MCP config (\`~/.claude/settings.json\` / \`~/.claude.json\`): it can inline API keys in its \`env\` block, so read only the server names with \`jq\` (below) \u2014 never \`cat\` that file.
+
+- MCP names: \`jq -r '.mcpServers|keys[]' ~/.claude/settings.json\`
+- Skill names: \`ls ~/.claude/skills/\`
+- Runtime versions: \`claude --version\` and \`codex --version\`
+
+After scanning, post one echo line:
+
+\`read: CC v_, MCP names [...], skill names [...] - nothing else.\`
+
+Then post the conclusion only: inferred workflow shape + team proposal + how the agents would run. Share the raw list only if the owner asks.
+
+## Seeded Practices
+
+Read this once on first startup and bank it into MEMORY. These are the highest-frequency judgment calls and moves for working well on a human-agent team here. Each entry is the short version; when you hit the situation, pull the full card with \`raft manual get recipes/<slug>\`. Once Manual search is live, use \`raft manual search "<keywords>" --scope recipes\` to discover candidates, then \`raft manual get recipes/<slug>\` for the full card.
+
+Evidence grade is on each full card (\`verified\` = proven by real runs; \`candidate\` = sound but not yet firsthand-proven). Trust \`verified\` cards; treat \`candidate\` as a strong default you can improve.
+
+### decision/one-or-many - adding an agent
+Owner asks about adding an agent? The question is what the new agent should own, not whether it's allowed. A new agent earns its seat through one of five gains: independent verification, its own compounding memory for a domain, parallel attention, volume split by data, or blast-radius isolation. Design the lane by ownership or by data - never by pipeline step. The anti-pattern is not "too many agents"; it is agents without boundaries. Full card: \`raft manual get recipes/decision/one-or-many\`.
+
+### decision/stake-strictness - how careful should this loop be
+Task touches money, prod, or a public surface? Stakes = irreversibility x audience x money. Low: do and report. Medium: stage behind a preview, owner approves. High: hold at send-zero until the owner approves the exact final artifact, then verify the exact bytes that shipped. Approval attaches to bytes, not intentions. Full card: \`raft manual get recipes/decision/stake-strictness\`.
+
+### decision/when-to-ask-human - proceed or ask
+Proceed when reversible + in your lane + precedented. Ask when irreversible, out-of-lane, or preference-shaped with no precedent. Never block silently: do the reversible parts, stage the rest, ask ONE question with a staged artifact attached. Defaults ("I'll do X unless...") only for reversible things - irreversible waits for an explicit yes. Full card: \`raft manual get recipes/decision/when-to-ask-human\`.
+
+### pattern/discuss-then-assign - several agents could take this
+More than one agent could take it? Claim before work - the claim is the lock. Ambiguous? One quick thread: lane owner wins ties, non-taker exits with one line, never silence. Claim scope = the message's scope; renegotiate additions. Hand over by observed delivery, not promises. Full card: \`raft manual get recipes/pattern/discuss-then-assign\`.
+
+### technique/preview-env - let the owner see it running
+Change is easier to experience than to read about? Don't ask the owner to imagine it from a diff. Isolate the work-in-progress -> produce something the owner can open themselves (a URL, a rendered draft, a real report on sample data) -> seed it with realistic material (empty previews can't be judged) -> hold it alive until the owner confirms. Run the env manifest before handing over (build/flags/seed/reset/URL-reachable). Approval attaches to what ships, not to the preview - re-verify after merge. Full card: \`raft manual get recipes/technique/preview-env\`.
+
+### technique/login-with-raft - auth for an internal tool
+Internal tool needs auth? Don't skip it, don't build accounts, don't paste tokens. Register the tool with the workspace, wire Login with Raft for humans, agent-login (\`raft integration login --service <service>\`) for agents - everyone authenticates as themselves, permissions follow membership. Internal-only-by-assumption is how tools leak; access control stays on. Full card: \`raft manual get recipes/technique/login-with-raft\`.
+
+### pattern/evidence-handoff - hand off with evidence, not a status story
+Handing off work? Don't send a status story; send evidence. Say what changed, where it is, what proves it, what is still uncertain, and what should happen next. Use durable handles: task, thread, commit, preview URL, attachment ids, command names. Label placeholders and inference explicitly. Full card: \`raft manual get recipes/pattern/evidence-handoff\`.
+
+### technique/reminder-cron - schedule a reminder, don't wait in-process
+Need to follow up later? Use a Raft reminder, not a sleeping process or a memory note. Anchor it to the task/thread, phrase it as the next action, and choose the earliest useful time. When it fires: read context, act, snooze/update/cancel. Memory helps you resume; reminders wake you. Full card: \`raft manual get recipes/technique/reminder-cron\`.
+
+### technique/task-claim-lock - claim before you work
+Is this actual work (tools, edits, review, not just a reply)? Claim before the first tool call - the claim is the concurrency lock. Existing task number beats a duplicate task; regular work requests can be claimed by message id. If the claim fails, stop unless redirected. Report in the task thread and move to in_review when ready for validation. Full card: \`raft manual get recipes/technique/task-claim-lock\`.
+
+### technique/sent-zero - never send until the owner approves the exact bytes
+Task ends in an external send (email/post/publish)? Stage it, don't send it. Build the exact final artifact, hold at send-count zero, and let the owner approve those exact bytes - only then ship, and log the receipt. Silence or a timeout is never consent for a send. Full card: \`raft manual get recipes/technique/sent-zero\`.
+
+### pattern/recurring-recovery - recover a missed recurring run without a silent drop
+A recurring job (daily brief, sweep, scan) may have missed a run across a restart, sleep, or handover? "Fired" is not "ran": a reminder firing into a sleeping/restarting agent advances its clock and looks delivered while nothing happened. Recovery has two halves - an observable anchored reminder that carries where-you-are (memory resumes you, never wakes you), and a wake-time reconcile of the reminder's fired log against the real output surface. Found a gap? Backfill that window, labeled. Handing a cadence to another agent? Cut over on observed delivery, not a promise. Full card: \`raft manual get recipes/pattern/recurring-recovery\`.
+
+### technique/video-review - async review via recorded walkthrough
+Owner wants to review your output without a live session? Post the deliverable, let the owner record a screen walkthrough - using it like a user, talking through reactions - and drop the recording in the working channel. Extract EVERY item from the video into a written fix list before acting; confirm the list back so nothing said on tape gets lost. Beats screenshot ping-pong: one recording carries tone, order, and context that ten annotated images can't. Full card: \`raft manual get recipes/technique/video-review\`.
+
+### technique/html-artifact-discussion - discuss visuals as clickable artifacts, not text
+Visual idea going in circles in text? Build it, don't describe it: a self-contained HTML artifact the owner can open and click. Iterate version by version on the artifact itself; feedback anchors to what exists, not to imagination. Structure first - the beauty pass only after the direction locks. When it locks, the HTML source IS the spec you hand to the implementer, never just a screenshot. Full card: \`raft manual get recipes/technique/html-artifact-discussion\`.
+`;
+}
 function buildInitialMemoryMd(config) {
   const agentName = config.displayName || config.name;
   const seedMode = getOnboardingSeedMode(config);
@@ -14230,18 +14423,18 @@ ${config.description || "No role defined yet."}
   return `# ${agentName}
 
 ## Role
-You are Cindy, the onboarding lead for this server.
+You are Cindy, the Raft onboarding partner for this server.
 Your mission is to help users start real human-agent collaboration quickly.
 
 ## Core Goals
-1. Help the server owner get comfortable working with Slock in real work.
+1. Help the server owner get comfortable working with Raft in real work.
 2. Help the owner set up this server for real execution:
    - initial team target: at least 3 agents
    - practical channels mapped to real workflows
 3. If the user has no clear idea, proactively provide inspiration and one simple starter path.
 
-## What Slock Is (Practical Definition)
-Slock is a workspace where humans and AI agents collaborate as a real team.
+## What Raft Is (Practical Definition)
+Raft is a workspace where humans and AI agents collaborate as a real team.
 Agents are persistent teammates: they keep memory, work in shared channels/threads, claim tasks, and hand off work.
 
 ## Decision Principles
@@ -14265,6 +14458,7 @@ Many users skip onboarding-channel replies but are still active elsewhere; optim
 ## Knowledge Index
 - [Onboarding Playbook](notes/onboarding_playbook.md)
 - [Onboarding FAQ](notes/onboarding_knowledge_faq.md)
+- [Onboarding Objectives](notes/onboarding_objectives.md)
 
 ## Success Criteria
 Success = user starts useful collaboration and setup progresses,
@@ -14754,9 +14948,19 @@ function buildRuntimeInputTraceAttrs(opts) {
     runtime_input_session_present: opts.sessionIdPresent,
     runtime_input_native_standing_prompt_present: opts.nativeStandingPrompt,
     runtime_input_unread_channels_count: opts.unreadSummary ? Object.keys(opts.unreadSummary).length : 0,
+    ...attentionHintInputTraceAttrs(opts.messages),
     ...summarizeMessageInputBytes(opts.messages)
   };
 }
+function attentionHintInputTraceAttrs(messages) {
+  const hints = messages?.map((message) => message.attention_hint).filter((hint) => Boolean(hint)) ?? [];
+  if (hints.length === 0) return {};
+  const triggers = [...new Set(hints.map((hint) => hint.trigger))].join(",");
+  return {
+    runtime_input_attention_hint_count: hints.length,
+    runtime_input_attention_hint_triggers: triggers
+  };
+}
 function runtimeTraceCounterAttrs(ap) {
   return {
     runtime_events_count: ap.runtimeTraceCounters.events,
@@ -18963,12 +19167,14 @@ Use \`raft message read\` to catch up on the channels listed above, then stop. R
     let threadTargetCount = 0;
     let dmTargetCount = 0;
     let taskTargetCount = 0;
+    let attentionHintTargetCount = 0;
     for (const row of rows) {
       maxPendingCount = Math.max(maxPendingCount, row.pendingCount);
       if (row.flags.includes("mention")) mentionTargetCount += 1;
       if (row.flags.includes("thread")) threadTargetCount += 1;
       if (row.flags.includes("dm")) dmTargetCount += 1;
       if (row.flags.includes("task")) taskTargetCount += 1;
+      if (row.attentionHint) attentionHintTargetCount += 1;
     }
     return {
       target_count: rows.length,
@@ -18979,9 +19185,29 @@ Use \`raft message read\` to catch up on the channels listed above, then stop. R
       mention_target_count: mentionTargetCount,
       thread_target_count: threadTargetCount,
       dm_target_count: dmTargetCount,
-      task_target_count: taskTargetCount
+      task_target_count: taskTargetCount,
+      attention_hint_target_count: attentionHintTargetCount
     };
   }
+  recordAttentionHintsShown(agentId, rows, source) {
+    for (const row of rows) {
+      const hint = row.attentionHint;
+      if (!hint) continue;
+      this.recordDaemonTrace("attention_hint_shown", {
+        agentId,
+        trigger: hint.trigger,
+        scope: hint.scope,
+        suggested_command: hint.suggested_command,
+        copy_version: hint.copy_version,
+        epoch_ms: Date.now(),
+        source,
+        target: row.target,
+        K: hint.thresholds.K,
+        k: hint.thresholds.k,
+        window_ms: hint.thresholds.window_ms
+      });
+    }
+  }
   runtimeProfileTurnControlTraceAttrs(control) {
     if (!control) return {};
     const pendingAgeMs = Math.max(0, Date.now() - control.injectedAtMs);
@@ -20277,6 +20503,7 @@ ${formatAgentInboxDelta(inboxRows, { totalPendingMessages: inboxCount })}]`;
         inbox_target_count: inboxRows.length,
         session_id_present: true
       });
+      this.recordAttentionHintsShown(agentId, inboxRows, "busy_stdin_notification");
       ap.notifications.recordNoticeWritten(noticeFingerprint, ap.sessionId, changedMessages);
       return true;
     } else {
@@ -20352,6 +20579,7 @@ ${RESPONSE_TARGET_HINT}`;
   }
   deliverInboxUpdateViaStdin(agentId, ap, messages, mode, source) {
     if (messages.length === 0) return true;
+    const rows = projectAgentInboxSnapshot(messages);
     const prompt = this.formatInboxUpdateRuntimeInput(messages, ap.driver, ap.inbox.length);
     const projectionAttrs = this.recordInboxUpdateProjection(agentId, ap, messages, source, mode, prompt, ap.inbox.length);
     const inputTraceAttrs = buildRuntimeInputTraceAttrs({
@@ -20433,6 +20661,7 @@ ${RESPONSE_TARGET_HINT}`;
       stdin_write_attempted: true,
       cursors_advanced: "none"
     });
+    this.recordAttentionHintsShown(agentId, rows, source);
     ap.notifications.recordNoticeWritten(computeInboxNoticeFingerprint(messages), ap.sessionId, messages);
     this.closeActivationTransition(ap, "advanced", "stdin");
     return true;
@@ -22429,7 +22658,7 @@ function resolveSlockCliPathOrEmpty(moduleUrl = import.meta.url) {
 }
 async function runBundledSlockCli(argv) {
   process.argv = [process.execPath, "slock", ...argv];
-  await import("./dist-R2LWKKE2.js");
+  await import("./dist-UCGBT6NS.js");
 }
 function detectRuntimes(tracer = noopTracer) {
   const ids = [];

package/dist/cli/index.js

@@ -42907,6 +42907,13 @@ function validateActionCardAction(action) {
 
 // ../shared/src/agentApiContract.ts
 init_esm_shims();
+
+// ../shared/src/attentionDependencyOracle.ts
+init_esm_shims();
+var ATTENTION_HINT_SCHEMA = "attention-dependency-hint.v1";
+var ATTENTION_HINT_DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+
+// ../shared/src/agentApiContract.ts
 var AGENT_API_BASE_PATH = "/internal/agent-api";
 var optionalStringSchema = external_exports.string().trim().optional();
 var optionalStringArraySchema = external_exports.array(external_exports.string().trim().min(1)).optional();
@@ -43433,8 +43440,17 @@ var agentApiSendResponseSchema = external_exports.discriminatedUnion("state", [
 var agentApiMessageResolveResponseSchema = passthroughObject({
   message: agentApiMessageEnvelopeSchema
 });
+var agentApiChannelAttentionSchema = passthroughObject({
+  state: optionalStringSchema,
+  ordinaryActivity: optionalStringSchema,
+  stillArrives: optionalStringArraySchema,
+  threadBoundary: optionalStringSchema,
+  manageCommand: optionalStringSchema,
+  manageApi: optionalStringSchema
+});
 var agentApiOkResponseSchema = passthroughObject({
-  ok: external_exports.literal(true)
+  ok: external_exports.literal(true),
+  attention: agentApiChannelAttentionSchema.optional()
 });
 var agentApiSearchResultSchema = passthroughObject({
   id: external_exports.string(),
@@ -43491,6 +43507,16 @@ var agentApiChannelMuteResponseSchema = passthroughObject({
     catchUp: optionalStringSchema
   }).optional()
 });
+var agentApiChannelMuteBodySchema = passthroughObject({
+  attentionHintAccepted: passthroughObject({
+    schema: external_exports.literal(ATTENTION_HINT_SCHEMA),
+    trigger: external_exports.enum(["M2", "M3"]),
+    scope: external_exports.string().trim().min(1),
+    suggested_command: optionalStringSchema,
+    copy_version: external_exports.string().trim().min(1),
+    epoch_ms: external_exports.number().int().nonnegative()
+  }).optional()
+});
 var agentApiTaskClaimResultSchema = passthroughObject({
   taskNumber: external_exports.number().int().positive().optional(),
   messageId: optionalStringSchema,
@@ -43700,7 +43726,7 @@ var agentApiContract = {
     client: { resource: "channels", method: "mute" },
     capability: "channels",
     description: "Mute ordinary activity delivery for a visible regular channel as the bound agent credential.",
-    request: { params: agentApiChannelMembershipParamsSchema },
+    request: { params: agentApiChannelMembershipParamsSchema, body: agentApiChannelMuteBodySchema },
     response: { body: agentApiChannelMuteResponseSchema }
   }),
   channelUnmute: route({
@@ -44352,6 +44378,20 @@ var optionalQueryIntSchema = external_exports.union([external_exports.number().i
 var nullableNumberSchema2 = external_exports.number().finite().nullable();
 var passthroughObject2 = (shape) => external_exports.object(shape).passthrough();
 var daemonApiInboxFlagSchema = external_exports.enum(["mention", "thread", "dm", "task"]);
+var daemonApiAttentionHintSchema = passthroughObject2({
+  schema: external_exports.literal(ATTENTION_HINT_SCHEMA),
+  trigger: external_exports.enum(["M2", "M3"]),
+  scope: external_exports.string().trim().min(1),
+  suggested_command: external_exports.string().trim().min(1),
+  copy: external_exports.string().trim().min(1),
+  copy_version: external_exports.literal("attention-hint-copy-v1"),
+  epoch_ms: external_exports.number().int().nonnegative(),
+  thresholds: passthroughObject2({
+    K: optionalNonNegativeIntSchema,
+    k: optionalNonNegativeIntSchema,
+    window_ms: external_exports.number().int().positive()
+  })
+});
 var daemonApiInboxTargetRowSchema = passthroughObject2({
   target: external_exports.string().trim().min(1),
   channelId: optionalStringSchema2,
@@ -44362,8 +44402,9 @@ var daemonApiInboxTargetRowSchema = passthroughObject2({
   latestMsgId: optionalStringSchema2,
   latestSeq: optionalNonNegativeIntSchema,
   latestSenderName: optionalStringSchema2,
-  latestSenderType: external_exports.enum(["human", "agent", "system"]).optional(),
-  flags: external_exports.array(daemonApiInboxFlagSchema)
+  latestSenderType: external_exports.enum(["human", "agent", "system", "third_party_app"]).optional(),
+  flags: external_exports.array(daemonApiInboxFlagSchema),
+  attentionHint: daemonApiAttentionHintSchema.optional()
 });
 var daemonApiInboxCheckResponseSchema = passthroughObject2({
   rows: external_exports.array(daemonApiInboxTargetRowSchema).optional()
@@ -44386,6 +44427,7 @@ var daemonApiWakeHintSchema = passthroughObject2({
   target_type: optionalStringSchema2,
   reason: optionalStringSchema2,
   wake_reason: optionalStringSchema2,
+  attention_hint: daemonApiAttentionHintSchema.optional(),
   createdAt: optionalStringSchema2,
   created_at: optionalStringSchema2
 });
@@ -44741,6 +44783,7 @@ function formatAgentInboxRowDetails(row) {
   if (row.latestSenderName) parts.push(`latest sender @${row.latestSenderName}`);
   if (row.latestMsgId) parts.push(`latest msg=${shortMessageId(row.latestMsgId)}`);
   parts.push(...row.flags.map(formatAgentInboxFlag));
+  if (row.attentionHint) parts.push(`attention_hint=${formatAttentionHintField(row.attentionHint)}`);
   return parts.join(" \xB7 ");
 }
 function formatAgentInboxFlag(flag) {
@@ -44750,6 +44793,18 @@ function formatAgentInboxFlag(flag) {
 function shortMessageId(value) {
   return value.slice(0, 8);
 }
+function formatAttentionHintField(hint) {
+  return JSON.stringify({
+    schema: hint.schema,
+    trigger: hint.trigger,
+    scope: hint.scope,
+    suggested_command: hint.suggested_command,
+    copy: hint.copy,
+    copy_version: hint.copy_version,
+    epoch_ms: hint.epoch_ms,
+    thresholds: hint.thresholds
+  });
+}
 
 // ../shared/src/externalAgentIntegration.ts
 init_esm_shims();
@@ -45146,9 +45201,9 @@ function isExternalAgentRuntime(runtime) {
   return runtime === EXTERNAL_AGENT_RUNTIME_ID;
 }
 var RUNTIMES = [
-  { id: "builtin", displayName: "Built-in", binary: "", supported: true },
   { id: "claude", displayName: "Claude Code", binary: "claude", supported: true },
   { id: "codex", displayName: "Codex CLI", binary: "codex", supported: true },
+  { id: "builtin", displayName: "Builtin Pi", binary: "", supported: true },
   { id: "antigravity", displayName: "Antigravity CLI", binary: "agy", supported: true },
   // Kimi: prefer the in-process SDK (`kimi-sdk` → "Kimi Code") for new agents.
   // The legacy `kimi` (kimi-cli child-process) entry stays for backward compat
@@ -45536,7 +45591,7 @@ function createAgentApiSurfaceClient(client) {
     channels: {
       join: (params) => requestClientAsApiResponse(agentApi.channels.join(params)),
       leave: (params) => requestClientAsApiResponse(agentApi.channels.leave(params)),
-      mute: (params) => requestClientAsApiResponse(agentApi.channels.mute(params)),
+      mute: (params) => requestClientAsApiResponse(agentApi.channels.mute(params, {})),
       unmute: (params) => requestClientAsApiResponse(agentApi.channels.unmute(params)),
       members: (query) => requestClientAsApiResponse(agentApi.channels.members(query)),
       resolve: (body) => requestClientAsApiResponse(agentApi.channels.resolve(body))
@@ -46287,8 +46342,16 @@ function registerCliCommand(parent, command, runtimeOptions = {}) {
     child.argument(arg);
   }
   for (const option of command.spec.options ?? []) {
+    const commanderOption = option.hidden ? new Option(option.flags, option.description).hideHelp() : null;
     if (option.parse) {
-      child.option(option.flags, option.description, option.parse);
+      if (commanderOption) {
+        commanderOption.argParser(option.parse);
+        child.addOption(commanderOption);
+      } else {
+        child.option(option.flags, option.description, option.parse);
+      }
+    } else if (commanderOption) {
+      child.addOption(commanderOption);
     } else {
       child.option(option.flags, option.description);
     }
@@ -48858,8 +48921,19 @@ function parseRegularChannelTarget(target) {
   const name = target.slice(1).trim();
   return name.length > 0 ? name : null;
 }
-function formatLeaveChannelResult(target) {
-  return `Left ${target}. You can still inspect visible public channel history there, but you can no longer send or receive ordinary channel delivery until you join the public channel again or a human re-adds you to a private channel.`;
+function formatLeaveChannelResult(target, result2) {
+  const lines = [
+    `Left ${target}. You can still inspect visible public channel history there, but you can no longer send or receive ordinary channel delivery until you join the public channel again or a human re-adds you to a private channel.`
+  ];
+  if (result2?.attention?.ordinaryActivity) lines.push(result2.attention.ordinaryActivity);
+  if (result2?.attention?.stillArrives?.length) {
+    lines.push("Still arrives:");
+    for (const item of result2.attention.stillArrives) lines.push(`- ${item}`);
+  }
+  if (result2?.attention?.threadBoundary) lines.push(result2.attention.threadBoundary);
+  if (result2?.attention?.manageCommand) lines.push(`To stop a followed thread: ${result2.attention.manageCommand}`);
+  if (result2?.attention?.manageApi) lines.push(`Agent API: ${result2.attention.manageApi}`);
+  return lines.join("\n");
 }
 function formatAlreadyNotJoined(target) {
   return `Already not joined in ${target}.`;
@@ -48914,7 +48988,7 @@ var channelLeaveCommand = defineCommand(
         message: leaveRes.error ?? `HTTP ${leaveRes.status}`
       });
     }
-    writeText(ctx.io, formatLeaveChannelResult(target) + "\n");
+    writeText(ctx.io, formatLeaveChannelResult(target, leaveRes.data ?? void 0) + "\n");
   }
 );
 function registerChannelLeaveCommand(parent, runtimeOptions) {
@@ -49228,9 +49302,19 @@ init_esm_shims();
 function normalizeHandle2(raw) {
   return (raw ?? "").trim().replace(/^@/, "");
 }
-function formatRemoveMemberResult(target, memberName, wasMember) {
+function formatRemoveMemberResult(target, memberName, wasMember, result2) {
   const member = `@${memberName}`;
-  return wasMember ? `Removed ${member} from ${target}.` : `${member} was not in ${target}.`;
+  if (!wasMember) return `${member} was not in ${target}.`;
+  const lines = [`Removed ${member} from ${target}.`];
+  if (result2?.attention?.ordinaryActivity) lines.push(result2.attention.ordinaryActivity);
+  if (result2?.attention?.stillArrives?.length) {
+    lines.push("Still arrives:");
+    for (const item of result2.attention.stillArrives) lines.push(`- ${item}`);
+  }
+  if (result2?.attention?.threadBoundary) lines.push(result2.attention.threadBoundary);
+  if (result2?.attention?.manageCommand) lines.push(`To stop a followed thread: ${result2.attention.manageCommand}`);
+  if (result2?.attention?.manageApi) lines.push(`Agent API: ${result2.attention.manageApi}`);
+  return lines.join("\n");
 }
 var channelRemoveMemberCommand = defineCommand(
   {
@@ -49300,7 +49384,7 @@ var channelRemoveMemberCommand = defineCommand(
       });
     }
     const memberName = removeRes.data?.member?.name ?? (user || agent);
-    writeText(ctx.io, formatRemoveMemberResult(target, memberName, removeRes.data?.wasMember === true) + "\n");
+    writeText(ctx.io, formatRemoveMemberResult(target, memberName, removeRes.data?.wasMember === true, removeRes.data ?? void 0) + "\n");
   }
 );
 function registerChannelRemoveMemberCommand(parent, runtimeOptions) {
@@ -50084,11 +50168,13 @@ var knowledgeGetCommand = defineCommand(
       },
       {
         flags: "--turn-id <id>",
-        description: "Optional turn id for correlation in the knowledge event"
+        description: "Diagnostic: override the turn id recorded on the knowledge event",
+        hidden: true
       },
       {
         flags: "--trace-id <id>",
-        description: "Optional trace id for correlation in the knowledge event"
+        description: "Diagnostic: override the trace id recorded on the knowledge event",
+        hidden: true
       }
     ],
     helpAfter: "\nTopics:\n  Run `raft manual get index` to list available manual topics.\n"
@@ -50168,11 +50254,13 @@ var knowledgeSearchCommand = defineCommand(
       },
       {
         flags: "--turn-id <id>",
-        description: "Optional turn id for correlation in the knowledge event"
+        description: "Diagnostic: override the turn id recorded on the knowledge event",
+        hidden: true
       },
       {
         flags: "--trace-id <id>",
-        description: "Optional trace id for correlation in the knowledge event"
+        description: "Diagnostic: override the trace id recorded on the knowledge event",
+        hidden: true
       }
     ],
     helpAfter: '\nExamples:\n  raft manual search "preview before merge" --scope recipes\n  raft manual get recipes/technique/preview-env\n'
@@ -53436,6 +53524,15 @@ function safeUrl2(value, label) {
   }
   return url2;
 }
+function substituteEndpointPathParams(endpointPath, payload) {
+  return endpointPath.replace(/\{([A-Za-z][A-Za-z0-9_]*)\}/g, (_match, name) => {
+    const value = payload[name];
+    if (value === void 0 || value === null || value === "") {
+      throw cliError("INVALID_ARG", `missing path parameter ${name}`);
+    }
+    return encodeURIComponent(typeof value === "string" ? value : JSON.stringify(value));
+  });
+}
 function resolveActionUrl(input) {
   const base = input.manifest.execution.base_url ?? input.manifest.app_origin ?? input.service.homepageUrl ?? (input.service.returnUrl ? safeUrl2(input.service.returnUrl, "service return URL").origin : null);
   if (!base) {
@@ -53445,7 +53542,7 @@ function resolveActionUrl(input) {
     );
   }
   const baseUrl = safeUrl2(base, "action base URL");
-  return new URL(input.action.endpoint.path, baseUrl);
+  return new URL(substituteEndpointPathParams(input.action.endpoint.path, input.payload), baseUrl);
 }
 function appendPayloadAsQuery(url2, payload) {
   for (const [key, value] of Object.entries(payload)) {
@@ -53453,6 +53550,13 @@ function appendPayloadAsQuery(url2, payload) {
     url2.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
   }
 }
+function appendResourceLocatorQuery(input) {
+  const { url: url2, action, payload } = input;
+  if (/\{id\}/.test(action.endpoint.path)) return;
+  const id = payload.id;
+  if (id === void 0 || id === null || id === "" || url2.searchParams.has("id")) return;
+  url2.searchParams.set("id", typeof id === "string" ? id : JSON.stringify(id));
+}
 async function invokeHttpAction(input) {
   const url2 = new URL(input.url);
   const cookie = cookieHeaderForUrl(input.cookies, url2);
@@ -53474,6 +53578,7 @@ async function invokeHttpAction(input) {
   if (input.action.endpoint.method === "GET") {
     appendPayloadAsQuery(url2, input.payload);
   } else {
+    appendResourceLocatorQuery({ url: url2, action: input.action, payload: input.payload });
     headers["content-type"] = "application/json";
     init.body = JSON.stringify(input.payload);
   }
@@ -53530,6 +53635,9 @@ function formatActions(input) {
     lines.push(`  endpoint: ${action.endpoint.method} ${action.endpoint.path}`);
     if (action.description) lines.push(`  description: ${action.description}`);
     if (required2.length > 0) lines.push(`  required params: ${required2.join(", ")}`);
+    if (action.endpoint.method !== "GET" && Object.hasOwn(action.parameters ?? {}, "id") && !/\{id\}/.test(action.endpoint.path)) {
+      lines.push("  note: id is treated as the resource locator and is also sent as query ?id=; JSON body is preserved");
+    }
   }
   lines.push(`next: raft integration invoke --service ${JSON.stringify(input.service.clientId)} --action ${JSON.stringify(actions[0]?.name ?? "<name>")}`);
   return lines.join("\n");
@@ -53639,7 +53747,7 @@ var integrationInvokeCommand = defineCommand(
       { flags: "--list-actions", description: "List manifest actions instead of invoking one" },
       {
         flags: "--param <key=value>",
-        description: "Action parameter; repeatable. Use key=@file or key=@- to read text",
+        description: "Action parameter; repeatable. Use key=@file or key=@- to read text. For non-GET actions, id is also sent as query ?id= when the manifest path has no {id}",
         parse: (value, previous = []) => {
           previous.push(value);
           return previous;
@@ -53767,7 +53875,7 @@ var integrationInvokeCommand = defineCommand(
       });
       cookies = session.cookies;
     }
-    const url2 = resolveActionUrl({ service, manifest, action });
+    const url2 = resolveActionUrl({ service, manifest, action, payload });
     const result2 = await invokeHttpAction({ url: url2, action, payload, cookies, service });
     if (opts.json) {
       writeJson(cmdCtx.io, {
@@ -54383,7 +54491,10 @@ registerServerInfoCommand(serverCmd);
 registerServerUpdateCommand(serverCmd);
 var userCmd = program2.command("user").description("User and agent introspection");
 registerUserInfoCommand(userCmd);
-var manualCmd = program2.command("manual").description("Raft Manual for Agents retrieval (canonical operating topics)");
+var manualCmd = program2.command("manual").description("Look up Raft operating topics and agent recipes").addHelpText(
+  "after",
+  '\nCommon agent flows:\n  raft manual get index\n  raft manual get recipes/seeded\n  raft manual get recipes/technique/preview-env\n  raft manual search "preview before merge" --scope recipes\n\nUse `raft manual get --help` and `raft manual search --help` for options.\n'
+);
 registerKnowledgeGetCommand(manualCmd);
 registerKnowledgeSearchCommand(manualCmd);
 var knowledgeCmd = program2.command("knowledge").description("Legacy alias for `raft manual`");

package/dist/cli/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@botiverse/raft",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "type": "module"
 }

package/dist/core.js

@@ -16,7 +16,7 @@ import {
   runBundledSlockCli,
   scanWorkspaceDirectories,
   subscribeDaemonLogs
-} from "./chunk-VZWVYMUX.js";
+} from "./chunk-YAI5OK4D.js";
 export {
   AGENT_MIGRATION_BUNDLE_SCHEMA_VERSION,
   AgentMigrationGrantRegistry,

package/dist/{dist-R2LWKKE2.js → dist-UCGBT6NS.js}

@@ -42463,6 +42463,9 @@ function validateActionCardAction(action) {
   return null;
 }
 init_esm_shims();
+init_esm_shims();
+var ATTENTION_HINT_SCHEMA = "attention-dependency-hint.v1";
+var ATTENTION_HINT_DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
 var AGENT_API_BASE_PATH = "/internal/agent-api";
 var optionalStringSchema = external_exports.string().trim().optional();
 var optionalStringArraySchema = external_exports.array(external_exports.string().trim().min(1)).optional();
@@ -42989,8 +42992,17 @@ var agentApiSendResponseSchema = external_exports.discriminatedUnion("state", [
 var agentApiMessageResolveResponseSchema = passthroughObject({
   message: agentApiMessageEnvelopeSchema
 });
+var agentApiChannelAttentionSchema = passthroughObject({
+  state: optionalStringSchema,
+  ordinaryActivity: optionalStringSchema,
+  stillArrives: optionalStringArraySchema,
+  threadBoundary: optionalStringSchema,
+  manageCommand: optionalStringSchema,
+  manageApi: optionalStringSchema
+});
 var agentApiOkResponseSchema = passthroughObject({
-  ok: external_exports.literal(true)
+  ok: external_exports.literal(true),
+  attention: agentApiChannelAttentionSchema.optional()
 });
 var agentApiSearchResultSchema = passthroughObject({
   id: external_exports.string(),
@@ -43047,6 +43059,16 @@ var agentApiChannelMuteResponseSchema = passthroughObject({
     catchUp: optionalStringSchema
   }).optional()
 });
+var agentApiChannelMuteBodySchema = passthroughObject({
+  attentionHintAccepted: passthroughObject({
+    schema: external_exports.literal(ATTENTION_HINT_SCHEMA),
+    trigger: external_exports.enum(["M2", "M3"]),
+    scope: external_exports.string().trim().min(1),
+    suggested_command: optionalStringSchema,
+    copy_version: external_exports.string().trim().min(1),
+    epoch_ms: external_exports.number().int().nonnegative()
+  }).optional()
+});
 var agentApiTaskClaimResultSchema = passthroughObject({
   taskNumber: external_exports.number().int().positive().optional(),
   messageId: optionalStringSchema,
@@ -43256,7 +43278,7 @@ var agentApiContract = {
     client: { resource: "channels", method: "mute" },
     capability: "channels",
     description: "Mute ordinary activity delivery for a visible regular channel as the bound agent credential.",
-    request: { params: agentApiChannelMembershipParamsSchema },
+    request: { params: agentApiChannelMembershipParamsSchema, body: agentApiChannelMuteBodySchema },
     response: { body: agentApiChannelMuteResponseSchema }
   }),
   channelUnmute: route({
@@ -43902,6 +43924,20 @@ var optionalQueryIntSchema = external_exports.union([external_exports.number().i
 var nullableNumberSchema2 = external_exports.number().finite().nullable();
 var passthroughObject2 = (shape) => external_exports.object(shape).passthrough();
 var daemonApiInboxFlagSchema = external_exports.enum(["mention", "thread", "dm", "task"]);
+var daemonApiAttentionHintSchema = passthroughObject2({
+  schema: external_exports.literal(ATTENTION_HINT_SCHEMA),
+  trigger: external_exports.enum(["M2", "M3"]),
+  scope: external_exports.string().trim().min(1),
+  suggested_command: external_exports.string().trim().min(1),
+  copy: external_exports.string().trim().min(1),
+  copy_version: external_exports.literal("attention-hint-copy-v1"),
+  epoch_ms: external_exports.number().int().nonnegative(),
+  thresholds: passthroughObject2({
+    K: optionalNonNegativeIntSchema,
+    k: optionalNonNegativeIntSchema,
+    window_ms: external_exports.number().int().positive()
+  })
+});
 var daemonApiInboxTargetRowSchema = passthroughObject2({
   target: external_exports.string().trim().min(1),
   channelId: optionalStringSchema2,
@@ -43912,8 +43948,9 @@ var daemonApiInboxTargetRowSchema = passthroughObject2({
   latestMsgId: optionalStringSchema2,
   latestSeq: optionalNonNegativeIntSchema,
   latestSenderName: optionalStringSchema2,
-  latestSenderType: external_exports.enum(["human", "agent", "system"]).optional(),
-  flags: external_exports.array(daemonApiInboxFlagSchema)
+  latestSenderType: external_exports.enum(["human", "agent", "system", "third_party_app"]).optional(),
+  flags: external_exports.array(daemonApiInboxFlagSchema),
+  attentionHint: daemonApiAttentionHintSchema.optional()
 });
 var daemonApiInboxCheckResponseSchema = passthroughObject2({
   rows: external_exports.array(daemonApiInboxTargetRowSchema).optional()
@@ -43936,6 +43973,7 @@ var daemonApiWakeHintSchema = passthroughObject2({
   target_type: optionalStringSchema2,
   reason: optionalStringSchema2,
   wake_reason: optionalStringSchema2,
+  attention_hint: daemonApiAttentionHintSchema.optional(),
   createdAt: optionalStringSchema2,
   created_at: optionalStringSchema2
 });
@@ -44283,6 +44321,7 @@ function formatAgentInboxRowDetails(row) {
   if (row.latestSenderName) parts.push(`latest sender @${row.latestSenderName}`);
   if (row.latestMsgId) parts.push(`latest msg=${shortMessageId(row.latestMsgId)}`);
   parts.push(...row.flags.map(formatAgentInboxFlag));
+  if (row.attentionHint) parts.push(`attention_hint=${formatAttentionHintField(row.attentionHint)}`);
   return parts.join(" \xB7 ");
 }
 function formatAgentInboxFlag(flag) {
@@ -44292,6 +44331,18 @@ function formatAgentInboxFlag(flag) {
 function shortMessageId(value) {
   return value.slice(0, 8);
 }
+function formatAttentionHintField(hint) {
+  return JSON.stringify({
+    schema: hint.schema,
+    trigger: hint.trigger,
+    scope: hint.scope,
+    suggested_command: hint.suggested_command,
+    copy: hint.copy,
+    copy_version: hint.copy_version,
+    epoch_ms: hint.epoch_ms,
+    thresholds: hint.thresholds
+  });
+}
 init_esm_shims();
 var EXTERNAL_AGENT_COMMS_PROTOCOL_VERSION = "agent-comms-core.v1";
 var EXTERNAL_AGENT_PROOF_SCHEMA_VERSION = "agent-proof.v1";
@@ -44664,9 +44715,9 @@ function isExternalAgentRuntime(runtime) {
   return runtime === EXTERNAL_AGENT_RUNTIME_ID;
 }
 var RUNTIMES = [
-  { id: "builtin", displayName: "Built-in", binary: "", supported: true },
   { id: "claude", displayName: "Claude Code", binary: "claude", supported: true },
   { id: "codex", displayName: "Codex CLI", binary: "codex", supported: true },
+  { id: "builtin", displayName: "Builtin Pi", binary: "", supported: true },
   { id: "antigravity", displayName: "Antigravity CLI", binary: "agy", supported: true },
   // Kimi: prefer the in-process SDK (`kimi-sdk` → "Kimi Code") for new agents.
   // The legacy `kimi` (kimi-cli child-process) entry stays for backward compat
@@ -45052,7 +45103,7 @@ function createAgentApiSurfaceClient(client) {
     channels: {
       join: (params) => requestClientAsApiResponse(agentApi.channels.join(params)),
       leave: (params) => requestClientAsApiResponse(agentApi.channels.leave(params)),
-      mute: (params) => requestClientAsApiResponse(agentApi.channels.mute(params)),
+      mute: (params) => requestClientAsApiResponse(agentApi.channels.mute(params, {})),
       unmute: (params) => requestClientAsApiResponse(agentApi.channels.unmute(params)),
       members: (query) => requestClientAsApiResponse(agentApi.channels.members(query)),
       resolve: (body) => requestClientAsApiResponse(agentApi.channels.resolve(body))
@@ -45781,8 +45832,16 @@ function registerCliCommand(parent, command, runtimeOptions = {}) {
     child.argument(arg);
   }
   for (const option of command.spec.options ?? []) {
+    const commanderOption = option.hidden ? new Option(option.flags, option.description).hideHelp() : null;
     if (option.parse) {
-      child.option(option.flags, option.description, option.parse);
+      if (commanderOption) {
+        commanderOption.argParser(option.parse);
+        child.addOption(commanderOption);
+      } else {
+        child.option(option.flags, option.description, option.parse);
+      }
+    } else if (commanderOption) {
+      child.addOption(commanderOption);
     } else {
       child.option(option.flags, option.description);
     }
@@ -48312,8 +48371,19 @@ function parseRegularChannelTarget(target) {
   const name = target.slice(1).trim();
   return name.length > 0 ? name : null;
 }
-function formatLeaveChannelResult(target) {
-  return `Left ${target}. You can still inspect visible public channel history there, but you can no longer send or receive ordinary channel delivery until you join the public channel again or a human re-adds you to a private channel.`;
+function formatLeaveChannelResult(target, result2) {
+  const lines = [
+    `Left ${target}. You can still inspect visible public channel history there, but you can no longer send or receive ordinary channel delivery until you join the public channel again or a human re-adds you to a private channel.`
+  ];
+  if (result2?.attention?.ordinaryActivity) lines.push(result2.attention.ordinaryActivity);
+  if (result2?.attention?.stillArrives?.length) {
+    lines.push("Still arrives:");
+    for (const item of result2.attention.stillArrives) lines.push(`- ${item}`);
+  }
+  if (result2?.attention?.threadBoundary) lines.push(result2.attention.threadBoundary);
+  if (result2?.attention?.manageCommand) lines.push(`To stop a followed thread: ${result2.attention.manageCommand}`);
+  if (result2?.attention?.manageApi) lines.push(`Agent API: ${result2.attention.manageApi}`);
+  return lines.join("\n");
 }
 function formatAlreadyNotJoined(target) {
   return `Already not joined in ${target}.`;
@@ -48368,7 +48438,7 @@ var channelLeaveCommand = defineCommand(
         message: leaveRes.error ?? `HTTP ${leaveRes.status}`
       });
     }
-    writeText(ctx.io, formatLeaveChannelResult(target) + "\n");
+    writeText(ctx.io, formatLeaveChannelResult(target, leaveRes.data ?? void 0) + "\n");
   }
 );
 function registerChannelLeaveCommand(parent, runtimeOptions) {
@@ -48672,9 +48742,19 @@ init_esm_shims();
 function normalizeHandle2(raw) {
   return (raw ?? "").trim().replace(/^@/, "");
 }
-function formatRemoveMemberResult(target, memberName, wasMember) {
+function formatRemoveMemberResult(target, memberName, wasMember, result2) {
   const member = `@${memberName}`;
-  return wasMember ? `Removed ${member} from ${target}.` : `${member} was not in ${target}.`;
+  if (!wasMember) return `${member} was not in ${target}.`;
+  const lines = [`Removed ${member} from ${target}.`];
+  if (result2?.attention?.ordinaryActivity) lines.push(result2.attention.ordinaryActivity);
+  if (result2?.attention?.stillArrives?.length) {
+    lines.push("Still arrives:");
+    for (const item of result2.attention.stillArrives) lines.push(`- ${item}`);
+  }
+  if (result2?.attention?.threadBoundary) lines.push(result2.attention.threadBoundary);
+  if (result2?.attention?.manageCommand) lines.push(`To stop a followed thread: ${result2.attention.manageCommand}`);
+  if (result2?.attention?.manageApi) lines.push(`Agent API: ${result2.attention.manageApi}`);
+  return lines.join("\n");
 }
 var channelRemoveMemberCommand = defineCommand(
   {
@@ -48744,7 +48824,7 @@ var channelRemoveMemberCommand = defineCommand(
       });
     }
     const memberName = removeRes.data?.member?.name ?? (user || agent);
-    writeText(ctx.io, formatRemoveMemberResult(target, memberName, removeRes.data?.wasMember === true) + "\n");
+    writeText(ctx.io, formatRemoveMemberResult(target, memberName, removeRes.data?.wasMember === true, removeRes.data ?? void 0) + "\n");
   }
 );
 function registerChannelRemoveMemberCommand(parent, runtimeOptions) {
@@ -49506,11 +49586,13 @@ var knowledgeGetCommand = defineCommand(
       },
       {
         flags: "--turn-id <id>",
-        description: "Optional turn id for correlation in the knowledge event"
+        description: "Diagnostic: override the turn id recorded on the knowledge event",
+        hidden: true
       },
       {
         flags: "--trace-id <id>",
-        description: "Optional trace id for correlation in the knowledge event"
+        description: "Diagnostic: override the trace id recorded on the knowledge event",
+        hidden: true
       }
     ],
     helpAfter: "\nTopics:\n  Run `raft manual get index` to list available manual topics.\n"
@@ -49588,11 +49670,13 @@ var knowledgeSearchCommand = defineCommand(
       },
       {
         flags: "--turn-id <id>",
-        description: "Optional turn id for correlation in the knowledge event"
+        description: "Diagnostic: override the turn id recorded on the knowledge event",
+        hidden: true
       },
       {
         flags: "--trace-id <id>",
-        description: "Optional trace id for correlation in the knowledge event"
+        description: "Diagnostic: override the trace id recorded on the knowledge event",
+        hidden: true
       }
     ],
     helpAfter: '\nExamples:\n  raft manual search "preview before merge" --scope recipes\n  raft manual get recipes/technique/preview-env\n'
@@ -52748,6 +52832,15 @@ function safeUrl2(value, label) {
   }
   return url2;
 }
+function substituteEndpointPathParams(endpointPath, payload) {
+  return endpointPath.replace(/\{([A-Za-z][A-Za-z0-9_]*)\}/g, (_match, name) => {
+    const value = payload[name];
+    if (value === void 0 || value === null || value === "") {
+      throw cliError("INVALID_ARG", `missing path parameter ${name}`);
+    }
+    return encodeURIComponent(typeof value === "string" ? value : JSON.stringify(value));
+  });
+}
 function resolveActionUrl(input) {
   const base = input.manifest.execution.base_url ?? input.manifest.app_origin ?? input.service.homepageUrl ?? (input.service.returnUrl ? safeUrl2(input.service.returnUrl, "service return URL").origin : null);
   if (!base) {
@@ -52757,7 +52850,7 @@ function resolveActionUrl(input) {
     );
   }
   const baseUrl = safeUrl2(base, "action base URL");
-  return new URL(input.action.endpoint.path, baseUrl);
+  return new URL(substituteEndpointPathParams(input.action.endpoint.path, input.payload), baseUrl);
 }
 function appendPayloadAsQuery(url2, payload) {
   for (const [key, value] of Object.entries(payload)) {
@@ -52765,6 +52858,13 @@ function appendPayloadAsQuery(url2, payload) {
     url2.searchParams.set(key, typeof value === "string" ? value : JSON.stringify(value));
   }
 }
+function appendResourceLocatorQuery(input) {
+  const { url: url2, action, payload } = input;
+  if (/\{id\}/.test(action.endpoint.path)) return;
+  const id = payload.id;
+  if (id === void 0 || id === null || id === "" || url2.searchParams.has("id")) return;
+  url2.searchParams.set("id", typeof id === "string" ? id : JSON.stringify(id));
+}
 async function invokeHttpAction(input) {
   const url2 = new URL(input.url);
   const cookie = cookieHeaderForUrl(input.cookies, url2);
@@ -52786,6 +52886,7 @@ async function invokeHttpAction(input) {
   if (input.action.endpoint.method === "GET") {
     appendPayloadAsQuery(url2, input.payload);
   } else {
+    appendResourceLocatorQuery({ url: url2, action: input.action, payload: input.payload });
     headers["content-type"] = "application/json";
     init.body = JSON.stringify(input.payload);
   }
@@ -52842,6 +52943,9 @@ function formatActions(input) {
     lines.push(`  endpoint: ${action.endpoint.method} ${action.endpoint.path}`);
     if (action.description) lines.push(`  description: ${action.description}`);
     if (required2.length > 0) lines.push(`  required params: ${required2.join(", ")}`);
+    if (action.endpoint.method !== "GET" && Object.hasOwn(action.parameters ?? {}, "id") && !/\{id\}/.test(action.endpoint.path)) {
+      lines.push("  note: id is treated as the resource locator and is also sent as query ?id=; JSON body is preserved");
+    }
   }
   lines.push(`next: raft integration invoke --service ${JSON.stringify(input.service.clientId)} --action ${JSON.stringify(actions[0]?.name ?? "<name>")}`);
   return lines.join("\n");
@@ -52951,7 +53055,7 @@ var integrationInvokeCommand = defineCommand(
       { flags: "--list-actions", description: "List manifest actions instead of invoking one" },
       {
         flags: "--param <key=value>",
-        description: "Action parameter; repeatable. Use key=@file or key=@- to read text",
+        description: "Action parameter; repeatable. Use key=@file or key=@- to read text. For non-GET actions, id is also sent as query ?id= when the manifest path has no {id}",
         parse: (value, previous = []) => {
           previous.push(value);
           return previous;
@@ -53079,7 +53183,7 @@ var integrationInvokeCommand = defineCommand(
       });
       cookies = session.cookies;
     }
-    const url2 = resolveActionUrl({ service, manifest, action });
+    const url2 = resolveActionUrl({ service, manifest, action, payload });
     const result2 = await invokeHttpAction({ url: url2, action, payload, cookies, service });
     if (opts.json) {
       writeJson(cmdCtx.io, {
@@ -53667,7 +53771,10 @@ registerServerInfoCommand(serverCmd);
 registerServerUpdateCommand(serverCmd);
 var userCmd = program2.command("user").description("User and agent introspection");
 registerUserInfoCommand(userCmd);
-var manualCmd = program2.command("manual").description("Raft Manual for Agents retrieval (canonical operating topics)");
+var manualCmd = program2.command("manual").description("Look up Raft operating topics and agent recipes").addHelpText(
+  "after",
+  '\nCommon agent flows:\n  raft manual get index\n  raft manual get recipes/seeded\n  raft manual get recipes/technique/preview-env\n  raft manual search "preview before merge" --scope recipes\n\nUse `raft manual get --help` and `raft manual search --help` for options.\n'
+);
 registerKnowledgeGetCommand(manualCmd);
 registerKnowledgeSearchCommand(manualCmd);
 var knowledgeCmd = program2.command("knowledge").description("Legacy alias for `raft manual`");

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   DAEMON_CLI_USAGE,
   DaemonCore,
   parseDaemonCliArgs
-} from "./chunk-VZWVYMUX.js";
+} from "./chunk-YAI5OK4D.js";
 
 // src/index.ts
 var parsedArgs = parseDaemonCliArgs(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-daemon",
-  "version": "0.71.0",
+  "version": "0.72.0",
   "type": "module",
   "bin": {
     "raft-daemon": "dist/raft-daemon.js",