{
  "edition": "R1",
  "language": "en",
  "title": "Custom Execution Guide",
  "intro": "Choose one supported task, obtain its exact handoff, follow the bounded steps and keep the result with its next owner. These five cases distinguish preparation, observation, report verification, an authorized configuration change and AI planning.",
  "cases": [
    {
      "id": "helper-preparation",
      "title": "Prepare one integration source document",
      "mode": "PREPARATION_ONLY",
      "availability": "Available now for local document preparation and reading published results. A complete customer Helper request package is still a separate prerequisite.",
      "goal": "Describe a status.read operation and identify what the supported target package must supply.",
      "prerequisites": [
        "A non-secret operation brief and an owner for the service description.",
        "The public status-document.json source example and its field reference; keep the original and edit a copy.",
        "Record the supplied tool/build and target references, or mark them unknown; the recorded macOS Helper build identity is unproven."
      ],
      "changes": "Creates or edits caller-owned local documents only. No product registration, runtime configuration or provider request.",
      "evidence_scope": "JSON syntax and source-field review can be completed here. Published DISCOVER PASSED establishes local source discovery; NORMALIZE DENIED / CONTRACT_INCOMPATIBLE leaves target compatibility open.",
      "steps": [
        {
          "title": "Describe the source",
          "action": "Use the brief to name the read operation, input service:string and output service:string plus healthy:boolean. Keep declared shapes separate from actual request values or a live reply.",
          "expected": "One reviewable operation description with no claimed service call.",
          "keep": "Operation brief, data owner and approved non-secret sample reference.",
          "stop": "If the intended service or data use is unclear, return the description to its owner.",
          "source_url": "/docs/worked-examples-en.html#contract"
        },
        {
          "title": "Edit and check a source copy",
          "action": "Follow the CUSTOM_API field table: retain protocol revision 1, primitive property types and consistent required lists. Use the published JSON syntax check if Python 3 is available. Keep notes in the brief, not unsupported JSON fields.",
          "expected": "A readable JSON source document; syntax success is recorded separately from product validation.",
          "keep": "Original/source-copy references, intended edits and any actual syntax result.",
          "stop": "Fix only the identified format error in the copy. Do not add invented contract or credential fields.",
          "source_url": "/docs/worked-examples-en.html#document"
        },
        {
          "title": "Separate source from request envelope",
          "action": "List the supplier-owned contract/adapter IDs and revisions that are still needed. The source belongs in draft.source of a matching complete request; do not combine public fragments into a claimed valid request or pass the source directly to r2-discover.",
          "expected": "A concrete missing-deliverable list for a complete versioned request, supported target and installation route.",
          "keep": "Supplied target references or explicit unknowns; responsible supplier contact.",
          "stop": "No complete matching package means stop before product preparation commands.",
          "source_url": "/docs/worked-examples-en.html#check"
        },
        {
          "title": "Read the retained outcomes and hand off",
          "action": "Read the published DISCOVER and NORMALIZE excerpts together. Record each operation, request_id, status, reason and lifecycle_stage. Both excerpts contain the same historical request ID; this is a record to inspect, not a key for reuse. R2 semantic denial can return process exit 0; read the JSON result.",
          "expected": "Discovery success and normalization denial remain distinct; the next owner receives the missing target/package question.",
          "keep": "Cited excerpts and a separate interpretation/next-action note.",
          "stop": "Do not claim normalized, registered or connected execution from DISCOVER PASSED.",
          "source_url": "/docs/worked-examples-en.html#acceptance"
        }
      ],
      "done": "A source copy, any actually performed syntax result, a correctly interpreted retained result and a named missing-deliverable handoff are recorded.",
      "closeout": "Keep the original and edited copy under the data owner’s retention choice. No service needs stopping in this preparation route. Continue product preparation only after the supplier supplies the matching complete package and scope.",
      "source_url": "/docs/worked-examples-en.html#start"
    },
    {
      "id": "headless-observation",
      "title": "Observe one supplied Headless service",
      "mode": "CONDITIONAL_OPERATION",
      "availability": "Read the reference now; run read-only queries only with the supplied client, intended local service and authorized query access.",
      "goal": "Record service presence, readiness and reasons without submitting a Work or changing the service.",
      "prerequisites": [
        "Exact client/service release, supported platform and the operator account.",
        "Supplied local socket and confirmation that the intended service is running; a desktop terminal is not automatically an appliance connection.",
        "Permitted status/health access and a new private output directory."
      ],
      "changes": "Queries service state and writes local observation files. It does not start the service, configure a provider or submit Work.",
      "evidence_scope": "A successful query proves the returned observation for that target/time. It does not grant Work authority or establish every dependent readiness item.",
      "steps": [
        {
          "title": "Confirm the observation target",
          "action": "Compare client path, service release, socket and account with the operator handoff. Use the reference help check to confirm the supplied command.",
          "expected": "The intended local query context is identified.",
          "keep": "Target/release and non-secret handoff references.",
          "stop": "Missing client or endpoint goes to delivery/operator before querying.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-handoff"
        },
        {
          "title": "Capture status and health separately",
          "action": "Follow the supplied baseline block using the same client/socket/account. Record each exit immediately and preserve status.json and health.json privately.",
          "expected": "Two query observations and their own exit codes, or the exact unperformed/failed stage.",
          "keep": "Observation time, command reference, exits and sanitized source references.",
          "stop": "Transport failure is not a reason to start or restart the service automatically.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-baseline"
        },
        {
          "title": "Interpret component states",
          "action": "Copy literal liveness, readiness, authority/runtime states and relevant reasons. Keep UNKNOWN visible and ask the affected component owner whether it blocks the intended next task.",
          "expected": "An observation summary that separates service presence from task-specific readiness.",
          "keep": "Literal states/reasons and the next-owner question.",
          "stop": "Do not apply the historical lab’s exception to this installation or infer permission from exit 0.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-health"
        }
      ],
      "done": "The intended target and actual query results are recorded; unanswered readiness questions have an owner.",
      "closeout": "Retain sanitized observations and leave the supplied service unchanged. Record that no Work was submitted. Any later service or Work action follows a separately supported authorized route.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-health"
    },
    {
      "id": "report-verification",
      "title": "Verify an existing Work report",
      "mode": "READING_AND_VERIFICATION",
      "availability": "Read the published example now. Actual file checks require authorized access to your own selected Work/revision and its report files.",
      "goal": "Check that the delivered JSON and PDF belong to the same selected Work and match their reported file hashes.",
      "prerequisites": [
        "An existing saved Work ID and selected report revision, supplied by the authorized operator or matching read query.",
        "Actual returned JSON/PDF paths or approved copies with an attributable handoff.",
        "An approved local viewer and file verifier for your platform; raw reports remain private."
      ],
      "changes": "Reads selected records and files; may save local review notes. It creates no new Work or replacement report.",
      "evidence_scope": "Reading a historical comparison proves what the publication reported. A fresh match requires your own file observations; validation and human acceptance are separate.",
      "steps": [
        {
          "title": "Bind the selected record",
          "action": "Compare the saved Work ID with list/show/selected report references where available, preserving the same installation/account context. Record the chosen revision.",
          "expected": "One attributable Work and report revision, or an explicit mismatch.",
          "keep": "Work/report/revision references and same-identity observations.",
          "stop": "A missing selected report or identity mismatch stops the file-completion claim.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-reconcile"
        },
        {
          "title": "Read outcome and closure",
          "action": "Copy execution_count, validation_results, final_result, receipt/closure and returned retry/replay fields. Keep human_acceptance null or pending exactly as returned.",
          "expected": "Literal outcome and product acceptance are recorded separately from reviewer judgment.",
          "keep": "Selected report fields and their source reference.",
          "stop": "Do not fill unavailable values from the recorded example.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-report"
        },
        {
          "title": "Verify physical files",
          "action": "Use the returned paths or approved copies. Compare JSON bytes with json_file_sha256 and PDF bytes with pdf_sha256; remove the sha256: prefix only for comparison. Open the PDF and compare its Work/result with JSON.",
          "expected": "Readable same-revision files with observed hash comparisons, or an identified access/mismatch issue.",
          "keep": "Expected/observed file hashes and readability/identity observations; keep private paths local.",
          "stop": "report_sha256 is not a raw-file checksum. Missing files or mismatch go to the service operator; do not regenerate silently.",
          "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-files"
        }
      ],
      "done": "The review states exactly which selected-file checks were performed and the product’s literal acceptance state. A reading-only exercise is labeled as such.",
      "closeout": "Keep raw files under the data owner’s retention decision and share only approved references. Record missing delivery or verification with its owner; this task does not stop services or accept Work.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-files"
    },
    {
      "id": "admin-configuration",
      "title": "Review one approved logging change",
      "mode": "CONDITIONAL_OPERATION",
      "availability": "Conditional on a provisioned, authorized Admin installation and a separately approved change. The recorded repaired local candidate does not supply fresh r232 bootstrap.",
      "goal": "Apply only the approved log_level WARN change and distinguish its action receipt, stored value and effective behavior.",
      "prerequisites": [
        "Exact organization/appliance/installation, current administrator/grant references and the supplied connection profile.",
        "The change owner’s exact approval, current-state review and the supported configuration payload/procedure.",
        "A retention/recovery disposition and a supported stored/effective-value observation if that proof is needed."
      ],
      "changes": "May change the registered log_level setting after authorization. The visible {\"log_level\":\"WARN\"} fragment is not a complete request; no service restart is required by this configuration contract.",
      "evidence_scope": "An applied decision, mutation flag, revision and audit reference prove the recorded action within scope. The general projection withholds values; effective WARN needs the installation’s supported observation.",
      "steps": [
        {
          "title": "Connect and capture the baseline",
          "action": "Follow the supplied Admin connection checklist. Confirm returned target identity, then Refresh and record appliance state revision and configuration revision separately.",
          "expected": "A current authorized target and a baseline attributable to that target.",
          "keep": "Target, grant/reference, observation time and both revisions; retain private profile values locally.",
          "stop": "Target mismatch or missing Admin provisioning stops the change path.",
          "source_url": "/docs/vibepackr-admin-guide-en.html#admin-prerequisites"
        },
        {
          "title": "Review and submit once",
          "action": "Open Appliance → Update configuration. Compare Target and Expected revision with the current appliance state revision, then compare Requested change with the owner-approved log_level WARN change. Cancel a mismatch; submit once only within the supplied approval.",
          "expected": "The actual decision/reason, mutation flag and audit reference, not a prefilled APPLIED result.",
          "keep": "Approved intended change, expected revision and literal action response.",
          "stop": "For stale revision refresh and re-review; for an uncertain timeout preserve and reconcile the existing request before another submission.",
          "source_url": "/docs/vibepackr-admin-guide-en.html#admin-configuration"
        },
        {
          "title": "Verify receipt and effect separately",
          "action": "Refresh and inspect Audit for the matching action and revision. Record stored and effective values only through the supported observation supplied by the operator; otherwise leave them unobserved. A changed revision alone is not an effective-value test.",
          "expected": "Action/revision evidence plus a separate observed or unresolved stored/effective-state record.",
          "keep": "Audit reference, post-action revisions and the source of any stored/effective observation.",
          "stop": "If effect is unproven, assign the observation to the operator; do not mask the gap with a restart.",
          "source_url": "/docs/vibepackr-admin-guide-en.html#admin-configuration"
        },
        {
          "title": "Retain the result and disconnect",
          "action": "Record whether the authorized change remains applied or an explicit recovery decision is pending. Disconnect after review; saved profile fields are not a current snapshot. Use only a separately supplied and authorized recovery procedure if needed.",
          "expected": "Final connection state, retained change disposition and next owner are explicit.",
          "keep": "Minimal support record and retention/recovery procedure references.",
          "stop": "Do not delete managed profiles/keys or invent an inverse change as routine cleanup.",
          "source_url": "/docs/vibepackr-admin-guide-en.html#admin-support"
        }
      ],
      "done": "The one approved action and matching audit/revision are recorded; stored/effective evidence is either observed through its supported path or explicitly open.",
      "closeout": "Retain the approved state or hand a recovery decision to the change owner. Disconnect and preserve required history. This case performs no automatic rollback, service restart or customer bootstrap.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-configuration"
    },
    {
      "id": "ai-planning",
      "title": "Prepare an AI setup handoff",
      "mode": "PLANNING_ONLY",
      "availability": "Planning is available now. A controlled product/provider call remains dependent on the supported customer setup, exact runtime binding and explicit operation authority.",
      "goal": "Make model, identity, data, budget and setup dependencies concrete enough for their owners to resolve.",
      "prerequisites": [
        "Named PoC, cloud/AI and data owners; one permitted use-case question.",
        "Non-secret project/location/model choices or explicit unknowns, and an identity-owner reference.",
        "Exact delivery release and supplied setup/binding procedure reference, or a recorded missing-procedure request."
      ],
      "changes": "Creates a planning worksheet only. It does not enable APIs, alter IAM, configure a runtime or call Vertex AI.",
      "evidence_scope": "A completed plan identifies who must verify the actual identity, model/location, binding, cost and data conditions. It is not connected AI or customer E2E proof. GAPE observation and assistant document review are separate from Vertex execution.",
      "steps": [
        {
          "title": "Fill non-secret choices",
          "action": "Use the published AI worksheet to record project, supported location, exact model, identity owner, approved data class and budget/retry limits. Leave missing values unknown.",
          "expected": "A concrete plan without tokens, keys or invented model defaults.",
          "keep": "Worksheet and owner-confirmation references.",
          "stop": "Resolve unclear data use or cost ownership before any later setup.",
          "source_url": "/docs/agent-ai-guide-en.html#vertex"
        },
        {
          "title": "Assign setup evidence",
          "action": "Ask the cloud owner to confirm API/billing, actual attached VM service identity, inference permissions/access scopes, model/location policy and network. Ask delivery for the exact supported binding/setup route. Record each as supplied, pending or unknown based on evidence.",
          "expected": "Each prerequisite has a responsible owner and evidence to obtain.",
          "keep": "Non-secret procedure, identity-owner and dependency references.",
          "stop": "Fresh r232 administrator-dependent setup remains stopped at C7; do not substitute a test initializer or another platform’s authentication recipe.",
          "source_url": "/guides/poc/deployment.html#ai"
        },
        {
          "title": "Define a future check and hand off",
          "action": "Agree what a separately authorized small task would prove: actual selected model/location, whether a call was sent, returned result, product validation and measured cost. Keep expected text separate from a recorded reply.",
          "expected": "A bounded future check, stop conditions and owner/resume handoff; no call has been made by this plan.",
          "keep": "Expected result, budget/retention plan and missing-evidence list.",
          "stop": "Do not infer a provider call from a selected runtime or silently change provider/model to fill a missing prerequisite.",
          "source_url": "/docs/agent-ai-guide-en.html#vertex-example"
        }
      ],
      "done": "Owners can see the proposed task, required setup proof, cost/data limits and exact conditions for a later authorized evaluation.",
      "closeout": "Retain the planning record; leave actual call/result/cost fields blank. Handoff the supported setup question to delivery/cloud owners. No cloud resource or credential cleanup is implied by this plan.",
      "source_url": "/docs/agent-ai-guide-en.html#vertex"
    }
  ],
  "failures": [
    {
      "id": "F-01",
      "symptom": "A required installation, request package or target handoff is missing",
      "check": "Identify the selected case and the exact missing standard deliverable. Keep a source document, a target-reference fragment and a complete request distinct. For Admin, confirm provisioning first.",
      "owner": "Delivery/interface owner; product administrator for established Admin access.",
      "evidence": "Case, exact release or unknown, missing item and supplied-reference list.",
      "resume_when": "The exact version-matched deliverable and required access are supplied and checked for the target.",
      "closeout": "Keep the preparation brief and owner request. Stop only dependent operational steps; do not invent a target or customer-specific replacement script.",
      "source_url": "/docs/worked-examples-en.html#handoff"
    },
    {
      "id": "F-02",
      "symptom": "Source format or protocol revision is rejected",
      "check": "Compare document kind/revision, required names, primitive properties and unsupported fields with the matching public table. Read the actual status/reason as well as process exit.",
      "owner": "Source-document owner; supplier for missing schema/version facts.",
      "evidence": "Original source copy, one proposed correction, operation/stage and literal reason.",
      "resume_when": "The author checks the bounded correction; a product recheck waits for the complete supported request and authorized scope.",
      "closeout": "Preserve the failed input/result. Do not relabel a captured MCP protocol or turn unknown observations into true.",
      "source_url": "/docs/worked-examples-en.html#errors"
    },
    {
      "id": "F-03",
      "symptom": "Normalization, validation or registration preparation cannot advance",
      "check": "Read operation, status, reason, lifecycle_stage and next_required_actions. CONTRACT_INCOMPATIBLE requires the exact supported target; REQUIRES_AUTHORITY requires the supplied approval/transport route.",
      "owner": "Supplier/interface owner for target compatibility; designated registration/authority owner for the supported route.",
      "evidence": "Request/correlation references where returned, target revisions, reached stage and literal reason.",
      "resume_when": "The responsible owner supplies the missing target or supported next-stage route and its required validation.",
      "closeout": "Retain the actual failed/pending disposition. Discovery success or exit 0 does not close this branch.",
      "source_url": "/docs/integration-sdk-guide-en.html#output"
    },
    {
      "id": "F-04",
      "symptom": "Headless transport fails or a required readiness item is unknown",
      "check": "Check supplied client, release, socket and account. If a response exists, separate liveness from readiness and preserve each relevant reason; identify what the intended next task requires.",
      "owner": "Service operator for endpoint/process state; relevant component owner for readiness.",
      "evidence": "Status and health exits, actual component states/reasons, target and observation time.",
      "resume_when": "The intended query context is restored and the owner resolves any readiness dependency before the affected next operation.",
      "closeout": "Save the observation and stop dependent work. Do not auto-restart or adopt the old lab admission as current permission.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-troubleshoot"
    },
    {
      "id": "F-05",
      "symptom": "A submitted action is uncertain or identity does not match",
      "check": "Preserve the original request and target. For Admin timeout use Reconcile exact request on the existing pending request; for Work inspect the saved Work under the same installation/account or ask support to reconcile.",
      "owner": "Admin/operator for the pending Admin request; Work owner and product support for Work identity.",
      "evidence": "Original request/Work reference, expected/observed target or ID, action, time and literal reason.",
      "resume_when": "The original action disposition and current state are reconciled, and any next action is explicitly supported and authorized.",
      "closeout": "Retain uncertainty until resolved. Do not submit a replacement request, new key or duplicate Work as a recovery shortcut.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-failures"
    },
    {
      "id": "F-06",
      "symptom": "Admin returns stale revision, denied session or invalid configuration",
      "check": "For STALE_REVISION refresh and re-review the original intent against the new appliance state. For denied/session-invalid results resolve the literal reason with the administrator. For INVALID_CONFIGURATION check registered keys, range and policy.",
      "owner": "Change owner for intent; access administrator for session/grant; configuration owner for allowed values.",
      "evidence": "Appliance and configuration revisions separately, original change, decision/reason and audit reference.",
      "resume_when": "The correct target/session and current revision are established and the exact change is reviewed again within its approval.",
      "closeout": "Keep the original failed result. Cancel if scope changed; do not overwrite Expected revision blindly or bypass a denial.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-failures"
    },
    {
      "id": "F-07",
      "symptom": "Report is missing, unreadable or fails file-hash comparison",
      "check": "Confirm selected Work/revision, actual returned paths or approved copies, and the file-specific hash fields. report_sha256 is not the file checksum.",
      "owner": "Service operator and product support for artifact access/correspondence.",
      "evidence": "Selected Work/report reference, expected/observed hashes and sanitized access/readability reason.",
      "resume_when": "The correct selected files are accessible and the discrepancy is resolved with retained comparison evidence.",
      "closeout": "Preserve the original references and issue. Do not regenerate or substitute another report to make the check pass.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-files"
    },
    {
      "id": "F-08",
      "symptom": "A recorded change has unproven effect or unclear recovery/retention",
      "check": "Separate the action response and revision from stored/effective observation. Confirm the intended retained state and the supplied recovery procedure; a hidden value stays unobserved.",
      "owner": "Service operator for supported observation; change/data owner for recovery and retention decisions.",
      "evidence": "Before/reported/after state, observation source, missing effective-value proof and recovery/retention reference.",
      "resume_when": "The owner supplies the missing observation or explicitly accepts the bounded unresolved handoff; any recovery action needs its own supported procedure and approval.",
      "closeout": "Record applied state and unresolved effect separately. Preserve history; do not invent rollback, restart, deletion or a successful effective-value claim.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-configuration"
    }
  ],
  "checks": [
    {
      "id": "CX-01",
      "title": "One task and its claim boundary",
      "expected": "One selected case, intended outcome, actual mode and expected deliverable are written. Preparation, recorded reading and live observations remain distinct.",
      "evidence": "Task plan with case ID, reviewer and permitted scope.",
      "source_url": "/docs/worked-examples-en.html#start"
    },
    {
      "id": "CX-02",
      "title": "Exact handoff and missing dependencies",
      "expected": "Applicable release, target, interface/schema revisions, access and supported procedure have supplied references or an explicit missing owner/action.",
      "evidence": "Handoff checklist and missing-deliverable records; no invented IDs or envelopes.",
      "source_url": "/docs/integration-sdk-guide-en.html#next"
    },
    {
      "id": "CX-03",
      "title": "Before state and exact action",
      "expected": "The relevant before state, identity/revision and actual action are recorded, or the step is explicitly unperformed. Query exits are captured separately.",
      "evidence": "Before observation, action/command reference, time and each exit where applicable.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-baseline"
    },
    {
      "id": "CX-04",
      "title": "Literal result and request correspondence",
      "expected": "Returned operation/request/work, status/reason, reached stage and revisions are copied literally and tied to the original action. Exit alone is not success.",
      "evidence": "Sanitized returned result and original request/Work reference, or explicit unavailable fields.",
      "source_url": "/docs/integration-sdk-guide-en.html#output"
    },
    {
      "id": "CX-05",
      "title": "Matching deliverable and file checks",
      "expected": "The actual deliverable is identified and reviewed against the expected scope. For reports, same Work/revision, readability and file-specific hashes are checked; inapplicable checks have a reason.",
      "evidence": "Deliverable reference; observed or unperformed file/identity comparison with evidence.",
      "source_url": "/docs/headless-operations-guide-en.html#headless-tutorial-files"
    },
    {
      "id": "CX-06",
      "title": "Reported, stored and effective state stay separate",
      "expected": "A response or changed revision is recorded as such. Stored/effective behavior is observed only through the supplied supported path; hidden or unavailable values remain unknown.",
      "evidence": "Separate reported-state, stored-state and effective-state fields with source/time or limitation.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-configuration"
    },
    {
      "id": "CX-07",
      "title": "Retained state, recovery and resources",
      "expected": "The final intended/observed state, retention owner, supplied recovery disposition and remaining resources/costs are recorded when applicable. No automatic rollback or zero-cost inference.",
      "evidence": "Closeout/resource rows, supported recovery/retention references and explicit unmeasured items.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-recovery"
    },
    {
      "id": "CX-08",
      "title": "Human review and next owner",
      "expected": "The reviewer explains the task result and each open item has an owner, next action and evidence needed to resume. Manual labels never alter product acceptance or authority.",
      "evidence": "Manual check dispositions, reviewer/date if supplied, literal product state separately and a sanitized handoff.",
      "source_url": "/docs/vibepackr-admin-guide-en.html#admin-support"
    }
  ]
}