# Forge agent package interoperability

The full Pipeline Forge and the standalone Zynga Forge executor use the same
`forge.agent-package.v2` format. Forge Studio may create and refine agents here; the standalone
distribution only verifies, imports, commissions, and executes them.

## 1. Create your developer identity once

```bash
./forge agent keygen \
  --developer-id asubramanian \
  --display-name "Aravind Subramanian"
```

By default this creates:

- `~/.config/forge/agent-developer-ed25519.pem` — private signing key, mode `0600`; never share it.
- `~/.config/forge/agent-developer-identity.json` — public identity; share this with Forge admins.

The command prints the Ed25519 SHA-256 fingerprint. Verify that exact fingerprint with the
executor administrator over a separate trusted channel.

This workstation's shareable public identity is also recorded at
`config/agent-developers/asubramanian.public.json`. Its presence in source control does not grant
trust; every executor administrator must still compare the fingerprint independently and run the
explicit trust command. The matching private key remains only in `~/.config/forge/`.

## 2. Create and export agents

Start the full Forge UI with `./forge start`, open an agent in Studio, and choose **Export** then
**Export package**. Forge automatically uses the default developer identity above and downloads one
signed `.forge-agent` file. Collaboration controls remain available under **Collaboration settings**
but are not part of the export flow.

The package includes the agent definition, capability contract, profile snapshot, dependency
manifest, complete portable folders for every required skill, and the sealed bytes/contracts for
Fabric-generated JSX or typed-plan capabilities. Built-in and native providers are recorded as
availability-checked Executor requirements because their host applications and runtime adapters are part of
the destination installation. Export fails instead of silently producing a partial package when a
required skill or referenced generated implementation cannot be found or verified. Credentials,
workstation roots, runtime memory/cache, certifications, approvals, and production authority are
excluded.

Claude, Codex, or Antigravity can also author an agent JSON file and package it directly:

```bash
./forge agent package /path/to/agent.json \
  --output /path/to/agent.forge-agent \
  --workspace tech-art \
  --skill-dir .claude/skills
```

Use `./forge agent inspect /path/to/agent.forge-agent` to review a package locally.

## 3. Trust the developer on the executor

Trust is an explicit local administrator action. Use the fingerprint obtained through the trusted
channel, not a value copied only from the package:

```bash
"$HOME/Library/Application Support/Zynga Forge/bin/forge" agent trust add \
  ~/.config/forge/agent-developer-identity.json \
  --fingerprint "ed25519:sha256:PASTE_VERIFIED_FINGERPRINT"
```

Then install the package:

```bash
"$HOME/Library/Application Support/Zynga Forge/bin/forge" agent install \
  /path/to/agent.forge-agent
```

Before writing anything, the importer verifies the signature and checks the destination profile,
runtime, capabilities, and required skills. Bundled skills and generated implementations are
installed automatically in quarantine. Imported generated implementations begin a new local
candidate lifecycle; source pilot/production approvals and source filesystem bindings are removed.
If a required built-in/native Executor capability is unavailable, import stops with the missing
dependency instead of creating a partially runnable agent.

Every imported agent starts disabled, decommissioned, and excluded from automatic routing. Review
its dependencies and complete the existing qualification/commissioning flow before execution.

## Security model

- Private developer keys are never committed, exported, copied into an agent package, or stored by
  the executor.
- The package contains the public identity and a signature over its content-addressed manifest.
- Unknown, revoked, conflicting, malformed, and unsigned developer packages are quarantined.
- A valid developer signature proves package authorship and integrity only. It never grants
  credentials, approvals, certification, commissioning, or production execution authority.