Admin And Operator Portal

The admin/operator portal is the FlowClaw control console.

It is used by:

• Platform Admins
• Desk Operators

It is not the merchant-facing portal.

What This Portal Controls

The console controls:

• route sessions
• operator queues
• route approvals
• manual proof confirmation
• runtime assistant tasks
• generated artifacts
• route review cases
• manual route evidence
• FlowClaw recommendation evidence
• quote evidence
• proof evidence
• outcome scoring
• readiness reviews
• controlled route reviews
• merchant visibility
• audit log

Global Shell

Area	Meaning	Notes
Tenant selector	Active Operator Company workspace.	Most data is scoped to this tenant.
Sidebar navigation	Main control areas and filters.	Used to move between dashboard, audit, session, and validation areas.
Top nav	Console identity and high-level action area.	Shows signed-in context and console actions.
Context bar	Shows Operator Company, workspace, session, and corridor context.	Use it to avoid working in the wrong tenant or session.
Filters	Control which sessions and rows are visible.	Important for seeing pending, degraded, completed, and active work.
Account area	Current user and sign out.	Ends the auth session.

Login And Role Gate

The portal requires an authenticated user.

Valid control-console users are normally:

• admin legacy role, shown as Platform Admin
• operator legacy role, shown as Desk Operator

If a Merchant Client signs in here, the user should be moved to /merchant.html.

Start Here Walkthrough

The walkthrough card has two modes.

Desk Operator Tab

Use this tab when a staff member is handling route review and proof work.

Step	Meaning
Pick operator company	Select the workspace you are working in.
Find work	Start with rows marked ACTION.
Open workbench	Use Action or Inspect to open a session.
Read Desk Decision	Check mode, approval, execution status, queue state, and next action.
Ask FlowClaw	Use runtime assistant to check proof gaps, risk, or route state.
Take control action	Approve Route, Claim Session, Confirm Step, or Resume Execution.

Platform Admin Tab

Use this tab when an admin is supervising operators, evidence quality, and operational readiness.

Step	Meaning
Pick operator company	Review one Operator Company at a time.
Scan health	Use counts for waiting, degraded, completed, and blocked work.
Open exceptions	Start with ACTION rows, high-value sessions, degraded sessions, or stuck sessions.
Review decision quality	Check route, policy, evidence, proof, and runtime analysis.
Escalate or approve	Approve only when operationally acceptable.
Generate artifacts	Create summaries, proof packages, or handoff notes for evidence.

Quick Runtime Actions

These buttons send prebuilt runtime requests.

Button	Meaning	Backend
Status	Ask runtime for current workspace/session status.	POST /runtime/requests
Cowork	Ask runtime to assist with a cowork/task-style workflow.	POST /runtime/requests
Generate	Ask runtime to generate an artifact.	POST /runtime/requests

If a session is selected, the request is scoped to that session. If no session is selected, it is workspace-scoped.

Session Table

The session table is the main queue of route work.

Column or control	Meaning
Session ID	Internal route session reference.
Tenant/workspace	Operator Company context.
Amount/currencies	Route request amount and corridor assets.
Mode	Simulation, guided execution, live safe probe, or automated execution.
Status	Current execution status.
Queue state	Whether a human action is needed.
Approval state	Whether the route is pending or approved.
ACTION	Open a session that needs human work.
INSPECT	Open a session for review even if no immediate action is required.

Session Actions

These buttons appear only when the selected session state allows them.

Button	When it appears	Meaning
Approve Route	Status is recommendation_ready and not already approved.	Desk/operator approval that the route may proceed operationally.
Resume Execution	Status is step_failed, execution_failed, execution_paused, or route_degraded.	Continue after a human reviews the failure or degraded state.
Claim Session	Queue is waiting for operator and no operator is assigned.	Assigns the work item to the current operator.

Merchant Accept Route and Desk Approve Route are different controls. Merchant acceptance means the merchant accepts the route. Desk approval means operations allows the route to proceed.

Desk Decision Panel

The Desk Decision panel explains what the operator should do next.

Field	Meaning
Mode	Execution mode for the session.
Approval	Current approval state.
Status	Current execution state.
Queue badge	Human queue state.
Next action	Plain English next operator action.

The next action changes depending on status, approval state, and queue state.

Session Snapshot

The Session Snapshot card summarizes one selected session.

Field	Meaning
Amount	Amount and currency pair.
Mode	Simulation/guided/live probe/automated execution.
Approval	Approval state.
Queue	Whether work is pending, degraded, blocked, or clear.
Route	Selected route ID.
Fee / Trust	Estimated route fee and trust score.

Route Steps

The Route Steps card shows the ordered path.

Each row shows:

• step number
• provider
• step type
• from asset
• to asset
• whether proof is required

If a step requires manual confirmation, the operator must not mark it done without proof.

Step Confirmation Required

This panel appears when the current session is waiting for a human step.

Field or button	Meaning
Proof reference	Transaction ID, receipt number, artifact reference, or other proof handle.
Confirmation note	Optional operator note.
Confirm Step	Calls POST /sessions/{session_id}/steps/{step_id}/confirm.

The Confirm Step button stays disabled until a proof reference is entered.

Evidence Panel

This card counts proof/session artifacts and runtime-generated artifacts.

Use it to verify whether a route has enough proof before approving, resuming, or marking a manual step complete.

Advanced Raw Session JSON

This collapsed section shows raw session JSON.

Purpose:

• troubleshooting
• API contract review
• support investigation

It should not be used as the normal operator workflow.

Route Review Cases

This workspace records route cases, manual route evidence, FlowClaw recommendations, quotes, proof, outcomes, and merchant-safe visibility.

Create Pilot Case

The create form records a case that the operator will use for route review, quote comparison, or controlled evidence collection.

Typical fields include:

Field	Meaning
Case/corridor details	What merchant/corridor/problem the case represents.
Amount and currencies	Payment size and route assets being tested.
Case source	Historical case, live quote comparison, controlled review, or operator-entered case.
Operator notes	Context needed for review.

Backend route: POST /pilot-cases.

Pilot Cases List

Shows created pilot cases and evidence status.

Backend route: GET /pilot-cases.

Use this list to select the active case for all downstream evidence panels.

Proof Quality Review

The Proof Quality panel reviews whether cases have enough proof for operational review.

Backend route: GET /pilot-cases/proof-quality.

It helps answer:

• Which cases lack proof?
• Which cases are excluded from review?
• Which evidence is weak or incomplete?

Outcome Evidence Review

The Outcome Evidence panel checks whether route case outcomes are meaningful.

Backend route: GET /pilot-cases/outcome-evidence.

It reviews:

• outcome labels
• confidence scores
• merchant clarity scores
• missing obvious route flags
• severe hallucination flags
• evidence completeness

Stage 0 Evidence

Stage 0 reviews historical route cases.

Backend route: GET /pilot-readiness/stage-0-evidence.

Goal: compare FlowClaw recommendations against known route history.

Stage 1 Evidence

Stage 1 reviews current quote evidence.

Backend route: GET /pilot-readiness/stage-1-evidence.

Goal: compare FlowClaw recommendations against current operator quotes.

Stage 2 Readiness

Stage 2 reviews readiness for a controlled route check.

Backend route: GET /pilot-readiness/stage-2-readiness.

The panel indicates whether controlled review preparation can begin.

Readiness Decision

The readiness decision form records governance state.

Backend route: POST /pilot-readiness/decisions.

Field	Meaning
Decision state	Readiness decision, such as locked or ready.
Decision notes	Admin explanation.
Supporting evidence refs	Case IDs, proof refs, or artifact refs that justify the decision.

This is a Platform Admin governance path, not a merchant or settlement-agent decision.

Governance Evidence

The governance evidence panel builds an evidence bundle for one pilot case.

Backend route: GET /pilot-governance/pilot-cases/{pilot_case_id}/evidence.

Use it before using a case as evidence for an operational readiness decision.

Controlled Probe Preparation

Controlled probe preparation checks whether a controlled route check is allowed.

Backend route: POST /pilot-readiness/controlled-probe-preparations.

The panel stays locked until the required evidence is present.

Controlled Probe Rail Ownership

This form records whether the rail used for the controlled review is operator-owned or merchant-owned and whether ownership is acknowledged.

Backend route: PUT /pilot-cases/{pilot_case_id}/controlled-probe/rail-ownership.

Field	Meaning
Account ownership type	Operator-owned or merchant-owned rail.
Operator eligibility confirmed	Confirms the operator is eligible to use that rail.
Evidence reference	Proof for ownership/eligibility.
Non-custodial boundary acknowledged	Records that FlowClaw is acting as route intelligence and workflow software.
Boundary note	Optional explanation.

Controlled Probe Settlement Leg

This form assigns a settlement or proof leg to a Settlement Agent.

Backend route: POST /controlled-probe-settlement-legs.

Field	Meaning
Pilot case	Case being probed.
Route reference ID	Route candidate or manual route being tested.
Step reference ID	Route step being assigned.
Settlement agent	Assigned verified_agent.
Reference details	What the agent needs to prove.
Expected completion window	Time expectation.

Settlement Agents can submit proof for assigned legs but cannot approve routes or bypass policy.

Controlled Probe Completion

This form records controlled probe completion proof.

Backend route: PUT /pilot-cases/{pilot_case_id}/controlled-probe/completion.

Complete it when supporting proof exists.

Controlled Probe Actuals

This form records actual probe results.

Backend routes:

• PUT /pilot-cases/{pilot_case_id}/controlled-probe/actuals
• GET /pilot-cases/{pilot_case_id}/controlled-probe/actuals

Fields include:

• actual fee
• actual timing
• final status
• proof reference
• failure or partial reason
• whether the evidence supports readiness

Manual Route

The manual route form captures the route a human operator used or would use.

Backend routes:

• POST /pilot-cases/{pilot_case_id}/manual-route
• GET /pilot-cases/{pilot_case_id}/manual-route

Field	Meaning
Manual route kind	Historical actual or operator-proposed route.
Route summary	Plain English route path.
Operator rationale	Why the operator chose it.
Provider/counterparty	Provider, bank, OTC, agent, or counterparty involved.
Estimated rate	Operator-estimated FX or conversion rate.
Estimated fee	Operator-estimated cost.
Expected completion time	Operator expectation.
Proof requirements	Proof the route would need.

FlowClaw Recommendation

This panel generates or stores FlowClaw's recommendation for a route case.

Backend routes:

• POST /pilot-cases/{pilot_case_id}/flowclaw-recommendation
• GET /pilot-cases/{pilot_case_id}/flowclaw-recommendation

Purpose: compare what FlowClaw recommends against the manual route and collected quotes.

Route Quote Evidence

This form records quotes collected by the operator.

Backend routes:

• POST /pilot-cases/{pilot_case_id}/route-quotes
• GET /pilot-cases/{pilot_case_id}/route-quotes
• PATCH /pilot-cases/{pilot_case_id}/route-quotes/{quote_id}/evidence-source-type

Use it to prove whether FlowClaw pricing and timing assumptions match reality.

Quote Comparison

This panel compares FlowClaw's recommendation with quote evidence.

Backend route: GET /pilot-cases/{pilot_case_id}/quote-comparison.

It shows whether the recommendation aligns with real quote evidence.

Proof Evidence

This form attaches proof to a route case.

Backend routes:

• POST /pilot-cases/{pilot_case_id}/proof-evidence
• GET /pilot-cases/{pilot_case_id}/proof-evidence
• GET /pilot-cases/{pilot_case_id}/proof-evidence/{pilot_proof_evidence_id}/download

Proof can be an artifact, receipt, screenshot, reference ID, or operator-verified record depending on the case.

Outcome

The outcome form records what happened.

Backend routes:

• PUT /pilot-cases/{pilot_case_id}/outcome
• GET /pilot-cases/{pilot_case_id}/outcome

Outcome should reference supporting evidence.

Outcome Scores

This form records scoring for the route case.

Backend route: PUT /pilot-cases/{pilot_case_id}/outcome-scores.

Score	Meaning
Operator confidence	Whether the operator trusts the recommendation.
Merchant clarity	Whether a merchant could understand the recommendation.

Quality Flags

This form records serious route quality issues.

Backend route: PUT /pilot-cases/{pilot_case_id}/quality-flags.

Important flags:

• missing obvious route
• severe hallucination
• weak or incomplete evidence

These flags help admins spot route quality issues that need review.

Merchant Visibility

This panel controls whether a route case appears in the Merchant Portal.

Backend route: POST /pilot-cases/{pilot_case_id}/merchant-visibility.

Field	Meaning
Merchant user	Assigned Merchant Client.
Visible flag	Whether the case appears in /merchant.html.
Merchant-safe summary	Safe explanation shown to the merchant.
Required action	Merchant action prompt.

Merchant visibility should use a clear summary, required action, and safe evidence language.

Workspace Runtime

This panel lets the operator ask FlowClaw questions without selecting a specific session.

Examples:

• "Summarize current queue health."
• "What cases are missing proof?"
• "Which sessions are degraded?"
• "Generate a handoff summary."

Backend route: POST /runtime/requests.

Session Workbench

The session workbench opens when a session is selected.

It includes:

• back button
• session snapshot
• desk decision
• route steps
• step confirmation
• runtime assistant
• artifacts
• raw JSON

Runtime Artifacts

Runtime-generated artifacts are shown in the workbench and workspace panels.

Common artifact actions:

Button	Meaning
Copy	Copy artifact content or reference.
Download	Download an artifact through backend-mediated access.

Related backend routes:

• GET /runtime/artifacts
• GET /runtime/artifacts/{artifact_id}
• GET /sessions/{session_id}/artifacts
• GET /artifacts/{artifact_id}/download
• POST /sessions/{session_id}/steps/{step_id}/artifacts
• POST /sessions/{session_id}/steps/{step_id}/artifacts/upload

Audit Log

The audit log shows tenant-scoped audit entries.

Backend route: GET /audit/log.

Use it to review:

• route creation
• approval
• resume
• manual step confirmation
• artifact attachment
• route case evidence changes
• readiness decisions
• controlled probe changes

Operating Rules

• Work in one Operator Company tenant at a time.
• Approve routes only after reviewing status, policy, and evidence.
• Confirm manual steps only with proof.
• Publish merchant-visible cases only with a safe summary.
• Record readiness decisions with supporting evidence references.
• Keep Settlement Agents limited to assigned proof submission.