@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/coach.mjs

@@ -1,771 +1,771 @@
-/**
- * Tool family: Fully Booked Coach operations.
- *
- * The coach profile contains only coach relevant tools. Draft and preview tools
- * never send or publish. Paid scouting keeps the existing price then confirm gate.
- */
-import { projectCoachBookConnectorResult } from '../coach-book-output-guard.mjs';
-import { z } from 'zod';
-
-export const FAMILY = 'coach';
-
-export const TOOLS = [
-  'km_coach_context',
-  'km_coach_method',
-  'km_coach_ask_book',
-  'km_coach_book_catalog',
-  'km_coach_book_recommend',
-  'km_coach_book_tool',
-  'km_coach_niche_fit',
-  'km_coach_daily_operator',
-  'km_coach_list_clients',
-  'km_coach_create_client',
-
-  'km_coach_list_records',
-  'km_coach_create_client_map',
-  'km_coach_revise_record',
-
-  'km_coach_write_record',
-
-  'km_coach_stalled_opportunities',
-  'km_coach_preview_action',
-  'km_coach_decide_action',
-
-  'km_coach_submit_daily_cookie',
-  'km_coach_run_scout',
-  'km_coach_list_scouts',
-  'km_coach_scout_status',
-  'km_coach_stop_scout',
-  'km_coach_record_scout_finding',
-  'km_coach_promote_scout_finding',
-];
-
-export const PROFILES = ['coach'];
-
-const COACH_METHOD_WORKFLOWS = [
-  'method_boundary',
-  'niche',
-  'capacity',
-  'acquisition',
-  'authority_content',
-  'strategy_session',
-  'client_map',
-  'renewal_referral_proof',
-  'scouting',
-];
-const COACH_OBJECT_TYPES = [
-  'CoachOperatingBrief', 'MethodologyActivation', 'CapacityPolicy', 'FullyBookedThreshold',
-  'NicheHypothesis', 'NicheScorecard', 'Offer', 'Program', 'Cohort', 'Channel', 'Integration',
-  'Relationship', 'ProspectProfile', 'Opportunity', 'PipelineStage', 'ScoutRun', 'ScoutFinding',
-  'Collaboration', 'ReferralPartner', 'AudienceSegment', 'GrowthSprint', 'Campaign', 'LeadMagnet',
-  'Tripwire', 'Engagement', 'ClientMAP', 'Session', 'SessionPreparation', 'Commitment', 'Outcome',
-  'ResultMeasure', 'ClientHealth', 'Renewal', 'ReferralRequest', 'Testimonial', 'ProofPermission',
-  'Handover', 'ContentIdea', 'ContentAsset', 'ContentCategory', 'ContentBrief',
-  'DailyCookieRequest', 'EditorialApproval', 'PublicationRequest', 'PerformanceObservation',
-  'ConfidentialNote', 'ConsentGrant', 'SecureReference', 'ActionRequest', 'Approval',
-  'ManagedTask', 'AuditEvent', 'ExportJob', 'SyncCursor',
-];
-const COACH_WRITABLE_OBJECT_TYPES = [
-  'CoachOperatingBrief', 'CapacityPolicy', 'FullyBookedThreshold',
-  'NicheHypothesis', 'NicheScorecard', 'Offer', 'Program', 'Cohort', 'Channel', 'Integration',
-  'Relationship', 'ProspectProfile', 'Opportunity', 'PipelineStage', 'ScoutFinding',
-  'Collaboration', 'ReferralPartner', 'AudienceSegment', 'GrowthSprint', 'Campaign', 'LeadMagnet',
-  'Tripwire', 'Engagement', 'Session', 'SessionPreparation', 'Commitment', 'Outcome',
-  'ResultMeasure', 'ClientHealth', 'Renewal', 'ReferralRequest', 'Testimonial', 'Handover',
-  'ContentIdea', 'ContentAsset', 'ContentCategory', 'ContentBrief', 'PerformanceObservation',
-  'ConfidentialNote', 'ManagedTask',
-];
-
-const SCOUT_MODES = [
-  'micro-niche-mapper',
-  'niche-validation-scout',
-  'collaborator-scout',
-  'ideal-client-twin-scout',
-  'past-client-opportunity-scout',
-  'referral-path-scout',
-  'ideal-client-scout',
-  'niche-and-growth-scout',
-  'ideal-organization-and-partner-scout',
-  'ideal-person-and-influencer-scout',
-  'podcast-collaboration-scout',
-];
-
-const PUBLIC_SCOUT_MODES = new Set([
-  'micro-niche-mapper',
-  'niche-validation-scout',
-  'collaborator-scout',
-  'ideal-client-twin-scout',
-  'ideal-client-scout',
-  'niche-and-growth-scout',
-  'ideal-organization-and-partner-scout',
-  'ideal-person-and-influencer-scout',
-  'podcast-collaboration-scout',
-]);
-
-const MODE_DIRECTION = {
-  'micro-niche-mapper': 'Map a broad market into specific groups that share context and an urgent problem.',
-  'niche-validation-scout': 'Find public evidence that the niche problem is urgent, reachable, and valuable.',
-  'collaborator-scout': 'Find people or organizations with a complementary offer and an aligned audience.',
-  'ideal-client-twin-scout': 'Find public prospects that match approved nonconfidential attributes of a strong client.',
-  'ideal-client-scout': 'Find public prospects that match the coach niche and offer.',
-  'niche-and-growth-scout': 'Find niche groups and practical audience growth paths.',
-  'ideal-organization-and-partner-scout': 'Find organizations and partners with a strong group and problem match.',
-  'ideal-person-and-influencer-scout': 'Find people and influencers who reach the coach niche.',
-  'podcast-collaboration-scout': 'Find podcasts where a useful collaboration fits the audience problem.',
-};
-
-const NICHE_EVIDENCE_REFERENCE = z.object({
-  id: z.string().min(1).max(80),
-  url: z.string().url().refine((value) => value.startsWith('https://'), 'Use one public HTTPS evidence URL.'),
-  observedAt: z.string().min(10).max(64),
-  summary: z.string().min(1).max(1000),
-  kind: z.enum(['direct', 'analogue', 'counterevidence']),
-}).strict();
-
-const NICHE_PREDICATE = z.object({
-  grade: z.union([z.literal(0), z.literal(0.5), z.literal(1)]),
-  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
-  rationale: z.string().min(1).max(1000),
-}).strict();
-
-const NICHE_COUNTEREVIDENCE = z.object({
-  query: z.string().min(1).max(500),
-  checkedAt: z.string().min(10).max(64),
-  outcome: z.enum(['none_found', 'found', 'inconclusive']),
-  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
-}).strict();
-
-const NICHE_FALSE_POSITIVE = z.object({
-  observed: z.boolean(),
-  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
-  note: z.string().max(1000),
-}).strict();
-
-function nicheDimension(predicates) {
-  return z.object({
-    predicates: z.object(Object.fromEntries(
-      predicates.map((predicate) => [predicate, NICHE_PREDICATE]),
-    )).strict(),
-    counterevidenceChecks: z.array(NICHE_COUNTEREVIDENCE).min(1).max(20),
-    falsePositive: NICHE_FALSE_POSITIVE,
-  }).strict();
-}
-
-const NICHE_FIT_INPUT = z.object({
-  toolSpecId: z.literal('fbc.niche-fit.v1'),
-  asOf: z.string().min(10).max(64),
-  hypothesis: z.object({
-    proposedPodcastNiche: z.string().min(1).max(500),
-    strategy: z.enum(['smaller_group', 'specific_problem', 'both']),
-    specificGroup: z.string().min(1).max(500).optional(),
-    specificProblem: z.string().min(1).max(500).optional(),
-    collaboratorProfile: z.string().min(1).max(1000),
-    podcastWorkingTitle: z.string().min(1).max(500),
-    collaborationHook: z.string().min(1).max(1000),
-    valueExchangeOffer: z.string().min(1).max(1000),
-    geography: z.string().min(1).max(200).optional(),
-    language: z.string().min(1).max(100).optional(),
-  }).strict(),
-  evidence: z.array(NICHE_EVIDENCE_REFERENCE).min(1).max(120),
-  dimensions: z.object({
-    findability: nicheDimension([
-      'discoverable_collaborators',
-      'reachable_contact_path',
-      'compelling_collaboration_offer',
-      'weekly_yes_pace',
-    ]),
-    bragability: nicheDimension([
-      'show_up_likelihood',
-      'compelling_story_hook',
-      'positive_status_association',
-      'share_behavior',
-    ]),
-    sellability: nicheDimension([
-      'reachable_owned_audience',
-      'specific_value_exchange',
-      'offer_through_collaboration',
-      'audience_response',
-    ]),
-  }).strict(),
-}).strict();
-
-function routeMissing(result) {
-  return result.status === 404 || result.status === 405 || result.status === 501;
-}
-
-const COACH_NOT_READY =
-  'The Fully Booked Coach managed routes are not deployed for this workspace yet. Nothing changed. Use draft mode and ask the operator to finish the coach migration and API deployment.';
-const COACH_BOOK_UNSAFE =
-  'KMHub rejected an unsafe Book OS response. Nothing changed.';
-
-function coachOut(result, out, text) {
-  return routeMissing(result) ? text(COACH_NOT_READY, true) : out(result);
-}
-
-function coachBookOut(result, kind, out, text) {
-  if (routeMissing(result)) return text(COACH_NOT_READY, true);
-  try {
-    return out(projectCoachBookConnectorResult(kind, result));
-  } catch {
-    return text(COACH_BOOK_UNSAFE, true);
-  }
-}
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_coach_context',
-    'Load the connected Fully Booked Coach workspace, method stage, capacity boundaries, privacy defaults, record counts, and tenant identity. Call this first in a coach conversation. It reads only and never changes anything.',
-    {},
-    async () => coachOut(await call('GET', '/coach/context'), out, text),
-  );
-
-  server.tool(
-    'km_coach_method',
-    'Load verified Fully Booked Coach guidance for one exact workflow. Use after workspace context and before giving method-based advice or preparing a related write. It returns approved guidance metadata only, never protected source text, and fails closed when the private tenant cassette is not ready.',
-    {
-      workflow: z.enum(COACH_METHOD_WORKFLOWS).describe('The exact Fully Booked Coach workflow that grounds this request.'),
-    },
-    async ({ workflow }) => coachOut(
-      await call('GET', `/coach/method${qs({ workflow })}`),
-      out,
-      text,
-    ),
-  );
-  server.tool(
-    'km_coach_ask_book',
-    'Ask the Book is intentionally closed by product decision. This compatibility tool performs no retrieval, provider call, or charge. Use the method catalog to find an available workflow.',
-    {
-      question: z.string().min(4).max(1200).describe('Legacy compatibility field. Ask the Book remains closed and does not process this question.'),
-      idempotency_key: z.string().min(1).max(120).regex(/^[A-Za-z0-9][A-Za-z0-9._:]{0,119}$/).describe('Legacy compatibility field. No run is created.'),
-      quote_id: z.string().uuid().optional().describe('Legacy compatibility field. No quote is used.'),
-      confirm_token: z.string().min(1).max(4096).optional().describe('Legacy compatibility field. No confirmation is consumed.'),
-    },
-    async () => text(
-      'Ask the Book remains intentionally closed by product decision. No retrieval ran, no provider was called, and nothing was charged. Use km_coach_book_catalog to find a method and km_coach_book_tool to start, advance, resume, or cancel a run.',
-      true,
-    ),
-  );
-
-  server.tool(
-    'km_coach_book_catalog',
-    [
-      'List, search, or describe the public Fully Booked Coach method library.',
-      'Catalog and search read the managed method catalog. Describe reads one exact method id.',
-      'This tool is read-only and returns public method metadata, source page locators, availability, and public input steps.',
-    ].join(' '),
-    {
-      action: z.enum(['catalog', 'search', 'describe']).describe('Use catalog for the full library, search for a local public-metadata match, or describe for one exact method.'),
-      query: z.string().trim().min(2).max(160).optional().describe('Required only for search. Matches public ids, titles, summaries, categories, executor kinds, and statuses.'),
-      tool_spec_id: z.string().regex(/^fbc[.]method[.][0-9]{3}[.][a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe('Required only for describe. Use the exact id returned by catalog or search.'),
-    },
-    async ({ action, query, tool_spec_id }) => {
-      if (action === 'describe') {
-        if (!tool_spec_id || query) {
-          return text('Describe requires only one exact tool_spec_id. Nothing changed.', true);
-        }
-        return coachBookOut(
-          await call('GET', `/coach/book/methods/${encodeURIComponent(tool_spec_id)}`),
-          'describe',
-          out,
-          text,
-        );
-      }
-      if (tool_spec_id) {
-        return text('Catalog and search do not accept tool_spec_id. Nothing changed.', true);
-      }
-      if (action === 'catalog' && query) {
-        return text('Catalog does not accept a search query. Use the search action instead.', true);
-      }
-      if (action === 'search' && !query) {
-        return text('Search requires a query. Nothing changed.', true);
-      }
-
-      const result = await call('GET', '/coach/book/methods');
-      if (routeMissing(result)) return text(COACH_NOT_READY, true);
-      let safeResult;
-      try {
-        safeResult = projectCoachBookConnectorResult('catalog', result);
-      } catch {
-        return text(COACH_BOOK_UNSAFE, true);
-      }
-      if (!safeResult.ok || action === 'catalog') return out(safeResult);
-
-      const data = safeResult.data && typeof safeResult.data === 'object' && !Array.isArray(safeResult.data)
-        ? safeResult.data
-        : {};
-      const methods = Array.isArray(data.methods) ? data.methods : [];
-      const needle = query.trim().toLowerCase();
-      const matches = methods.filter((method) => {
-        if (!method || typeof method !== 'object' || Array.isArray(method)) return false;
-        const publicSpec = method.public_spec && typeof method.public_spec === 'object'
-          && !Array.isArray(method.public_spec)
-          ? method.public_spec
-          : {};
-        return [
-          method.tool_spec_id,
-          method.title,
-          method.summary,
-          method.category,
-          method.implementation_status,
-          method.executor_kind,
-          method.effect_class,
-          method.availability_class,
-          publicSpec.title,
-          publicSpec.summary,
-          publicSpec.category,
-          publicSpec.executorKind,
-          publicSpec.effectClass,
-        ].filter((value) => typeof value === 'string').join(' ').toLowerCase().includes(needle);
-      });
-      return out({
-        ...safeResult,
-        data: {
-          ...data,
-          methods: matches,
-          search: {
-            query: query.trim(),
-            matched: matches.length,
-            total: methods.length,
-          },
-        },
-      });
-    },
-  );
-
-  server.tool(
-    'km_coach_book_recommend',
-    [
-      'Recommend up to three public Fully Booked Coach methods for one coaching goal.',
-      'This read-only tool uses the deterministic KMHub ranker and performs no source retrieval, no provider call, no write, no charge, and no external effect.',
-      'It never exposes protected source text, source code, or skill files. Ask the Book remains closed.',
-    ].join(' '),
-    {
-      goal: z.string().trim().min(4).max(600).describe('Describe the coaching outcome or problem in plain language.'),
-      availability_scope: z.enum(['runnable_only', 'include_pending']).optional().describe('Use runnable_only by default, or include pending methods for planning visibility.'),
-      max_minutes: z.number().int().min(5).max(240).optional().describe('Optional maximum estimated method duration.'),
-      executor_kind: z.enum(['deterministic_single_step', 'guided_multi_step']).optional().describe('Optional execution-style filter.'),
-      effect_class: z.enum(['none', 'action_preview']).optional().describe('Optional effect boundary filter.'),
-    },
-    async ({
-      goal,
-      availability_scope,
-      max_minutes,
-      executor_kind,
-      effect_class,
-    }) => coachBookOut(
-      await call('GET', `/coach/book/methods/recommend${qs({
-        goal,
-        availability_scope,
-        max_minutes,
-        executor_kind,
-        effect_class,
-      })}`),
-      'recommendation',
-      out,
-      text,
-    ),
-  );
-
-  server.tool(
-    'km_coach_book_tool',
-    [
-      'Start, advance, resume, or cancel one generic Fully Booked Coach method run.',
-      'Start, advance, and cancel are confirmed zero-cost writes. Show any 409 confirmation sentence and wait for an explicit yes before retrying once with the exact returned confirm_token.',
-      'Never invent or self-confirm a token. Resume is a read-only run lookup and accepts only action plus run_id.',
-      'This tool creates only bounded method artifacts and action previews. It cannot contact, publish, spend, or perform an external connector action.',
-    ].join(' '),
-    {
-      action: z.enum(['start', 'advance', 'resume', 'cancel']),
-      tool_spec_id: z.string().regex(/^fbc[.]method[.][0-9]{3}[.][a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe('Required only for start. Use the exact method id from the catalog.'),
-      run_id: z.string().uuid().optional().describe('Required for advance, resume, and cancel.'),
-      step_id: z.string().min(1).max(80).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/).optional().describe('Required for start and advance. Use the exact current public step id.'),
-      values: z.record(z.unknown()).optional().describe('Required for start and advance. Send one bounded object containing only the current public step fields.'),
-      idempotency_key: z.string().min(1).max(96).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,95}$/).optional().describe('Required for start, advance, and cancel. Reuse it for an exact confirmation retry.'),
-      confirm_token: z.string().min(1).max(4096).optional().describe('Use only the exact token returned in a 409 response after the coach explicitly approves the displayed confirmation sentence.'),
-    },
-    async ({
-      action,
-      tool_spec_id,
-      run_id,
-      step_id,
-      values,
-      idempotency_key,
-      confirm_token,
-    }) => {
-      if (action === 'resume') {
-        if (!run_id || tool_spec_id || step_id || values || idempotency_key || confirm_token) {
-          return text('Resume accepts only action and run_id. Nothing changed.', true);
-        }
-        return coachBookOut(
-          await call('GET', `/coach/book/runs/${encodeURIComponent(run_id)}`),
-          'run',
-          out,
-          text,
-        );
-      }
-
-      if (action === 'start') {
-        if (!tool_spec_id || run_id || !step_id || !values || !idempotency_key) {
-          return text('Start requires tool_spec_id, step_id, values, and idempotency_key, with no run_id. Nothing changed.', true);
-        }
-        return coachBookOut(await call(
-          'POST',
-          `/coach/book/methods/${encodeURIComponent(tool_spec_id)}/runs`,
-          {
-            tool_spec_id,
-            step_id,
-            values,
-            idempotency_key,
-            ...(confirm_token ? { confirm_token } : {}),
-          },
-        ), 'run', out, text);
-      }
-
-      if (action === 'advance') {
-        if (!run_id || tool_spec_id || !step_id || !values || !idempotency_key) {
-          return text('Advance requires run_id, step_id, values, and idempotency_key, with no tool_spec_id. Nothing changed.', true);
-        }
-        return coachBookOut(await call(
-          'POST',
-          `/coach/book/runs/${encodeURIComponent(run_id)}/steps`,
-          {
-            step_id,
-            values,
-            idempotency_key,
-            ...(confirm_token ? { confirm_token } : {}),
-          },
-        ), 'run', out, text);
-      }
-
-      if (!run_id || tool_spec_id || step_id || values || !idempotency_key) {
-        return text('Cancel requires only run_id and idempotency_key, plus an explicit confirm_token retry when KMHub requests it. Nothing changed.', true);
-      }
-      return coachBookOut(await call(
-        'POST',
-        `/coach/book/runs/${encodeURIComponent(run_id)}/cancel`,
-        {
-          idempotency_key,
-          ...(confirm_token ? { confirm_token } : {}),
-        },
-      ), 'run', out, text);
-    },
-  );
-
-  server.tool(
-    'km_coach_daily_operator',
-    'Build today\'s operating view from client sessions, commitments, stalled opportunities, approvals, Daily Cookie work, and capacity. Use for what needs me today or a morning review. It reads only and never sends, schedules, or publishes.',
-    {},
-    async () => coachOut(await call('GET', '/coach/daily-operator'), out, text),
-  );
-
-  server.tool(
-    'km_coach_list_clients',
-    'List recent clients in this coach workspace so a named client can be resolved before reading or writing a Client MAP, session, commitment, outcome, or confidential note. It never searches another tenant.',
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many clients to return. Default 25.'),
-    },
-    async ({ limit }) => coachOut(await call('GET', `/coach/clients${qs({ limit: limit ?? 25 })}`), out, text),
-  );
-
-  server.tool(
-    'km_coach_create_client',
-    'Create one client in the connected coach workspace after confirming the person or company details. Use a stable idempotency key for this exact request. This creates only the client record. It does not create a Client MAP, engagement, invoice, message, or external action.',
-    {
-      client_type: z.enum(['individual', 'company']).optional().describe('Default individual.'),
-      first_name: z.string().min(1).max(200).describe('Required display or contact first name.'),
-      last_name: z.string().max(200).optional(),
-      company_name: z.string().max(300).optional(),
-      email: z.string().email().max(320).optional(),
-      phone: z.string().max(100).optional(),
-      notes: z.string().max(4000).optional(),
-      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact client create request.'),
-    },
-    async (args) => coachOut(await call('POST', '/coach/clients', args), out, text),
-  );
-  server.tool(
-    'km_coach_list_records',
-    'Read shared coach records from KMHub, optionally filtered by object type, exact client, or lifecycle state. Use for Client MAPs, sessions, commitments, outcomes, opportunities, consent, content, or operations. Local only Booked records are never available here.',
-    {
-      object_type: z.enum(COACH_OBJECT_TYPES).optional().describe('One fully_booked_coach.v1 object type.'),
-      client_id: z.string().uuid().optional().describe('Exact KMHub client UUID.'),
-      state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional().describe('Lifecycle state such as active, planned, or submitted.'),
-      limit: z.number().int().min(1).max(200).optional().describe('How many records to return. Default 50.'),
-    },
-    async ({ object_type, client_id, state, limit }) =>
-      coachOut(await call('GET', `/coach/records${qs({ object_type, client_id, state, limit: limit ?? 50 })}`), out, text),
-  );
-
-  server.tool(
-    'km_coach_create_client_map',
-    'Create the first Client MAP for one exact existing coach client. Resolve the client, call km_coach_method for client_map, confirm the complete MAP with the coach, and use this only when no current Client MAP exists. A later change must use km_coach_revise_record.',
-    {
-      client_id: z.string().uuid().describe('Exact KMHub client UUID.'),
-      destination: z.string().min(1).max(4000),
-      current_state: z.string().min(1).max(4000),
-      obstacles: z.array(z.string().min(1).max(1000)).max(50).optional(),
-      measures: z.array(z.object({
-        id: z.string().min(1).max(200),
-        name: z.string().min(1).max(500),
-        baseline: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
-        target: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
-        actual: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
-        evidence_ref: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
-      }).strict()).max(50).optional(),
-      route: z.array(z.string().min(1).max(1000)).max(50).optional(),
-      permissions: z.array(z.string().min(1).max(500)).max(50).optional(),
-      change_source: z.string().max(200).optional(),
-      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact first MAP request.'),
-    },
-    async (args) => coachOut(await call('POST', '/coach/client-maps', args), out, text),
-  );
-
-  server.tool(
-    'km_coach_revise_record',
-    'Create one immutable successor for an exact current coach record. Read the current record first, keep the complete replacement body inside the same client and privacy boundary, and use one stable idempotency key. The server refuses protected object types and records that already have a successor.',
-    {
-      record_id: z.string().uuid().describe('Exact current coach record UUID.'),
-      body: z.record(z.unknown()).describe('Complete replacement body. Never include a credential, token, API key, or password.'),
-      lifecycle_state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional(),
-      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact revision.'),
-    },
-    async ({ record_id, ...body }) => coachOut(
-      await call('POST', `/coach/records/${encodeURIComponent(record_id)}/revisions`, body),
-      out,
-      text,
-    ),
-  );
-  server.tool(
-    'km_coach_write_record',
-    'Create one idempotent shared Fully Booked Coach record in KMHub. Use for new operational facts, sessions, commitments, outcomes, opportunities, or content drafts. Client MAP creation and record revisions require KMHub dedicated reviewed workflows. Consent, approval, and publication records require dedicated human-reviewed KMHub workflows. Do not use for local only notes or credential values. Reusing the same idempotency key returns the original record.',
-    {
-      object_type: z.enum(COACH_WRITABLE_OBJECT_TYPES).describe('A safe draft or operational fully_booked_coach.v1 object type. Consent, approval, publication, audit, and execution records require dedicated human-reviewed routes.'),
-      idempotency_key: z.string().min(1).max(200).describe('A stable key for this exact create request.'),
-      client_id: z.string().uuid().optional().describe('Required for client scoped delivery records.'),
-      privacy_scope: z.enum(['business', 'client_shared', 'client_confidential']).optional().describe('Privacy boundary. Default business.'),
-      lifecycle_state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional().describe('Validated lifecycle state when this object has one.'),
-      body: z.record(z.unknown()).optional().describe('Object fields. Never include a credential, token, API key, or password.'),
-
-    },
-    async (args) => coachOut(await call('POST', '/coach/records', args), out, text),
-  );
-
-  server.tool(
-    'km_coach_stalled_opportunities',
-    'Find open coach opportunities with no current next action or an overdue next action. Use before drafting a stalled prospect message. It reads only and does not contact anyone.',
-    {},
-    async () => coachOut(await call('GET', '/coach/stalled-opportunities'), out, text),
-  );
-
-  server.tool(
-    'km_coach_preview_action',
-    'Record the complete preview for one outbound or sensitive coach action. The preview includes target, content, channel, and expected effect. This has no external side effect and always returns approval required. There is deliberately no send tool in the pilot coach profile.',
-    {
-      target: z.string().min(1).max(500).describe('Exact recipient or destination.'),
-      content: z.string().min(1).max(10000).describe('The complete content that would be used.'),
-      channel: z.string().min(1).max(80).describe('Channel such as email, LinkedIn, or Daily Cookie review.'),
-      expected_effect: z.string().min(1).max(1000).describe('What the action is intended to change.'),
-      risk: z.enum(['internal', 'external', 'money', 'sensitive']).optional().describe('Default external.'),
-      action_class: z.string().max(120).optional().describe('Stable action class such as prospect_follow_up.'),
-      target_scope: z.string().max(200).optional().describe('The precise action boundary.'),
-      client_id: z.string().uuid().optional().describe('Exact client when the action is client scoped.'),
-      privacy_scope: z.enum(['business', 'client_shared', 'client_confidential']).optional(),
-      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact preview.'),
-    },
-    async (args) => coachOut(await call('POST', '/coach/action-previews', args), out, text),
-  );
-
-  server.tool(
-    'km_coach_decide_action',
-    'Record one human approve or reject decision for an exact current ActionRequest. This creates immutable decision evidence only. It never sends, schedules, charges, publishes, or executes the approved action. First show the stored preview and the KMHub confirmation sentence, then retry unchanged with the returned confirm_token after the coach explicitly agrees.',
-    {
-      action_request_id: z.string().uuid().describe('Exact current ActionRequest UUID.'),
-      decision: z.enum(['approve', 'reject']),
-      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact decision.'),
-      note: z.string().max(2000).optional(),
-      confirm_token: z.string().optional().describe('Use only after the coach explicitly approves the exact decision confirmation sentence returned by KMHub.'),
-    },
-    async ({ action_request_id, ...body }) => coachOut(
-      await call('POST', `/coach/action-requests/${encodeURIComponent(action_request_id)}/decision`, body),
-      out,
-      text,
-    ),
-  );
-  server.tool(
-    'km_coach_submit_daily_cookie',
-    'Record a Daily Cookie brief using one book category: problem, dream, process, or proof. This connector step does not start paid production. The coach reviews scope and starts the managed production queue in KMHub Growth. Direct publishing stays disabled. Every client-linked request requires an active content reuse consent grant.',
-    {
-      category: z.enum(['problem', 'dream', 'process', 'proof']),
-      source_scope: z.enum(['business_owned', 'client_linked']).describe('Use business_owned only when no client material is involved. Use client_linked with client_id and consent_grant_id.'),
-      audience: z.string().min(1).max(500),
-      useful_idea: z.string().min(1).max(4000),
-      channel: z.string().min(1).max(80),
-      objective: z.string().max(1000).optional(),
-      due_at: z.string().max(80).optional(),
-      notes: z.string().max(4000).optional(),
-      client_id: z.string().uuid().optional(),
-      consent_grant_id: z.string().uuid().optional(),
-      idempotency_key: z.string().min(1).max(200),
-    },
-    async (args) => coachOut(await call('POST', '/coach/daily-cookie', args), out, text),
-  );
-
-  server.tool(
-    'km_coach_run_scout',
-    [
-      'Start one public or coach connected acquisition scout using only coach modes.',
-      'Past client opportunity and referral path are owned record reviews, so this tool refuses those two and directs the model to KMHub records.',
-      'Public provider work can cost money. Call first without confirm_spend to use the read-only price route. Run only after the coach explicitly agrees and call again with confirm_spend true.',
-      'KMHub may also return a confirmation sentence and confirm_token. Show the sentence, get an explicit yes, and retry the same arguments with that token.',
-      'Every successful coach run stores normalized ScoutFinding records with public source evidence. It creates no generic leads, deals, or outbound drafts. Read those findings after the run and do not record them a second time.',
-    ].join(' '),
-    {
-      mode: z.enum(SCOUT_MODES),
-      who_to_find: z.string().min(1).max(2000).describe('The group and problem criteria in the coach\'s words.'),
-      area: z.string().max(200).optional(),
-      target_count: z.number().int().min(1).max(100).optional(),
-      outreach_context: z.string().max(1000).optional().describe('The real coach offer and useful reason to connect.'),
-      idempotency_key: z.string().min(1).max(170).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,169}$/).describe('Stable key for this exact Scout intent. Reuse it for the price, confirmation, and any retry.'),
-      confirm_spend: z.boolean().optional().describe('Leave out for the free price preview. Set true only after explicit agreement.'),
-      confirm_token: z.string().optional().describe('Use only the token KMHub returned for these exact arguments after the coach explicitly approved its confirmation sentence.'),
-    },
-    async ({ mode, who_to_find, area, target_count, outreach_context, idempotency_key, confirm_spend, confirm_token }) => {
-      if (!PUBLIC_SCOUT_MODES.has(mode)) {
-        return text(
-          `${mode} uses owned KMHub relationships and client history. Use km_coach_list_records instead. Nothing ran and nothing was charged.`,
-        );
-      }
-      const direction = MODE_DIRECTION[mode] || 'Find coach acquisition opportunities with public evidence.';
-      const endpoint = confirm_spend === true ? '/sourcing/missions' : '/sourcing/missions/estimate';
-      return out(await call('POST', endpoint, {
-        describe: `Fully Booked Coach scout: ${direction} Coach criteria: ${who_to_find}`,
-        area,
-        target_count: target_count ?? 25,
-        outreach_context,
-        idempotency_key,
-        vertical_flavor: 'business_coach',
-        coach_scout_mode: mode,
-        deep_research: true,
-        ai_copywriting: false,
-        confirm_spend,
-        confirm_token,
-      }));
-    },
-  );
-
-  server.tool(
-    'km_coach_list_scouts',
-    'List recent provider scout runs for this workspace. This reads status only, costs nothing, and starts nothing.',
-    {
-      limit: z.number().int().min(1).max(50).optional(),
-      status: z.enum(['queued', 'running', 'succeeded', 'failed', 'canceled']).optional(),
-    },
-    async ({ limit, status }) => out(await call('GET', `/sourcing/missions${qs({ limit: limit ?? 10, status })}`)),
-  );
-
-  server.tool(
-    'km_coach_scout_status',
-    'Check one provider scout run and return current progress or results. This reads only and costs nothing.',
-    {
-      mission_id: z.string().uuid(),
-    },
-    async ({ mission_id }) => out(await call('GET', `/sourcing/missions/${encodeURIComponent(mission_id)}`)),
-  );
-
-  server.tool(
-    'km_coach_stop_scout',
-    'Stop a queued or running provider scout. Use immediately when the coach says stop or the criteria are wrong. Work already completed remains, and no future provider work should continue.',
-    {
-      mission_id: z.string().uuid(),
-      confirm_token: z.string().optional().describe('Use only the token KMHub returned after the coach explicitly approved stopping this exact scout.'),
-    },
-    async ({ mission_id, confirm_token }) => out(await call('POST', `/sourcing/missions/${encodeURIComponent(mission_id)}/cancel`, { confirm_token })),
-  );
-
-  server.tool(
-    'km_coach_record_scout_finding',
-    'Record one verified coach scout finding after deduplication. Every finding requires source evidence, group match, problem evidence, rationale, uncertainty, a duplicate key, readiness, and a safe next step. It does not contact anyone.',
-    {
-      mode: z.enum([...PUBLIC_SCOUT_MODES]),
-      source_evidence: z.array(z.object({
-        url: z.string().url(),
-        observed_at: z.string().datetime(),
-        summary: z.string().min(1).max(2000),
-      })).min(1),
-      group_match: z.string().min(1).max(2000),
-      problem_evidence: z.string().min(1).max(4000),
-      rationale: z.string().min(1).max(4000),
-      uncertainty: z.string().min(1).max(2000),
-      duplicate_key: z.string().min(1).max(300),
-      safe_next_step: z.string().min(1).max(2000),
-      readiness: z.enum(['research_only', 'relationship_opportunity', 'outreach_ready']),
-      idempotency_key: z.string().min(1).max(200),
-    },
-    async ({ idempotency_key, ...finding }) =>
-      coachOut(await call('POST', '/coach/records', {
-        object_type: 'ScoutFinding',
-        idempotency_key,
-        privacy_scope: 'business',
-        lifecycle_state: finding.readiness,
-        body: finding,
-      }), out, text),
-  );
-  server.tool(
-    'km_coach_promote_scout_finding',
-    'Promote one exact current reviewed public ScoutFinding into one business relationship and one opportunity. Use only after the coach selects the automatically stored finding and confirms the editable prospect fields. This creates no client, message, outbound request, charge, or external action. Exact retries return the original promotion.',
-    {
-      scout_finding_id: z.string().uuid().describe('Exact current ScoutFinding UUID.'),
-      name: z.string().min(1).max(300).describe('Reviewed relationship and opportunity name.'),
-      context: z.string().max(2000).optional(),
-      source_label: z.string().max(300).optional(),
-      next_action: z.string().max(1000).optional(),
-      next_action_due_at: z.string().datetime().max(80).optional(),
-      state: z.enum(['identified', 'qualified', 'conversation', 'strategy_session', 'proposed', 'nurture']).optional(),
-      idempotency_key: z.string().min(1).max(170).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,169}$/).describe('Stable key for this exact finding promotion.'),
-    },
-    async ({ scout_finding_id, ...body }) => coachOut(
-      await call('POST', `/coach/scout-findings/${encodeURIComponent(scout_finding_id)}/promote`, body),
-      out,
-      text,
-    ),
-  );
-  server.tool(
-    'km_coach_niche_fit',
-    [
-      'Run or resume the source-locked Podcast Niche Selector from Fully Booked Coach PDF pages 115 to 125.',
-      'A new run is deterministic, uses no provider, costs $0, sends nothing, publishes nothing, and requires a confirmation before saving the artifact and human decision.',
-      'Use run_id alone to resume the identical run created in native web or Claude. Never recreate a run from memory when a run id is available.',
-    ].join(' '),
-    {
-      input: NICHE_FIT_INPUT.optional().describe('The complete evidence-backed scorecard for a new run.'),
-      run_id: z.string().uuid().optional().describe('An existing Book OS run to resume. Use this without input or idempotency_key.'),
-      idempotency_key: z.string().min(1).max(96).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,95}$/).optional().describe('Stable key for one new scorecard run and its confirmation retry.'),
-      confirm_token: z.string().min(1).max(4096).optional().describe('Use only after the coach approves saving the displayed zero-cost run.'),
-    },
-    async ({ input, run_id, idempotency_key, confirm_token }) => {
-      if (run_id) {
-        if (input || idempotency_key || confirm_token) {
-          return text('Resume accepts only run_id. Nothing changed.', true);
-        }
-        return coachBookOut(
-          await call('GET', `/coach/book/runs/${encodeURIComponent(run_id)}`),
-          'run',
-          out,
-          text,
-        );
-      }
-      if (!input || !idempotency_key) {
-        return text('A new niche run requires the complete scorecard input and one stable idempotency_key. Nothing changed.', true);
-      }
-      return coachBookOut(await call(
-        'POST',
-        '/coach/book/tools/niche-fit/runs',
-        {
-          tool_spec_id: 'fbc.niche-fit.v1',
-          input,
-          idempotency_key,
-          confirm_token,
-        },
-      ), 'run', out, text);
-    },
-  );
-}
+/**
+ * Tool family: Fully Booked Coach operations.
+ *
+ * The coach profile contains only coach relevant tools. Draft and preview tools
+ * never send or publish. Paid scouting keeps the existing price then confirm gate.
+ */
+import { projectCoachBookConnectorResult } from '../coach-book-output-guard.mjs';
+import { z } from 'zod';
+
+export const FAMILY = 'coach';
+
+export const TOOLS = [
+  'km_coach_context',
+  'km_coach_method',
+  'km_coach_ask_book',
+  'km_coach_book_catalog',
+  'km_coach_book_recommend',
+  'km_coach_book_tool',
+  'km_coach_niche_fit',
+  'km_coach_daily_operator',
+  'km_coach_list_clients',
+  'km_coach_create_client',
+
+  'km_coach_list_records',
+  'km_coach_create_client_map',
+  'km_coach_revise_record',
+
+  'km_coach_write_record',
+
+  'km_coach_stalled_opportunities',
+  'km_coach_preview_action',
+  'km_coach_decide_action',
+
+  'km_coach_submit_daily_cookie',
+  'km_coach_run_scout',
+  'km_coach_list_scouts',
+  'km_coach_scout_status',
+  'km_coach_stop_scout',
+  'km_coach_record_scout_finding',
+  'km_coach_promote_scout_finding',
+];
+
+export const PROFILES = ['coach'];
+
+const COACH_METHOD_WORKFLOWS = [
+  'method_boundary',
+  'niche',
+  'capacity',
+  'acquisition',
+  'authority_content',
+  'strategy_session',
+  'client_map',
+  'renewal_referral_proof',
+  'scouting',
+];
+const COACH_OBJECT_TYPES = [
+  'CoachOperatingBrief', 'MethodologyActivation', 'CapacityPolicy', 'FullyBookedThreshold',
+  'NicheHypothesis', 'NicheScorecard', 'Offer', 'Program', 'Cohort', 'Channel', 'Integration',
+  'Relationship', 'ProspectProfile', 'Opportunity', 'PipelineStage', 'ScoutRun', 'ScoutFinding',
+  'Collaboration', 'ReferralPartner', 'AudienceSegment', 'GrowthSprint', 'Campaign', 'LeadMagnet',
+  'Tripwire', 'Engagement', 'ClientMAP', 'Session', 'SessionPreparation', 'Commitment', 'Outcome',
+  'ResultMeasure', 'ClientHealth', 'Renewal', 'ReferralRequest', 'Testimonial', 'ProofPermission',
+  'Handover', 'ContentIdea', 'ContentAsset', 'ContentCategory', 'ContentBrief',
+  'DailyCookieRequest', 'EditorialApproval', 'PublicationRequest', 'PerformanceObservation',
+  'ConfidentialNote', 'ConsentGrant', 'SecureReference', 'ActionRequest', 'Approval',
+  'ManagedTask', 'AuditEvent', 'ExportJob', 'SyncCursor',
+];
+const COACH_WRITABLE_OBJECT_TYPES = [
+  'CoachOperatingBrief', 'CapacityPolicy', 'FullyBookedThreshold',
+  'NicheHypothesis', 'NicheScorecard', 'Offer', 'Program', 'Cohort', 'Channel', 'Integration',
+  'Relationship', 'ProspectProfile', 'Opportunity', 'PipelineStage', 'ScoutFinding',
+  'Collaboration', 'ReferralPartner', 'AudienceSegment', 'GrowthSprint', 'Campaign', 'LeadMagnet',
+  'Tripwire', 'Engagement', 'Session', 'SessionPreparation', 'Commitment', 'Outcome',
+  'ResultMeasure', 'ClientHealth', 'Renewal', 'ReferralRequest', 'Testimonial', 'Handover',
+  'ContentIdea', 'ContentAsset', 'ContentCategory', 'ContentBrief', 'PerformanceObservation',
+  'ConfidentialNote', 'ManagedTask',
+];
+
+const SCOUT_MODES = [
+  'micro-niche-mapper',
+  'niche-validation-scout',
+  'collaborator-scout',
+  'ideal-client-twin-scout',
+  'past-client-opportunity-scout',
+  'referral-path-scout',
+  'ideal-client-scout',
+  'niche-and-growth-scout',
+  'ideal-organization-and-partner-scout',
+  'ideal-person-and-influencer-scout',
+  'podcast-collaboration-scout',
+];
+
+const PUBLIC_SCOUT_MODES = new Set([
+  'micro-niche-mapper',
+  'niche-validation-scout',
+  'collaborator-scout',
+  'ideal-client-twin-scout',
+  'ideal-client-scout',
+  'niche-and-growth-scout',
+  'ideal-organization-and-partner-scout',
+  'ideal-person-and-influencer-scout',
+  'podcast-collaboration-scout',
+]);
+
+const MODE_DIRECTION = {
+  'micro-niche-mapper': 'Map a broad market into specific groups that share context and an urgent problem.',
+  'niche-validation-scout': 'Find public evidence that the niche problem is urgent, reachable, and valuable.',
+  'collaborator-scout': 'Find people or organizations with a complementary offer and an aligned audience.',
+  'ideal-client-twin-scout': 'Find public prospects that match approved nonconfidential attributes of a strong client.',
+  'ideal-client-scout': 'Find public prospects that match the coach niche and offer.',
+  'niche-and-growth-scout': 'Find niche groups and practical audience growth paths.',
+  'ideal-organization-and-partner-scout': 'Find organizations and partners with a strong group and problem match.',
+  'ideal-person-and-influencer-scout': 'Find people and influencers who reach the coach niche.',
+  'podcast-collaboration-scout': 'Find podcasts where a useful collaboration fits the audience problem.',
+};
+
+const NICHE_EVIDENCE_REFERENCE = z.object({
+  id: z.string().min(1).max(80),
+  url: z.string().url().refine((value) => value.startsWith('https://'), 'Use one public HTTPS evidence URL.'),
+  observedAt: z.string().min(10).max(64),
+  summary: z.string().min(1).max(1000),
+  kind: z.enum(['direct', 'analogue', 'counterevidence']),
+}).strict();
+
+const NICHE_PREDICATE = z.object({
+  grade: z.union([z.literal(0), z.literal(0.5), z.literal(1)]),
+  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
+  rationale: z.string().min(1).max(1000),
+}).strict();
+
+const NICHE_COUNTEREVIDENCE = z.object({
+  query: z.string().min(1).max(500),
+  checkedAt: z.string().min(10).max(64),
+  outcome: z.enum(['none_found', 'found', 'inconclusive']),
+  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
+}).strict();
+
+const NICHE_FALSE_POSITIVE = z.object({
+  observed: z.boolean(),
+  evidenceIds: z.array(z.string().min(1).max(80)).max(40),
+  note: z.string().max(1000),
+}).strict();
+
+function nicheDimension(predicates) {
+  return z.object({
+    predicates: z.object(Object.fromEntries(
+      predicates.map((predicate) => [predicate, NICHE_PREDICATE]),
+    )).strict(),
+    counterevidenceChecks: z.array(NICHE_COUNTEREVIDENCE).min(1).max(20),
+    falsePositive: NICHE_FALSE_POSITIVE,
+  }).strict();
+}
+
+const NICHE_FIT_INPUT = z.object({
+  toolSpecId: z.literal('fbc.niche-fit.v1'),
+  asOf: z.string().min(10).max(64),
+  hypothesis: z.object({
+    proposedPodcastNiche: z.string().min(1).max(500),
+    strategy: z.enum(['smaller_group', 'specific_problem', 'both']),
+    specificGroup: z.string().min(1).max(500).optional(),
+    specificProblem: z.string().min(1).max(500).optional(),
+    collaboratorProfile: z.string().min(1).max(1000),
+    podcastWorkingTitle: z.string().min(1).max(500),
+    collaborationHook: z.string().min(1).max(1000),
+    valueExchangeOffer: z.string().min(1).max(1000),
+    geography: z.string().min(1).max(200).optional(),
+    language: z.string().min(1).max(100).optional(),
+  }).strict(),
+  evidence: z.array(NICHE_EVIDENCE_REFERENCE).min(1).max(120),
+  dimensions: z.object({
+    findability: nicheDimension([
+      'discoverable_collaborators',
+      'reachable_contact_path',
+      'compelling_collaboration_offer',
+      'weekly_yes_pace',
+    ]),
+    bragability: nicheDimension([
+      'show_up_likelihood',
+      'compelling_story_hook',
+      'positive_status_association',
+      'share_behavior',
+    ]),
+    sellability: nicheDimension([
+      'reachable_owned_audience',
+      'specific_value_exchange',
+      'offer_through_collaboration',
+      'audience_response',
+    ]),
+  }).strict(),
+}).strict();
+
+function routeMissing(result) {
+  return result.status === 404 || result.status === 405 || result.status === 501;
+}
+
+const COACH_NOT_READY =
+  'The Fully Booked Coach managed routes are not deployed for this workspace yet. Nothing changed. Use draft mode and ask the operator to finish the coach migration and API deployment.';
+const COACH_BOOK_UNSAFE =
+  'KMHub rejected an unsafe Book OS response. Nothing changed.';
+
+function coachOut(result, out, text) {
+  return routeMissing(result) ? text(COACH_NOT_READY, true) : out(result);
+}
+
+function coachBookOut(result, kind, out, text) {
+  if (routeMissing(result)) return text(COACH_NOT_READY, true);
+  try {
+    return out(projectCoachBookConnectorResult(kind, result));
+  } catch {
+    return text(COACH_BOOK_UNSAFE, true);
+  }
+}
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_coach_context',
+    'Load the connected Fully Booked Coach workspace, method stage, capacity boundaries, privacy defaults, record counts, and tenant identity. Call this first in a coach conversation. It reads only and never changes anything.',
+    {},
+    async () => coachOut(await call('GET', '/coach/context'), out, text),
+  );
+
+  server.tool(
+    'km_coach_method',
+    'Load verified Fully Booked Coach guidance for one exact workflow. Use after workspace context and before giving method-based advice or preparing a related write. It returns approved guidance metadata only, never protected source text, and fails closed when the private tenant cassette is not ready.',
+    {
+      workflow: z.enum(COACH_METHOD_WORKFLOWS).describe('The exact Fully Booked Coach workflow that grounds this request.'),
+    },
+    async ({ workflow }) => coachOut(
+      await call('GET', `/coach/method${qs({ workflow })}`),
+      out,
+      text,
+    ),
+  );
+  server.tool(
+    'km_coach_ask_book',
+    'Ask the Book is intentionally closed by product decision. This compatibility tool performs no retrieval, provider call, or charge. Use the method catalog to find an available workflow.',
+    {
+      question: z.string().min(4).max(1200).describe('Legacy compatibility field. Ask the Book remains closed and does not process this question.'),
+      idempotency_key: z.string().min(1).max(120).regex(/^[A-Za-z0-9][A-Za-z0-9._:]{0,119}$/).describe('Legacy compatibility field. No run is created.'),
+      quote_id: z.string().uuid().optional().describe('Legacy compatibility field. No quote is used.'),
+      confirm_token: z.string().min(1).max(4096).optional().describe('Legacy compatibility field. No confirmation is consumed.'),
+    },
+    async () => text(
+      'Ask the Book remains intentionally closed by product decision. No retrieval ran, no provider was called, and nothing was charged. Use km_coach_book_catalog to find a method and km_coach_book_tool to start, advance, resume, or cancel a run.',
+      true,
+    ),
+  );
+
+  server.tool(
+    'km_coach_book_catalog',
+    [
+      'List, search, or describe the public Fully Booked Coach method library.',
+      'Catalog and search read the managed method catalog. Describe reads one exact method id.',
+      'This tool is read-only and returns public method metadata, source page locators, availability, and public input steps.',
+    ].join(' '),
+    {
+      action: z.enum(['catalog', 'search', 'describe']).describe('Use catalog for the full library, search for a local public-metadata match, or describe for one exact method.'),
+      query: z.string().trim().min(2).max(160).optional().describe('Required only for search. Matches public ids, titles, summaries, categories, executor kinds, and statuses.'),
+      tool_spec_id: z.string().regex(/^fbc[.]method[.][0-9]{3}[.][a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe('Required only for describe. Use the exact id returned by catalog or search.'),
+    },
+    async ({ action, query, tool_spec_id }) => {
+      if (action === 'describe') {
+        if (!tool_spec_id || query) {
+          return text('Describe requires only one exact tool_spec_id. Nothing changed.', true);
+        }
+        return coachBookOut(
+          await call('GET', `/coach/book/methods/${encodeURIComponent(tool_spec_id)}`),
+          'describe',
+          out,
+          text,
+        );
+      }
+      if (tool_spec_id) {
+        return text('Catalog and search do not accept tool_spec_id. Nothing changed.', true);
+      }
+      if (action === 'catalog' && query) {
+        return text('Catalog does not accept a search query. Use the search action instead.', true);
+      }
+      if (action === 'search' && !query) {
+        return text('Search requires a query. Nothing changed.', true);
+      }
+
+      const result = await call('GET', '/coach/book/methods');
+      if (routeMissing(result)) return text(COACH_NOT_READY, true);
+      let safeResult;
+      try {
+        safeResult = projectCoachBookConnectorResult('catalog', result);
+      } catch {
+        return text(COACH_BOOK_UNSAFE, true);
+      }
+      if (!safeResult.ok || action === 'catalog') return out(safeResult);
+
+      const data = safeResult.data && typeof safeResult.data === 'object' && !Array.isArray(safeResult.data)
+        ? safeResult.data
+        : {};
+      const methods = Array.isArray(data.methods) ? data.methods : [];
+      const needle = query.trim().toLowerCase();
+      const matches = methods.filter((method) => {
+        if (!method || typeof method !== 'object' || Array.isArray(method)) return false;
+        const publicSpec = method.public_spec && typeof method.public_spec === 'object'
+          && !Array.isArray(method.public_spec)
+          ? method.public_spec
+          : {};
+        return [
+          method.tool_spec_id,
+          method.title,
+          method.summary,
+          method.category,
+          method.implementation_status,
+          method.executor_kind,
+          method.effect_class,
+          method.availability_class,
+          publicSpec.title,
+          publicSpec.summary,
+          publicSpec.category,
+          publicSpec.executorKind,
+          publicSpec.effectClass,
+        ].filter((value) => typeof value === 'string').join(' ').toLowerCase().includes(needle);
+      });
+      return out({
+        ...safeResult,
+        data: {
+          ...data,
+          methods: matches,
+          search: {
+            query: query.trim(),
+            matched: matches.length,
+            total: methods.length,
+          },
+        },
+      });
+    },
+  );
+
+  server.tool(
+    'km_coach_book_recommend',
+    [
+      'Recommend up to three public Fully Booked Coach methods for one coaching goal.',
+      'This read-only tool uses the deterministic KMHub ranker and performs no source retrieval, no provider call, no write, no charge, and no external effect.',
+      'It never exposes protected source text, source code, or skill files. Ask the Book remains closed.',
+    ].join(' '),
+    {
+      goal: z.string().trim().min(4).max(600).describe('Describe the coaching outcome or problem in plain language.'),
+      availability_scope: z.enum(['runnable_only', 'include_pending']).optional().describe('Use runnable_only by default, or include pending methods for planning visibility.'),
+      max_minutes: z.number().int().min(5).max(240).optional().describe('Optional maximum estimated method duration.'),
+      executor_kind: z.enum(['deterministic_single_step', 'guided_multi_step']).optional().describe('Optional execution-style filter.'),
+      effect_class: z.enum(['none', 'action_preview']).optional().describe('Optional effect boundary filter.'),
+    },
+    async ({
+      goal,
+      availability_scope,
+      max_minutes,
+      executor_kind,
+      effect_class,
+    }) => coachBookOut(
+      await call('GET', `/coach/book/methods/recommend${qs({
+        goal,
+        availability_scope,
+        max_minutes,
+        executor_kind,
+        effect_class,
+      })}`),
+      'recommendation',
+      out,
+      text,
+    ),
+  );
+
+  server.tool(
+    'km_coach_book_tool',
+    [
+      'Start, advance, resume, or cancel one generic Fully Booked Coach method run.',
+      'Start, advance, and cancel are confirmed zero-cost writes. Show any 409 confirmation sentence and wait for an explicit yes before retrying once with the exact returned confirm_token.',
+      'Never invent or self-confirm a token. Resume is a read-only run lookup and accepts only action plus run_id.',
+      'This tool creates only bounded method artifacts and action previews. It cannot contact, publish, spend, or perform an external connector action.',
+    ].join(' '),
+    {
+      action: z.enum(['start', 'advance', 'resume', 'cancel']),
+      tool_spec_id: z.string().regex(/^fbc[.]method[.][0-9]{3}[.][a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe('Required only for start. Use the exact method id from the catalog.'),
+      run_id: z.string().uuid().optional().describe('Required for advance, resume, and cancel.'),
+      step_id: z.string().min(1).max(80).regex(/^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/).optional().describe('Required for start and advance. Use the exact current public step id.'),
+      values: z.record(z.unknown()).optional().describe('Required for start and advance. Send one bounded object containing only the current public step fields.'),
+      idempotency_key: z.string().min(1).max(96).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,95}$/).optional().describe('Required for start, advance, and cancel. Reuse it for an exact confirmation retry.'),
+      confirm_token: z.string().min(1).max(4096).optional().describe('Use only the exact token returned in a 409 response after the coach explicitly approves the displayed confirmation sentence.'),
+    },
+    async ({
+      action,
+      tool_spec_id,
+      run_id,
+      step_id,
+      values,
+      idempotency_key,
+      confirm_token,
+    }) => {
+      if (action === 'resume') {
+        if (!run_id || tool_spec_id || step_id || values || idempotency_key || confirm_token) {
+          return text('Resume accepts only action and run_id. Nothing changed.', true);
+        }
+        return coachBookOut(
+          await call('GET', `/coach/book/runs/${encodeURIComponent(run_id)}`),
+          'run',
+          out,
+          text,
+        );
+      }
+
+      if (action === 'start') {
+        if (!tool_spec_id || run_id || !step_id || !values || !idempotency_key) {
+          return text('Start requires tool_spec_id, step_id, values, and idempotency_key, with no run_id. Nothing changed.', true);
+        }
+        return coachBookOut(await call(
+          'POST',
+          `/coach/book/methods/${encodeURIComponent(tool_spec_id)}/runs`,
+          {
+            tool_spec_id,
+            step_id,
+            values,
+            idempotency_key,
+            ...(confirm_token ? { confirm_token } : {}),
+          },
+        ), 'run', out, text);
+      }
+
+      if (action === 'advance') {
+        if (!run_id || tool_spec_id || !step_id || !values || !idempotency_key) {
+          return text('Advance requires run_id, step_id, values, and idempotency_key, with no tool_spec_id. Nothing changed.', true);
+        }
+        return coachBookOut(await call(
+          'POST',
+          `/coach/book/runs/${encodeURIComponent(run_id)}/steps`,
+          {
+            step_id,
+            values,
+            idempotency_key,
+            ...(confirm_token ? { confirm_token } : {}),
+          },
+        ), 'run', out, text);
+      }
+
+      if (!run_id || tool_spec_id || step_id || values || !idempotency_key) {
+        return text('Cancel requires only run_id and idempotency_key, plus an explicit confirm_token retry when KMHub requests it. Nothing changed.', true);
+      }
+      return coachBookOut(await call(
+        'POST',
+        `/coach/book/runs/${encodeURIComponent(run_id)}/cancel`,
+        {
+          idempotency_key,
+          ...(confirm_token ? { confirm_token } : {}),
+        },
+      ), 'run', out, text);
+    },
+  );
+
+  server.tool(
+    'km_coach_daily_operator',
+    'Build today\'s operating view from client sessions, commitments, stalled opportunities, approvals, Daily Cookie work, and capacity. Use for what needs me today or a morning review. It reads only and never sends, schedules, or publishes.',
+    {},
+    async () => coachOut(await call('GET', '/coach/daily-operator'), out, text),
+  );
+
+  server.tool(
+    'km_coach_list_clients',
+    'List recent clients in this coach workspace so a named client can be resolved before reading or writing a Client MAP, session, commitment, outcome, or confidential note. It never searches another tenant.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many clients to return. Default 25.'),
+    },
+    async ({ limit }) => coachOut(await call('GET', `/coach/clients${qs({ limit: limit ?? 25 })}`), out, text),
+  );
+
+  server.tool(
+    'km_coach_create_client',
+    'Create one client in the connected coach workspace after confirming the person or company details. Use a stable idempotency key for this exact request. This creates only the client record. It does not create a Client MAP, engagement, invoice, message, or external action.',
+    {
+      client_type: z.enum(['individual', 'company']).optional().describe('Default individual.'),
+      first_name: z.string().min(1).max(200).describe('Required display or contact first name.'),
+      last_name: z.string().max(200).optional(),
+      company_name: z.string().max(300).optional(),
+      email: z.string().email().max(320).optional(),
+      phone: z.string().max(100).optional(),
+      notes: z.string().max(4000).optional(),
+      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact client create request.'),
+    },
+    async (args) => coachOut(await call('POST', '/coach/clients', args), out, text),
+  );
+  server.tool(
+    'km_coach_list_records',
+    'Read shared coach records from KMHub, optionally filtered by object type, exact client, or lifecycle state. Use for Client MAPs, sessions, commitments, outcomes, opportunities, consent, content, or operations. Local only Booked records are never available here.',
+    {
+      object_type: z.enum(COACH_OBJECT_TYPES).optional().describe('One fully_booked_coach.v1 object type.'),
+      client_id: z.string().uuid().optional().describe('Exact KMHub client UUID.'),
+      state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional().describe('Lifecycle state such as active, planned, or submitted.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many records to return. Default 50.'),
+    },
+    async ({ object_type, client_id, state, limit }) =>
+      coachOut(await call('GET', `/coach/records${qs({ object_type, client_id, state, limit: limit ?? 50 })}`), out, text),
+  );
+
+  server.tool(
+    'km_coach_create_client_map',
+    'Create the first Client MAP for one exact existing coach client. Resolve the client, call km_coach_method for client_map, confirm the complete MAP with the coach, and use this only when no current Client MAP exists. A later change must use km_coach_revise_record.',
+    {
+      client_id: z.string().uuid().describe('Exact KMHub client UUID.'),
+      destination: z.string().min(1).max(4000),
+      current_state: z.string().min(1).max(4000),
+      obstacles: z.array(z.string().min(1).max(1000)).max(50).optional(),
+      measures: z.array(z.object({
+        id: z.string().min(1).max(200),
+        name: z.string().min(1).max(500),
+        baseline: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
+        target: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
+        actual: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
+        evidence_ref: z.union([z.string().min(1).max(1000), z.number(), z.null()]).optional(),
+      }).strict()).max(50).optional(),
+      route: z.array(z.string().min(1).max(1000)).max(50).optional(),
+      permissions: z.array(z.string().min(1).max(500)).max(50).optional(),
+      change_source: z.string().max(200).optional(),
+      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact first MAP request.'),
+    },
+    async (args) => coachOut(await call('POST', '/coach/client-maps', args), out, text),
+  );
+
+  server.tool(
+    'km_coach_revise_record',
+    'Create one immutable successor for an exact current coach record. Read the current record first, keep the complete replacement body inside the same client and privacy boundary, and use one stable idempotency key. The server refuses protected object types and records that already have a successor.',
+    {
+      record_id: z.string().uuid().describe('Exact current coach record UUID.'),
+      body: z.record(z.unknown()).describe('Complete replacement body. Never include a credential, token, API key, or password.'),
+      lifecycle_state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional(),
+      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact revision.'),
+    },
+    async ({ record_id, ...body }) => coachOut(
+      await call('POST', `/coach/records/${encodeURIComponent(record_id)}/revisions`, body),
+      out,
+      text,
+    ),
+  );
+  server.tool(
+    'km_coach_write_record',
+    'Create one idempotent shared Fully Booked Coach record in KMHub. Use for new operational facts, sessions, commitments, outcomes, opportunities, or content drafts. Client MAP creation and record revisions require KMHub dedicated reviewed workflows. Consent, approval, and publication records require dedicated human-reviewed KMHub workflows. Do not use for local only notes or credential values. Reusing the same idempotency key returns the original record.',
+    {
+      object_type: z.enum(COACH_WRITABLE_OBJECT_TYPES).describe('A safe draft or operational fully_booked_coach.v1 object type. Consent, approval, publication, audit, and execution records require dedicated human-reviewed routes.'),
+      idempotency_key: z.string().min(1).max(200).describe('A stable key for this exact create request.'),
+      client_id: z.string().uuid().optional().describe('Required for client scoped delivery records.'),
+      privacy_scope: z.enum(['business', 'client_shared', 'client_confidential']).optional().describe('Privacy boundary. Default business.'),
+      lifecycle_state: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/).optional().describe('Validated lifecycle state when this object has one.'),
+      body: z.record(z.unknown()).optional().describe('Object fields. Never include a credential, token, API key, or password.'),
+
+    },
+    async (args) => coachOut(await call('POST', '/coach/records', args), out, text),
+  );
+
+  server.tool(
+    'km_coach_stalled_opportunities',
+    'Find open coach opportunities with no current next action or an overdue next action. Use before drafting a stalled prospect message. It reads only and does not contact anyone.',
+    {},
+    async () => coachOut(await call('GET', '/coach/stalled-opportunities'), out, text),
+  );
+
+  server.tool(
+    'km_coach_preview_action',
+    'Record the complete preview for one outbound or sensitive coach action. The preview includes target, content, channel, and expected effect. This has no external side effect and always returns approval required. There is deliberately no send tool in the pilot coach profile.',
+    {
+      target: z.string().min(1).max(500).describe('Exact recipient or destination.'),
+      content: z.string().min(1).max(10000).describe('The complete content that would be used.'),
+      channel: z.string().min(1).max(80).describe('Channel such as email, LinkedIn, or Daily Cookie review.'),
+      expected_effect: z.string().min(1).max(1000).describe('What the action is intended to change.'),
+      risk: z.enum(['internal', 'external', 'money', 'sensitive']).optional().describe('Default external.'),
+      action_class: z.string().max(120).optional().describe('Stable action class such as prospect_follow_up.'),
+      target_scope: z.string().max(200).optional().describe('The precise action boundary.'),
+      client_id: z.string().uuid().optional().describe('Exact client when the action is client scoped.'),
+      privacy_scope: z.enum(['business', 'client_shared', 'client_confidential']).optional(),
+      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact preview.'),
+    },
+    async (args) => coachOut(await call('POST', '/coach/action-previews', args), out, text),
+  );
+
+  server.tool(
+    'km_coach_decide_action',
+    'Record one human approve or reject decision for an exact current ActionRequest. This creates immutable decision evidence only. It never sends, schedules, charges, publishes, or executes the approved action. First show the stored preview and the KMHub confirmation sentence, then retry unchanged with the returned confirm_token after the coach explicitly agrees.',
+    {
+      action_request_id: z.string().uuid().describe('Exact current ActionRequest UUID.'),
+      decision: z.enum(['approve', 'reject']),
+      idempotency_key: z.string().min(1).max(200).describe('Stable key for this exact decision.'),
+      note: z.string().max(2000).optional(),
+      confirm_token: z.string().optional().describe('Use only after the coach explicitly approves the exact decision confirmation sentence returned by KMHub.'),
+    },
+    async ({ action_request_id, ...body }) => coachOut(
+      await call('POST', `/coach/action-requests/${encodeURIComponent(action_request_id)}/decision`, body),
+      out,
+      text,
+    ),
+  );
+  server.tool(
+    'km_coach_submit_daily_cookie',
+    'Record a Daily Cookie brief using one book category: problem, dream, process, or proof. This connector step does not start paid production. The coach reviews scope and starts the managed production queue in KMHub Growth. Direct publishing stays disabled. Every client-linked request requires an active content reuse consent grant.',
+    {
+      category: z.enum(['problem', 'dream', 'process', 'proof']),
+      source_scope: z.enum(['business_owned', 'client_linked']).describe('Use business_owned only when no client material is involved. Use client_linked with client_id and consent_grant_id.'),
+      audience: z.string().min(1).max(500),
+      useful_idea: z.string().min(1).max(4000),
+      channel: z.string().min(1).max(80),
+      objective: z.string().max(1000).optional(),
+      due_at: z.string().max(80).optional(),
+      notes: z.string().max(4000).optional(),
+      client_id: z.string().uuid().optional(),
+      consent_grant_id: z.string().uuid().optional(),
+      idempotency_key: z.string().min(1).max(200),
+    },
+    async (args) => coachOut(await call('POST', '/coach/daily-cookie', args), out, text),
+  );
+
+  server.tool(
+    'km_coach_run_scout',
+    [
+      'Start one public or coach connected acquisition scout using only coach modes.',
+      'Past client opportunity and referral path are owned record reviews, so this tool refuses those two and directs the model to KMHub records.',
+      'Public provider work can cost money. Call first without confirm_spend to use the read-only price route. Run only after the coach explicitly agrees and call again with confirm_spend true.',
+      'KMHub may also return a confirmation sentence and confirm_token. Show the sentence, get an explicit yes, and retry the same arguments with that token.',
+      'Every successful coach run stores normalized ScoutFinding records with public source evidence. It creates no generic leads, deals, or outbound drafts. Read those findings after the run and do not record them a second time.',
+    ].join(' '),
+    {
+      mode: z.enum(SCOUT_MODES),
+      who_to_find: z.string().min(1).max(2000).describe('The group and problem criteria in the coach\'s words.'),
+      area: z.string().max(200).optional(),
+      target_count: z.number().int().min(1).max(100).optional(),
+      outreach_context: z.string().max(1000).optional().describe('The real coach offer and useful reason to connect.'),
+      idempotency_key: z.string().min(1).max(170).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,169}$/).describe('Stable key for this exact Scout intent. Reuse it for the price, confirmation, and any retry.'),
+      confirm_spend: z.boolean().optional().describe('Leave out for the free price preview. Set true only after explicit agreement.'),
+      confirm_token: z.string().optional().describe('Use only the token KMHub returned for these exact arguments after the coach explicitly approved its confirmation sentence.'),
+    },
+    async ({ mode, who_to_find, area, target_count, outreach_context, idempotency_key, confirm_spend, confirm_token }) => {
+      if (!PUBLIC_SCOUT_MODES.has(mode)) {
+        return text(
+          `${mode} uses owned KMHub relationships and client history. Use km_coach_list_records instead. Nothing ran and nothing was charged.`,
+        );
+      }
+      const direction = MODE_DIRECTION[mode] || 'Find coach acquisition opportunities with public evidence.';
+      const endpoint = confirm_spend === true ? '/sourcing/missions' : '/sourcing/missions/estimate';
+      return out(await call('POST', endpoint, {
+        describe: `Fully Booked Coach scout: ${direction} Coach criteria: ${who_to_find}`,
+        area,
+        target_count: target_count ?? 25,
+        outreach_context,
+        idempotency_key,
+        vertical_flavor: 'business_coach',
+        coach_scout_mode: mode,
+        deep_research: true,
+        ai_copywriting: false,
+        confirm_spend,
+        confirm_token,
+      }));
+    },
+  );
+
+  server.tool(
+    'km_coach_list_scouts',
+    'List recent provider scout runs for this workspace. This reads status only, costs nothing, and starts nothing.',
+    {
+      limit: z.number().int().min(1).max(50).optional(),
+      status: z.enum(['queued', 'running', 'succeeded', 'failed', 'canceled']).optional(),
+    },
+    async ({ limit, status }) => out(await call('GET', `/sourcing/missions${qs({ limit: limit ?? 10, status })}`)),
+  );
+
+  server.tool(
+    'km_coach_scout_status',
+    'Check one provider scout run and return current progress or results. This reads only and costs nothing.',
+    {
+      mission_id: z.string().uuid(),
+    },
+    async ({ mission_id }) => out(await call('GET', `/sourcing/missions/${encodeURIComponent(mission_id)}`)),
+  );
+
+  server.tool(
+    'km_coach_stop_scout',
+    'Stop a queued or running provider scout. Use immediately when the coach says stop or the criteria are wrong. Work already completed remains, and no future provider work should continue.',
+    {
+      mission_id: z.string().uuid(),
+      confirm_token: z.string().optional().describe('Use only the token KMHub returned after the coach explicitly approved stopping this exact scout.'),
+    },
+    async ({ mission_id, confirm_token }) => out(await call('POST', `/sourcing/missions/${encodeURIComponent(mission_id)}/cancel`, { confirm_token })),
+  );
+
+  server.tool(
+    'km_coach_record_scout_finding',
+    'Record one verified coach scout finding after deduplication. Every finding requires source evidence, group match, problem evidence, rationale, uncertainty, a duplicate key, readiness, and a safe next step. It does not contact anyone.',
+    {
+      mode: z.enum([...PUBLIC_SCOUT_MODES]),
+      source_evidence: z.array(z.object({
+        url: z.string().url(),
+        observed_at: z.string().datetime(),
+        summary: z.string().min(1).max(2000),
+      })).min(1),
+      group_match: z.string().min(1).max(2000),
+      problem_evidence: z.string().min(1).max(4000),
+      rationale: z.string().min(1).max(4000),
+      uncertainty: z.string().min(1).max(2000),
+      duplicate_key: z.string().min(1).max(300),
+      safe_next_step: z.string().min(1).max(2000),
+      readiness: z.enum(['research_only', 'relationship_opportunity', 'outreach_ready']),
+      idempotency_key: z.string().min(1).max(200),
+    },
+    async ({ idempotency_key, ...finding }) =>
+      coachOut(await call('POST', '/coach/records', {
+        object_type: 'ScoutFinding',
+        idempotency_key,
+        privacy_scope: 'business',
+        lifecycle_state: finding.readiness,
+        body: finding,
+      }), out, text),
+  );
+  server.tool(
+    'km_coach_promote_scout_finding',
+    'Promote one exact current reviewed public ScoutFinding into one business relationship and one opportunity. Use only after the coach selects the automatically stored finding and confirms the editable prospect fields. This creates no client, message, outbound request, charge, or external action. Exact retries return the original promotion.',
+    {
+      scout_finding_id: z.string().uuid().describe('Exact current ScoutFinding UUID.'),
+      name: z.string().min(1).max(300).describe('Reviewed relationship and opportunity name.'),
+      context: z.string().max(2000).optional(),
+      source_label: z.string().max(300).optional(),
+      next_action: z.string().max(1000).optional(),
+      next_action_due_at: z.string().datetime().max(80).optional(),
+      state: z.enum(['identified', 'qualified', 'conversation', 'strategy_session', 'proposed', 'nurture']).optional(),
+      idempotency_key: z.string().min(1).max(170).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,169}$/).describe('Stable key for this exact finding promotion.'),
+    },
+    async ({ scout_finding_id, ...body }) => coachOut(
+      await call('POST', `/coach/scout-findings/${encodeURIComponent(scout_finding_id)}/promote`, body),
+      out,
+      text,
+    ),
+  );
+  server.tool(
+    'km_coach_niche_fit',
+    [
+      'Run or resume the source-locked Podcast Niche Selector from Fully Booked Coach PDF pages 115 to 125.',
+      'A new run is deterministic, uses no provider, costs $0, sends nothing, publishes nothing, and requires a confirmation before saving the artifact and human decision.',
+      'Use run_id alone to resume the identical run created in native web or Claude. Never recreate a run from memory when a run id is available.',
+    ].join(' '),
+    {
+      input: NICHE_FIT_INPUT.optional().describe('The complete evidence-backed scorecard for a new run.'),
+      run_id: z.string().uuid().optional().describe('An existing Book OS run to resume. Use this without input or idempotency_key.'),
+      idempotency_key: z.string().min(1).max(96).regex(/^[A-Za-z0-9][A-Za-z0-9:._-]{0,95}$/).optional().describe('Stable key for one new scorecard run and its confirmation retry.'),
+      confirm_token: z.string().min(1).max(4096).optional().describe('Use only after the coach approves saving the displayed zero-cost run.'),
+    },
+    async ({ input, run_id, idempotency_key, confirm_token }) => {
+      if (run_id) {
+        if (input || idempotency_key || confirm_token) {
+          return text('Resume accepts only run_id. Nothing changed.', true);
+        }
+        return coachBookOut(
+          await call('GET', `/coach/book/runs/${encodeURIComponent(run_id)}`),
+          'run',
+          out,
+          text,
+        );
+      }
+      if (!input || !idempotency_key) {
+        return text('A new niche run requires the complete scorecard input and one stable idempotency_key. Nothing changed.', true);
+      }
+      return coachBookOut(await call(
+        'POST',
+        '/coach/book/tools/niche-fit/runs',
+        {
+          tool_spec_id: 'fbc.niche-fit.v1',
+          input,
+          idempotency_key,
+          confirm_token,
+        },
+      ), 'run', out, text);
+    },
+  );
+}