Part.1 · Installation and first connection

Navigate: Installation and first use · Post-install tools · Use cases · Troubleshooting cases

First installation: choose your starting point

You do not need to install every tool in sequence. Choose one goal below. Only a browser is needed to read this page. SDK synthetic exercises do not require an appliance account, customer activation or a live API connection.

Find each tool in the post-install tool index. Install a tool when its step needs it. Live connection, registration and Work require the release's separately authorized route.

Ten-minute preparation: computer and supplied files

1. Identify the installation target. VM images belong on the server; PackrGUI and Builder run on the workstation. SDK can run portably on the integration workstation. A Document is JSON data, not a separate application installer.
2. Check OS and CPU using the read-only commands below. arm64/aarch64 and x86_64/AMD64 require different packages. Current recorded SDK combinations are macOS ARM64, Debian 13 AMD64 and Windows AMD64; another Linux distribution or Windows ARM is not the same combination.
3. Check the supplied inventory for the main program, optional dependencies, examples, version, digest, signature status and native prerequisites. The SDK Rust set is optional; it does not change the connected environment's default.
4. Choose a fresh workspace. Separate original archives, extracted programs, editable inputs and per-run results. Use an organization-approved private folder; preserve existing directories.
5. For connection-dependent routes obtain the required profile from your administrator. An address alone is insufficient: obtain account/device enrollment instructions, expected organization/installation identity, TLS server name and support route.

# macOS Terminal only
sw_vers
uname -m
# Linux terminal only
cat /etc/os-release
uname -m

# Windows PowerShell
$PSVersionTable.PSVersion
(Get-CimInstance Win32_OperatingSystem).Caption
(Get-CimInstance Win32_ComputerSystem).SystemType

Choose the procedure by file type

Generic .pkg/.exe/.deb names later in this guide only illustrate hashing. Do not look for the SDK under those names. In this local operator edition the current SDK packages table links the actual archives and digests. Other components need their own release inventory. Do not assume a portal, download URL or signature status exists.

Before copying a command

• Use bash examples in macOS Terminal/Linux shells and powershell examples in Windows PowerShell. Prompts such as $ or PS C:\> are not part of commands.
• Replace /absolute/path/..., C:\absolute\path\... and bracketed fields with your actual supplied values first. Keep the quotes, especially for spaces. Do not interchange Unix ./bin/... and Windows .\bin\... paths.
• Variables such as install_root and $installRoot exist only in the shell where you initialized them. A new terminal requires the resume instructions below. Check folder spelling, case and accidental .json.txt extensions.
• Run one step at a time and inspect the result, even inside a command block. Expected output in this guide is not an execution record. Stop subsequent commands when a step fails.
• Preserve original examples and save copies as UTF-8. PowerShell 5.1's default > or Out-File may write UTF-16. Use a UTF-8 editor for input JSON and check its save encoding.

Understand the folder layout

VibePackr-SDK-install-01/
  sdk/             extracted program; bin, docs, examples
  dependencies/    optional set; retain as verification input
  inputs-02/       editable complete input.json copy
  runs/
    custom-01/     created after the first successful run
    mcp-01/        separate MCP result
    custom-api-candidate-02/  new result for modified input

This is a layout illustration; SDK sections contain creation commands. Prepare the runs parent, then let the SDK create final candidate directories such as custom-01. GAPE also uses a fresh output path. Helper log directories and product-managed Builder candidates are separate.

Record progress and resume later

Record installation, connection, candidate generation and real Work separately. At the end of each exercise save the date, tool version/path, input digest, actual command or UI action, result location, last successful step and next owner. Troubleshooting starts with this record.

On resuming, preserve archives and results. The SDK guide shows how to restore path variables; select absolute input/output paths again for other tools too. If execution is uncertain, query the existing Work/request ID before acting; a new submission is not a way to resolve a possibly duplicated operation. Use the troubleshooting index for the blocked step.

How to use this guide

This guide helps customer operators proceed from receiving files to checking the first Work result. Product status and the signed manifest for the exact release are authoritative. Examples and generic operating-system commands do not override product refusals or release instructions.

• Audience: appliance installation administrator, PackrGUI user, and optionally Builder operator. Installation, permission grants, and Pack approval may have different owners.
• Before you begin: the release delivery inventory and signature instructions, supported-environment list, authority to install in your organization, network and authentication details, and the release support route. Never attach passwords or private keys to a support request.
• Completion condition: separately confirm file verification, service readiness, administrator scope, authenticated connection, validated runtime binding, authorized actual Work, and its result and receipt for the same release and installation. Success at one step does not establish success at the next.
• Stop condition: stop before the next step if a file digest or signature differs, the host identity is unexpected, the customer or installation identity differs, permission is denied, or state integrity is warned about. Record the original message and time, then use the release support route.

1. Check the delivery and target environment

1. For a release with a published official portal, begin at setup.vibepackr.com. For offline setup, open the delivered Start_Setup.html. Confirm that the portal and offline page name the same release and component inventory. Distinguish a portal outage from an appliance problem.
2. Check the delivery inventory for the appliance image, PackrGUI for your operating system, and the actual availability of optional Enterprise Pack Builder and Additional Packs. A component shown on an introduction page must not be installed unless the release inventory includes it.
3. Compare the received files with the version, platform, and SHA-256 values in the release manifest, then verify signatures using the supplied official procedure. A digest detects changed bytes but does not replace signature verification. Generic file-hash examples are shasum -a 256 filename on macOS, sha256sum filename on Linux, and Get-FileHash -Algorithm SHA256 filename in Windows PowerShell. Follow your shell's quoting rules for filenames with spaces.
4. Check the release compatibility list for the supported cloud or virtualization target, CPU architecture, memory and disk, network and authentication path, and runtime. If you plan to use a local 7B model, check its execution resources separately. Use the supplied compatibility list for minimum requirements.
5. Record the release ID, filenames and digests, image identity, target platform, and verification result. Do not rename a mismatching file to make it appear valid or substitute another platform's package.

Continue when: the exact delivered files have matching signatures and digests and the target environment is supported.

Worked file check on the receiving workstation

Use the filename and expected SHA-256 from this release's signed inventory. These are read-only operating-system commands. Replace the example filename with the received file and complete the release's signature verification separately. Do not use a digest copied from an older guide.

# macOS Terminal
shasum -a 256 "VibePackr-installer-for-this-platform.pkg"
# Linux shell
sha256sum "VibePackr-installer-for-this-platform.deb"

# Windows PowerShell
Get-FileHash -Algorithm SHA256 "VibePackr-installer-for-this-platform.exe"

Example decision: the manifest says A1... while the local command prints B2.... Stop before installation, retain the exact filename and two digests, and ask the delivery owner for a corrected signed file. Renaming the file does not change its digest.

2. Deploy a new appliance in the customer environment

1. Deploy a new instance from the signed appliance image supplied for your release. Do not substitute an image from another version or copy an existing VM as an installer.
2. Allow first boot to finish. Running in a cloud console means the VM is powered on. Confirm product service readiness separately in product status or the release diagnostic. During initialization, follow the official wait and status procedure instead of repeatedly attempting connections.
3. Record the newly generated installation identity, customer organization, service endpoint, and connection method. If two independent instances display the same installation or host identity, stop use and investigate the clone state.
4. Compare the host identity displayed on first administrator or client connection against the release's official verification route. Do not reuse an earlier VM's key for a new VM or ignore an identity warning.

Continue when: first boot has finished, the product service reports ready, and the unique installation identity and authenticated access route are confirmed.

3. Register the first administrator and allowed scope

1. Open the Customer Setup UI inside the customer environment or the administrator procedure named by the release. An operating-system login alone does not create the product's Appliance Administrator authority.
2. Have the actual administrator confirm the customer, installation, and supported runtime scope, then finish enrollment using the product's required method. Automatic binding operates inside that approved scope. It does not approve every possible environment change.
3. Confirm the minimum observation and runtime-binding permissions, target, and validity period in product status. Stop if the account name is right but the customer or installation identity differs.
4. If the release requires interactive terminal input, do not pipe copied commands through a non-interactive remote script. The administrator must confirm directly in the designated local wizard or interactive session.
5. Read administrator status again after enrollment. If storage access or Permission denied occurs, do not repair ownership, permissions, or lock files by hand. Send the exact error through the release support route.

Continue when: the product confirms the administrator role, allowed scope, and validity period for this installation.

4. Discover and automatically bind a local runtime

1. Prepare a local runtime and model supported by your release. For example, if the supplied compatibility list includes Ollama and a Qwen model, confirm their versions and resource requirements. Do not treat the example as a default model for every installation.
2. Distinguish detected → validated → bound in the Packr or PackrGUI setup wizard. Core applies a binding only after validating the observed installation, customer, and runtime identity against administrator scope. A model file or running runtime process alone is not a binding.
3. Check the current binding's runtime type, model reference, installation identity, status, and recorded time. A binding does not establish that inference or Work ran.
4. After replacing or restarting the runtime, or changing a model alias, wait for a fresh observation and confirm the product's new validated binding. Do not use an old binding screen as proof of the new runtime.
5. For an out-of-scope change or ambiguous model selection, use the administrator action shown by the wizard. Do not edit product storage or force reuse of a prior binding.
6. For offline operation, confirm that the model is already local and the release's local-only network configuration is effective. Check your network policy and actual communication record before concluding that no external traffic occurred.

Continue when: the product shows a validated binding for the supported runtime and model on this installation.

5. Connect PackrGUI, headless clients, and Builder

1. Install PackrGUI for your operating system as named by the release manifest. macOS, Windows, and Linux packages are not interchangeable. If your operating system displays a security warning, check the signature and supplied installation instructions; do not bypass its security checks.
2. Connect to the customer appliance through the address, network, and authentication route named by the release. Separately confirm that the server responds, authentication succeeds, and customer and installation identities match in product status. An open window does not prove an authenticated connection.
3. If you operate without a GUI, check the release's headless CLI or service route separately. A successful GUI connection does not prove headless readiness or Work authority.
4. Install Enterprise Pack Builder only when it is an actual component of this release, following its separate installer and permission guide. Builder helps prepare and validate Pack candidates. Creating a candidate does not approve, entitle, or execute a Pack.
5. If the release requires Safari web passkey verification, use the official HTTPS origin and supervised enrollment procedure. Passkey enrollment and approval for each Work are different actions. A browser opening or returning to the app does not itself prove Core approval. Never borrow another account's credential after a refusal.

For the next tasks after connection, use the post-install tools guide. It explains where to install and how to use Builder, GAPE, Integration Helper, SDK Engine, and Contract & Document. It also includes the Non-SI architecture diagram.

Continue when: the product confirms authentication, installation identity, and permitted functions for each client route you plan to use.

6. Run the first Work and inspect its receipt

1. Select a supported Pack or test Work named by the release. Check its contract, scope, preconditions, approval, and entitlement before execution. Do not run a Builder candidate as though it were an approved Pack.
2. Review the product's execution plan and target environment, then run one Work through the customer-authorized path. Actual Work is a separate step from installation, connection, and runtime binding.
3. If the Work uses a local model, confirm in that Work record that a model call actually occurred. A bound runtime or responsive model can exist without a Work call.
4. Compare final status, result validation, Work record, and receipt against the same installation and release identity. A failure, stop, rollback, or pending validation is not a success receipt.
5. Complete the following checklist before declaring first use. Record not checked separately from failure, but do not mark it complete.

Operational use cases

After installation, start at the use-case index to follow the work in order. New installation, runtime change and rebinding, separate PackrGUI and headless routes, Builder candidates, and first Work each describe owners, prerequisites, evidence, and failure branches. Cases A–J below are symptom-driven troubleshooting guides.

7. Troubleshooting examples

The following situations may arise during installation and use. Exact product messages can vary by version and platform. Perform only the safe action shown here; pass identity, authority, and state-integrity failures to the support route. Open each linked case for a worked example, ordered checks, outcome branches, sample support request, and completion and stop conditions. If you are unsure which case fits, start with the troubleshooting index.

Case A — The VM is running but the product is not ready

• Symptom: The cloud console shows a running VM while product status is still initializing or the service is not ready.
• Check first: Inspect the first-boot completion indicator and product status. If an error says that a required initialization component is missing, record the image ID and message.
• Safe action: Follow the release's wait and read-only diagnostic procedure once. If a component is missing or readiness never appears, send the image ID and status to support. Do not install random packages or delete service state files in the customer VM.

Case B — SSH or the app shows a different host identity

• Symptom: A host-key change warning, authenticated server identity mismatch, or unexpected installation identity.
• Check first: Determine whether you are connecting to a new instance rather than the old one, and verify the address, organization, and installation ID. Do not automatically reuse an old trust entry after a host-key change.
• Safe action: Stop the connection and verify the current host identity using the release's independent official route. Do not ignore the warning, disable host checks, or replace a stored key before verification.

Case C — A connection refusal could be network or authentication

• Symptom: A connection timeout immediately after boot, login refusal, or a client window that opens but remains unauthenticated.
• Check first: Check in order: VM and service readiness, official address and network path, current account and authentication method, then product customer and installation identity. A timeout and a login refusal require different actions.
• Safe action: Follow the release's stated recheck procedure. Do not switch to another person's key or account. Record the failing stage, time, and exact message.

Case D — Administrator enrollment refuses non-interactive input

• Symptom: A command sent by remote script or pipe is refused because a real terminal or user confirmation is required.
• Check first: See whether the release requires an interactive local wizard or terminal.
• Safe action: Have the actual administrator complete the designated interactive procedure. Do not simulate confirmation with automated input. Read back the recorded role and scope afterward.

Case E — Storage access fails after administrator enrollment

• Symptom: The administrator was registered, but subsequent observation or binding stops with Permission denied or a storage access error.
• Check first: Read the displayed refusal code and stage, service readiness, and installation identity. Distinguish a storage access error from a role or scope refusal.
• Safe action: Do not change product state files or OS permissions by hand. Check whether your release includes the fix and send support the exact error and version.

Case F — The runtime is visible but not bound

• Symptom: A local model is installed and the runtime is running, but product status says only detected or refused.
• Check first: Check supported model and runtime, installation identity, administrator scope, Core validation state, and refusal reason. If the model alias or runtime address changed, confirm the status follows a fresh observation.
• Safe action: For an in-scope environment, follow the release wizard's re-observation procedure. For an out-of-scope or ambiguous model, request the explicit administrator action. Do not edit the database to display BOUND.

Case G — Local model startup lacks memory or network access

• Symptom: The local model does not start, or a download or metadata check times out in an offline environment.
• Check first: Check the release's model-specific memory requirements, whether the model is already local, and your organization's external-network policy. Check binding status and Work status separately.
• Safe action: Provision resources that meet the supported requirements and use the release's local-model preparation route for offline operation. Do not report failed outbound attempts as successful inference or as zero outbound traffic.

Case H — A Pack candidate exists but cannot be run

• Symptom: Builder displays a candidate, but it is not listed as an approved Pack for Work or execution is refused.
• Check first: Separately confirm candidate validation, approval, customer entitlement, contract scope, and preconditions.
• Safe action: Follow the product approval procedure. Prepared in Builder is not execution permission.

Case I — Binding succeeded but there is no Work receipt

• Symptom: Runtime status says bound, but no result or receipt is available.
• Check first: Determine whether a Work was actually submitted, approved, and executed, and whether its final status is success, failure, stop, or rollback. A binding screen alone does not create a receipt.
• Safe action: Follow the release's first-Work procedure and record location. Never substitute an earlier binding record for a Work receipt.

Case J — A new VM contains an earlier user's traces

• Symptom: A new customer VM exposes an unexpected user home, access key, prior installation identity, or settings.
• Check first: Confirm the image identity and whether this is a new instance. Stop use if unexpected traces of an earlier user are present.
• Safe action: Do not begin Work on that VM; notify the deployment owner and support. Do not delete another user's files to make an unverified image appear approved.

8. Changes, recovery, and support requests

1. After changing a runtime, model, network, customer, or installation scope, do not assume the old binding still applies. Confirm new observation → Core validation → new binding → any required Work recheck. An out-of-scope change needs the administrator procedure.
2. If a failure repeats, do not retry indefinitely. Preserve the first error, the release's support procedure, and the state before the change. Recover only through the release-provided route; do not edit internal product state, keys, or receipts.
3. Include the release and component versions, operating system, step, displayed state or refusal code, time and time zone, reproduction steps, safe actions already taken, and scope of impact in a support request. Do not send customer data, raw prompts, passwords, private keys, passkey responses, or full logs. Use the minimum-disclosure path directed by support.
4. Stop urgently for a signature or host-identity mismatch, different customer or installation ID, suspected privilege expansion, prior-user residue, or a state-integrity warning. Stop installation or Work and provide the first evidence to support.

Installation record and support details

The installer should record the release and image IDs, the exact files and digests installed on each platform, supported-environment checks, initial administrator scope, authenticated connections, and current runtime binding. For any Work that was run, keep its final state, result validation, and receipt location with the same installation and Work ID.

Check macOS, Windows and Linux clients and the headless route separately. A connection on one platform does not verify installation, authentication or permissions on another. If a screen or command differs from the example here, follow the instructions supplied with your release and include the product's actual message and your steps in a support request. Exclude customer data and secrets.

Online/closed-network environments and component task map

Online operation uses approved network/provider routes; closed on-premises operation provisions required installation assets, models and documentation before transfer. This guide fixes neither as the product default. The optional SDK Rust dependency set prepares SDK adapter-build Rust coverage; it does not replace appliance images, model weights, provider credentials or all native OS development tools.

Checks after operational changes

After a client update recheck that client’s connection, authentication and installation identity. After a runtime change recheck fresh observation, validation and binding. After a Pack change recheck exact version, trust, current entitlement and preconditions. Retain the previous records and recovery target. If something changes unexpectedly, record the first differing observation and return to that component’s procedure.

Additional Packs use files and registration procedures appropriate to the supplied release, customer and installation scope. Copying a folder or renaming a candidate does not replace registration/approval. First application requires the approved plan, postcondition validation and receipt. Removal/rollback follows that Pack’s declared recovery procedure and current authority.

First blockage: start from the last confirmed step

The same symptom can require different actions at different stages. Choose the last step you directly confirmed below. A failed step does not require repeating the entire installation or deleting earlier results.

Write an actionable support request

This is a worksheet. Replace brackets with actual observations; write unconfirmed for unknown values. Do not invent product error codes or success timestamps.

Goal: [e.g. first SDK Custom synthetic candidate]
OS/CPU and tool version: [actual observations]
Selected route: [installed-toolchain run / supplied-set run-offline / GUI, etc.]
Last success: [e.g. analyze actually confirmed]
Failed step/time: [actual stage, local timestamp and timezone]
Observation: [actual status/reason or OS error; redact secrets]
Input/package reference: [version and SHA-256; no customer contents]
Earlier results: [present/absent; distinguish this attempt]
Next check requested: [e.g. approved native prerequisites]

Do not send raw full logs, customer responses, keys, tokens or profile contents in bulk. Share only redacted minimal messages/identifiers through the organization's support route. After resolution, recheck the first failed step and affected outputs, then continue.

First identify the current stage

Do not collapse every problem into “installation failed.” Record the last state you actually confirmed. This reduces unnecessary reinstalls and permission changes.

A short worked example

“I deployed a new VM for release [ID]. The VM runs, but the product is not ready. I have not enrolled an administrator or started Work. The first message was [verbatim] at [time with zone].” Start with A. Even if a client connection error appears at the same time, do not change authentication settings under C before product readiness is proven.

Conversely, if product readiness and network reachability are confirmed but login alone is refused, use C for authentication. If only a binding screen exists and there is no Work receipt, use I. This order does not prove a root cause. It prevents declaring an unproven later stage successful.

Stop immediately when

Stop self-service for a signature or file-digest mismatch, unexpected host identity, different customer or installation ID, suspected privilege expansion, earlier-user data, or state-integrity warning. Collect only the minimum case-specific support evidence. Do not put passwords, tokens, private keys, passkey responses, customer data, or full logs in an ordinary support request.

Choose the next procedure from the symptom

Online operation uses approved network/provider routes; closed on-premises operation provisions required installation assets, models and documentation before transfer. This guide fixes neither as the product default. The optional SDK Rust dependency set prepares SDK adapter-build Rust coverage; it does not replace appliance images, model weights, provider credentials or all native OS development tools.

Example support handover: release/component/OS, time and timezone, last confirmed stage, first refusal, performed change, current result and next owner. Keep unconfirmed, refused, waiting, failed and completed states distinct. Exclude secrets and customer content.

Find the closest of 30 detailed scenarios

A broad issue category can contain different symptoms and remedies. Follow the example IDs below through situation, observation, action and resumption criteria. They are teaching scenarios; actual incident histories require separate evidence.

For SDK, Builder, GAPE, Integration Helper and source Document issues, also use the detailed examples in the post-install tool guides. Do not transfer preparation success between tools or to actual Work.

Back to installation and first-use guide

Choose by task

How to use this collection

Each use case follows situation → prerequisites → steps → failure branches → completion evidence. If several symptoms appear, start at the last proven state. For symptom-specific resolution, use the case index. Include only minimal release, installation, and verbatim error details in support requests; omit customer content and secrets.

Choose a use case by owner and output

Online operation uses approved network/provider routes; closed on-premises operation provisions required installation assets, models and documentation before transfer. This guide fixes neither as the product default. The optional SDK Rust dependency set prepares SDK adapter-build Rust coverage; it does not replace appliance images, model weights, provider credentials or all native OS development tools.

Example support handover: release/component/OS, time and timezone, last confirmed stage, first refusal, performed change, current result and next owner. Keep unconfirmed, refused, waiting, failed and completed states distinct. Exclude secrets and customer content.

Back to installation and first-use guide

First use: checklist for the first result

Start with each guide's first exercise. CLI examples select an absolute executable path, so a global PATH change is unnecessary. Launch GUI apps using the supplied installation procedure and release-specific screen names; do not invent menus or download URLs.

The optional SDK Rust set is not an installer for other applications. Rust installation is not required for every tool. Users checking an existing installation do not create another VM or repeat initial administrator enrollment.

How the parts fit together

This diagram shows how your organization owns its environment and operations, while integration tools help you understand, prepare and declare work and the product controls execution. Open the image in a separate tab to zoom. Check the supplied component list for tools and versions available to install.

Check the tools you need

Choose the tools you need below. Local SDK exercises and Document preparation do not require appliance installation first. Confirm each component's availability, platform, version and installer in the supplied component list. Do not substitute a file from another release for a missing tool.

Choose the next task

What the installation set must contain

The Non-SI installation set must let a customer reach these guides online or offline from Start_Setup.html and identify the exact installable components for the appliance, the customer's workstation platform, Builder, GAPE, Integration Helper, SDK interfaces or Engine, and Contract & Document templates. Components can be delivered in separate platform installers inside one versioned set; they must be listed with hashes, compatibility, prerequisites, and the responsible installer. The set must also explain when a component is unavailable for the specific release. A documentation link or a historical implementation is not a substitute for an installable, validated component.

Install the SDK Engine separately on your integration workstation. Check the SDK Engine guide and supplied component list for the platform installer, supported appliance version, and installation and removal steps.

If a received file does not match the supplied list or signature verification fails, stop installation and contact your supplier's support route. Install only the verified file listed for your platform.

Recommended sequence

1. For appliance-connected work, complete installation and first use through an authenticated client and validated runtime binding. Local SDK synthetic examples and Document preparation start directly at their first exercises. Check each tool in the exact release inventory before opening it.
2. Use GAPE if a revision-bound architecture question matters. Review the observation and its limits; do not use a diagram as an approval.
3. Define the operation in a Document and obtain the exact supported Contract and adapter reference from the supplier. Integration Helper can then validate and prepare a candidate within its supported input format.
4. If the release supplies an SDK interface or Engine for this target, verify its published revision and follow its validation and package procedure. If the release does not list it, stop that path; do not infer availability from this infographic or an older SDK artifact.
5. Use Builder to prepare a Pack candidate if a supported existing Pack is insufficient. Keep candidate validation, approval, entitlement, and Work execution as separate recorded steps.
6. For an actual operation, follow the first Work guide and verify its final receipt. A preparation artifact cannot replace the receipt.

Common support record

Record the release and component versions, customer and installation identity, the exact input revision or candidate ID, the typed status and reason, the last proven step, and the expected next action. Omit private keys, credentials, customer payloads, raw prompts, and internal engineering exports. Stop when identity, signature, authority, or state integrity differs.

Online/closed-network environments and component task map

Online operation uses approved network/provider routes; closed on-premises operation provisions required installation assets, models and documentation before transfer. This guide fixes neither as the product default. The optional SDK Rust dependency set prepares SDK adapter-build Rust coverage; it does not replace appliance images, model weights, provider credentials or all native OS development tools.

Checks after operational changes

After a client update recheck that client’s connection, authentication and installation identity. After a runtime change recheck fresh observation, validation and binding. After a Pack change recheck exact version, trust, current entitlement and preconditions. Retain the previous records and recovery target. If something changes unexpectedly, record the first differing observation and return to that component’s procedure.

Additional Packs use files and registration procedures appropriate to the supplied release, customer and installation scope. Copying a folder or renaming a candidate does not replace registration/approval. First application requires the approved plan, postcondition validation and receipt. Removal/rollback follows that Pack’s declared recovery procedure and current authority.

Back to installation and first-use guide

Why this case matters

A cloud console can report Running while the appliance is still initializing. Confirm product readiness in the setup interface before connecting clients or starting Work.

Example situation

You created a new appliance and the cloud console says Running. PackrGUI cannot connect, while product status says initializing or service not ready. Record the cloud and product states separately.

Check in this order

1. Confirm the received image's release ID and that this is a new deployment. Stop if it is an older test VM or a different release image.
2. Read the release's first-boot completion condition and expected wait procedure. Do not invent an arbitrary time limit as a success condition.
3. Inspect VM running state and product service readiness separately. A running process is not enough when product readiness is absent.
4. Use only the release-provided read-only diagnostic to inspect the first-boot stage, required components, and service refusal reason. Use exact commands and log locations from the release guide.
5. Even if a network error appears at the same time, do not assume networking is the cause before service readiness is established.

If this release supplies packrctl and the authorized local operating route, these read-only commands show why VM power and product readiness need separate checks. Read the returned readiness and reason fields; a nonzero health exit can represent UNKNOWN or NOT_READY and is not a reason to restart the VM blindly.

packrctl status --json
packrctl health --json

What to do with the result

Field decision example: first boot has power only

Assume an operator creates a VM at 10:00 and sees running in the console at 10:02, while product status remains initializing. The evidence establishes VM power only. Service readiness, administrator enrollment, and client access remain unverified. Record image ID and boot time, perform the release-defined wait and status check once, then escalate a persistent refusal. Do not repair guest packages or initialization files directly on the customer VM.

Example support request

“Release ID [value], instance creation time [with zone], VM state [Running], product status [exact displayed text], first-boot stage [value], and first error [verbatim]. No customer Work was started.”

Send the minimum status output named by the release, not customer data or a full system log.

Completion and stop conditions

Complete: the product reports service readiness for this installation identity. Stop: an initialization gap, integrity warning, release mismatch, or repeated readiness failure appears. Do not delete recovery files, reinstall, or force-start services.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario A-1: The VM is running while first boot is still in progress

Situation: An installer opens the GUI as soon as a new VM powers on. The GUI times out while the first-boot view still shows initialization. Product readiness must be checked before attributing the symptom to credentials.

Read these observations separately.

• VM: running. This confirms power only.
• Product: initializing. No readiness completion has been recorded.
• GUI: timeout. Before readiness, this does not establish an authentication cause.

Check and action sequence:

1. Check image and creation records for the same instance, then locate the release-defined completion signal and wait policy.
2. Check whether initialization is making progress in product status. Do not reenroll accounts or reinstall clients while readiness is absent.
3. After readiness is observed, record installation identity and recheck the original GUI connection.

Condition for resuming: Proceed to administrator setup only when that new installation is ready and identity matches; verify GUI connection separately.

If still unresolved: If the supplied wait limit is exceeded or progress stops, retain the first error and last update time and hand over to the image/deployment owner.

Worked scenario A-2: A process exists but required initialization fails

Situation: The management view shows a running service process while product health remains not ready. The first error describes an unavailable required initialization component or configuration. Compare the image and product readiness before treating a restart as a fix.

Read these observations separately.

• Process start: confirmed. Initialization success is separate.
• Health: not ready. Retain its exact reason and observation time.
• Inventory: delivered and actual image identity still need comparison.

Check and action sequence:

1. Compare current instance provenance with the delivered image/release. Do not interpret it using another version’s instructions.
2. Separate the first initialization refusal from later status using supplied read-only status/health output.
3. If a missing asset is confirmed, use the supplier’s image repair/replacement procedure; do not add arbitrary guest packages.

Condition for resuming: After supported correction, recheck current image/installation identity and readiness. A restarted process alone does not close the case.

If still unresolved: With an unconfirmed cause or different image, hold enrollment/Work and hand over minimal errors and image identity.

Worked scenario A-3: Yesterday’s readiness screenshot is healthy but today’s connection fails

Situation: A user assumes the server is healthy because an earlier readiness screenshot exists. Maintenance or a reboot occurred later, and today’s product status has not been read. Separate prior success from current observation.

Read these observations separately.

• Earlier screenshot: predates the change; it is not current-state evidence.
• Change record: retain only known reboot/update times.
• Current state: unconfirmed; a network fault is not established yet.

Check and action sequence:

1. Check whether the current target is the same instance. A replacement also needs Cases B/J identity checks.
2. Read post-change status/health and first errors. Once readiness is confirmed, separate reachability/authentication with Case C.
3. Bind before/after status to the actual change and recheck affected stages.

Condition for resuming: Record recovery only for the current readiness, identity and client authentication actually reconfirmed.

If still unresolved: If current status cannot be read, retain that unconfirmed stage and management-path issue instead of filling it with an old screenshot.

Fill the case-specific support record

Image/instance provenance, creation time, current status/health, initialization stage, first refusal and last update time.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: A-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Why this case matters

A host key may change when an instance is replaced or reconfigured. A warning means the identity of the destination is not yet confirmed; do not disable the check to reconnect.

Example situation

You reconnect to yesterday's address and SSH or the app warns that the server identity changed. You may believe it is the same VM, but it could be a new instance, a regenerated key, a wrong address, or an unverified host.

Check in this order

1. Stop the connection. Record the warning time, destination, and displayed identity information. Do not include private keys or credentials.
2. In the release-approved management console, confirm the target instance name, installation ID, and creation or restart history. An unchanged address does not prove an unchanged host.
3. Compare the current host identity through an independent authenticated route supplied by the product or cloud. A value obtained only through the warned connection cannot authenticate that same connection.
4. Follow a release-defined trust-update procedure only when the independent values match and you have authority to update trust. Otherwise hand the case to the administrator or support.
5. After connection, separately confirm the customer and installation identity. Host-key proof does not grant product authority.

What to do with the result

Field decision example: key warning at an unchanged address

Suppose a connection tool reports a different host key at the same address. A new instance might reuse the address, or the original instance might have regenerated its key. The warning alone cannot decide which. Keep the connection stopped while comparing instance and disk identity in the management console with the current key from a release-approved independent authenticated route. If either side is unavailable, do not delete or replace saved trust.

Example support request

“Release ID [value], expected installation ID [value], target [official alias], warning time [with zone], warning type [verbatim], and instance-replacement check [result]. I did not proceed after the warning.”

Completion and stop conditions

Complete: current host identity, installation identity, and official destination match independent evidence. Stop: if any identity mismatch remains, do not disable host checks, ignore the warning, or arbitrarily delete or replace saved keys.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario B-1: Host-key warning after a replacement VM reuses an address

Situation: An operator replaces a VM and the client connects to yesterday’s address. The client warns that the server key changed. Address reuse is a possible explanation, not verified identity for the current channel.

Read these observations separately.

• Address: unchanged; this does not establish the same instance.
• Management console: independently check the replacement record.
• Host fingerprint: distinguish the warning-channel value from an independent value.

Check and action sequence:

1. Keep the connection stopped while checking current instance/disk/image identity through the approved console.
2. Obtain the current public-key fingerprint through the release’s independent authenticated route and compare it.
3. Only after a match, have an authorized owner apply the supplied trust-update procedure and verify product installation identity.

Condition for resuming: Return to connection only after both current host and product installation identity match expectations.

If still unresolved: Without an independent match, hold and hand over to the identity owner; do not delete trust records or disable checking.

Worked scenario B-2: Distinguish a stale saved endpoint from the intended server

Situation: A bookmark or client-profile alias looks familiar, but the connected product is not the expected installation. Even a valid server key does not establish that the intended work target was selected.

Read these observations separately.

• Profile alias: a human label; retain it separately from target identity.
• Host identity: may be valid for another approved server.
• Customer/installation display: do not use the session for work when it differs.

Check and action sequence:

1. Compare the published endpoint with the saved profile’s actual address and port.
2. Compare customer/installation identity with independent installation records; do not inspect another customer’s content.
3. Select the correct profile through approved client settings and recheck identity/scope in a fresh session.

Condition for resuming: Continue only with current evidence of authentication to the intended target.

If still unresolved: If the official endpoint cannot be bound to the intended installation, stop access and involve address/identity owners.

Worked scenario B-3: The host is said to be unchanged but its key changes again

Situation: A legitimate key update was verified once, but another warning occurs for the same claimed instance. A reboot or configuration-change explanation alone does not authorize repeated trust updates.

Read these observations separately.

• Key change: occurred again between observations; retain each transition.
• Instance: compare the claim of sameness with actual console identity.
• Current key: a difference from the verified value is unconfirmed again.

Check and action sequence:

1. Retain the first update’s basis and the later warning’s time and target.
2. Have the owner compare approved changes with current independently obtained identity.
3. Do not repeat connection until the cause and current identity are verified.

Condition for resuming: Recheck the specified connection only after the owner verifies current host/installation and change history.

If still unresolved: Escalate unexplained repeated key changes as an identity issue, not routine profile cleanup.

Fill the case-specific support record

Expected target alias, warning time, replacement history, independent fingerprint verification and product installation identity match.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: B-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Why this case matters

A timeout and a login refusal require different checks. A timeout can indicate reachability or service readiness; a refusal after reaching the server points to authentication or access scope.

Example situation

PackrGUI cannot connect. One attempt reports connection timed out; the next reports login refused. The first may concern reachability or readiness, while the second may concern authentication or scope. Record them as separate events.

Check in this order

1. Confirm the current appliance release ID and installation ID.
2. Distinguish a running VM from a ready product service. If the product is not ready, resolve Case A first.
3. Check the official release destination and network route against the customer's firewall policy. Do not open a different port or public Internet route on your own.
4. Only after reachability is established, check the current account, release-specified login method, and its customer and installation scope.
5. Even after authentication succeeds, confirm the customer and installation identity and permitted functions in product status. Login alone is not runtime binding or Work authority.

Branch by message

Recheck and support evidence

After a remedy, recheck service readiness → reachability → authentication → product installation identity in order. Include both the first and later errors with their exact text and times in support requests. Identify the destination only by an official shareable alias. Never send a password, token, or private key.

Completion and stop conditions

Complete: an authenticated client displays the expected customer and installation identity. Stop: do not work around identity mismatch or an unverified auth route by borrowing an account or key or disabling host checks.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario C-1: Separate a connection timeout from product unreadiness

Situation: The same account worked yesterday, but today there is no response and no login prompt. Check server readiness and the approved route before assuming a password problem.

Read these observations separately.

• Client: timed out without an authentication response.
• Server readiness: requires a current observation.
• Address/port: not assumed correct before comparison with the release.

Check and action sequence:

1. Confirm current readiness with Case A; resolve unreadiness first.
2. Have the owner compare the endpoint with approved DNS/firewall/access routes; do not open arbitrary ports.
3. After reachability recovers, check authentication and customer/installation identity separately.

Condition for resuming: Record connection recovery only when response, authentication and identity are confirmed on the approved route.

If still unresolved: If the failing segment is unknown, hand over the last reachable point and timeout to the network owner.

Worked scenario C-2: The server responds but the session has expired

Situation: The GUI verifies server identity but login is refused; headless queries are also refused for the current account. Separate a responding network from a valid session.

Read these observations separately.

• Server response: present; separate it from simple reachability failure.
• Session: retain the exact observed expired/unauthenticated message.
• Other route: do not assume GUI and headless share the same account/session.

Check and action sequence:

1. Check the release login method, account and validity period.
2. Reauthenticate the permitted current account through the supported flow and check returned customer/installation scope.
3. Query each needed GUI/headless route separately; do not copy user tokens into a service.

Condition for resuming: The connection stage closes for the route whose current authenticated session shows the correct installation.

If still unresolved: If authorization still refuses after reauthentication, hand exact scope/reason to the account owner without passwords or tokens.

Worked scenario C-3: GUI works while the automation service cannot connect

Situation: The workstation GUI works, but a scheduled server task is refused. Query from the service’s execution location and identity instead of reusing the GUI screenshot as success evidence.

Read these observations separately.

• GUI: success for the current user session.
• Automation: may use another account, route and permitted scope.
• Failure: distinguish timeout from authentication refusal using the original message.

Check and action sequence:

1. Check that the release supplies a headless route and service-authentication procedure.
2. Record the service endpoint, execution account, session and customer/installation scope separately.
3. After the owner corrects the failing route, recheck read-only status with the same service identity.

Condition for resuming: Record automation readiness only after its own authentication, identity and permitted functions are confirmed.

If still unresolved: If service authentication or scope authority is unavailable, hand over that state instead of copying user credentials.

Fill the case-specific support record

Access route, current readiness, timeout/identity/authentication failure stage, session state and customer/installation scope.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: C-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

Administrator enrollment may require a live, interactive confirmation. A value sent through a script or pipe can be refused. Confirm the product's success record before using administrator functions.

Example situation

An installation operator ran administrator enrollment from an automation script. The output refuses it because user confirmation is required. The binding wizard then cannot find administrator scope. Treating the command as successful would create a second failure.

Check in this order

1. Find whether the release requires the local setup UI or a genuinely interactive terminal for enrollment.
2. Determine whether the attempt came from a pipe, scheduled task, or non-interactive remote session. Do not include a secret input or confirmation word in support evidence.
3. Read current product administrator enrollment status without changing it. Do not start subsequent binding if there is no success record.
4. Have the authorized actual administrator review customer, installation, and runtime scope and confirm directly in the release-designated interactive flow.
5. Read back the resulting role, allowed scope, validity period, and installation identity. Distinguish OS login from product administrator enrollment.

Example branches

Example support request

“Release [value], enrollment stage [value], input method [interactive/non-interactive], product refusal [verbatim], enrollment status [none/present/unavailable]. No secret input is attached.”

Completion and stop conditions

Complete: the real administrator's product role and scope for this installation are recorded and readable. Stop: do not fake confirmation with automation or substitute OS administrator rights for product authority.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario D-1: Administrator confirmation is refused through a remote pipe

Situation: A setup script runs enrollment and receives a refusal requiring a real terminal or user confirmation. Check the supplied interactive requirement before treating it as an enrollment defect.

Read these observations separately.

• Input route: pipe or noninteractive job.
• Product result: the required human confirmation was not satisfied.
• Enrollment: no completed role/scope record exists yet.

Check and action sequence:

1. Locate the supported local wizard or interactive-terminal enrollment route.
2. Have the actual administrator review installation/customer/runtime scope and expiry.
3. Immediately read back the recorded role and scope after enrollment.

Condition for resuming: Record administrator setup complete only with human confirmation and product enrollment results.

If still unresolved: If the interactive route is unavailable, hand over that constraint without automated confirmation or token manipulation.

Worked scenario D-2: An OS administrator logs in without a product administrator role

Situation: An OS administrator expects the same authority inside the product. The product indicates no administrator role for the current installation.

Read these observations separately.

• OS login: succeeded.
• Product role: absent or unconfirmed for this installation.
• Installation scope: another installation’s enrollment is not reusable.

Check and action sequence:

1. Check current product installation identity against the subject of earlier enrollment.
2. Identify the owner authorized to enroll a product administrator for this installation.
3. Check recorded product role/scope/expiry instead of elevating OS privileges.

Condition for resuming: Perform observations within scope only after confirming product administrator enrollment for the current installation.

If still unresolved: Without enrollment authority, hand over to its owner rather than expanding scope through attempts.

Worked scenario D-3: Enrollment completes with an unexpected customer/runtime scope

Situation: After enrollment appears complete, runtime binding is refused. The recorded scope refers to another customer/installation or a narrower runtime scope than intended.

Read these observations separately.

• Enrollment completion: establishes role existence.
• Permitted scope: coverage of the current request is separate.
• Refusal: retain its exact target and reason.

Check and action sequence:

1. Compare current installation/customer/runtime references with the administrator record.
2. Identify the mismatch and have the authorized owner decide a supported scope change.
3. Read back changed scope, then restart the affected observation/validation stage.

Condition for resuming: Proceed only when the request is within recorded scope and the product has revalidated it.

If still unresolved: Hold when original authority cannot be established; do not edit stored enrollment records.

Fill the case-specific support record

Enrollment route/interactivity, current installation identity, actual human confirmation and product role/scope/expiry.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: D-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

An administrator may complete enrollment and still see an access refusal when the product reads the policy. Verify enrollment success and subsequent access success separately; the refusal reason determines the next step.

Example situation

Enrollment appeared successful. The first runtime observation then returns Permission denied or a storage-access error. Preserve the first error instead of enrolling the administrator repeatedly.

Check in this order

1. Record the first product error's time, stage, and refusal code. Do not overwrite the first event with retries.
2. Confirm the release and installation ID still match those used at enrollment. Stop if the product may be reading another installation's policy.
3. Inspect product service readiness and administrator enrollment status separately in the release's read-only status view.
4. Distinguish storage-access failure from absent administrator role and from out-of-scope authority. These require different responses.
5. Consult the exact release's known-fix or support guidance. Editing file ownership or lock files is not a customer troubleshooting step.

What to do with the result

Support evidence

Provide release and installation IDs, first refusal message, whether enrollment succeeded, service readiness, and time. Do not attach lock files, the internal database, raw administrator policy, private keys, or full logs.

Completion and stop conditions

Complete: the product can read the administrator status and process an allowed observation. Stop: do not repeat enrollment, widen file permissions, delete a lock file, or change the service account.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario E-1: The first status read fails after successful enrollment

Situation: Enrollment completes, but a later policy/status read shows Permission denied. Preserve enrollment and the first access error separately before repeating enrollment.

Read these observations separately.

• Enrollment result: exists.
• Subsequent read: ended in access refusal.
• Basis: product reasons must still distinguish store access from role scope.

Check and action sequence:

1. Compare release and installation identity for both results.
2. Retain the exact failed stage/reason and read-only service readiness.
3. Check supported corrections for that version; do not change file ownership or lock files directly.

Condition for resuming: After supported correction, read the administrator state and confirm permitted observation for the same installation.

If still unresolved: If store access remains refused, hand over the first error/version without attaching the database to an ordinary ticket.

Worked scenario E-2: Reads work but out-of-scope operations are refused

Situation: Administrator status reads normally while one runtime/capability request is refused. Treating every refusal as filesystem permissions can hide an actual scope boundary.

Read these observations separately.

• Administrator read: succeeds.
• Specific request: reported outside current scope.
• Other operations: success does not authorize this request.

Check and action sequence:

1. Compare requested installation/customer/capability/runtime with permitted scope.
2. Have the owner distinguish a necessary scope change from an incorrectly selected target.
3. After a supported target/authority correction, recheck the same bounded request.

Condition for resuming: Record recovery only for the permitted capability successfully rechecked.

If still unresolved: Without scope authority, do not broaden permissions or replace service accounts.

Worked scenario E-3: Store access first fails after an update

Situation: An existing installation fails its administrator status read after an update. Earlier successful reads exist, but none after the update. Bind changed version, current identity and failed stage together.

Read these observations separately.

• Earlier version: successful read is recorded.
• Current version: the first read fails.
• Installation identity: any change must be checked separately.

Check and action sequence:

1. Check exact before/after versions and the approved change record.
2. Use allowed read-only diagnostics for current installation/service/administrator state.
3. Have the owner use that version’s recovery/rollback procedure; do not mix arbitrary older files.

Condition for resuming: Close this access issue only with a confirmed recovery version, current installation and successful read.

If still unresolved: Hold without a supported recovery procedure or on an integrity warning; hand over minimal errors and change history.

Fill the case-specific support record

Enrollment result, first access failure stage/time, service state, current role/scope and before/after versions.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: E-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

Finding a local model and binding it to this installation are separate steps. After a model alias or runtime address changes, check the current binding result before using the model for Work.

Example situation

The administrator confirms the local model is installed. PackrGUI says the runtime is detected but not bound. If a model alias or runtime address changed yesterday, distinguish the old state from the current observation.

Check in this order

1. Confirm the runtime type and model are supported by this release. A model file alone does not establish support.
2. Read detection time, validation status, and binding status separately. Check that the view is not from an earlier boot.
3. Confirm the current customer and installation IDs and whether the approved administrator scope includes this runtime location and model.
4. Preserve any ambiguity or out-of-scope reason exactly as shown. Do not guess which of several models to write into product storage.
5. Use the release wizard's re-observation or scope-approval procedure. Then read the new binding model reference and installation ID.
6. Even after binding, check actual Work calls separately in Case I.

Example branches

Field decision example: old binding after an alias change

Assume a runtime alias changes at 11:00 while the product still shows a bound record from 10:30. That record belongs to the prior state. A new discovery time, Core validation, and binding time and model reference after 11:00 are needed to establish rebinding. New detection alone is insufficient; use the branch table above to locate the first refused gate.

Times are illustrative. Record actual product state and refusal codes; do not edit internal storage.

Example support request

“Release [value], installation ID [value], runtime type [shareable name], expected model [name], change time [value], detection/validation/binding states [separately], refusal [verbatim]. No Work was run.”

Completion and stop conditions

Complete: the product displays a fresh binding linked to the current observation and approved scope. Stop: do not edit the database or copy an earlier refused binding.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario F-1: Model files exist without an observed runtime

Situation: An operator expects binding because model files were provisioned. The product has no current runtime observation or only discovery status. Check file provisioning, process state and product observation separately.

Read these observations separately.

• Model files: presence only is confirmed.
• Runtime process: supported version and actual execution need checking.
• Product observation: fresh observation/validation/binding is not established.

Check and action sequence:

1. Compare provisioned runtime/model/address with release-supported combinations.
2. Read current observation and reason in the product discovery/setup flow.
3. After supported preparation, confirm product validation of a fresh observation.

Condition for resuming: Record binding complete only for validated/bound current installation runtime/model references.

If still unresolved: Without a supported target/observation route, hand over instead of creating binding-state files.

Worked scenario F-2: An alias changes while the old binding remains visible

Situation: After a model alias change, the screen still shows the old binding. Distinguish an old display, absent fresh observation and a refused new target before deciding what changed.

Read these observations separately.

• Change record: distinguish before/after alias or address values.
• Displayed binding: may refer to a pre-change observation.
• Fresh observation: separately check time, target and any refusal.

Check and action sequence:

1. Retain previous binding references and newly intended runtime/model references.
2. Use the supplied observation/validation procedure and compare its time with the change.
3. If the new target is out of scope, await its authority owner instead of copying old results.

Condition for resuming: Record application of the new environment only when the fresh observation’s target and binding match.

If still unresolved: Do not start new Work for the changed target on an old binding when fresh observation/reasons are unconfirmed.

Worked scenario F-3: Several models are discovered and the intended target is ambiguous

Situation: Several models exist and the product discovers a runtime without applying binding. Selecting the first available model arbitrarily would not establish the intended supported target.

Read these observations separately.

• Discovery: multiple candidates are visible.
• Administrator scope: the permitted model/runtime needs checking.
• Product result: preserve ambiguity/scope refusal as returned.

Check and action sequence:

1. Identify the intended target and supplier-supported combination first.
2. Have the administrator check current installation scope through the product flow.
3. After the exact target is established, read fresh observation/validation results.

Condition for resuming: Continue within scope only after the intended target and validated binding are recorded.

If still unresolved: Do not invent a default target without selection authority or a supported combination.

Fill the case-specific support record

Current runtime/model references, before/after values, observation time, validation/refusal and permitted administrator scope.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: F-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

Local model startup can fail because a model is unavailable, resources are insufficient, or a network check cannot complete. Check the exact message and the supplied offline setup procedure before changing network policy.

Example situation

A customer plans to use a local model in an offline environment. The runtime waits for a model download or a metadata check times out. Alternatively, model startup fails, but the screen alone does not distinguish insufficient memory from a missing model.

Check in this order

1. Check the release's supported model, architecture, memory, and disk requirements. Size the VM from that list.
2. Confirm by the product or release-defined method that the model is already available locally. A download screen is not proof of local installation.
3. Confirm the customer's offline policy and the release-required local-only configuration. Do not open an Internet egress path on your own in a restricted environment.
4. Separate model-process startup, runtime discovery, binding validation, and Work execution. Different failing stages need different actions.
5. Read recorded call and failure status. Do not report a timed-out vendor metadata request as successful AI inference.
6. If resources change, follow the customer's approved environment-change procedure and observe, validate, and bind the runtime again.

What to do with the result

Example support request

“Release [value], OS/architecture [value], model [value], local model presence [value], failing stage [startup/discovery/validation/Work], first error [verbatim], external-network policy [allowed/blocked]. No prompts or customer data attached.”

Completion and stop conditions

Complete: the supported local model is prepared and the current runtime is validated and bound. Actual inference and Work still require separate checks. Stop: unknown requirements, unapproved Internet access, or an unsupported claim that no external inference occurred.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario G-1: The model exits during loading but memory shortage is unconfirmed

Situation: The model exits shortly after startup. A user wants to add memory before checking the error. Resource, architecture and model provisioning facts need to be reviewed together.

Read these observations separately.

• Process: starts and then exits.
• Failure reason: resource shortage is not established without the actual error.
• Support conditions: compare model, architecture, memory and disk requirements.

Check and action sequence:

1. Compare exact model version/architecture with release requirements.
2. Read available resources and first exit reason through permitted diagnostics.
3. If a resource shortage is confirmed, have the environment owner apply an approved change and observe again.

Condition for resuming: Record preparation complete when the model starts under supported conditions and current observation/validation/binding are confirmed.

If still unresolved: Without an exact failure reason, hand over exit observations/support requirements instead of repeatedly resizing or replacing models.

Worked scenario G-2: A closed network waits for model files that were not provisioned

Situation: A closed on-premises environment has client packages and SDK dependencies but no model files. The runtime waits for a model download. Provisioned Rust dependencies do not establish model-weight availability.

Read these observations separately.

• SDK dependencies: provisioning for Rust compilation.
• Model: local provisioning needs a separate check.
• External route: do not open a blocked policy to resolve provisioning.

Check and action sequence:

1. Check intended model/version, licensing, digests and storage requirements in supplied inventories.
2. Have the owner provision it through an approved offline model-import route.
3. After file verification, check model start, fresh observation and binding in sequence.

Condition for resuming: Close preparation only with verified local model assets and confirmed runtime binding.

If still unresolved: With an unconfirmed import route or rights, involve provisioning/licensing owners instead of fetching arbitrary model files.

Worked scenario G-3: Separate an online metadata failure from local operation

Situation: A local model is provisioned while an external metadata request times out. That result alone establishes neither failure of all local inference nor absence of external communication.

Read these observations separately.

• External lookup: attempted and timed out.
• Local inference: requires its own invocation/result.
• Product Work: requires separate Work identity/receipt checks.

Check and action sequence:

1. Check customer policy and actual application of supplied local-only configuration.
2. Record external lookup failure, local model start, binding and Work observations separately.
3. Recheck with allowed diagnostics; policy changes or external-model substitution follow their owners’ separate procedures.

Condition for resuming: Record success only for confirmed local stages and retain external lookup failure separately.

If still unresolved: Without confirmed communication scope/model selection, hand over without claiming no external traffic or completed local Work.

Fill the case-specific support record

OS/architecture, model/runtime versions, required/current resources, local provisioning, first exit and external lookup status.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: G-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

The real boundary

Pack Builder helps prepare and validate Packs. Candidate creation, saving a file, a prepared screen state, and passkey enrollment are separate states. None automatically grants customer Pack approval, entitlement, or execution authority.

Example situation

An operator creates a Pack candidate in Builder. Preview and structural validation pass, yet it does not appear in PackrGUI's execution list or a Work request is refused. “Builder made it, so it can run” is not a valid conclusion.

Check in this order

1. Confirm this release actually supplies Builder and that its installer signature and version match.
2. Inspect candidate validation status and its defect list. Distinguish structural validation from execution approval.
3. Confirm the Pack's exact version, contract, requested capability, and target environment.
4. Inspect Pack approval and customer entitlement separately for this installation. Do not reuse approval from another customer or installation.
5. Review preconditions and any separate user approval or passkey requirement. A browser opening or returning to the app does not prove approval.
6. If a refusal remains, repair the candidate or follow the approval process. Do not run refused Work through another path.

What to do with the state

Example support request

“Release [value], Builder version [value], candidate ID/version [shareable value], validation [state], approval [state], customer entitlement [state], first Work refusal [verbatim].” Do not attach Pack source, internal contract text, or a passkey response.

Completion and stop conditions

Complete: the exact Pack is validated, approved, and entitled for this customer installation, with preconditions met. Stop: do not relabel a candidate as an approved Pack or bypass refused execution.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario H-1: Candidate structure validates while approval is pending

Situation: Builder shows candidate validation PASS and the user looks for it in the execution list. No approval exists for that exact revision yet; a stage remains between preparation and approved use.

Read these observations separately.

• Candidate validation: success within its specified checks.
• Approval: pending.
• Execution: no Work start/receipt exists.

Check and action sequence:

1. Check that candidate ID/revision/digest and validation result refer to the same bytes.
2. Hand purpose, candidate digest and validation to the release approval owner.
3. After approval, separately check current customer/installation entitlement and preconditions.

Condition for resuming: Move only to execution preparation after exact-candidate approval, entitlement and preconditions are confirmed.

If still unresolved: Without approval, do not copy the candidate into Pack folders or execute through another account.

Worked scenario H-2: Approval exists but entitlement belongs to another installation

Situation: A Pack approved for one installation is expected to work in another. The product refuses current-installation entitlement. Separate approval existence from its applicable scope.

Read these observations separately.

• Pack approval: check its exact version and scope.
• Current installation: may differ from the approved/entitled installation.
• Refusal: an authority result for the current request.

Check and action sequence:

1. Compare current customer/installation/Pack version with entitlement references.
2. Have the authority owner decide the needed entitlement through supported procedures; do not copy another installation’s files.
3. After entitlement is confirmed, recheck preconditions/plan for the same target.

Condition for resuming: Proceed with that Pack only when authority and plan are confirmed for the current installation.

If still unresolved: Without the authority owner’s confirmation, do not rename approval files or edit installation IDs for reuse.

Worked scenario H-3: The candidate changes after approval

Situation: A declaration or candidate file changes after review. The earlier approval screen remains, but the candidate digest differs. Determine whether the new bytes are actually covered.

Read these observations separately.

• Existing approval: refers to the previous candidate digest.
• Current candidate: changed revision/digest.
• Current validation: requires a result for the changed candidate.

Check and action sequence:

1. Retain before/after digests and change purpose.
2. Use the supported process to check validation and approval coverage for the new candidate.
3. Reconcile references across the current candidate, approval, entitlement and execution plan.

Condition for resuming: Proceed with the changed candidate only when current bytes are covered by the required results.

If still unresolved: Do not copy an old approval or edit only manifest digests to make references appear aligned.

Fill the case-specific support record

Candidate ID/revision/digest, validation subject, approval purpose/scope, current entitlement, preconditions and actual Work presence.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: H-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

A local runtime can be bound without any Work being submitted. Runtime readiness and completed Work have different records.

Example situation

PackrGUI shows the runtime as bound. An operator believes the first task is complete, but the Work list has no result or receipt. Alternatively, a Work was submitted but remains pending/stopped/rolled back.

Check in this order

1. Confirm that Work was actually submitted under the same customer, installation, and release identity.
2. Check approval, entitlement, and preconditions for the requested Pack or operation.
3. In the product Work record, inspect approval, execution start, model call, result validation, and final status separately. If a stage is absent, the claim stops there.
4. For a local model, confirm a call bound to that Work. A generally responsive model is not evidence that this Work called it.
5. Only after final success, locate the result and receipt with the same Work ID. Failure, stop, and rollback are not success receipts.
6. If the receipt is absent, follow the release's record-query procedure and send support the first missing stage. Do not create a receipt file manually.

If your installation includes packrctl and you are authenticated, inspect rather than rerun an uncertain Work. Replace the placeholder with the returned Work ID.

packrctl work list --limit 10 --json
packrctl work show "PASTE_RETURNED_WORK_ID" --json

An empty list for the permitted principal does not prove that another principal never submitted Work. A report file or model response does not replace the product's typed Work and receipt record.

Identify the last proven step

Example: runtime bound, Work readiness unknown

Suppose a local model alias changes and the appliance shows a new BOUND state, while Work readiness shows UNKNOWN. Record the installation and release, binding time, separate authority and runtime states, exact reason shown, and whether a Work ID exists. If readiness remains UNKNOWN, stop before submission and send these values through the supplied support route. Repeating a command, editing state files, or treating a binding record as a receipt cannot establish Work completion.

Field decision example: confusing model response with Work completion

Suppose an operator gets an answer to a model test prompt and sees bound in the GUI, then reports first Work complete. With no Work ID, even submission is unproven. With an ID, separately check approval, execution start, model call, result validation, closure, and receipt. Use this table for the Work on your own installation.

Report the first missing gate. Do not use another Work's receipt or a manually created file to fill the gap.

Example support request

“Release [value], installation ID [value], Work ID [if any], Pack/operation [shareable name], last confirmed state [value], first refusal/missing stage [verbatim], model call [yes/no/unknown], receipt [absent/present].” Do not send raw prompts or results.

Completion and stop conditions

Complete: the same authorized Work has a successful final state, validated result, and matching receipt. Stop: never fill a missing record with a binding screen, inferred model call, or another Work's receipt.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario I-1: A model test responds but no Work ID exists

Situation: An operator sees a model test response and a bound-runtime screen and assumes the first Work completed. No matching request exists in the product Work list. Distinguish model testing from product execution.

Read these observations separately.

• Model response: a standalone test result.
• Binding: a runtime preparation result.
• Work: no actual submitted ID is confirmed.

Check and action sequence:

1. Read the product Work list with the permitted current account and establish whether the request was submitted.
2. Record submission unconfirmed when no ID is found; do not generalize to another account’s history.
3. If an authorized first Work is needed, start through its plan/authority procedure and retain the returned ID.

Condition for resuming: Do not mark first Work complete before its actual authority/execution/validation/terminal state/receipt are confirmed.

If still unresolved: Without submission authority or a supported Pack, hand over preparation state instead of manufacturing a receipt from the model response.

Worked scenario I-2: The submitted Work result is delayed

Situation: A Work submission returns an actual ID, then the client disconnects. Before resubmitting the request, query that returned ID to avoid duplicate execution.

Read these observations separately.

• Submission: an actual returned ID exists.
• Client: only the disconnection is confirmed.
• Execution result: a connection error establishes neither success nor failure.

Check and action sequence:

1. Read the same customer/installation/Work ID through the product query route.
2. Retain actual returned waiting/running/failure/rollback/success state and update time.
3. For terminal success reconcile result validation/receipt; otherwise use supplied wait/support procedures.

Condition for resuming: Handle the result only after confirming that same Work’s termination, result and receipt.

If still unresolved: If querying is unavailable or status is unconfirmed, hand over ID, first connection error and last state without resubmitting.

Worked scenario I-3: A report exists but its receipt refers to another installation or Work

Situation: A shared folder contains reports and receipts from several runs. Similar file names do not bind them to the current Work.

Read these observations separately.

• Result file: exists, but its execution binding is unconfirmed.
• Receipt: customer/installation/Work references need checking.
• Product record: current Work terminal state and result digest are the comparison basis.

Check and action sequence:

1. First read the returned Work ID’s product record and its current result digest.
2. Compare receipt execution/installation references and results of the supplied verification procedure.
3. Preserve mismatching files unchanged, distinguish them from other runs and hand over to the owner.

Condition for resuming: Record completion only when the same execution’s record, result and verified receipt align.

If still unresolved: Keep the current Work unconfirmed instead of editing receipt IDs or hashes to make them match.

Fill the case-specific support record

Returned Work ID, current customer/installation, last state/update time, result digest and receipt references/verification.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: I-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Observed pattern and meaning

A newly deployed VM should have its own installation and host identity. An existing organization name, administrator, or access key on first setup needs investigation before the VM is used.

Example situation

You create a new customer VM from an official image, but setup displays an earlier organization name or an apparently pre-enrolled administrator. Or you notice an unexpected user home, access key, or already-used installation ID. Do not assume it is harmless sample data and continue Work.

Check in this order

1. Do not start Work. Pause external connection and additional user enrollment.
2. Record the received official image's release ID and deployment method and the new instance creation time.
3. Compare displayed customer and installation identities with the expected values. Do not open or copy another customer's data.
4. In the cloud management view, confirm only that the instance came from the intended official image. Do not investigate internal disk files for a cause.
5. Send the release support or deployment owner the minimum first-observation information, image ID, installation ID, and time. Await the owner's isolation or replacement decision.

What to do with the result

Field decision example: prior account residue on a new installation

If a new VM shows an unexpected user home or prior installation ID, do not browse it to decide whether it contains customer data. The finding itself requires review of image identity and access state. Stop Work and new user enrollment. Record only image ID, new instance ID, observation time, and product-displayed installation identity.

Example support request

“Release [value], official image ID [value], new instance creation time [with zone], expected installation ID [value], displayed identity type [customer/user/installation], minimal description of first screen [value]. No Work or additional enrollment was performed.”

Do not attach another customer's name, file contents, key, or full disk image to an ordinary support ticket.

Completion and stop conditions

Complete: the authorized owner independently verifies the image and fresh installation identity and explicitly releases it for use. Stop: a customer must not delete earlier files or replace keys to make an unverified image appear clean.

Distinguish three similar-looking symptoms

Return to the original procedure after correction

Record the first refused stage and the corrected item, then check its current result. Recheck earlier proven stages when the change affects them. Proceed only with the required current evidence. Include exact version, time with timezone, failed stage/reason, last confirmed state, change and recheck result in support handover. The illustrative table is not an established cause or execution history.

How to read the detailed cases

The three cases below are worked teaching scenarios for realistic field conditions. Their illustrative states are not invented product error codes or customer incident histories. Distinguish causes using values observed in your own installation. Cite supplied execution records only within their recorded scope.

Each example supplies context, observations, discriminating checks/actions, resumption criteria and unresolved handover. One symptom can have several causes; do not blindly continue after the first refusal.

Worked scenario J-1: A new VM’s first setup shows an earlier organization

Situation: A supposedly new installation shows an unexpected organization or administrator during first setup. Verify provenance before assuming sample data and entering customer information.

Read these observations separately.

• VM creation: a new-instance record exists.
• Product display: differs from the intended organization/installation.
• Content: do not inspect earlier data or credentials directly.

Check and action sequence:

1. Stop Work, further enrollment and customer data entry.
2. Record only signed image/instance provenance, creation time and the type of displayed identity.
3. Hand over to image/deployment owners and follow approved isolation/replacement decisions.

Condition for resuming: Return to setup only after the owner independently verifies image/new identity and explicitly resumes use.

If still unresolved: Do not erase displays or user directories to make it appear to be a fresh installation.

Worked scenario J-2: Two different VMs show the same installation identity

Situation: A team creates two VMs with the same product installation ID but different addresses and instance names. Even before establishing a cloning/provenance cause, independent installation identity needs verification.

Read these observations separately.

• Instances: two creation records exist.
• Installation ID: the same value is displayed.
• Host identity: a separate item from product installation identity.

Check and action sequence:

1. Hold Work/enrollment on both and retain their separate provenance/creation records.
2. Use management records to check fresh official-image deployment versus an existing disk/VM copy.
3. Hand installation identity/image verification to its owner; do not manually alter IDs or keys.

Condition for resuming: Use them as independent environments only after unique identities and approved resumption are confirmed.

If still unresolved: Do not alternate environments to hide the issue or distribute copied approval/entitlement files.

Worked scenario J-3: Earlier state reappears in a replacement VM

Situation: A replacement instance shows the same earlier state. Creating more instances from the same input does not establish that the source problem is resolved.

Read these observations separately.

• Original/replacement VMs: retain separate instance records.
• Images: compare exact generation and provenance separately.
• Repetition: record as an observation without claiming a confirmed cause.

Check and action sequence:

1. Stop repeated creation/customer data input and retain minimal image/creation/identity observations for both VMs.
2. Have the supplier owner verify the source image/procedure and identify an exact supported replacement.
3. After replacement recheck new image provenance, installation identity and readiness.

Condition for resuming: Close only with verified replacement provenance distinguished from the problematic input, unique identity and a resumption decision.

If still unresolved: Preserve original evidence; do not modify or reseal the original/Golden image yourself.

Fill the case-specific support record

Official image/instance provenance, creation time, displayed identity type, expected-identity match and hold/handover state.

Keep original status separate from interpretation and include a timezone. This is a record worksheet, not a product API request or execution receipt.

case: J-[1/2/3]
release / component / OS: [actual values]
observed_at: [actual time and timezone]
last_confirmed_stage: [actual observation]
first_refusal: [minimal original message, no secrets]
changed_item: [actual change or none]
recheck_result: [observed / refused / not run]
next_owner: [authorized role]

Exclude full logs, customer data, keys, tokens and passkey responses from ordinary tickets. Retain originals after handover. Changes to authority, identity or deployment scope follow the appropriate owner’s supported procedure.

Back to installation and first-use guide

Operational goal and prerequisites

A customer deploys the supplied appliance image as a new VM, then enrolls a local Appliance Administrator for its newly generated installation identity. Before deployment, have the component list, signature verification procedure, supported-environment list, and your organization's deployment approval ready.

Example conversation

The installer asks, “The VM says Running. Can I connect the GUI now?” The administrator responds, “First boot and product service readiness are separate checks. We also need to confirm a fresh installation identity.” That distinction is the first gate.

Sequence and records to retain

1. Stop before installation if signature or digest differs. Do not rename a file to hide the mismatch.
2. If the VM runs but service readiness is absent, follow the first-boot case.
3. For a host-identity warning, use the host-identity case. Do not update trust first.
4. Do not substitute a non-interactive script for administrator confirmation. Classify a refusal using the interactive enrollment case.
5. Read back role, scope, and validity period after enrollment. OS login and product administrator authority are separate.

Success and failure boundary

This use case proves only exact signed files, fresh installation identity, ready service, and recorded scope from the real administrator. Runtime binding and Work receipt require later checks. For another customer's identity, earlier-user residue, or an integrity warning, stop use and follow the image-residue case.

Detailed scenario: VM power and product readiness differ

Suppose the installer creates a VM at 09:00. The cloud console shows running at 09:02, but the product wizard has no ready result. Record VM creation time, image ID, and last product-status time separately. GUI authentication errors while initialization continues do not necessarily prove a failed first boot. Perform the release-defined wait and status check once; if readiness remains unproven, follow Case A.

The deployment operator and authority owner may be different people. The operator hands over installation ID and image provenance; the owner reviews the customer, installation, and runtime scope in the product. Close this stage only when the read-only result shows the scope and expiry.

Example handover record

Bracketed values are placeholders, not invented release data. A different customer or previous installation value stops handover.

A concrete operational walkthrough

The VM creator and product administrator may be different owners. Online installation obtains files through an approved portal or delivery route. Closed-network installation prepares the matching image, clients, needed models, digests and documentation before transfer. Both environments confirm actual identity and administrator scope in the installed product.

Records to reconcile before closing this use case

Before handover retain readiness, administrator role/scope/expiry tied to one installation ID and the next client owner. Hand over incomplete enrollment explicitly; do not mark runtime or Work complete.

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

Operational goal and prerequisites

Within the already approved installation and runtime scope, a local model alias or observed runtime value changes. Core validates the fresh observation and updates the binding. First capture the current installation identity, administrator scope, supported model, and prior binding state.

Example situation

An operator changes a local model alias. The model server runs, but PackrGUI still shows the prior binding time. “The model responds” does not prove that the new model is bound.

Before and after

Work through the change

1. Record the change and time. Do not delete the old binding or edit internal product storage.
2. Use the release wizard's discovery or re-observation route to confirm the new runtime is found.
3. Check the approved customer, installation, and runtime scope. For an out-of-scope change, request an administrator decision rather than expecting automatic application.
4. Read detected → validated → bound and any refusal reason in order. Do not guess among ambiguous model candidates.
5. Confirm the new binding's model reference, installation ID, and time follow the change. Only then record rebinding.
6. Run and validate actual Work and its receipt separately. See the missing-receipt case.

Failure branches and support evidence

If nothing is detected, inspect runtime startup and the official connection route. If validation is refused, use the binding case to separate scope, identity, and ambiguity. In support requests, send before/after state and time, installation ID, and product refusal; omit internal storage and customer prompts.

Completion condition

A fresh observation and new Core binding for this change must be recorded under the same installation identity. This does not establish a Work result or macOS and Windows auto-binding validation.

Detailed scenario: only the model alias changed

Assume a local alias changes from model-A to model-B at 10:00. A bound record at 09:40 belongs to the earlier state. Compare the change time with a later discovery time, then confirm Core validated the new model reference under the same installation ID and approved scope. If multiple candidates become visible, do not silently choose one.

If no new binding appears, classify the stage: no detection suggests runtime readiness or connection checks; an out-of-scope observation goes to the approval owner; an ambiguous target needs an explicit model choice. A screen that merely repeats an earlier timestamp does not establish a new binding.

Example change record

Times and model names illustrate the procedure, not actual release evidence. Verify subsequent Work through its own record.

A concrete operational walkthrough

During a maintenance window, change one supported model alias or runtime address at a time. Retain supported versions, the binding reference and last state before the change; then compare the fresh observation with the intended value. A successful online check or process restart alone does not establish a new binding.

Records to reconcile before closing this use case

Separate before/after runtime/model references, observation times, validation reason, effective binding and any separately authorized Work. A rollback also requires a newly observed/validated result.

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

First connection exercise: separate general users from VM administrators

Goal: connect your client to an already prepared company VM and confirm matching customer/installation identity. This exercise does not automatically execute Work. If no company VM exists, the deployment owner follows installation sections 1–4; general users receive the installation identity, readiness and connection material.

1. Material to obtain from the administrator

Obtain the actual compatible client file, digest/signature status, customer/installation/release references, endpoint and TLS server name, account/device enrollment method, allowed role and enrollment expiry/renewal support route. Receive any per-device profile through the organization's secure channel. Do not paste private keys into documentation or place them in a common installer ZIP. Use automatic enrollment portals only when the release actually provides one.

2. OS-specific preparation and launch location

If the app cannot open, record an application launch problem, before server connection. Check the exact OS warning, app path/version/CPU and included files. Disabling OS protections or running as administrator is not a general remedy.

3. Connect, enroll and confirm identity

1. Open the app and use the release's connection/profile procedure. Compare the supplied endpoint, TLS server name and profile; do not guess a new server.
2. Complete the release's supported user/device enrollment. OS login, browser return or selecting a profile does not establish completed enrollment. Report expired or unregistered state to the administrator.
3. Compare displayed customer/installation/release identity with the administrator's expected values. Record authentication and server readiness separately. Stop if another organization/installation appears.
4. Begin with a status query. If no permitted Work is available, ask the administrator to check the current role/entitlement. General users do not need VM administrator login.
5. Only users who need headless operation separately query authentication through that release's CLI/service profile. Do not copy GUI credentials arbitrarily or mark headless complete from GUI success.

Expected result: record the launched client's version/path, matching customer/installation reference and actual authentication state. If user enrollment or operational connection is not yet validated for that candidate, retain it as unconfirmed; do not fill in an assumed successful screen.

If blocked: launch problem → package/OS preparation; timeout/authentication → case C; changed identity → case B; admin enrollment → D/E. Follow the separate first Work use case for actual execution.

Operational goal

A customer connects from a workstation GUI and, if operational automation is required, checks the release-provided headless route separately. Even against the same appliance, the routes can differ in installer, authentication, session, allowed functions, and result evidence.

Example situation

An operator sees the status screen in PackrGUI on a Mac. The team says, “Then headless Work on our Linux server is ready too.” That conclusion is unverified. Each client must directly prove authentication, installation identity, and permitted function.

Route-specific checklist

Carry out the checks

1. Compare each platform's exact installer with the release manifest. A successful Mac package does not authorize a Windows package.
2. In the GUI, separately confirm service response, completed authentication, customer and installation IDs, and current permitted functions. An open window is not authenticated status.
3. If headless is in the release, follow its own official authentication, connection, and scope procedure. Do not copy GUI credentials into it on your own.
4. Compare the installation seen by both routes, but do not assume their sessions or permissions are equivalent.
5. For actual Work, confirm final state and receipt on the route that performed it. Record each route separately.

Headless read-only check when this release supplies packrctl

After the installation operator supplies the approved local access route, use these commands if packrctl is included with your installation. Run them on the authorized appliance or managed client. They read status and health; they do not authenticate a GUI session or authorize Work.

packrctl status --json > headless-status.json
packrctl health --json > headless-health.json

Read the JSON readiness and reason fields as well as the exit status. UNKNOWN is not READY. If packrctl is absent from the exact delivery inventory, record the headless route as not supplied rather than reusing a development binary.

Failure branch

If one route fails, use the connection and auth case before copying settings from the successful one. A host-identity warning requires an immediate stop under the identity case.

Completion condition

Record each route as verified only after its installer, connection, authentication, installation ID, and intended function have been checked directly.

Check what your release supplies

For each platform, confirm the installer name, signature, supported version, and connection method in the supplied component list. After installation, record the server identity, authenticated session, and matching customer and installation IDs. If a platform installer or headless client is absent from the list, ask your supplier for the supported option before using another package.

Detailed scenario: only the GUI connects

Suppose PackrGUI on a Mac displays the expected installation ID, while a server automation client cannot connect. The GUI account, token lifetime, and network route may differ from those of the service. A GUI screenshot is not headless authentication proof. First verify that the release includes a headless client; if so, record that route's account, endpoint, and refusal separately.

Conversely, a successful headless status query does not prove that a GUI session exists or has the same authority. Record the last proven stage for each route, such as GUI: authenticated, installation matched and headless: network reachable only.

Platform validation worksheet

Write unverified until a route is exercised. Do not copy success between operating systems or clients.

A concrete operational walkthrough

Suppose the desktop GUI works while scheduled automation is refused. Compare the GUI session and automation service execution location, account, network route and installation scope separately. Use the release service-authentication procedure instead of copying GUI tokens or keys into automation.

Records to reconcile before closing this use case

Retain separate rows for GUI/headless package, version, authentication, installation ID, permitted features and status result. Record an unavailable route as unavailable; bind actual Work receipts to the route used.

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

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

Operational goal and starting conditions

A customer runs one supported Pack or release-named test operation through the governed product path and confirms final result and receipt for the same installation and Work ID. Service readiness, authenticated connection, administrator scope, and current runtime binding must be checked first.

Example situation

An operator reports, “Qwen is bound, so the first Work is complete.” The reviewer asks, “Are the Work ID, execution approval, model call, result validation, and receipt tied to the same operation?” If no Work was submitted, the supported state is only runtime readiness.

Stage-by-stage questions

Carry out one operation

1. Select one approved target and review plan and environment. Do not treat a Builder candidate as an approved Pack.
2. Complete the customer's permitted user approval route. Passkey enrollment, browser return, and actual Work approval are separate.
3. After submission, capture the product-recorded Work ID and read approval, start, and execution state for that ID in order.
4. For local AI, confirm a model call linked to this Work, not just a generally responsive model.
5. Bind result validation, failure or rollback status, and final receipt to the same release, installation, and Work ID. Never rewrite failure, stop, or rollback as success.
6. If the receipt is missing, start from the last confirmed step in the missing-receipt case. Do not create records manually.

Conditional CLI example for an authorized installation

If your release supplies packrctl and lists CREATE_AUDIT_ARTIFACT as a supported operation, use this example only after that one Work is approved and the appliance reports the required authority and preconditions. Replace the key with an approved unused value. This operation creates a local audit artifact; it does not inspect an attached customer document or demonstrate a Qwen model call.

packrctl work run CREATE_AUDIT_ARTIFACT "create audit artifact" \
  "REPLACE_WITH_ONE_UNUSED_APPROVED_KEY" --json > work-run.json
# Copy the returned result.work.work_id; do not invent a Work ID.
packrctl work show "PASTE_RETURNED_WORK_ID" --json > work-show.json

Inspect the typed result, final state, validation, receipt reference and human-acceptance state in the returned records. A command exit code or a generated JSON file alone is not a success receipt. Do not reissue work run after an uncertain result; reconcile the original request through the product's supported route.

Support request and completion

For support, provide release, installation and Work IDs, shareable Pack or operation name, last confirmed stage, first error, and receipt status. Do not attach prompts, customer data, or raw results to an ordinary ticket. Complete: successful final state, validated result, and receipt for the same authorized Work are confirmed together.

Detailed scenario: model responds, but no Work receipt exists

Suppose an operator sees a local model respond and reports first Work complete. First check for a Work ID. Without it, even product receipt of a Work request is unproven. With an ID, read approval, start, model call, result validation, and final state separately. A general model response cannot substitute for a call bound to this Work.

For example, after changing a local model alias, the GUI may show a new BOUND state while Work readiness remains UNKNOWN. Record the authority, runtime, and Work readiness shown by your installation and any exact reason code. Do not submit Work until the required state is ready; send those values through the release support route if readiness remains unknown. Use the worksheet below for your own first Work.

One-Work evidence worksheet

Do not treat a failed, stopped, or rolled-back result as successful merely because a record file exists. Report the first missing gate; exclude raw prompts and output from ordinary support requests.

A concrete operational walkthrough

Plan one approved read operation. Immediately before execution check installation, Pack, input, current authority and plan; retain the actual returned Work ID. If a connection issue delays the result, query that same ID instead of starting duplicate Work to obtain a response.

Records to reconcile before closing this use case

Check that terminal state, postcondition validation, result digest, Work record and receipt refer to one execution. Record failure, rollback, waiting and unconfirmed states separately; a standalone model response does not replace the product receipt.

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

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

First observation exercise: prepare, run and open results

Inspect what you received first. If you received only an approved snapshot and viewer, open the supplied HTML viewer in a browser, read snapshot ID/source revision/disclosure class and select one node. You do not need new source or a new manifest. An owner with an executable and approved manifest can run the local exercise below. A source Document or SDK input.json is not a GAPE manifest.

Select the executable and a fresh output path

Replace gape_exe/$gapeExe and gape_manifest/$gapeManifest with the actual executable and approved manifest's absolute paths. The manifest's source paths and revision must exist too. Prepare only the output parent, leaving gape-observation-01 absent. Do not expand the source scope by guessing paths.

gape_exe="/absolute/path/packr-gape"
gape_manifest="/absolute/path/approved-manifest.json"
gape_output="$HOME/gape-observation-01"
test -f "$gape_exe" && test -f "$gape_manifest" || exit 1
test ! -e "$gape_output" || exit 1
"$gape_exe" snapshot "$gape_manifest" "$gape_output" || exit 1
"$gape_exe" validate-snapshot "$gape_output/gape-architecture-snapshot.json" || exit 1
ls -la "$gape_output"

$gapeExe = 'C:\absolute\path\packr-gape.exe'
$gapeManifest = 'C:\absolute\path\approved-manifest.json'
$gapeOutput = Join-Path $env:USERPROFILE 'gape-observation-01'
if (!(Test-Path -LiteralPath $gapeExe -PathType Leaf) -or !(Test-Path -LiteralPath $gapeManifest -PathType Leaf)) { throw 'Executable or approved manifest missing' }
if (Test-Path -LiteralPath $gapeOutput) { throw 'Choose a fresh output path' }
& $gapeExe snapshot $gapeManifest $gapeOutput
if ($LASTEXITCODE -ne 0) { throw 'Snapshot failed' }
& $gapeExe validate-snapshot (Join-Path $gapeOutput 'gape-architecture-snapshot.json')
if ($LASTEXITCODE -ne 0) { throw 'Snapshot validation failed' }
Get-ChildItem -LiteralPath $gapeOutput

What to read: snapshot stdout contains snapshot ID, node/edge/finding counts and execution_authority: NONE. Do not assume zero findings. Preserve validation and actual generated files. Open the included viewer if supplied; otherwise read snapshot JSON in an editor. Do not guess an HTML filename.

Short exercise: record one node's name, source revision, relationship and observation limits. To compare snapshots preserve both originals and check whether the release supports compare before.json after.json. Do not infer behavior outside observation. Keep engineering snapshots internal and use an approved PUBLIC_SAFE projection for external sharing.

If blocked: missing executable → installation preparation; missing source path/revision → approved-input preparation; failed snapshot validation → observation validation. Continue with GAPE-1/2 below; do not invent a manifest to expand scope.

When to use it

Use GAPE when an integration owner needs to understand which component and interface a proposed operation depends on. Check that the exact release provides the GAPE tool and an approved input manifest. A general source folder, screenshot, or architecture infographic is not a manifest.

Prepare the observation

1. Record the approved source revision, folders to inspect, exclusions, expected rules, and sharing level. GAPE observes the selected saved revision; unsaved edits and live runtime behavior may be outside that result.
2. If your component list includes packr-gape and an approved manifest, run packr-gape snapshot manifest.json new-output-folder with a new output folder. Otherwise ask for the supported observation procedure.
3. Validate the generated snapshot with packr-gape validate-snapshot gape-architecture-snapshot.json when that command is supplied. Validation checks the snapshot's structure and provenance, not actual runtime behavior.
4. Open the approved offline viewer. Start with one node and relationship, note its source revision and observation limitation, then compare it with the independent expected Contract or owner rule. Keep UNRESOLVED or STALE as findings; do not promote them to consistent by editing the viewer.
5. Share only the PUBLIC_SAFE projection where allowed. Keep engineering input, internal paths, source ranges, and finding explanations inside the approved engineering environment.

Command example for a release that actually supplies GAPE

Use the commands below only when your installation includes packr-gape and an approved manifest for a source tree you are allowed to inspect. The output directory must be new. validate-snapshot checks the snapshot, not the running appliance.

packr-gape snapshot approved-manifest.json new-observation-folder
packr-gape validate-snapshot new-observation-folder/gape-architecture-snapshot.json

Use the filename actually emitted by your release if it differs from this example; record the manifest digest, source revisions, snapshot ID, validation result, and execution_authority: NONE. If the binary or approved manifest is absent, stop this path and record not supplied for this release.

Worked example: a diagram appears to prove an adapter

An operator sees a relationship between PackrGUI and an integration adapter in a GAPE snapshot. The relationship is STATIC_SOURCE; the current customer runtime may use another feature configuration, and a dynamic call may be outside the saved source observation. Record the exact source version shown in the snapshot and ask the integration owner for the supplied Contract and connection evidence. Do not write “connected” or “authorized” in a deployment record.

Worked example: observation and expectation disagree

The snapshot contains an interface association but the expected owner rule is missing or bound to a different revision. GAPE reports UNRESOLVED or STALE. Preserve the manifest identity, snapshot digest, finding, and exact revision. The responsible owner reconciles the Contract and source separately; refreshing a graphic is not a repair.

Completion evidence

The observation is complete when the manifest, snapshot validation result, selected projection, revision, disclosure class, limitations, and any unresolved findings are recorded. Integration registration or Work remains a separate path. Continue with Integration Helper or the Contract & Document guide.

A practical operational use case

Before a new integration, an owner may need to understand which components handle data. Pin the stored revision in the approved manifest and trace one node and its relations. Record provenance and unobserved dynamic paths; when comparing another document, retain both revisions. The diagram alone does not establish a runtime incident cause.

Symptom-specific checks and return to operation

Minimum handover to the next owner

Handover: source revision, manifest and snapshot digests, observation scope, disclosure class, selected nodes/relations, unresolved items and next owner. Keep snapshot validation separate from runtime evidence.

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 GAPE-1: Reviewing an old snapshot after source changes

Situation: A diagram reported as inconsistent belongs to an earlier stored revision. First distinguish current source, approved manifest and observation revisions.

Read these observations separately.

• Diagram: has a specific snapshot ID/source revision.
• Current source: unsaved changes may be outside observation.
• Validation: snapshot structure checks are not runtime validation.

Check and action sequence:

1. Compare manifest digest, snapshot creation time and exact stored revision.
2. For a new observation, use approved inputs/supplied commands and fresh output.
3. Retain both observations and identify changed relations/limits.

Condition for resuming: Continue scoped observation review when the intended revision matches a validated snapshot.

If still unresolved: With an unconfirmed manifest/revision, retain unconfirmed observation rather than editing the diagram to match.

Worked scenario GAPE-2: A node is hidden by filters or outside observation scope

Situation: A search finds no component and a user assumes absence. Filters, manifest exclusions and supported language can limit visibility/observation.

Read these observations separately.

• No search result: an outcome for the selected view scope.
• Manifest: defines observed folders and exclusions.
• Implementation absence: not established by this view alone.

Check and action sequence:

1. Check search/filter settings and the original observation’s scope/revision/exclusions.
2. Request an authorized observation for another scope; do not add private data to a public view.
3. Distinguish out-of-scope, view filtering and unconfirmed state, then hand source questions to the owner.

Condition for resuming: Cite only relations confirmed for that revision/scope.

If still unresolved: Do not label it unimplemented/absent without source support.

Post-install tools

First preparation exercise: inspect one complete request step by step

Required: a compatible Helper executable, complete request.json and supplier-published target references. SDK and Helper are separate executables. An SDK JSON excerpt is not a complete request. Before reusing a full SDK example, verify that the Helper release supports the same target and envelope.

1. Preserve the supplied request and make a working copy. Confirm complete request_id, correlation_id, draft and its definition/source/mapping/fixture. Do not add real API tokens.
2. Replace the executable/request paths below with actual absolute paths. helper-first-01 is a fresh log directory. Run only the first command, then inspect its result.
3. Read stdout's status, reason, lifecycle_stage, next_required_actions and candidate digest. Do not expect a singular next_action field. This CLI can return exit code 0 while printing a typed refusal, so exit code/`$LASTEXITCODE` alone is not permission to proceed.
4. Only after successful discovery, run normalize → validate → prepare → status from the existing section, one step at a time against the same request copy. Do not feed the preceding result JSON into the next command; each command takes the full request.
5. Preserve DENIED, implementation-needed, authority-needed or unknown states and read the next actions. r2-submit is unnecessary for the first exercise. Use a new request copy and log folder when modifying inputs.

helper_exe="/absolute/path/packr-integration-helper"
helper_request="/absolute/path/request.json"
helper_logs="$HOME/helper-first-01"
test -f "$helper_exe" && test -f "$helper_request" || exit 1
test ! -e "$helper_logs" || exit 1
mkdir "$helper_logs" || exit 1
"$helper_exe" r2-discover "$helper_request" > "$helper_logs/01-discover.json" 2> "$helper_logs/01-discover.stderr.txt"
helper_exit=$?
cat "$helper_logs/01-discover.json"
cat "$helper_logs/01-discover.stderr.txt"
# Record helper_exit separately from JSON status/reason.

$helperExe = 'C:\absolute\path\packr-integration-helper.exe'
$helperRequest = 'C:\absolute\path\request.json'
$helperLogs = Join-Path $env:USERPROFILE 'helper-first-01'
if (Test-Path -LiteralPath $helperLogs) { throw 'Choose a fresh log folder' }
New-Item -ItemType Directory -Path $helperLogs -ErrorAction Stop | Out-Null
& $helperExe r2-discover $helperRequest 2> (Join-Path $helperLogs '01-discover.stderr.txt') | Out-File -LiteralPath (Join-Path $helperLogs '01-discover.json') -Encoding utf8
$helperExit = $LASTEXITCODE
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.json') -Raw -Encoding UTF8
Get-Content -LiteralPath (Join-Path $helperLogs '01-discover.stderr.txt')

These are logs, not replacement input requests. Save subsequent outputs separately as 02-normalize, 03-validate, 04-prepare and 05-status. Expected exercise outputs are stage decisions and candidate preparation records, not live API connection, registration or Work. When a published target is missing, use TARGET_NOT_PROVIDED as your progress note and keep it separate from the product's actual reason. See IH-1/2 for refusals and handover.

Inputs and ownership

Prepare a candidate

1. Start with a read-only operation in a supported source format. For example, describe status.read with a service string input and service/healthy output. Do not paste a live token or customer response into the document.
2. Obtain the supplier-published target Contract and adapter revisions. If they are missing, record TARGET_NOT_PROVIDED; a display name that looks similar is not a valid match.
3. Use a complete request file supplied for your release. If the included Helper offers r2-discover, r2-normalize, r2-validate, r2-prepare, and r2-status, run those stages in that order with request.json. Preserve each status, reason, stage, and next action.
4. Correct only the field or mapping rejected by the actual result. The bounded example format supports primitive fields and explicit mappings; an unsupported transform or required unmapped field remains denied. A scaffold marked REQUIRES_IMPLEMENTATION still needs an adapter implementation.
5. Use r2-submit only in the release's authorized submission route. The CLI returns REQUIRES_AUTHORITY without trusted registration transport. Canonical registration requires a separate sealed active approval for the exact candidate and purpose. Registration still does not bind or authorize Work.

Reproducible local preparation example

If your component list includes the Helper executable and a matching complete request.json, run one stage at a time. Preserve each JSON result and read status, reason, stage, and next action before continuing; a shell exit alone is insufficient. The request needs a supported target reference from your release, not the illustrative status.read description above.

packr-integration-helper r2-discover request.json > 01-discover.json
packr-integration-helper r2-normalize request.json > 02-normalize.json
packr-integration-helper r2-validate request.json > 03-validate.json
packr-integration-helper r2-prepare request.json > 04-prepare.json
packr-integration-helper r2-status request.json > 05-status.json

Decision example: discovery can report status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED while normalization reports DENIED / CONTRACT_INCOMPATIBLE. Keep both files; stop before prepare and obtain the correct published target. Do not run all five commands blindly when an earlier typed result refuses progression.

Worked example: source accepted, target rejected

r2-discover reports status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED for a synthetic status.read document. r2-normalize then reports DENIED / CONTRACT_INCOMPATIBLE because no published target was bound. The source document is structurally accepted; the integration is not ready. Ask the supplier or integration owner for the exact target reference. Do not invent a Contract ID or change the display name until it matches by coincidence.

Worked example: candidate submitted, no registration

The validated candidate produces REQUIRES_AUTHORITY at submission. Record the candidate digest and approval purpose requested. The authorized owner must evaluate that exact candidate through the native registration path. Repeating the CLI call or adding a flag cannot turn a preparation status into registration.

Completion evidence

Preparation requires the input and target revisions, request identity, each typed result, candidate digest, unresolved gap, and next owner. A live provider connection, registration, binding, authorized Work, and receipt require separate evidence. For the source declaration, continue with Contract & Document.

A practical operational use case

For example, connect a service-status source Document to published target references. Prepare with synthetic data and inspect status, reason and next action at each stage. A normalization refusal stops progression to prepare/submit. If inputs change, record the new request revision/digest and distinguish the old refusal from the new result.

Symptom-specific checks and return to operation

Minimum handover to the next owner

Handover: full request digest, source/target revisions, request/correlation IDs, typed stage results, candidate digest, scaffold implementation needs, submission/registration state and next owner. Keep live API connection tests separate from preparation results.

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 IH-1: Discovery passes but target normalization is refused

Situation: Synthetic source read_quality is discovered, but the full request references another Contract/adapter revision. Running straight through preparation would hide the first refusal.

Read these observations separately.

• Discovery: status=PASSED, reason=NONE, lifecycle_stage=DISCOVERED concerns source discovery.
• Normalization: DENIED / CONTRACT_INCOMPATIBLE concerns target compatibility.
• Preparation: not completed yet.

Check and action sequence:

1. Retain normalization status/reason/next action and stop prepare/submit.
2. Compare the full request with exact published targets; do not choose a merely similar label.
3. After obtaining supported references, retain changed request revision/digest and validate from the affected stage.

Condition for resuming: Check preparation only after that request passes normalization/semantic validation.

If still unresolved: Without a published target, hand over unavailable-target state instead of inventing IDs/digests.

Worked scenario IH-2: Preparation artifacts exist but submission requires authority

Situation: Preparation artifacts exist, but CLI submission returns REQUIRES_AUTHORITY. Copying local candidate files into server registration locations is not a remedy.

Read these observations separately.

• prepare: a candidate-preparation result.
• submit: requires a trusted registration route and exact authority purpose.
• Work: registration, binding and execution remain separate.

Check and action sequence:

1. Retain candidate digest, submission result and request/correlation IDs.
2. Check whether the release supplies an actual registration transport and owner.
3. Hand over to the approved registration procedure for that candidate/purpose/customer/installation.

Condition for resuming: Record registration only from the actual registration result; confirm Work separately.

If still unresolved: Do not turn preparation into registration through repeated CLI submission or copied credentials.

Post-install tools

First Document exercise: save a file and hand it to Helper

Goal: save the complete source Document below as quality-document.json and check syntax. This file contains a source declaration only; it is not a complete SDK/Helper request or GAPE manifest.

1. Create an organization-approved fresh working folder and open a text editor. Copy only the JSON block from its opening { through the final }. Do not include code fences or the json label.
2. Save as quality-document.json, UTF-8. Use plain text rather than a Word/formatted document; check for an accidental .json.txt suffix. Reopen the saved file and confirm operations.read_quality exists.
3. Use the command below when Python 3 is already available on macOS/Linux. Windows can use PowerShell's built-in JSON parser; this exercise does not require installing Python.
4. After parsing, compare resource/component/score in properties with their required lists. This review and JSON parsing do not replace product semantic validation.
5. Preserve an original copy, then place the object into draft.source of the supplier's complete request. Do not insert a file-path string or double-encoded JSON string. Check target references, mapping and fixture separately in the supplied request, then follow Helper's first exercise.

document_path="/absolute/path/quality-document.json"
python3 -m json.tool "$document_path"

$documentPath = 'C:\absolute\path\quality-document.json'
Get-Content -LiteralPath $documentPath -Raw -Encoding UTF8 -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop | Format-List
Get-FileHash -LiteralPath $documentPath -Algorithm SHA256

Expected result: the parser displays an object without a parsing error. On syntax errors inspect the reported line/column, commas, quotes and braces. This parser does not adjudicate every duplicate key or unsupported product schema. Record syntax checked / Helper semantic validation not executed, and add actual Helper results separately.

Small edit exercise: renaming an input requires reviewing properties, required, explicit request mappings and the supported target together. Check the supplied original once before editing. DOC-1/2 cover name mismatch and incomplete requests.

Decide which artifact you are editing

Build a bounded source Document

1. Write a short goal and the operation's data boundary. Example: read_quality accepts a resource name and returns a component name and quality score as strings. It does not change the resource.
2. In the supported CUSTOM_API format, set document_kind to CUSTOM_API, use the supported protocol_revision value, and place read_quality under operations. Declare input_schema as an object with a required resource string. Declare output_schema as an object with required component and score strings. Copy the complete example below for punctuation and nesting; these inline field names are an explanation, not a full JSON file.
3. Keep property names and required lists consistent. The bounded example accepts only supported primitive fields; nested objects, arrays, extra JSON Schema keywords, duplicate keys, and comments are not silently accepted. Never put a credential or sample production response into schema defaults or descriptions.
4. Check JSON syntax on a local copy, for example with python3 -m json.tool quality-document.json. A syntax PASS proves only that JSON parsed. Preserve the original document and its digest when making a correction.
5. Obtain the exact published capability, Contract, adapter, operation and revision identifiers. Put those references in the release-defined request envelope, not inside the standalone source Document. Then follow the Integration Helper preparation path.

Complete source Document example

The CUSTOM_API example below declares a read-only read_quality operation. It does not call a live API or create a product Contract. Save the JSON as quality-document.json; put it under draft.source in the complete request supplied for your release and provide a compatible supported target reference.

{
  "document_kind": "CUSTOM_API",
  "protocol_revision": "1",
  "operations": {
    "read_quality": {
      "input_schema": {
        "type": "object",
        "properties": {"resource": {"type": "string"}},
        "required": ["resource"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "component": {"type": "string"},
          "score": {"type": "string"}
        },
        "required": ["component", "score"]
      }
    }
  }
}

python3 -m json.tool quality-document.json > /dev/null
sha256sum quality-document.json

The first command proves JSON syntax only. Use shasum -a 256 quality-document.json on macOS or Get-FileHash -Algorithm SHA256 quality-document.json in PowerShell. The Helper's typed validation still decides whether the full envelope, target and mapping are acceptable.

Worked example: valid JSON, wrong target revision

The source document parses and discovery accepts read_quality. The request references an adapter revision from a different release. Normalization refuses the target. Compare the release manifest and supplier reference; correct the target revision in a new request only if an approved compatible value exists. Changing the source operation name to force a match would conceal the actual mismatch.

Worked example: a field is renamed without updating required

An editor changes the input property from resource to resource_name but leaves required: ["resource"]. The document is syntactically valid JSON but semantically inconsistent. Restore the property or update the required list, then re-run the exact local parser and Helper validation. Do not treat a successful syntax check as Contract validation.

Completion evidence

Keep the source Document revision and digest, exact published target references, request identity, typed Helper result, and remaining approval owner. Do not call the declaration “connected” until actual authenticated registration and runtime evidence exists; do not call it “executed” without Work and receipt.

A practical operational use case

Suppose a read-only quality query needs one additional output field. Separate the human goal, source schema, target reference and full request envelope. Review output properties, required fields, synthetic response and explicit mapping together. Retain unsupported schema extensions as implementation requirements; a customer document does not replace a product-issued Contract.

Symptom-specific checks and return to operation

Minimum handover to the next owner

Handover: source Document revision/digest, envelope revision, published Contract/adapter references, mappings, synthetic inputs/expected outputs, parsing/semantic results and change reason. Distinguish an unfilled template from a complete executable request.

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 DOC-1: A property is renamed while required stays unchanged

Situation: The input property resource is renamed resource_name, but required still lists resource. JSON parsing can succeed while the declaration is semantically inconsistent.

Read these observations separately.

• Syntax: JSON parsing succeeds.
• Declaration: properties and required name different fields.
• Target/mapping: source-change effects need separate checking.

Check and action sequence:

1. Retain the complete Document and original revision/digest.
2. Establish the intended field and align property/required/explicit mapping within supported coverage.
3. Perform and distinguish local JSON parsing and Helper semantic validation.

Condition for resuming: Use the changed request for preparation only after both parsing and semantic validation are confirmed.

If still unresolved: Retain unsupported schema extensions as implementation requirements instead of silently accepting them.

Worked scenario DOC-2: A source Document excerpt is used as a full request

Situation: A user saves a short CUSTOM_API example and sends it to Helper/SDK. The source description may be valid, but it is not the complete envelope containing request identity, targets, mappings and fixture.

Read these observations separately.

• Source Document: input for draft.source.
• Full request: needs request_id/correlation_id/draft and supported references.
• Excerpt: explains fields; it is not a complete executable input.

Check and action sequence:

1. Obtain the supplied version-matched full request template and retain its original.
2. Populate source/target/mapping/fixture in their defined locations without secrets or live customer responses.
3. After parsing, use product analyze or Helper stage decisions for semantic checks.

Condition for resuming: Proceed to preparation only with a complete request and published target validated within supported coverage.

If still unresolved: Do not guess explanatory values as real target identifiers when required references are unavailable.

Post-install tools