Manage Account

Maintain account state and impact history — the consolidated account writer.

Actions:

• objective_expansion: inspect current customers for the objective offer and save reviewed expansion candidates (id = objective UUID). Preparation creates reviewable work and does not contact anyone.
• discovery_create: start discovery for an engagement with no current record (no id; DiscoveryCreateRequest). Read customer_impact first. Provide journey_id, the known situation and/or pain, and a reason. The receipt id is the new claim_id. Facts remain unconfirmed; missing SPICED points stay unknown. This does not define a delivery promise, assign a priority or advance a deal. Existing records must use discovery_fact. Retries use the same request_key.
• discovery_fact: edit one canonical SPICED point (DiscoveryFactRequest). Fetch customer_impact first. Copy the element's edit_values into values, edit those values, and provide the operator's reason. Pass discovery.claim_id, value_hash, edit_id, and review.id as claim_id, expected_value_hash, expected_edit_id, and expected_review_id. Null clears a field. Decision edits change criteria/process only; use buying_roles for engagement roles. This preserves frozen delivery terms, timeline commitments and results. Edited facts require a fresh customer review; recording is not confirmation.
• discovery_review: review one exact SPICED element (no id; DiscoveryReviewRequest). Include the element edit_id as expected_edit_id. Read account impact first. Use discovery.claim_id and the element's review.id as expected_review_id; pass the element's value_hash as expected_value_hash. Confirm or contradict with a reviewed original customer email/transcript quotation and current source IDs. Explicitly attribute account sources to the engagement when necessary. Withdraw the latest assertion with its predecessor and reason, without new sources. Missing facts cannot be confirmed; a new claim revision or changed proof needs review. No deal stage, claim confidence, impact verification or measurement changes occur.
• renewal_review: assigned-owner acceptance, dismissal or reported completion of a RenewalDecision (no id). Read customer_impact.renewal.work first for action_id and expected_version; pass account_id, decision and a review note. Completion records work only: it never sends, verifies impact or renews terms.
• customer_growth_record: record an internal growth proposal (no id; CustomerGrowthRecord). Read customer_impact.customer_growth first. Pass account_id, expected_fingerprint and draft as the current account owner. Proposals cover advocacy, referral, nurture or retirement and require current sources. Recording never sends, publishes or changes account state.
• customer_growth_review: review sourced growth work (no id; CustomerGrowthDecision). Read customer_impact.customer_growth first. Pass account_id, action_id, expected_version, expected_fingerprint, decision and note. Permission decisions require the exact customer source and separate permission scope. Completion records internal work only; it never sends, publishes, enrolls, retires an account or changes billing.
• kickoff_plan: save a KickoffPlanRequest (no id). Read customer_impact first for kickoff_plan.expected_fingerprint. Save a draft revision or quote a native customer statement about the exact plan reference. Never sends.
• critical_event_step: record a reviewed CriticalEventStepRequest (no id). Fetch customer_impact first. Pin timeline_evidence_id, action_id, expected_version and expected_decision_id for that decision. accept is assigned-owner approval of manual work; confirm requires original customer words and a reviewed commitment date; complete requires current evidence, accepted work and completed prerequisites. Corrections append; retract withdraws confirmation/completion proof without undoing action history. No sending, customer-impact verification or result credit occurs.
• critical_event: save a human-reviewed CriticalEventRequest (no id). Fetch customer_impact first. Pin its current promise, criterion and occurrence; use critical_event.evidence_id as expected_evidence_id. Name the customer's consequence and sources. Ordered steps have distinct keys, calendar-day durations, optional workspace owners and earliest starts; dependencies name earlier keys. Saving proposes human-only Actions, never approves execution, confirms customer commitments, or changes the promised deadline. Revisions replace proposed steps only; progressed work must retain its commitments.
• buying_roles: revise sourced buying roles for one engagement (no id; JourneyBuyingRolesRequest). Read fetch type=customer_impact first; use its buying_roles.evidence_id as expected_evidence_id. Replace the full members list, naming each person's role, reason and source_evidence_ids. An empty list explicitly clears all assignments. Preserve unknowns; job titles and deal stakeholder membership do not prove authority. Show the exact revision and obtain human approval. attribute_sources_to_journey=true explicitly assigns account evidence to this engagement. This is an operator assessment, not customer confirmation, deal qualification, or verified impact.
• journey_measurement_fact: record/correct/retract a sourced operator fact for an approved journey observation (no id; JourneyMeasurementFactRequest). Pin run_action_id, journey_id and independent exact-journey source_evidence_ids. checkpoint_balance describes the balance at the approved horizon; terminal_loss records its event time; impact_followup attests continuous observation with no qualifying impact from commitment through observed_at for the pinned promise. Requires explicit reviewed_source_records confirmation and an owner/operator. It does not certify complete external source coverage.
• customer_journey: record one sourced engagement (no id; payload is CustomerJourneyCreate: account_id, offer_id, kind, source_key, source_evidence_id and optional originating deal / trial relationship). Read fetch type=customer_impact id=account UUID first. Account UI: Impact tab.
• impact_promise: record/revise a sourced promise (no id; ImpactPromiseRequest). Freeze the journey, next promise_revision, criteria, owner and verifier policy. Supply expected_claim_id from the workspace. Preserve existing SPICED context.
• impact_report: report/correct/retract one criterion occurrence (no id; ImpactObservationRequest). Use the exact claim_id and current predecessor. attribute_sources_to_journey=true explicitly attributes matching account evidence to THIS result; it never rewrites the original source. Show this assignment to the user. Customer confirmation needs a matching inbound source, person and quotation. A model's assertion is not confirmation.
• impact_verify: verify the exact saved observation (no id; ImpactVerificationRequest). Obtain the user's explicit verification decision; recording a report is not permission to verify it. Current tenant membership, frozen verifier policy and source validity are rechecked by the same REST path. No action changes canonical First Impact/Recurring Impact metrics yet.
• task: create a follow-up task on the account (id = the account's company UUID; payload as for manage_person task).
• note: add a note to the account's record (id = the account's company UUID; payload = {body}). The response's note id and updated_at identify the note for a later edit.
• parent: set or clear corporate ownership (id=child company UUID). payload={parent_company_id: UUID|null, expected_parent_company_id: UUID|null, source:{url,title?,observed_at}}. Read fetch company_family first. A public source is required even when clearing. Native owner or operator only. Does not merge companies, inherit research, or add family members to CRM.
• list: create, rename, archive, or unarchive an account list. No id; payload={action, list_id? (required except create), name? (create/rename), description?}.
• list_members: add/remove tenant accounts in a list. No id; payload={action: add|remove, list_id, company_ids: [UUID, ...]} (1–200). Lists never change objectives or start outreach.
• state: update an account's lifecycle state (id = the account's company_id; payload = {renewal_at?, notes?, service_model?, scoped_labor_minutes_per_month?}. The lifecycle stage is NOT settable: it is a projection over recorded facts — a won deal (committed), the first post-commit impact event (onboarded), recurring impact (adopting; expansion_ready when no deal is open), sixty days without impact (dormant), a recorded churn event or a cancelled bound subscription (churned). Record the fact with record_impact or a deal outcome and the stage follows; the state read carries lifecycle with the basis and the facts). service_model (managed | self_serve_support | design_partner) and the scoped labor limit are the VRU-864 delivery-economics settings.
• record_impact: log a value-delivered impact event on an account (id = company_id; payload = {practice, event_type, person_id?, value_delivered_numeric?, value_delivered_unit?, source_type?, source_id?, occurred_at?, summary?, metadata?}).
• delete_impact: permanently remove an impact event (id = the impact EVENT/activity id, not the account). DESTRUCTIVE.
• adopt_directory: add a shared canonical company to this tenant's CRM (id = directory company UUID; no payload). The global company remains shared and cannot be edited unless the tenant separately owns it.
• record_labor: log labor done OUTSIDE this harness — calls, meetings, email, work in other tools (no id; payload = {entries: [{company_id?, service_model, work_type, minutes, source_ref?, note?}], work_date?, source? (operator_manual, the default | harness_telemetry)}). Do NOT log this session's own time: the server measures every harness MCP session from its tool calls automatically, so logging it here counts the minutes twice (source=harness_telemetry from an MCP call is refused). Idempotent per entry on source_ref (a source_ref reused with different content is refused — use one per piece of work; the 'mcp_span:' prefix is reserved for the server's own telemetry). operator_manual entries are confirmed at insert. The batch is write-safe: per-entry errors are reported in errors, never silently half-applied. Service model self_serve_support marks founder repair on a self-serve account — never blend it into managed. Work types: onboarding, campaign_ops, reply_handling, meeting, content, research, repair, support, expansion, admin.
• confirm_labor: the daily one-line confirmation of YOUR day (no id; payload = {work_date, entries?, confirm_telemetry?}). entries REPLACE your day for their account outright (every prior active row of yours there, of any source, is superseded, so corrected minutes win; a colleague's rows stay); confirm_telemetry=true stamps your own remaining unconfirmed telemetry as-is, never a colleague's. Refreshes each touched account's labor-scope claim in the ledger (failures reported in claim_failures). Read the economics with fetch type='unit_economics'.

Bulk: id arrays loop with per-item status (partial failure reported per item, never silent; max 100). Every action checks its payload keys against the route's own model first: an unknown key is a 422 that names it and lists the fields the action takes. Values are validated by the underlying route's schema.