Discovery pilot START (staging)

This pilot runs on Fly staging, not api.agentchain.cloud. Staging API base: https://agentchain-discovery-staging.fly.dev/api/v1/discovery Current contracts: discovery schema 0.3.0 · capability index 0.3.0 · intent rules intent-rules-v2 · recipes discovery-recipes-v3. Production OpenAPI at docs.agentchain.cloud/openapi.json does not include discovery routes until GCP cutover. Use discovery-openapi.json (pilot subset), this page, and the staging base above. Human / agent entry (marketing): humbleaf.xyz/agent-assessment · Machine bundle: /.well-known/humbleaf-agent-entry.json

Roles

Role	What you do
Operator	Sign in at the console, issue discovery access for your workspace, review the same assessment, end access when done
Assessor (human or agent)	Use discovery access + this START; no operator login
Anonymous	Intent preview only — no saved assessment

Assessments belong to the operator workspace that issued the grant. External assessor grants are single-assessment actors: they can read and mutate only sessions created by that same grant. Operator credentials remain workspace-wide.

Intent preview: console.agentchain.cloud/discovery/preview
Workspace (assessor or operator): console.agentchain.cloud/discovery

Operators sign in on the workspace page, then use Invite your agent to issue access and copy the invitation (public or private copy actions). If assessor access expired, the operator issues new access. Stale browser credentials clear on 401 when an operator session is also present.

Invitation (operator)

At issuance the console builds an invitation from the live API response:

Environment label and API base (not hardcoded staging copy)
Workspace id the assessor will write into
Actual scopes and expiry
Objective and declared exploration allowance (operator-entered)
Selected track, exact least-privilege scopes, START URL, and the track-specific return contract

Use Copy private invitation once to bundle token-free instructions with the acdg_… credential. Deliver through your secret channel. Do not put credentials in URL query parameters or public docs. If the invitation already included discovery access, the assessor proceeds without asking again. If not, stop after anonymous preview and request an invitation. Private export is an explicit operator opt-in; it is not part of every assessor grant.

Stateless API (no credential)

Preview

POST https://agentchain-discovery-staging.fly.dev/api/v1/discovery/public/preview
Content-Type: application/json

{
  "desiredOutcome": "Identify one bounded workflow where Humbleaf can improve accountability.",
  "workflowFamily": "other",
  "consequentialActions": "unknown",
  "currentFriction": "unknown",
  "availableInput": "none",
  "explorationAllowance": "unknown",
  "excludedExperimentIds": ["refund_policy_boundary"]
}

If the result asks candidateFocus, send the second request with the entire original input, root-level previewAnswers, and the actual available input:

POST https://agentchain-discovery-staging.fly.dev/api/v1/discovery/public/preview
Content-Type: application/json

{
  "desiredOutcome": "Identify one bounded workflow where Humbleaf can improve accountability.",
  "workflowFamily": "other",
  "consequentialActions": "unknown",
  "currentFriction": "unknown",
  "availableInput": "approved_spec",
  "explorationAllowance": "unknown",
  "excludedExperimentIds": ["refund_policy_boundary"],
  "previewAnswers": [
    {
      "questionId": "candidateFocus",
      "selectedOptionId": "candidate_findings_review"
    }
  ]
}

The completed result selects document_only_review. Preserve the exact completed input for session import. Preview is stateless: it creates no session and grants no authority.

Public projection (recipes + rules, no tenant state)

GET https://agentchain-discovery-staging.fly.dev/api/v1/discovery/public/projection

Optional reference sample (MerchantLine refund exercise only)

GET https://agentchain-discovery-staging.fly.dev/api/v1/discovery/public/sample/merchantline-orders

Use this only when the selected track is reference_refund_sample or the operator explicitly accepts it as a labeled exercise. It is never required for a general findings-only assessment.

Authenticated assessment

Use X-Discovery-Grant: acdg_… (assessor) or Authorization: Bearer … (operator JWT). Never put either credential in a URL. The console active mode selects which header is sent; do not rely on silent fallback. Track-specific scopes:

fit_shortlist: discovery:create, discovery:read
document_only_review: create, read, submit source, answer, recommend, complete
comparison tracks: create, read, submit source, answer, draft, compare
discovery:export_own: optional and explicit; never a default

1. Create session (revalidate imported plan)

After public preview, send the exact completed previewInput plus versions from the preview/projection response. The server fully recomputes it. Missing answers, stale versions, and recommendation mismatch fail closed with an actionable 400 error.

POST https://agentchain-discovery-staging.fly.dev/api/v1/discovery/sessions
X-Discovery-Grant: acdg_…
Content-Type: application/json

{
  "workflowGoal": "Review consequential operations in one approved specification",
  "importedPlan": {
    "previewInput": {
      "desiredOutcome": "Identify one bounded workflow where Humbleaf can improve accountability.",
      "workflowFamily": "other",
      "consequentialActions": "unknown",
      "currentFriction": "unknown",
      "availableInput": "approved_spec",
      "explorationAllowance": "unknown",
      "excludedExperimentIds": ["refund_policy_boundary"],
      "previewAnswers": [
        {
          "questionId": "candidateFocus",
          "selectedOptionId": "candidate_findings_review"
        }
      ]
    },
    "rulesVersion": "intent-rules-v2",
    "capabilityIndexVersion": "0.3.0",
    "clientRecommendationId": "document_only_review"
  }
}

2. Submit source

POST …/sessions/{sessionId}/source
Content-Type: application/json

{
  "label": "Operator-approved workflow API",
  "document": { … one bounded OpenAPI 3.x object … }
}

The raw body is not retained. The service stores its digest, a sanitized endpoint snapshot, findings, and questions. External references are recorded and never fetched.

3. Give every question an explicit disposition

POST …/sessions/{sessionId}/answers
Content-Type: application/json

{
  "questionId": "q_approver_mapping",
  "answeredBy": "Your name",
  "disposition": "reports_information",
  "statement": "Describe how approval works today, if known."
}

Allowed dispositions are reports_information, reports_absence, unknown, not_applicable, defers, and requests_clarification. Missing or invalid disposition fails closed. not_applicable is not normalized into substantive information. Every answer is reported context with attestation: none; it never establishes owner authority.

4A. Findings-only: submit one assessor recommendation

Use this branch only when selectedTrack is document_only_review.

POST …/sessions/{sessionId}/recommendations
Content-Type: application/json

{
  "assessorVersion": "external-agent/1",
  "disposition": "PROCEED",
  "riskRanking": [
    {
      "rank": 1,
      "endpointRef": "POST /configuration/releases",
      "rationale": "Potential production configuration mutation."
    }
  ],
  "pilotRanking": [
    {
      "rank": 1,
      "endpointRef": "POST /configuration/releases",
      "rationale": "Bounded, reversible shadow observation with a named owner."
    }
  ],
  "recommendedRouteEndpointRef": "POST /configuration/releases",
  "reasonCodes": ["BOUNDED_SHADOW_FEASIBLE"],
  "boundaryHypothesis": {
    "allow": ["Staging-only observation with no downstream write."],
    "approvalRequired": ["Production activation or expanded authority."],
    "deny": ["Cross-tenant scope or payload changed after approval."]
  },
  "evidenceRequirements": ["actor", "input digest", "decision", "resulting state"],
  "blockingUnknowns": ["Accountable production owner is not yet attested."]
}

REVISE, DEFER, and NO_RESPONSIBLE_RECOMMENDATION are valid. The server validates route references but does not replace assessor judgment with a hardcoded ranking. It binds the record to the source digest, reported-context digest, capability version, author, and generation time.

4B. Findings-only: explicitly finish

POST …/sessions/{sessionId}/complete-track
Content-Type: application/json

{
  "track": "document_only_review",
  "reason": "All generated questions have explicit dispositions and the current recommendation is ready for operator review."
}

This mutation requires discovery:complete. It records actor and reason. It fails if the source is missing, a question is untouched, or the recommendation is absent/stale. Success returns state: ready_for_review and reviewKind: findings_only. It does not authorize execution.

4C. Policy-comparison tracks only: create draft

POST …/sessions/{sessionId}/drafts
Content-Type: application/json

{
  "endpointRef": "POST /v2/orders/{orderId}/refunds",
  "title": "Refund guard",
  "approvalThresholdMinor": 5000,
  "perOperationCapMinor": 10000,
  "currency": "USD"
}

5. Policy-comparison tracks only: synthetic comparison

POST …/drafts/{draftId}/comparison

Expect executionAuthorized: false, comparisonKind: synthetic_policy_test.

6. Read / export

GET …/sessions/{sessionId}
GET …/sessions/{sessionId}/export  # only with explicit discovery:export_own

An external assessor can read or export only a session created by that same grant. An operator can review all sessions in the operator workspace. Reissuing a grant does not transfer session access.

Console locators (no tokens in URL)

The workspace UI lists these for a saved session:

Session / recommendation: https://console.agentchain.cloud/discovery?session={sessionId}
Findings: …?session={sessionId}#findings
Open questions: …#questions
Policy boundary (comparison tracks only): …&draft={draftId}&comparison={comparisonId}

Links locate artifacts; they do not grant new permission. Operators read with their signed-in session in the same workspace.

End access

When review and follow-up are complete, the operator uses End access in the invitation panel. That stops future assessor requests; it does not delete the assessment. A ready_for_review state or an existing comparison does not auto-revoke access.

Limits

Synthetic comparisons only; executionAuthorized stays false.
A recommendation, proposed boundary, comparison, or ALLOW label grants no execution authority.
Exploration spend limits are declared/reported, not Humbleaf-enforced on this release unless documented otherwise.
Assessor answers are reported context, not cryptographic owner attestation.

Appendix — assessor report (required sections)

When you return findings to the operator, include all of the following in plain language (≤600 words plus a compact evidence table is fine). The operator should run the internal operator review playbook (v1) — 30-minute script with the same three console locators — before End access.

Establishes

What this assessment demonstrates with inspectable evidence in the operator workspace:

The selected track and the exact completed preview input.
Document-derived findings from one supplied source digest.
Reported context as assessor-attributed statements, not owner proof.
For findings-only: one structured disposition, separate risk/pilot rankings, boundary hypotheses, evidence requirements, and blocking unknowns.
For comparison tracks only: a draft and synthetic result with executionAuthorized: false.

Does not establish

What you must not imply — for example:

Live execution, production approval, or enforcement on the customer’s API.
Cryptographic attestation that operational facts in answers are true.
Full Authority Surface Map coverage or paid guard deployment.
That a synthetic verdict “passing” or showing approval required means the pilot succeeded — success for the operator is an integration decision, not comparison-green alone.

If the console marks a recommendation or comparison stale, report it as historical and do not reuse it as current evidence.

Smallest next integration

One concrete next step if the assessor disposition is PROCEED — for example:

Upload approved OpenAPI and re-run assessment on their real surface (not only MerchantLine reference sample).
Authority Surface Map or scoped pilot SKU on a named route/guard.
Owner interview to resolve a specific open question id from #questions.

Return sessionId for every track. Return draftId and comparisonId only when the selected track created them. Include the applicable token-free console locators:

Session / recommendation: https://console.agentchain.cloud/discovery?session={sessionId}
Findings: https://console.agentchain.cloud/discovery?session={sessionId}#findings
Open questions: https://console.agentchain.cloud/discovery?session={sessionId}#questions
Policy boundary (comparison tracks only): https://console.agentchain.cloud/discovery?session={sessionId}&draft={draftId}&comparison={comparisonId}

End with PROCEED, REVISE, DEFER, or NO_RESPONSIBLE_RECOMMENDATION, and explain risk priority separately from pilot priority. The operator revokes discovery access after review; that step is not assessor-automated.

Agent assessment (pilot)

Getting Started

Operator Manual

Discovery pilot START (staging)

Roles

Invitation (operator)

Stateless API (no credential)

Preview

Public projection (recipes + rules, no tenant state)

Optional reference sample (MerchantLine refund exercise only)

Authenticated assessment

1. Create session (revalidate imported plan)

2. Submit source

3. Give every question an explicit disposition

4A. Findings-only: submit one assessor recommendation

4B. Findings-only: explicitly finish

4C. Policy-comparison tracks only: create draft

5. Policy-comparison tracks only: synthetic comparison

6. Read / export

Console locators (no tokens in URL)

End access

Limits

Appendix — assessor report (required sections)

Establishes

Does not establish

Smallest next integration

​Roles

​Human entry (no login)

​Invitation (operator)

​Stateless API (no credential)

​Preview

​Public projection (recipes + rules, no tenant state)

​Optional reference sample (MerchantLine refund exercise only)

​Authenticated assessment

​1. Create session (revalidate imported plan)

​2. Submit source

​3. Give every question an explicit disposition

​4A. Findings-only: submit one assessor recommendation

​4B. Findings-only: explicitly finish

​4C. Policy-comparison tracks only: create draft

​5. Policy-comparison tracks only: synthetic comparison

​6. Read / export

​Console locators (no tokens in URL)

​End access

​Limits

​Appendix — assessor report (required sections)

​Establishes

​Does not establish

​Smallest next integration

Roles

Human entry (no login)

Invitation (operator)

Stateless API (no credential)

Preview

Public projection (recipes + rules, no tenant state)

Optional reference sample (MerchantLine refund exercise only)

Authenticated assessment

1. Create session (revalidate imported plan)

2. Submit source

3. Give every question an explicit disposition

4A. Findings-only: submit one assessor recommendation

4B. Findings-only: explicitly finish

4C. Policy-comparison tracks only: create draft

5. Policy-comparison tracks only: synthetic comparison

6. Read / export

Console locators (no tokens in URL)

End access

Limits

Appendix — assessor report (required sections)

Establishes

Does not establish

Smallest next integration