Integration Helper & SDK Developer Guide

01 · Start here: prepare an integration for review

VibePackr governs AI execution. When work needs an external capability, such as information returned by an API, the integration must describe that capability in a form the product understands. Your first task is to prepare that description and see what still needs to be resolved.

You supply the intended operation, input/output descriptions and supported non-secret references. The supplier must provide the matching Helper/SDK deliverable, public input format and supported target contract. The Integration Helper checks and organizes the input, then prepares a candidate—a proposed integration—or a plan with missing items. This is the first useful result to review; it is not a live provider connection.

First reading: choose the right tool → understand the declaration → follow a small example → read the stages → request the missing delivery items. Use the detailed reference when you have a matching deliverable.

02 · Roles and scope

Component roles and supported scope

Choose the tool by the job you are doing. The Helper prepares an integration description; the SDK is the programming interface for a consumer that has the supported library. Neither is a substitute for deploying the customer appliance.

Use these roles to decide what to request from the supplier and what result to expect.

For appliance setup, follow the customer guide.

GAPE R1 observes committed-source structure without calling an AI provider. External agent assistance and the product Vertex runtime are separate paths; see Agents & AI.

03 · Contract/Document declarations: what you author

Input examples and delivery boundary

A declaration makes your intended integration concrete enough to check. Think of it as an application form: it describes the operation and information to connect, while the product checks whether they fit an existing supported interface.

Purpose: Describe an integration’s inputs, outputs and capabilities in a versioned document so the product can check them against a supported contract. Uploading arbitrary prose or JSON does not create a new product contract.

Authoring sequence

1. Request the delivery version and approved public schema/sample from the supplier. Use the source-document exercise for preparation while the complete customer package remains pending.
2. Select the supported document kind and operation, then supply required fields. Do not author internal policy/authority records or raw credentials.
3. Use validation for the matching R0/R2 format and inspect status/reason. Preserve failures and correct the input when formats differ.
4. Review the preparation result and unresolved items before handing it to the supported registration-review route.

The bounded R2 inputs are CUSTOM_API documents and specified MCP initialize/tools-list observations. The worked source document now supplies the complete source shape, field descriptions and locally observed discovery results. The complete customer request envelope, target references and delivery package still need confirmation. Generic OpenAPI import, every MCP revision and automatic provider connectivity are not established.

04 · Illustrative walkthrough: describe one read operation

Conceptual example only. Imagine that an engineering team wants one read-only status operation from its own service considered for integration. The team first describes the operation, the information it takes, the information it returns and any non-secret credential reference. This story does not establish support for a particular service or define an executable schema.

After the supplier provides a supported public format and target contract, those descriptions become a declaration. The Helper reads it, normalizes it into a consistent descriptor (a structured description), checks the fields and mappings, and prepares a candidate or reports what is missing. A mapping says which source field corresponds to a target field.

The useful result is a candidate or an explanation of the next required action. For example, REQUIRES_AUTHORITY from r2-submit means the current CLI has not registered the integration; even a valid candidate needs a supported approval and registration route. Keep the candidate locally and ask support for that route, giving the version, operation and sanitized reason. Do not report the service as connected or running from that response. This is an interpretation of the documented behavior, not a captured successful run.

Continue with the same case in Worked examples: complete source JSON, a Contract-reference fragment, recorded local results, negative cases and downloads.

05 · From declaration to execution linkage

Supported preparation stages

Each stage answers a different question: can the input be understood, does it meet the format, what candidate can be prepared, and what approval is still needed? Read the stage reached before deciding your next action.

Do not promote errors, unknowns or authority-pending states to the next stage automatically. This sequence explains the boundaries; it is not a currently complete customer execution procedure.

06 · What to prepare now and request next

Prepare a short integration brief: the goal, intended operation, non-secret input/output descriptions, intended target if already supplied, and questions about required mappings. The exact public format—not this brief—will determine required and optional fields.

Contact support@vibepackr.com to request the matching binary/crate, supported platform and installation instructions, approved public schema with a successful sample, and supported registration route. If you need architecture planning, identify that need and request its public input package too.

For a failed preparation attempt, send the tool/product version, operation, input-schema revision if known, and sanitized status/reason. Ask about the specific missing item: a format mismatch, missing input, unavailable credential reference or registration route. Do not attach the entire document, bundle, log or secret value. Your current deliverable can be a well-defined integration brief while those supplier items remain pending.

07 · Detailed reference: use with a matching deliverable

You can stop the first reading here. For implementation work, start with versions and delivery, then use the relevant R0 or R2 command reference. Architecture planning has a separate input and result format. Use response/error fields to interpret a result and the diagnostic examples only for their stated purpose.

08 · Versions and delivery

Customer delivery confirmation pending

A tool and its input format must agree on versions. Confirm the supplied artifact first so you do not mistake an installation or format mismatch for an integration problem.

The documentation baseline is 0.1.0-r232. Helper R0/R2 and architecture-planning implementations have been identified; this does not mean that every customer image installs the CLI or exposes it on PATH. The existing Rust SDK compatibility declaration is 0.1.x, not an ABI guarantee across every combination.

• Request the exact binary/crate, supported platform, installation method and matching input format from the supplier.
• R0 uses packr.integration-helper.v1; the R2 machine schema is packr.integration-onboarding.r2.v1.
• Current development and a future successor are separate from r232. The final customer delivery version and public successful-input package are pending.
• No unconfirmed package-manager installation command or download URL is provided.

Technical compatibility reference: existing SDK consumers are PackrGUI and the embedded GEC subset. This identifies existing library use, not customer package delivery.

09 · Helper R0 commands

Syntax reference · delivery prerequisites apply

R0 lets you inspect successive views of the same declared source. Use these commands to examine preparation results, not to pipe one result into the next command.

Reference syntax for an environment supplied with the matching binary and input format. source.json is a placeholder for a file you must prepare. Each command consumes the same source JSON; do not pass the previous stdout as the next input.

R0 processes declared HTTP/REST, CLI and executable metadata, structural local IPC, structured manifests and existing runtime-provider metadata within their stated support grades. This preparation path does not run arbitrary shell commands or scan networks. R0 gRPC, WebSocket, SDK generation and repository onboarding are deferred. Successful stdout JSON distinguishes decision=PASS from authority=NONE. Errors use stderr JSON with stage/reason/message and exit code 2.

packr-integration-helper discover source.json
packr-integration-helper normalize source.json
packr-integration-helper validate source.json
packr-integration-helper prepare source.json
packr-integration-helper inspect source.json

10 · Helper R2 commands and required inputs

Syntax reference · delivery prerequisites apply

R2 returns a structured response that a program can read. Choose the operation for the question you need answered and inspect its status and reason before using the result.

Each command reprocesses a matching-version request.json. Required top-level fields are request_id, correlation_id and draft; the exact public draft format is pending delivery.

Confirmed mapping transforms are bounded IDENTITY (including renaming) and STRING_TO_INTEGER. Scaffold generation produces preparation assets marked REQUIRES_IMPLEMENTATION, not a finished SDK/adapter or automatic registration. Retained validation for these six preparation machine operations is limited to a local synthetic environment.

Use the input and result walkthrough to distinguish the source document from the complete request. R2 semantic denial can return process exit code 0: inspect status and reason.

packr-integration-helper r2-discover request.json
packr-integration-helper r2-normalize request.json
packr-integration-helper r2-validate request.json
packr-integration-helper r2-prepare request.json
packr-integration-helper r2-status request.json
packr-integration-helper r2-submit request.json

11 · Contract-bound planning and result validation

Public customer support unconfirmed

Architecture planning compares a requested integration with the product’s known components and relationships. It helps expose missing connections or inputs before anyone attempts execution.

Implementation identified · public customer support pending confirmation

r2-plan-architecture consumes validated structural information and exact product contract/target/required-input bindings to produce a binding plan, validation plan, gap report and guide projection. r2-validate-architecture-bundle checks the generated bundle’s format, identities, consistency and absence of granted authority.

Once a public format is supplied, the user authors the requested target and permitted inputs. Users do not invent product contract, registration, ownership or authority facts, or internal structural snapshots, to assert success. The complete input’s public support contract and customer delivery package are unconfirmed, so executable input and command examples are withheld.

The output name public_guide does not authorize publishing the entire bundle. Do not send full internal bundles or snapshots to customers. Successful bundle validation is not deployment, a provider call or authority issuance.

12 · Responses, errors and next actions

Implementation-based reference

A command finishing normally only means its process ended. The response says whether the requested preparation step succeeded and what still needs attention.

R2 denials are also returned as stdout JSON envelopes, and the process may exit normally. Do not mark success from the exit code alone.

This is not a complete error list. Preserve unknown reasons too. Architecture-planning responses differ from this machine envelope; inspect READY/NOT_READY or the validation result in that format.

13 · Minimal error-handling and Rust API examples

Static example · product execution unverified

These two small references answer narrow diagnostic questions: can you handle an invalid request response, and can a supplied Rust library expose its schema constant? They do not demonstrate a successful integration.

Reference examples for a development environment supplied with the binary/crate through an approved route. They were not executed or compiled in this documentation task. In invalid-request.json, save only {}, then use the command below to check a missing-required-input response.

Statically expected fields are status=DENIED, reason=INVALID_REQUEST, request_id=UNAVAILABLE and result=null. A successful example will be added when the public input format/sample is confirmed.

The Rust example prints the public schema constant. Its expected value is packr.integration-helper.v1; this does not validate crate installation, distribution or ABI compatibility.

packr-integration-helper r2-validate invalid-request.json

use packr_engine_core::integration_helper::INTEGRATION_HELPER_SCHEMA_VERSION;

fn main() {
    println!("{}", INTEGRATION_HELPER_SCHEMA_VERSION);
}

14 · Authentication, data and support

Access and safe support requests

When asking for help, a version and a short result usually identify the failing step more safely than a complete input file. Keep access details and customer data out of the request.

Local file-read/execution permissions are required but do not substitute for product registration or work authority. Helper preparation commands do not issue a remote authentication session or registration authority. Distinguish a credential reference from actual secret availability.

• Do not put passwords, tokens, private keys or raw credentials in requests.
• Input files remain caller-owned; the Helper not retaining them does not delete the caller’s files.
• Real provider/customer-data processing requires separate supported connectivity, authority and data conditions.
• Confirm pending language bindings, installation routes, public successful schemas, architecture-input packages and registration transport with the supplier.

Contact support@vibepackr.com with the version, operation and sanitized status/reason. Do not send full input documents, bundles, logs or secrets.

15 · Integration glossary

Contract

The supported target interface and conditions the product checks against.

Document / declaration

Your description of an integration in a supported format. It supplies information for checking; it does not grant permission.

Descriptor / normalization

A descriptor is a structured description. Normalization puts supported input into a consistent representation.

Candidate

A prepared integration proposed for registration review.

SDK / API

A software development kit provides a programming surface; an application programming interface defines how software calls it. The supported Packit boundary here is the public Rust API described above.

GAPE

The source of structural observations about product components and their relationships used by architecture planning.

Credential reference

A supported identifier referring to credentials, not the secret value or proof that the credentials are available.

Binding / READY

A binding associates exact items, such as an integration revision and target. READY in a planning result means the planning checks were satisfied; actual work still needs its own access and approval.

16 · Common integration questions

Can I begin with an existing API description?

Use it to prepare the integration brief. The accepted executable input is limited to the supplied format: bounded CUSTOM_API and specified MCP observations are described in the reference. Generic OpenAPI import or every MCP revision is not promised.

Does prepare or submit make the integration usable?

Preparation creates a candidate. The current R2 CLI submit still requires authority and has no trusted registration transport. Registration and work execution need their respective supported routes.

Where are the positive JSON examples?

The worked examples include complete source documents and their locally observed discovery results. They are not full CLI request envelopes. The minimal {} CLI example deliberately shows a denial; a complete customer request package with supported target references is still pending.

Do I need Vertex AI just to prepare a Helper candidate?

The bounded R2 preparation machinery does not require cloud AI. Customer AI work is a separate path with its own setup and validation requirements.

Should I send a full request file to support?

Start with the minimum version, operation and sanitized status/reason in the support request guidance. Keep secrets, full input documents and internal bundles out of the message.