Part.6 · Builder and Additional Packs

Builder: prepare a Pack candidate after setup

First candidate exercise: input through handover

Goal: prepare the release's supplied read-only exercise Pack/candidate as a new revision and inspect validation. Do not modify an operational Pack or choose a service-changing Work for the first exercise. If no exercise input is supplied, write the goal below and request a compatible example from support.

1. Open the OS-specific app using its install instructions. Confirm connected customer/installation/release and Builder role. Stop if only an app window is open without connection.
2. Open the supplied exercise candidate or supported Pack using the release's selection/import procedure. Use version-specific screen names. Record candidate ID, original revision and input.
3. Write this human goal note, not JSON/API input: Purpose: one synthetic inspection result / Input: supplied synthetic data / Output: review result / Changes: no customer service changes / Failure: inspect declared recovery state. Populate supported product fields in the provided template's format.
4. Save a new candidate and record the actual returned ID/revision. Run its validation and inspect that revision's result, reasons and missing fields. Saving and validation are separate checks.
5. For a refusal, correct only the reported declaration and validate the new revision. On success, hand over the candidate reference, validation, purpose and pending approval/entitlement. File creation is not a reason to execute Work.

Expected output: the product's candidate reference and validation record. Do not expect SDK adapter.rs or a GAPE snapshot. For product-managed candidates use the release's export procedure rather than finding and copying arbitrary state files.

Next exercise: follow first Work only after approval, current entitlement and preconditions are established. If validation passed while approval is pending, record candidate preparation/handover complete, Work not executed. Continue with BLD cases and case H below.

Before opening Builder

1. Confirm the appliance release and Builder platform package are compatible, signed, and included in the delivery inventory. A Mac package does not establish Windows or Linux installability.
2. Confirm appliance readiness, authenticated Builder role, customer and installation identity, and a validated runtime binding if the candidate needs it. A local socket refusal or an open Builder window is not an authenticated server connection.
3. Identify the existing Pack or capability you intend to extend. If an approved Pack already meets the need, use its supported path instead of creating a duplicate.

Prepare and validate

1. Write the intended outcome, target environment, allowed inputs, data boundary, preconditions, and rollback disposition. For example: “Create one audit artifact for this installation; read only the declared source; record a receipt; do not change a customer service.”
2. Select only a Contract and capability supplied for the release. Do not invent a capability identifier because an input document is syntactically valid.
3. Create the candidate in Builder, then run the product's candidate validation. Record candidate ID, revision, validation status, exact reason, and the rule that was checked. Fix a reported declaration defect in the candidate and validate again; do not alter Core policy files.
4. Submit the validated candidate through the release's approval route. Confirm formal Pack approval and customer-installation entitlement separately. A passkey can identify a person for a particular approval only when the release's enrollment and server verification path is available; opening Safari and returning to the app proves neither enrollment nor approval.
5. Before Work, read the plan, target, current authority and preconditions. Execute through the governed product route only after those checks pass, then match the final result to its receipt.

Worked example: validation passes, Work is refused

Here is an illustrative operator record, not a Builder API payload or an observed receipt. Enter actual values from the installed release and keep the refusal separate from validation:

Release: [signed release ID]
Installation: [customer-approved reference]
Candidate: [Builder candidate ID and revision]
Validation: PASS (structure only)
Approval: PENDING
Entitlement: NOT_CHECKED
Work: NOT_STARTED
Next owner: Pack approval owner

The candidate declares an audit artifact and structural validation returns PASS. Work submission returns “approval pending.” Record candidate validated / execution not authorized. The next action belongs to the approval owner; repeating submission, using a different account, or copying the candidate into a Pack directory cannot change that state. If approval exists but entitlement is missing, the entitlement owner must resolve the exact customer and installation scope.

Worked example: browser returns without an approval

The passkey page opens and returns to Builder, but Core does not show a verified approval for the same session, plan, and candidate. Keep the Work in a denied or pending state. Check the displayed correlation ID and the release-defined credential enrollment status; do not paste passkey responses into a support ticket.

Completion evidence

Candidate preparation ends with a validated candidate and a recorded handover. Approved Pack use requires separate approval, entitlement, current preconditions, actual Work, validated result, and matching receipt. See the candidate refusal case and first Work guide.

A practical operational use case

Suppose a team needs a weekly inspection artifact with a different input shape. First check whether the supported input of an existing approved Pack already covers it. If a new candidate is needed, retain the original Pack reference, changed declaration, candidate revision and validation result. The approver reviews that exact candidate digest; the operator separately checks the current installation entitlement and preconditions.

Symptom-specific checks and return to operation

Minimum handover to the next owner

Handover: original Pack reference, candidate ID/revision/digest, intended change, supported platform, validation, approval, entitlement, preconditions, rollback disposition and next owner. If no Work ran, record candidate preparation only.

Read the tool-specific troubleshooting examples

These teaching examples use documented input, command and authority boundaries. Read them alongside actual product states/reasons; do not treat illustrative outcomes as execution history. Distinguish checks shared by online/offline environments from checks specific to the optional dependency route.

Worked scenario BLD-1: The app returns from browser confirmation without an approval record

Situation: A user returns from a passkey page and assumes approval. The product has no verified approval for the same candidate, plan and session.

Read these observations separately.

• Browser return: confirms navigation only.
• Credential enrollment: separate from a particular operation’s approval.
• Candidate/plan: must match the approval subject.

Check and action sequence:

1. Compare returned correlation references and current candidate/plan in product state.
2. Check that the release supplies the enrollment/server approval verification route.
3. Do not start Work before the authority owner confirms current state.

Condition for resuming: After product confirmation of exact-subject approval, separately check entitlement/preconditions.

If still unresolved: Do not fill missing approval with raw passkey responses or another account’s credentials.

Worked scenario BLD-2: A failed run leaves partial artifacts and a rollback state

Situation: A candidate/approved Pack operation fails but leaves some files. Before treating presence as success or deleting files and retrying, inspect product failure/rollback state.

Read these observations separately.

• File presence: may indicate partial activity only.
• Work state: check failure, rollback and postcondition validation separately.
• Authority: do not assume it automatically covers a new execution.

Check and action sequence:

1. Retain Work/plan/candidate identity and last validation result.
2. Have the owner check the Pack’s supported recovery procedure and rollback result.
3. After current state is established, evaluate new plan/authority/preconditions through the supported route.

Condition for resuming: Record validated recovery separately from any later authorized execution.

If still unresolved: Do not hide failure by deleting original results, marking manual success or using another execution route.

Post-install tools

Use case 4: Prepare a Builder candidate for Pack approval

Operational goal

A customer prepares and validates a needed function as a Pack candidate, then hands it to the authorized approval and entitlement owners. Check first whether an existing Pack solves the need. Creating a new candidate does not open an execution path.

Example conversation

A Builder user says, “Validation shows passed, so I will run it now.” The administrator replies, “That is candidate validation. We still need Pack approval, entitlement for this installation, contract scope, and preconditions separately.”

States and owners

Work through the sequence

1. Confirm this release supplies Builder and verify Builder installer version and signature.
2. Define requirements inside supported scope and specify the candidate's contract, data boundary, and preconditions. Do not present out-of-scope behavior as supported.
3. Inspect Builder validation and defects, then revise the candidate. Record only the exact scope of validation.
4. Submit candidate ID, version, requested capability, and validation result to the approval owner. Do not send full source or customer data outside the necessary approval path.
5. Confirm approval and entitlement separately for this customer installation in product status. If passkey enrollment is required, use the release-defined supervised administrator route; browser return alone is not approval.
6. For actual Work, separately review the plan, approval, and preconditions, then verify execution with a receipt.

When refused

Use the validation, approval, entitlement, and precondition branches in the Builder candidate case. Do not copy the candidate into a deployment directory or run a refused command under another account.

Completion condition

Preparation is complete only when candidate validation and formal approval and entitlement are each confirmed. This does not mean Work succeeded.

Detailed scenario: candidate validated, execution refused

Suppose Builder reports that a candidate passed structural validation, but Work submission is refused. This is not automatically a product defect. Structure and contract validation, approval owner decision, installation entitlement, and execution-time preconditions are distinct gates. Classify the first stopped gate from the product's actual state.

For example, candidate validation PASS with approval pending means candidate prepared, no execution authority. Even an approved Pack cannot run for a mismatched customer or installation scope or failed precondition. Do not edit candidate files or policy storage to force a permitted state.

Approval handover worksheet

Brackets are fields for actual product records. Do not copy validation PASS into the approval field.

A concrete operational walkthrough

For example, adapt an inspection Pack input to a new target. Check existing Pack coverage first, then create only the needed candidate as a new revision. If the candidate changes after review, do not treat the previous approval as covering the new bytes.

Records to reconcile before closing this use case

Record candidate generation/validation, approval, installation entitlement, preconditions and Work receipt as separate states. Include unexecuted stages and the next authority owner.

Keep the planned procedure, performed actions, observed results and remaining stages separate. This scenario explains the procedure; the documentation update does not execute it in a customer environment.

Back to use-case index