Enterprise-agent Skills · detailed reference

# Local agent connection: administrator setup and recovery

Ordinary workers give the AI agent a goal and approved inputs. The administrator
or setup agent connects the release to the organization's runtime once, using
that runtime's supported skill and MCP import mechanisms. Workers do not edit
this kit or connection files. A runtime without MCP can use the supplied public
CLIs through its permitted tool interface and the corresponding Skills.

## What is supplied

`packr-agent-mcp` (`packr-agent-mcp.exe` on Windows) is a local stdio adapter.
It exchanges one UTF-8 JSON-RPC message per line, up to 1 MiB. It opens no HTTP
listener and starts no external executable. Keep its protocol stdout separate
from stderr. Supported MCP protocol versions are 2024-11-05, 2025-03-26 and
2025-06-18. This does not require a particular model provider.

The release catalog binds the adapter's exact bytes, OS/CPU and supported tools.
Use the catalog and digest supplied for the same package; do not copy a catalog
from another OS or generate a new one merely to bypass a mismatch. An adapter
update requires a matching catalog and a fresh reviewed registration.

| Available tool | Request fields | Result/use |
|---|---|---|
| `vibepackr.setup.status` | `{}` | Local adapter setup state; separate from appliance readiness |
| `vibepackr.headless.health` | `{}` | Native health query through the configured local control-plane socket |
| `vibepackr.headless.status` | `{}` | Native status query |
| `vibepackr.headless.work_list` | `limit` (1–100) | Read existing Work references |
| `vibepackr.headless.work_show` | `work_reference` | Read the original Work's minimized state |
| `vibepackr.gape.validate_snapshot` | `input_id` | Validate a registered snapshot against its approved source scope |
| `vibepackr.gape.compare` | `before_input_id`, `after_input_id` | Compare two registered snapshots |
| `vibepackr.sdk.analyze` | `input_id` | Analyze a supported full integration request |
| `vibepackr.integration_helper.discover` | `input_id` | Discover the request's supported integration shape |
| `vibepackr.integration_helper.normalize` | `input_id` | Normalize the declared request |
| `vibepackr.integration_helper.validate` | `input_id` | Validate declarations |
| `vibepackr.integration_helper.prepare` | `input_id` | Prepare a local integration candidate |
| `vibepackr.integration_helper.status` | `input_id` | Read its native preparation status |

These MCP tools do not install an appliance, bind a runtime, submit Work, generate
an SDK adapter or drive Builder. Use the release-supplied public CLI/GUI and its
Skill for those tasks when authorized. A Helper candidate does not grant execution
authority. GAPE snapshot creation uses the supplied GAPE CLI; subsequent validation
and comparison can use MCP. Reobserve changed architecture when adding a legacy
system or runtime to an installation already in use.

## Administrator/setup-agent steps

1. Extract the matching OS package and verify its supplied checksums. Keep the
   adapter, release catalog and public call schema together. Check the actual
   binary with `packr-agent-mcp --version`; this alone is not a connection test.
2. Prepare a private workspace and a new private setup request. Use the OS's
   owner-only access mechanism: on Unix, directories 0700 and files 0600; on
   Windows, the current user's private access rules. Do not loosen permissions
   to satisfy a check. Existing workspace files and results are preserved.
3. The setup request uses schema `packr.agent-mcp.setup-request.v1`, a **fresh**
   absolute `output_directory`, runtime profile `GENERIC_STDIO_DESCRIPTOR`, and
   a registration object. The registration contains:
   - `schema_version`: `packr.agent-mcp.registration.v1`;
   - `catalog_path` and the package's `expected_release_catalog_digest`;
   - a stable `workspace_id` and absolute private `workspace_root`;
   - `inputs`, mapping each permitted input ID to its relative file path,
     exact SHA-256, `maximum_bytes` (up to 1048576) and format
     `HELPER_REQUEST_V2` or `GAPE_SNAPSHOT_R1`;
   - `control_plane_socket`: the administrator-approved local socket, or
     `null` when only local preparation is required;
   - `approved_gape_repositories`: the explicit permitted source roots for
     snapshot validation, or an empty list when that operation is not needed.
4. Run the supplied binary's `register` command with that private setup request.
   For example, from the directory containing the actual release executable:

   ```sh
   ./packr-agent-mcp register /absolute/private/setup-request.json
   ```

   On Windows use the equivalent `packr-agent-mcp.exe register` invocation with
   the actual private Windows path. The setup agent supplies real values; the
   example path is not an installation default. Registration writes only its
   fresh output directory and private local workspace records.
5. Retain `registration.json`, `mcp-server.json` and `SETUP_RECEIPT.json` inside
   the private setup output. The descriptor contains a command, arguments and
   an empty environment object. Import it through the runtime's documented MCP
   configuration mechanism. It is not a universal host-settings file and does
   not overwrite the host's settings. Import the relevant `skills/` folders
   separately using its supported mechanism, or explicitly attach their Markdown.
6. Verify a **live** initialize/initialized exchange and `tools/list`, then call
   `vibepackr.setup.status`. Confirm the expected release and 13 tool IDs.
   Record which Skills the runtime actually read. A descriptor or copied Skill
   file alone proves neither loading nor a successful connection.
7. For appliance queries, verify the configured installation and permitted local
   connection with native health/status. An unconfigured socket can be valid for
   an analysis-only workspace, but it does not establish appliance binding.

Do not put credentials, customer prompts, endpoints or raw logs into MCP tool
arguments. Input IDs refer only to administrator-registered local files. Each
changed input or expanded source scope needs a new reviewed registration and
fresh setup output; retain the previous one and its operation records.

## Example call and result

After initialization, call the SDK analyzer with an input ID that was actually
registered. Replace the catalog digest with the exact supplied 64-character value:

```json
{
  "schema_version": "packr.agent-mcp.call.v1",
  "operation_ref": "sdk:analysis-001",
  "expected_release_catalog_digest": "<package catalog digest>",
  "workspace_id": "integration-lab",
  "request": {"input_id": "supported-synthetic-request"}
}
```

The example's placeholder digest is intentionally not executable. The host passes
these arguments to `vibepackr.sdk.analyze`; it must not add a source path, command,
environment variable or network address to the request. The response preserves
`transport_status`, `product_result` and `reconciliation` separately. A valid
synthetic request can return payload `native_return: "Ok"`; malformed `{}` input
returns native reason `INVALID_INPUT` and payload `native_return: "Err"`. Record
the actual result rather than converting every transport success into product PASS.

## Failure and interruption cases

| Actual observation | Concrete example | Next action |
|---|---|---|
| `CATALOG_IDENTITY_OR_ALLOWLIST_DENY` | A Windows adapter was paired with a Linux catalog, or adapter bytes changed | Preserve the mismatch; use the matching intact release. Administrator creates a fresh registration after the package identity is verified. |
| `PRIVATE_FILE_PERMISSIONS_DENY` / `WORKSPACE_PRIVATE_DIRECTORY_DENY` | A shared folder exposes registration/workspace files to other users | Administrator supplies a proper private location; retain evidence. Do not grant broader permissions or suppress checks. |
| `INPUT_NOT_REGISTERED` | The agent guessed an input ID for a new legacy request | Stop that call. Setup agent registers the approved file/digest in a fresh reviewed setup. |
| `INPUT_DIGEST_DRIFT` | The JSON was edited after registration | Preserve both versions. Validate the new input and create a fresh registration and operation reference. Do not overwrite the original operation. |
| `TOOLS_LIST_STATE_OR_PARAMS_DENY` | The host listed tools before initialization | Use the host's supported MCP handshake. Do not treat this as a product integration failure. |
| `CONTROL_PLANE_NOT_CONFIGURED` | Local SDK analysis works, but health has no configured socket | Continue authorized local preparation. Administrator supplies the actual supported local connection before appliance queries. |
| `OPERATION_IDENTITY_CONFLICT` | One operation reference was reused for another tool or changed inputs | Query/reconcile the original operation first. A distinct reviewed task gets a distinct reference. |
| `RECONCILIATION_REQUIRED_NO_REINVOKE` | The adapter reserved an operation, then the process stopped before a recorded result | Preserve the reservation. Query the original product reference when one exists; otherwise have the administrator resolve the uncertain step. Do not delete the journal or resubmit to force progress. |
| `ADAPTER_LOCAL_CACHED_RESULT_NOT_NEW_PRODUCT_EXECUTION` | Same operation and same inputs were called again | Treat the response as the retained result; it is not another execution or a current appliance health observation. Use a new reference for an intentionally new authorized observation. |
| Timeout or cancellation notification | The host disconnects while a native call is running | Reconcile the same reference after reconnect. Synchronous native calls cannot be interrupted by this adapter; a cancellation notification proves no rollback or absence of effects. |

The adapter's journal is a local transport checkpoint, not a product Work receipt.
For a Work that was executed through another supported interface, retain and
reconcile that same Work's product validation, recovery state and receipt.

# Agent operator note — not a product execution receipt

- Task and approved scope: [actual reference]
- Time and timezone: [actual observation]
- Agent/runtime and instruction file actually loaded: [actual values]
- OS/CPU, package version and SHA-256: [actual values]
- Component and executable path: [actual local value; redact before sharing]
- Input and digest: [permitted reference; omit customer contents]
- Output directory: [fresh local path]
- Connection / expected and observed installation: [actual non-secret references]
- Last proven stage: [actual observation]
- Invocation / process exit: [exact supported command, no secret arguments / code]
- Product status and reason: [unaltered returned values or not observed]
- Candidate / revision / digest: [returned values or not produced]
- Work ID: [returned ID or not submitted]
- Result validation: [actual product result or not run]
- Matching product receipt: [actual reference or not observed]
- Preserved prior result / recovery state: [actual observations]
- Expansion, if applicable: [new legacy/connector/runtime/model; exact target]
- Working baseline / existing bindings / in-flight Work: [retained references]
- GAPE before and after / revisions / common and added scope: [actual references]
- GAPE validation / comparison and Helper impact result: [actual results or missing]
- New-target and affected existing-use checks: [actual outcomes or not run]
- Activation / rollback disposition: [actual product/procedure reference or pending]
- First failure and corrective action: [minimal error / change or none]
- Remaining prerequisite and next owner: [specific item / role]

Do not convert this note into a product PASS, approval, receipt or human
acceptance. Keep secrets, raw prompts, customer content and full logs out of a
shared copy. An unchanged original request must be reconciled before any retry.

# VibePackr enterprise agent integration kit

Ordinary workers do not edit these files. An administrator or supported setup
flow connects the kit to the organization's runtime and supplied installation.

Use this kit to help your organization's AI runtime agent install, connect,
prepare integrations and operate VibePackr through the interfaces supplied in
your release. Instructions are in English. Existing Parts 1–8 remain the full
user manuals.

## 1. Load the instructions

This kit does not install itself into your agent or change your agent settings.
First extract it into a private workspace and read this file.

- If your runtime supports `SKILL.md` folders, use its documented skill import
  mechanism to import the relevant folders under `skills/`. Each folder is
  self-contained. Do not copy VibePackr's internal development skills.
- Otherwise attach or explicitly ask the agent to read the required `SKILL.md`
  files as Markdown. Use the same instructions without claiming native skill
  discovery or automatic loading.
- Confirm which skill name and file the agent actually read. File installation
  alone does not prove the runtime loaded it. Start with a read-only task, such
  as identifying the supplied package and listing missing prerequisites.
- [runtime-plan.example.toml](runtime-plan.example.toml) is a human/agent planning worksheet. It is **not**
  a product connection profile, import format, permission grant or executable
  agent configuration. An administrator or the setup agent fills permitted values
  in a private planning copy. Ordinary workers do not edit this file. Never put keys, passwords or tokens in it.

No particular AI provider, hosted model, local model, MCP host or coding agent
is required by these instructions. Native skill discovery and tool execution
depend on your runtime's actual features and your organization's policy.

For the supplied local MCP adapter, the administrator/setup agent follows
[MCP setup and recovery](MCP_SETUP.md). It generates a private connection
descriptor; ordinary workers do not edit Skills, TOML or MCP JSON. The runtime's
documented import step and a live connection check are still required. Read the
supported tool table before assuming that a CLI action also has an MCP tool.

## 2. Choose a path

Start with [the workflow coordinator](skills/vibepackr-agent-workflow/SKILL.md)
for a multi-tool task or an interrupted run. Its case reference covers
installation, binding, integration, partial effects and resumption.

For an installation already in use, start with
[post-installation expansion](skills/vibepackr-postinstall-expansion/SKILL.md).
Adding a legacy system, connector, AI runtime or model requires a new GAPE
observation of the approved changed architecture and a comparison with the
retained baseline. Runtime discovery/binding is a separate product check; GAPE
does not establish runtime readiness or access permission.

| Stage | Skill folder | Inputs | Observable result |
|---|---|---|---|
| Appliance installation | [vibepackr-install](skills/vibepackr-install/SKILL.md) | Complete approved appliance package, Linux administrator authority | Installer exit and actual health/readiness observations |
| Architecture observation | [vibepackr-gape](skills/vibepackr-gape/SKILL.md) | Approved manifest and permitted revision-bound source scope | Snapshot and snapshot-validation result |
| Preparation before declarations | [vibepackr-integration-helper](skills/vibepackr-integration-helper/SKILL.md) | Complete supported synthetic/request envelope | Discovery/normalization findings |
| Contract and Document declarations | [vibepackr-declarations](skills/vibepackr-declarations/SKILL.md) | Complete source Document, full request and published target references | Parsed draft and reviewed mapping |
| Validation after declarations | [vibepackr-integration-helper](skills/vibepackr-integration-helper/SKILL.md) | Revised full envelope | Actual validation/preparation/status responses |
| Adapter candidate, when needed | [vibepackr-sdk-engine](skills/vibepackr-sdk-engine/SKILL.md) | Supported full request, selected toolchain/dependency set | New adapter candidate and its manifest |
| Pack candidate, when needed | [vibepackr-builder](skills/vibepackr-builder/SKILL.md) | Supplied Builder, supported template/Pack, permitted role | Candidate revision and actual validation state |
| Governed operation | [vibepackr-headless](skills/vibepackr-headless/SKILL.md) or [vibepackr-packrgui](skills/vibepackr-packrgui/SKILL.md) | Provisioned appliance connection, identity, current role and authorized operation | Same Work's result, validation and receipt |

The usual route is installation → optional GAPE observation → Helper discovery
→ declarations → Helper validation/preparation → SDK and/or Builder when the
integration requires them → authorized operation. Helper is used on **both**
sides of declaration work. Skip SDK when a supplied supported integration
already meets the requirement. Skip Builder when an existing approved Pack
already meets it. Do not build a new adapter or Pack merely to complete a list.

The expansion route is: preserve the working baseline → rerun GAPE for the
approved changed scope → compare observations → Helper impact assessment →
declarations and conditional SDK/Builder work → product validation of the new
connection/binding → isolated example and affected existing-use checks →
supported activation within the organization's authority. Keep the old
connection and in-flight Work intact until the change has a validated disposition.

## 3. Keep four facts separate

1. The AI agent can draft requests and invoke permitted tools.
2. The product returns the actual validation, binding and authority decisions.
3. A candidate or a successful local synthetic example is not an approved Pack
   or an operational Work.
4. Completion requires the actual result and, for executed Work, its matching
   product validation and receipt. The agent's notes are not that receipt.

Use only release-supplied public commands and supported interfaces. Do not
replace a refusal with invented success, guessed IDs, modified manifests,
direct store edits or arbitrary shell workers. Do not weaken authentication,
certificate checks, isolation or approval requirements to make a step pass.

## 4. Run a safe first exercise

Ask your agent:

> Read START_HERE.md and the SDK Engine skill. Identify the actual OS/CPU,
> executable, package identity and synthetic request. Show the planned inputs
> and fresh output folder. Analyze the supplied synthetic request within my
> authorized local workspace. Preserve existing results. Do not submit Work,
> enroll a customer, contact a provider or change an appliance.

For appliance operation, start by reading the headless or GUI skill and
confirming the administrator-supplied connection and expected installation.
Do not substitute the local SDK exercise for an appliance connection check.

Online and offline environments are supported choices. The optional SDK Rust
dependency set is intended for closed on-premises builds; offline mode is not
the default. That set does not supply model weights, provider access, every
third-party tool or all native OS prerequisites.

## 5. Record and resume

Use [RUN_RECEIPT.template.md](RUN_RECEIPT.template.md) for a minimized operator note. Preserve originals,
record actual process exits separately from product JSON, and use a fresh
output directory when changing inputs. If a request times out after submission,
reconcile its original ID/state before submitting again.

Host identities, credentials, customer data, prompts and raw logs remain inside
the organization's approved boundary. Do not send them to a hosted AI runtime,
support service or another operator unless that exact disclosure is authorized.
Refer to credentials through your approved credential mechanism, not chat text.

If the release does not supply an interface, template, required enrollment
material or suitable native environment, record the missing prerequisite and
the responsible owner. Continue independent preparation; do not invent a route.

## Manual mapping

Part.1 installation; Part.2 GAPE; Part.3 Integration Helper; Part.4 Contract and
Document; Part.5 SDK Engine; Part.6 Builder; Part.7 PackrGUI/headless; Part.8
operations and troubleshooting. Use the supplied manual index to open the
current headings, including when an older filename redirects to the same Part.

# Administrator/setup-agent planning worksheet only. VibePackr and AI runtimes do not import this file.
# Blank values are deliberately unconfigured; they grant no authority.
format = "vibepackr-agent-plan-worksheet"
version = 1
language = "en"

[runtime]
name = ""
instruction_loading_method = "" # native skill import or explicit Markdown read
loaded_skill_names = []          # fill only after observed loading
data_processing_boundary = ""   # organization-approved location/provider scope

[release]
package_reference = ""
sha256 = ""
os_cpu = ""
manual_index = ""

[paths]
appliance_package = ""
packrctl = ""
packrgui = ""
builder = ""
gape = ""
integration_helper = ""
sdk_engine = ""
request = ""
fresh_output = ""
optional_rust_dependencies = ""

[connection]
supplied_profile_reference = "" # non-secret reference; not profile contents
expected_installation_reference = ""
expected_release_reference = ""
credential_reference = ""       # reference only; never a secret value
observed_binding_reference = "" # actual product result, not an intended alias

[task]
goal = ""
network_choice = "UNSET"        # choose online or offline for this task
authorized_scope_reference = ""
input_reference = ""
observed_work_id = ""           # copy returned ID; never invent one
last_proven_stage = ""
next_owner = ""

[observations]
process_exit = "NOT_RUN"
product_status = "NOT_OBSERVED"
product_reason = "NOT_OBSERVED"
validation = "NOT_RUN"
receipt_reference = "NOT_OBSERVED"

[checkpoint]
original_request_reference = ""
input_sha256 = ""
candidate_reference = ""
candidate_revision = ""
candidate_sha256 = ""
last_observed_binding_reference = ""
pending_effects = "NOT_OBSERVED"
recovery_state = "NOT_OBSERVED"
first_failure_reference = ""
next_required_check = ""

# Expansion planning references only. These values are not product decisions.
[expansion]
change_kind = "UNSET" # legacy_system, connector, ai_runtime, model, agent_runtime
existing_installation_reference = ""
known_good_configuration_reference = ""
existing_binding_reference = ""
active_work_references = []
requested_target_reference = ""
approved_source_scope_reference = ""
baseline_gape_manifest_reference = ""
baseline_gape_snapshot_reference = ""
baseline_gape_revision = ""
new_gape_manifest_reference = ""
new_gape_snapshot_reference = ""
new_gape_revision = ""
common_scope_reference = ""
added_scope_reference = ""
gape_comparison_reference = ""
helper_impact_result_reference = ""
affected_existing_use_checks = []
new_target_check_reference = ""
rollback_procedure_reference = ""
activation_disposition_reference = ""

---
name: vibepackr-agent-workflow
description: Coordinate enterprise installation, runtime binding and integration across VibePackr tools, including interrupted tasks and expansion of an installation already in use. Use before choosing a tool or resuming a task; preserve product decisions and existing results.
---

# Coordinate and resume enterprise agent work

Use the organization's approved goal, input scope, release and target. Read the
relevant tool skill from this installed kit before invoking it. A skill provides
instructions; an actually available CLI, GUI or MCP tool performs the action.
Do not claim a tool was called because a plan mentions it.

If the administrator has connected the release's local MCP adapter, read
[MCP setup and recovery](../../MCP_SETUP.md) for its exact tool subset and
operation references. Use only tools actually returned by the connected server.
SDK generation, Builder, installation and binding changes use their supplied
public interfaces and separate tool skills; do not invent equivalent MCP calls.

## Establish the current checkpoint

Record actual package/component versions, OS/CPU, executable paths, expected
installation, authorized data-processing location, input digests, fresh output
path and last proven step. Preserve any original request/Work ID, candidate
revision, binding reference, pending operation and recovery state.

Keep product status/reason values unchanged. The case labels in
[interruption-cases.md](references/interruption-cases.md) are operator guidance,
not product decision codes. Use them to choose the next **permitted preparation
task**; the product still decides validation, binding, authority and execution.

## Choose the next tool from observed facts

For a new legacy system, connector, AI runtime or model added after installation,
read the kit's `vibepackr-postinstall-expansion` skill first. Rerun GAPE for the
approved changed architecture, compare with its retained baseline and pass the
permitted impact findings to Helper. A previous installation check or binding
does not validate a newly added target. Preserve active Work and the known-good
configuration; do not restart installation as the default expansion path.

1. Confirm installation and connection prerequisites before binding/operation.
2. Use GAPE when a revision-bound architecture observation is needed and its
   source/manifest scope is actually permitted. Post-installation expansion
   requires a new observation; if the required scope is unavailable, record that
   exact missing prerequisite and continue only independent preparation.
3. Use Helper discovery/normalization to identify supported source/target work.
4. Use Contract and Document authoring to correct or create supported declarations;
   return the full request to Helper validation/preparation/status.
5. If returned findings establish an implementation requirement within the
   supported scope, use Builder to prepare a reviewable candidate/plan. Include
   the exact Helper request/result, goal, target, I/O and data boundary.
6. From that plan, use the declarations skill and/or SDK Engine as needed.
   Declarations may be needed both before generation and to align the resulting
   candidate afterward. SDK generation produces a local adapter candidate,
   never an automatically registered or approved integration.
7. Return the exact revised request/candidate to the supplied Helper and Builder
   validation paths. Tie every result to its input digest/revision.
8. Use the release's actual review/registration/approval/entitlement procedure.
   Only then assist authorized operation through PackrGUI or headless.
9. For an executed Work, reconcile that same Work's result, validation, recovery
   and receipt. Human acceptance stays separate.

Use existing supported integration/Packs when sufficient. SDK and Builder are
conditional tools; invoking every tool is not an acceptance condition. A
Builder plan can coordinate SDK/declaration work, but it cannot create a missing
public interface, privileged permission or approved target by assertion.

## On interruption or an unexpected result

Stop dependent actions at the first new unexplained result. Preserve the
original input, tool response/exit, current candidate and last proven step.
Use the case reference to distinguish missing prerequisites, declaration errors,
implementation requirements, identity/authority refusals and uncertain partial
effects. Do not route every failure into Builder.

- Correct an established input defect in a copy, then rerun only its affected
  checks using a fresh result directory.
- Reconcile delayed or ambiguous mutations by original request/Work identity;
  do not resubmit, reinstall, regenerate an ID or start a second recovery.
- For partial application, query the product's current recovery/postcondition
  state. Use only supported, authorized recovery. Preserve preimages and outputs.
- For a genuinely unclassified case, collect minimal non-secret observations,
  name the missing fact/owner and continue independent preparation. Do not guess
  success, apply speculative fixes or start an unbounded retry loop.

## Resume after restart or handoff

Re-read the operator checkpoint. Confirm the same installation/release and
input/candidate digests. Query the original operation where available; retained
notes are not current readiness/authority. If identity or inputs changed, retain
the predecessor and establish a new reviewed plan before mutation. Resume the
first unproven required step, not the entire pipeline.

## Execution boundary

Do not use Builder/SDK to bypass a trust, permission, policy, entitlement or
validation refusal. Do not expose customer content to another AI provider, edit
protected product stores, modify a frozen base image, execute arbitrary shell
workers, invent endpoints or turn generated files into product receipts.

Ordinary workers give goals and approved inputs. They do not edit these skills
or TOML configuration. Initial registration/connection and security-sensitive
choices belong to the organization's administrator or supported setup flow.

# Interruption and resumption cases

These are troubleshooting paths, not product error codes or guaranteed causes.
Read the actual release's status/reason first. Each row names the next permitted
step and the evidence needed to return. An unexpected result remains unknown
until its cause and correction are established.

## Installation and dependencies

| Case / observation | Next step and owner | Return evidence / stop boundary |
|---|---|---|
| I01 Package checksum differs | Installation skill; retain candidate, obtain verified package | Trusted expected identity matches; no force install |
| I02 OS or CPU differs | Administrator selects the supported OS/CPU package | Actual package/platform match; Builder cannot repair a binary mismatch |
| I03 install.sh lacks adjacent files | Obtain the complete appliance assembly | Required manifest/binaries/scripts/units supplied; never fetch arbitrary files |
| I04 Installer requires root | Authorized administrator performs the install | Installer exit and health; no agent privilege expansion |
| I05 Another release is installed | Supported upgrade/recovery procedure | Preserved old/new identity and validated disposition; no manifest overwrite |
| I06 Installation interrupted | Read retained installer/current state before another install | Exact stage and partial effects established; do not assume rerun is idempotent |
| I07 VM/process active, health not ready | Installation/headless health and readiness procedure | Actual ready state, identity and first-boot result |
| I08 Offline set missing/wrong platform | SDK dependency verification; approved prerequisite provisioning | Exact set/platform verification and native prerequisites; no silent download |
| I09 Disk/memory/native compiler failure | Preserve first OS/tool error; verify resource/prerequisite cause | Required resources actually available; do not classify a timeout as memory failure |

## Connection and runtime binding

| Case / observation | Next step and owner | Return evidence / stop boundary |
|---|---|---|
| B01 Endpoint times out | GUI/headless connection check, then administrator/network owner | Correct address/readiness/reachability; no automatic firewall opening |
| B02 Server identity changes | Stop affected connection; administrator reconciles identity | Approved expected identity; never disable certificate/host validation |
| B03 Authentication/enrollment refused | Supported enrollment/session procedure | Current authenticated role at expected installation; no Builder fallback |
| B04 Model files exist but no runtime observation | GUI runtime discovery/observation procedure | Current runtime reference observed; file presence alone is insufficient |
| B05 Runtime observed, binding not validated | Read exact product validation/binding reason | Validated current binding returned; do not infer from an alias |
| B06 Alias/model changed, old binding remains | Preserve running Work, inspect new observation and current binding | Exact new model/reference validated and bound within scope |
| B07 Multiple possible runtimes | Obtain intended administrator-approved target | One exact target established; do not choose by similarity |
| B08 Runtime restarts mid-task | Reconcile original Work and new runtime observation separately | Current binding plus original Work state; no automatic resubmission |
| B09 Hosted runtime cannot receive this data | Continue locally or use an approved minimized representation | Authorized data boundary established before transmission |

## Integration preparation and candidate work

| Case / observation | Next step and owner | Return evidence / stop boundary |
|---|---|---|
| C01 Malformed/incorrectly encoded JSON | Declarations skill edits a copy of complete input | Full request parses; syntax does not replace semantic checks |
| C02 Source-only Document submitted as full request | Put source object into supplied full envelope | Required request fields retained, Helper sees full request |
| C03 properties/required/mapping differ | Declarations skill reviews all related fields | Revised full request passes affected Helper checks |
| C04 Synthetic score number supplied instead of string | Correct fixture type in a copy | Supported STRING_TO_INTEGER mapping returns its actual validation result |
| C05 Published target/template is missing | Administrator/product integration owner supplies supported material | Exact supported target/template exists; no guessed ID/digest |
| C06 Existing supported integration is sufficient | Helper prepare/status and normal review handoff | Actual prepared candidate/status; SDK/Builder may be skipped |
| C07 Helper establishes supported adapter implementation need | Builder prepares candidate/plan → declarations and SDK as required | New adapter candidate plus aligned request; Helper/Builder revalidation |
| C08 Supported reusable Pack composition is needed | Builder skill with supplied template and permitted capabilities | Exact new candidate/revision and validation; approval still separate |
| C09 Builder cannot prepare while disconnected | Restore supported connection/role | Actual Builder readiness; never enable disabled UI by editing state |
| C10 SDK fails after partial output | Retain output/input/toolchain and precise first failure | Frozen correction, fresh directory, affected checks passed; no blind regeneration |
| C11 Existing result folder or candidate revision reused | Preserve predecessor, select a fresh result/revision | Actual new reference/digest; do not overwrite evidence |
| C12 Candidate changes after review | Return exact new revision to affected checks/review | Review/approval binds the new digest; old approval is not copied |
| C13 Desired integration exceeds supplied capabilities | Retain bounded goal/findings; product integration owner | Supported route or a separately approved product change; no arbitrary workers |

## Execution, recovery and handoff

| Case / observation | Next step and owner | Return evidence / stop boundary |
|---|---|---|
| R01 Prepared candidate, approval pending | Hand off exact candidate to approval owner | Actual current approval; preparation is not authority |
| R02 Approval exists, entitlement/installation differs | Reconcile exact installation entitlement | Product accepts current scope; never route around the refusal |
| R03 Submission times out with no returned ID | Reconcile original request/key through supported query/support | Acceptance/current state established before another submission |
| R04 Work ID exists, result delayed | Query that same Work | Current execution/recovery state; no new Work to replace waiting |
| R05 Result file exists, receipt/validation missing | Same-Work query and Part.8 case I | Matching validation/receipt or explicit incomplete result |
| R06 Partial mutation or recovery pending | Supported product recovery query/procedure | Validated postconditions/current state; no manual success marking or new repair |
| R07 Agent/runtime crashes | Load retained checkpoint, revalidate identity and query original operation | Actual current state reconciled; resume first unproven step |
| R08 Operator changes input/target while paused | Preserve old plan; review new scope and revision | New input/target bound to required checks and authority |
| R09 Unknown error, several plausible causes | Preserve first result, run bounded authorized read-only discriminator | Exact affected boundary established; no speculative Builder/SDK loop |
| R10 Tool/MCP connection disappears | Reconnect through supplied setup; query original operation | Same target/release and original state; tool restart is not task success |

## Post-installation expansion

Use the kit's `vibepackr-postinstall-expansion` skill for this entire path.

| Case / observation | Next step and owner | Return evidence / stop boundary |
|---|---|---|
| E01 Add a new legacy system to a working installation | Preserve baseline; rerun GAPE, then Helper impact assessment | Validated changed observation and supported interface/request; no reinstall |
| E02 Add an inference runtime/model | GAPE for approved architecture changes; separate product runtime discovery/binding | Exact runtime/model and validated current binding; GAPE is not runtime discovery |
| E03 Add an enterprise agent runtime | Re-observe approved architecture change; supported kit loading and tool/connection checks | Instructions actually read and tool availability/installation verified |
| E04 Baseline snapshot cannot be located | Retain current state; obtain legitimate baseline or record missing comparison | Current snapshot may be validated, but no before/after or no-drift claim |
| E05 New system expands observation scope | Reconcile common versus added scope before comparison | Scope-qualified comparison; do not treat unrelated inventories as unchanged |
| E06 No approved source scope or GAPE manifest | Integration/source owner supplies supported material | GAPE prerequisite resolved; independent preparation only until then |
| E07 Existing supported adapter/Pack is sufficient | Helper preparation and ordinary review path | Exact new-target result; SDK/Builder can be skipped |
| E08 New adapter/declarations are required | Helper → Builder plan → SDK/declarations → affected validation | Exact revision/digest and updated GAPE observation if source changed |
| E09 Old runtime has in-flight Work | Preserve old binding and reconcile active Work before supported change | Original Work and recovery state established; no alias replacement or resubmit |
| E10 New target needs different permissions/data location | Administrator/integration owner uses normal provisioning process | Actual permitted boundary; do not broaden access through Skills |
| E11 New example passes, old use fails | Preserve outputs; inspect affected GAPE/Helper findings and supported recovery | Both affected uses validated or explicit unresolved disposition; no global pass |
| E12 New runtime needs missing native/model dependencies | Verify exact prerequisites and selected online/offline route | Supplied SDK dependency set is not model/runtime provisioning |
| E13 New target is prepared but not registered/bound | Inspect actual product review/registration/binding state | Actual accepted target and current authority; files are not activation |
| E14 Change response is lost after submission | Reconcile the original change request/Work | Acceptance and partial effects known before recovery or another request |
| E15 Expansion is interrupted and agent restarts | Load checkpoint; recheck baseline, target, digests and original state | Resume first unproven check; keep working connection and prior results |

## Worked case: Helper requires implementation

Input: a full supported synthetic Custom request; the actual Helper result
identifies an implementation requirement. Keep the input digest and original
result. Give Builder the same target, operation, I/O, permitted capabilities,
data boundary and recovery needs. Builder prepares a candidate/plan through its
supported interface. If that plan needs an adapter, use the SDK skill in a fresh
folder. If declarations need alignment, edit a full request copy with the
declarations skill. Return the exact new candidate/request to Helper and Builder
checks, then the supported approval/registration path. Do not run an operational
Work merely because local synthetic compilation succeeded.

## Worked case: unclear timeout after submission

Input: a submitted operation whose response was lost. Preserve the original
request and idempotency reference. Query the original returned Work ID if one
exists; otherwise use the release's reconciliation procedure. Neither Builder
generation nor a new Work is a remedy for unknown acceptance. Resume only after
the original operation's current state and any partial effects are established.

## Worked case: agent restart during offline candidate creation

Retain the input, selected dependency set, toolchain identity and partially
created output. On restart check whether the original tool is still running and
what it actually produced. Do not overwrite the directory or label presence a
pass. Once the original attempt is terminal and an exact correction is known,
use a fresh output folder and rerun only the affected local candidate/checks.
No external download is inferred from the need to resume.

---
name: vibepackr-builder
description: Help an enterprise user prepare and revise supported Pack candidates in the supplied Builder, then hand off validation, approval and entitlement separately. Use when an existing approved Pack does not meet the task.
---

# Prepare a Pack candidate with Builder

Confirm the supplied OS Builder/version, authenticated role/installation,
supported Pack or template and approved input scope. Read Part.6. Do not invent
a generic Builder CLI or use a text worksheet as a product import.

First check whether an existing approved Pack already meets the requirement.
If so, follow its supported operating procedure and omit unnecessary building.

## Prepare

1. Write a reviewable human note: task goal, input/output, target, data boundary,
   supported capability, preconditions, expected result and recovery needs.
2. Use the supplied Builder's actual template fields or documented interface.
   Populate a fresh candidate using authorized synthetic data first.
3. Record its actual ID/revision/digest and each returned validation reason.
   Preparation can be disabled while disconnected or unauthorized; do not
   enable it by editing UI state.
4. To change one field, retain the original, document before/after and produce
   a new candidate revision. Revalidate the exact revised candidate.
5. Hand off candidate reference, actual validation, approval purpose/scope and
   entitlement state to the responsible owner. Do not approve your own draft
   merely because a local check succeeded.

Example **operator note**, not product JSON:

```text
Candidate: [actual returned ID and revision]
Validation: [actual result and reason]
Approval: [actual state or not requested]
Entitlement: [actual state or not checked]
Work: [actual returned ID or not submitted]
```

Candidate preparation does not grant execution authority. The product performs
its own current authority, trust, compatibility and execution checks. Do not
modify the engine, sign a Pack with an invented identity, edit protected state
or add arbitrary shell execution to make the candidate run.

## Failure

Missing template/target: retain the draft and obtain the release-supported
material. Validation refusal: correct the exact declared input and create a
new revision. Pending approval or wrong installation entitlement: hand off the
exact candidate to that owner, without resubmission. Partial application or
recovery pending: query the same Work/recovery state and stop further applying
until current state is established. Preserve previous Packs, outputs and notes.

---
name: vibepackr-declarations
description: Assist with supported Contract and source Document declarations, complete Helper/SDK request envelopes and field mappings. Use between Helper discovery and validation; drafting never grants registration or execution authority.
---

# Declare a supported operation

Read Part.4 and obtain the full supplied `quality-document.json`, full
`read-only-custom-api.json` request and release-published target references.
Preserve originals; edit UTF-8 working copies in a private folder. Do not make
up a schema, target, operation ID, adapter revision or digest.

## Understand the two file roles

- The source-only Document describes source operations and schemas.
- The complete request retains `request_id`, `correlation_id`, `draft.source`,
  `draft.definition`, `draft.mapping` and `draft.fixture` from its supplied
  shape. An excerpt is not a replacement request.

For the first exercise, replace only the **object value** of `draft.source`
with the supplied full source object. Do not substitute a filesystem path or
quote the whole JSON as a string. Keep the full request's other fields.

## Review and check

1. Check source operations, input/output types, required fields and supported
   target. If renaming `resource`, update its `properties` entry and `required`
   together, then review mapping and target impact.
2. In the synthetic Custom example source score is a string. Use `"88"`, not
   `88`, for the supported `STRING_TO_INTEGER` mapping to quality_score.
3. Parse the full JSON working copy. On an environment with Python 3:

   ```sh
   python3 -m json.tool "$request"
   ```

   On Windows use `Get-Content -Raw -Encoding UTF8 | ConvertFrom-Json` with
   error handling. Syntax parsing does not prove every duplicate key, supported
   schema, compatibility or authority requirement.
4. Run the supplied Helper normalization/validation against the **full** request
   and retain its actual result. Review changes against the exact new revision.

## Handoff and failures

Keep source Document, complete request, non-secret change notes and only the
checks actually executed. If JSON parses but the source object is in the wrong
slot, correct the envelope copy; do not weaken the validator. If semantic checks
refuse a type/mapping/target, resolve that precise declaration with the supported
schema and recheck the changed input. Record missing published material as a
prerequisite for that step.

Declarations describe intent and scope. They do not grant approval, entitlement,
registration or execution authority. Do not change engine contracts, protected
policy or product state from this authoring workflow.

---
name: vibepackr-gape
description: Produce and compare revision-bound GAPE architecture observations from an approved manifest and permitted source scope. Use during integration preparation and rerun when adding a legacy system, connector or AI runtime to an existing installation; observation does not authorize execution.
---

# Observe architecture with GAPE

Obtain the actual supplied `packr-gape` executable, an approved manifest, its
permitted source scope and the revision to observe. A human worksheet or SDK
request is not a GAPE manifest. Do not guess the manifest schema or collect
unrelated repositories. Read Part.2.

## First snapshot

Set the variables to actual paths. Choose a fresh output directory:

```sh
test -x "$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
```

On Windows use `& $gapeExe snapshot $gapeManifest $gapeOutput`, followed by
`validate-snapshot` with `Join-Path`; record `$LASTEXITCODE` after each command.

Inspect the generated `gape-architecture-snapshot.json`, input manifest,
projection/drift records and supplied viewer. Verify the observed revision and
actual validation result. Output presence alone is not a validated snapshot.

## Compare

Preserve both observations, validate each, then run:

```sh
"$gape_exe" compare "$before_snapshot" "$after_snapshot"
```

Record scope/revision differences as well as returned drift; do not interpret
an unmatched scope as a clean architecture. Give Helper the permitted findings
needed for planning, not an invented registration or execution permission.

## Re-observe an installation being expanded

Keep the previous validated snapshot, manifest, revision and scope. Take a new
snapshot for the approved connector/deployment source changes and validate it
before comparison. Read `vibepackr-postinstall-expansion` from the same kit for
the full handoff. GAPE observes its supported manifest/source inputs; do not
pretend it discovers live databases, authenticates to a new legacy application
or probes an AI provider. Obtain separate runtime/interface observations from
the supplied product tools.

When the new system expands the scope, compare the common scope explicitly and
list the added scope separately. A comparison between unmatched inventories is
not proof that existing dependencies are unchanged. If no retained baseline is
available, record that fact, validate the current permitted observation and
withhold any before/after claim until a legitimate baseline is established.
Do not reconstruct an old snapshot by guessing or broaden source access.

Give Helper the permitted changed interfaces/dependencies, snapshot references,
scope differences and unresolved findings. After implementation changes, create
another fresh observation if the observed source/revision changed. Preserve all
predecessors. No snapshot or comparison grants binding or Work authority.

## Failures and sharing

If a path/revision is missing, obtain the authorized input rather than scanning
everything. If validation fails, preserve the original output and first error;
correct the manifest/source selection and use a fresh observation directory.
If comparison scope differs, reconcile it before making a drift claim.

Snapshots and source-derived views can disclose private architecture. A file
named `public-safe` is not blanket sharing permission. Inspect the actual view
and organization disclosure scope before giving any output to a hosted AI agent
or external recipient. Observation does not authorize integration or execution.

---
name: vibepackr-headless
description: Use the supplied Packr headless packrctl client for status, health and same-Work queries, and assist an explicitly authorized Work submission. Use with a provisioned release-compatible appliance connection.
---

# Packr headless operation

Confirm the actual executable/version, expected appliance installation, current
authentication/role and release-supplied connection procedure. `packrctl` is a
client; opening it does not start or authorize an independent engine.

Use only supplied public commands. On a local appliance, if the administrator
supplies a specific absolute control socket, the client accepts `--socket PATH`.
Do not invent a remote URL option or substitute an arbitrary socket/profile.

## Read-only checks

```sh
"$ctl_exe" status --json
"$ctl_exe" health --json
"$ctl_exe" work list --limit 10 --json
"$ctl_exe" work show "$returned_work_id" --json
```

Set variables to the supplied executable and actual returned Work ID first.
In PowerShell invoke the actual path with `& $ctlExe ...`; inspect
`$LASTEXITCODE` after each call. Record process exit and the unchanged JSON
status/reason separately. Expected output is the product's actual response;
do not create a replacement success object.

## Authorized Work

Only after the operation, intent, target, data boundary and current authority
are established may the agent invoke the supplied form:

```sh
"$ctl_exe" work run "$approved_operation_id" "$approved_intent" "$unused_approved_key" --json
```

This is a mutation, not a health check. Use the actual supported operation and
idempotency procedure. Preserve the returned `result.work.work_id`, then query
that same ID. Validation, execution, recovery, receipt and human acceptance are
distinct. Do not invent an ID, approval or receipt, reinterpret a refusal, edit
the store, or launch an arbitrary shell worker.

## Failure

On missing socket/readiness, return to appliance setup. On identity mismatch or
authentication refusal, stop the affected action and use the administrator's
connection/enrollment procedure. On delayed submission, reconcile the original
request and key before another attempt; a changed plan with an old key can
conflict. A visible runtime/model response does not prove a Work completed.

Keep credentials and customer input out of prompts/logs. Report only the actual
last proven stage and minimized evidence. See Part.7 and Part.8.

---
name: vibepackr-install
description: Help an enterprise operator prepare and install the complete supplied VibePackr Linux appliance package, then check actual service readiness. Use for install.sh and appliance setup; client and SDK packages follow their own instructions.
---

# Install the VibePackr appliance

## Before action

Obtain the complete approved appliance package, its trusted expected digest,
supported Linux release/CPU and the operator's target administrator authority.
The separately published `install.sh` is not a standalone installer. It needs
the package binaries, release manifest, checksum file, units, docs and scripts.
Do not fetch arbitrary missing files or run a website snippet through a shell.

Inspect a fresh extraction. Compare the outer package to its trusted expected
SHA-256, then inspect the supplied checksum manifest. A checksum file beside
an archive does not independently establish publisher authenticity.

The installer requires root, creates the product runtime account/directories,
installs systemd units and starts the control plane. This is a real target
mutation: proceed only within the organization's approved install scope. A
different already-installed release is refused; do not edit its manifest to
force replacement. Do not modify a frozen base image.

## Execute and verify

From the **complete appliance package root**, the supported install command is:

```sh
sudo sh ./install.sh
```

Record its actual exit and first error. This recipe is not permission to run
sudo, enroll a customer, open firewall ports, expose a listener or deploy to a
cloud account. Obtain those actual prerequisites through the approved operator.

After installation use the supplied `health.sh` / installed
`/opt/vibepackr/health` and release's first-boot/readiness procedure. Confirm
readiness, installation identity and authentication separately. Do not equate
an installed file, active process or VM power state with ready operation.

## Failure and recovery

- Exit 77: this installer requires administrator execution; return to the
  authorized administrator, without broadening the agent's own privileges.
- Checksum mismatch: preserve the candidate and stop installing it; obtain a
  verified package through the approved distribution route.
- Exit 65/different installed release: retain both identities and use the
  release's supported upgrade/recovery procedure. Do not force symlink changes.
- Service not ready: retain the first failing stage and minimized diagnostics.
  Use the supplied health/readiness instructions before client connection.

Review the supplied `disable.sh` and `uninstall.sh` before separately authorized
recovery/removal. Their names do not prove rollback or data retention. Preserve
customer state and evidence; never delete directories as a substitute for a
validated recovery. Read Part.1 and Part.8 for the installed release.

---
name: vibepackr-integration-helper
description: Run supported Integration Helper discovery before declarations and validation/preparation after declarations, retaining complete request envelopes and actual product responses. Use for preparation and registration handoff, not operational execution.
---

# Integration Helper before and after declarations

Read Part.3. Obtain the supplied `packr-integration-helper`, the release's
complete request example and published target references. Use authorized
synthetic content first. Copy the full example into a fresh private workspace;
a source Document, path string or excerpt is not a full request.

When adding a legacy system or runtime to an installation already in use, read
the kit's `vibepackr-postinstall-expansion` skill. Rerun GAPE for the approved
changed architecture and bring its validated comparison/scope findings into
this assessment. Preserve working declarations, bindings and active Work.
An earlier successful Helper result does not validate the new target.

## A. Discover and normalize before declaration work

```sh
"$helper_exe" r2-discover "$request" > "$fresh_logs/01-discover.json" 2> "$fresh_logs/01-discover.stderr.txt"
helper_exit=$?
```

Create `fresh_logs` first and refuse an existing result directory. Record exits
and read the original JSON status/reason. Inspect the discovery result before
proceeding; a refusal or incompatible input returns to that declaration. When
that result permits the next preparation step, normalize the full request:

```sh
"$helper_exe" r2-normalize "$request" > "$fresh_logs/02-normalize.json" 2> "$fresh_logs/02-normalize.stderr.txt"
normalize_exit=$?
```

Review source operation, declared target and supported transforms. Use the
declarations skill/Part.4 to edit a **copy** of the complete envelope while
retaining its required request identity and other fields.

## B. Validate and prepare after declaration work

Invoke one step at a time and capture stdout/stderr/exit into separate new
files, using the same pattern:

```sh
"$helper_exe" r2-validate "$request"
"$helper_exe" r2-prepare "$request"
"$helper_exe" r2-status "$request"
```

For Windows invoke with `& $helperExe ...`; save UTF-8 output and
`$LASTEXITCODE` for every step. Do not treat exit zero as a substitute for the
returned product decision.

Report actual preparation stage, implementation need and request/candidate
references. If existing supported integration is sufficient, skip SDK. Use SDK
only for a supported adapter candidate requirement. Use Builder only when a
new Pack candidate is required.

## Failure / handoff

`draft.source` must be the complete source object, not a filename or escaped
JSON string. Check `properties`, `required`, mapping and input types together.
For the supplied Custom example, score is a string, such as `"88"`; the
supported transform yields integer quality_score. Do not fabricate target IDs
or normalization digests.

Preserve refusals and previous candidates. Preparation is not registration,
approval or execution. Use only a release-supplied registration route with
actual authority; if none is supplied, hand off the exact prepared candidate
and missing prerequisite. Do not invent an endpoint or edit product stores.

---
name: vibepackr-packrgui
description: Assist enterprise users with the supplied PackrGUI connection, runtime binding observations and Work result/receipt checks. Use actual release UI and supported interfaces; do not assume GUI automation support.
---

# PackrGUI assistance

Read Part.7 for the supplied release. Confirm OS/CPU, complete app/runtime
bundle, actual executable and version. Windows portable files must stay with
their bundled runtime/resources. Do not bypass OS security warnings or claim
official signing where none is supplied.

Collect the administrator-supplied endpoint/TLS name, expected customer and
installation/release references, enrollment method and permitted role. A client
checklist is a human worksheet, not an importable connection profile. Never
invent connection fields, API routes or UI screen names.

For a new runtime/model added after installation, use the kit's
`vibepackr-postinstall-expansion` skill before changing the working binding.
That path reruns GAPE on approved architecture changes and uses Helper impact
assessment. The separate UI discovery/validation/binding checks below are still
required; a GAPE snapshot is not a live runtime check.

1. Open the actual supplied app using its installation instructions.
2. Follow the release's supported profile/connection procedure. Keep secrets in
   the approved credential mechanism; do not expose them in an agent prompt.
3. Inspect current readiness, authentication, installation identity and role
   separately. Record a refusal as returned.
4. For runtime changes, distinguish discovery, observation, validation and the
   current bound reference. File presence or an alias is not a validated bind.
5. Assist a Work only within the approved operation/plan/authority. Copy the
   actual returned Work ID and inspect that Work's result, validation and
   matching receipt. Do not resubmit to resolve a delayed result.

If this AI runtime has no permitted GUI-control tool, guide the operator or use
the supplied headless route when actually available and authorized. Record which
route was observed; headless success does not prove the GUI works. A launch
screen alone proves only that screen, not appliance connection or Work execution.

## Common failures

- App will not open: check OS/CPU, full bundle and exact original warning;
  preserve the package and use the supported installation path.
- Timeout: distinguish address/network/service readiness from authentication.
- Identity/role mismatch: stop operation and reconcile with the administrator.
- Runtime visible but not bound: inspect the product's current observation,
  validation and binding reasons; do not relabel cached state.
- Result without matching receipt: keep the same Work ID, consult Part.8 case I
  and report the last proven stage.

Do not change core files, force a success state or weaken security to proceed.

---
name: vibepackr-postinstall-expansion
description: Add a legacy system, connector, AI runtime, model or enterprise agent runtime to a VibePackr installation already in use. Rerun GAPE, compare the approved changed architecture, use Helper for impact assessment and route conditional SDK, Builder and declaration work while preserving working connections and active Work.
---

# Expand an installation already in use

Use this skill when a working installation gains a new system or runtime.
Read the relevant tool skills supplied in this kit. Ordinary workers describe
the goal and permitted input; the administrator or supported setup flow supplies
installation, connection, identity and credential references. Workers do not
edit Skills or configuration files to make a new target appear connected.

## 1. Preserve and identify the working baseline

Record the actual installation/release, component versions, known-good
configuration reference, existing connections/bindings, active Work and pending
recovery. Preserve previous declarations, Pack/adapter revisions, validation
results and GAPE observations. Keep secrets in the approved credential store.
Do not reinstall, replace the working binding or interrupt active Work merely
to add a target. Use a fresh local result directory for this change.

Classify the requested target accurately:

| Added target | Separate facts to establish |
|---|---|
| Legacy application, API, database or connector | Supported interface/version, approved data scope, authentication reference, read/write intent and expected input/output |
| AI inference runtime or model | Exact runtime/model identity, permitted processing location, actual discovery, compatibility, current validation and binding |
| Enterprise AI agent runtime | Actual instruction loading, supplied tool availability, expected installation connection and permitted processing location |

Adding an inference runtime and importing a skill into an agent are different
steps. Neither proves the other. A reachable address is not a validated binding.

## 2. Rerun GAPE before planning the integration change

Use `vibepackr-gape` to validate the retained baseline and produce a new
revision-bound snapshot from an approved manifest and source scope. Compare the
two validated snapshots. Record changed interfaces/dependencies, common scope,
added scope and unresolved findings. Keep both original snapshots and manifests.

GAPE operates on supported manifest/source inputs. It does not log into the new
legacy system or discover a live model runtime. Use separate supported product
discovery for those facts. If source access, a suitable manifest or a comparable
baseline is missing, record the specific gap. Independent preparation can
continue, but do not label the change impact-checked or silently skip GAPE.

After SDK/Builder work changes observed source, take another fresh validated
snapshot and compare the affected scope again. Do not modify a frozen base image.

## 3. Use Helper to assess the new target and affected connections

Pass the permitted GAPE findings, exact target/interface references, full
request envelope and desired I/O to `vibepackr-integration-helper`. Use discovery
and normalization before editing declarations; use validation, preparation and
status afterward. Keep original product statuses/reasons and request identities.

Check whether a supplied integration or approved Pack already meets the goal.
If it does, use that supported preparation/review path. If an implementation
requirement is established within the supported scope, use Builder to prepare
the candidate/plan, then SDK and/or Contract and Document authoring as needed.
Return the exact revised candidate and request to Helper and Builder checks.
An identity, policy, trust or permission refusal is not a Builder repair task.

## 4. Prepare the environment and verify the actual connection

Use only release-supported target selection, provisioning and binding routes.
Keep the existing working configuration intact while preparing the new target.
Do not invent a second active binding, alias or parallel operation mode if the
release does not supply it. If changing a single binding is necessary, use its
supported change procedure and retain the original reference and recovery plan.

Check native prerequisites and versions for the new adapter/runtime. Online or
offline is an explicit environment choice; the optional Rust dependency set
covers supported SDK builds, not model weights, provider access or every legacy
driver. No silent downloads, network opening, credential copying, new provider
disclosure or permission expansion follows from this skill.

For inference runtimes, observe the exact new runtime/model, run the supplied
validation and inspect the actual returned binding. For an enterprise agent,
confirm it read the relevant Skills and can discover the supplied tools, then
perform a supported read-only connection check against the expected installation.
For legacy systems, verify the exact declared interface and data boundary through
the approved interface checks. Preparation and actual connection are distinct.

## 5. Validate the new use and affected existing uses

Start with a supplied synthetic or explicitly approved bounded input in a fresh
output folder. Preserve the input digest, expected output contract, actual output
and validation. Do not use customer production mutations as a connectivity test.
Operational Work requires the product's current authority and normal review path.

Rerun the affected existing-use checks selected from the actual GAPE/Helper
impact findings. Include shared authentication, routing, declarations, runtime
binding or Pack revisions when the change touches them. A successful new example
does not prove existing use is unaffected. Record unavailable checks as unproven.

Activate only through the supported change procedure within the organization's
actual authority. Do not copy a prior approval onto a new target or digest.
For executed Work, reconcile its matching result, validation and receipt.

## 6. Resume or recover without losing the working state

Retain the original change request, input/candidate digest, before/after GAPE
references, Helper result, current binding, active Work and last proven stage.
After interruption, query the original operation before another submission.
Resume the first unproven check; do not restart the whole installation.

If validation fails before application, preserve the rejected candidate and use
the working configuration. If application was partial or acceptance is unknown,
use the supported reconciliation/recovery procedure before switching anything
back. A saved configuration alone is not restore authority or proven rollback.

## Example: add a legacy API to an existing installation

Retain the working integration and baseline. Observe the approved connector
source change with GAPE; record the new API schema and any changed common
dependencies. Give Helper those findings and the full supported request. If
Helper establishes that an adapter is required, prepare the Builder plan,
generate the SDK candidate in a fresh folder and align the declarations. Return
the exact new revision to validation and review. Run the supplied synthetic
example and the affected original integration checks. Keep the old connection
until the supported activation and recovery dispositions are established.

## Example: add another AI runtime after months of use

Keep the current runtime binding and in-flight Work references. Rerun GAPE on
the approved runtime connector/deployment source change and compare scope with
the retained baseline. Separately discover the new runtime/model through the
product, inspect compatibility and data-processing location, then use Helper
and the actual binding procedure. Do not repoint the old alias to make discovery
look successful. Check the new bounded example and affected existing routing/
binding uses; retain both observations and the actual activation disposition.

Stop dependent changes when the exact target, required observation, interface,
authority or recovery state cannot be established. Preserve the working baseline
and continue independent preparation. This instruction does not grant authority.

---
name: vibepackr-sdk-engine
description: Analyze supplied synthetic Custom API/MCP requests and build SDK adapter candidates with an existing online toolchain or the optional offline Rust dependency set. Use when a supported integration needs an adapter candidate.
---

# SDK Engine candidate workflow

Read Part.5. Confirm the supplied SDK executable, package identity, OS/CPU and
complete synthetic request. Preserve previous results and use a fresh output
directory for every changed or comparison run. Analyze the request first:

```sh
"$sdk_exe" analyze "$request" unused
```

Record actual process exit and returned result. A source Document or README
snippet is not the complete request. Use the supplied
`examples/read-only-custom-api.json` or `examples/read-only-mcp-transcript.json`.

## Choose online or offline explicitly

With an existing permitted Rust/native toolchain:

```sh
"$sdk_exe" run "$request" "$fresh_output"
```

For closed on-premises use the matching optional dependency set. Its platform
identifier is `MACOS_ARM64`, `WINDOWS_AMD64` or `DEBIAN_13_AMD64`:

```sh
"$sdk_exe" verify-offline-dependencies "$platform" "$dependencies"
"$sdk_exe" run-offline "$request" "$fresh_output" "$dependencies"
```

Verify the dependency set before building. On macOS, where the supplied release
requires an explicit installed Command Line Tools selection, append
`--macos-developer-selection COMMAND_LINE_TOOLS` to `run-offline`; do not change
system-wide developer selection. Other selections follow that release's guide.
Windows uses `& $sdkExe ...` and checks `$LASTEXITCODE` after each invocation.

Offline is a deployment choice, not the product default. Do not silently download
missing dependencies on a closed network. The optional set does not replace
all native OS prerequisites, model files or unrelated tool dependencies.

## Inspect and revise

Read the actual new `README.md`, `adapter.rs`, `manifest.json` and compiled
candidate outputs. For the supplied Custom example edit a full input copy:

```text
draft.fixture.response.component = "my-test-component"
draft.fixture.response.score = "88"
```

These are field-edit instructions, not standalone JSON. Preserve full request
identity, source, definition and mapping. Analyze again and build into a new
directory. Compare generated source, manifest and library digest separately;
changing fixture data can change a manifest while generated adapter logic
remains the same. Byte reproducibility comparisons require the same input,
release, platform and selected toolchain.

## Failures / next stage

Missing native compiler/SDK, wrong dependency platform or failed verification:
retain the refusal and obtain the approved prerequisite. Type error: correct
the exact declaration, not the validator. Existing output directory: preserve
it and select a new path. Unexpected digest difference: retain inputs and
toolchain identity before investigating; never relabel it a pass.

SDK local output is an adapter candidate. It is not a registered integration,
approved Pack or executed operational Work. Hand off through the release's
supported review/registration path; use Builder only if a Pack candidate is
also required. Do not contact live APIs/providers from a synthetic exercise.