---
audience: agent-operator
publication: agent-reference
stable_id: aiwg.agent-reference.git-native-marketplace
---

# Git-Native Package Exchange

Marketplace provenance remains authoritative in this workflow. Dataset
Intelligence can project its core agents, entities, activities, and relations,
but non-core attributes require a governed extension; see the [dataset
migration guide](../addons/dataset-intelligence/migration-guide.md).

AIWG can exchange frameworks, addons, extensions, and standalone plugin
wrappers directly through Git. A catalog improves discovery but is not a
central authority: package identity and integrity remain bound to the
publisher's canonical Git remote, immutable commit, Git tree, artifact
inventory, signature, and local trust policy.

The exchange stores W3C PROV evidence in a lossless Fortemi Knowledge Shard
`2.0.0/full-v1`. It also records operation receipts for publish, install,
verify, export, and import.

## Consumer quickstart

Pin a tag or commit before deploying. Project-local state is recommended for
team repositories because the lock, receipts, Fortemi shard, package registry,
and marketplace index stay under the project's `.aiwg/` directory.

```bash
aiwg install https://git.example.org/team/agent-pack.git \
  --ref v1.2.3 \
  --package agent-pack \
  --project-local \
  --deploy \
  --provider claude

aiwg marketplace verify team/agent-pack --project-local
```

Use `--global` instead of `--project-local` to make the package available from
the user AIWG configuration. Global is the default when neither flag is
present. `--target <directory>` selects the project for local state and
deployment. The two scope flags are mutually exclusive.

A repository may contain a root bundle or a standalone
`.aiwg/plugins/<id>/manifest.json` wrapper. Use `--package <id>` when more than
one standalone wrapper is present. Repositories with no deployable artifact,
ambiguous wrappers, unsafe paths, or wrapper/payload type mismatches fail
before registration or deployment.

Without a trusted publisher signature, a valid direct package is recorded as
`integrity-only`. Add `--verify` when installation must require a valid Ed25519
signature chained to a local trust root. Verification fails closed on unknown
required fields, signature or digest mismatch, dependency substitution,
rollback, disallowed deprecation/yanking, or a mutable ref moving against an
existing lock.

## State and trust

Marketplace state lives in one of these locations:

- project: `<project>/.aiwg/marketplace/`
- global: `~/.aiwg/marketplace/` (or the active global AIWG config directory)

Each scope has its own `index.json`, `catalogs.json`, `trust.json`, immutable
package records, receipts, Fortemi shards, and imported artifact cache. Normal
install, import, verify, catalog-add, and catalog-remove operations update the
selected index atomically.

`trust.json` uses
`schemas/marketplace/aiwg-marketplace-trust.v1.schema.json`. A trust root has
`trustRoot: true`; a rotated or delegated key names `delegatedBy` and includes
the delegation signature. `validFrom`, `validUntil`, `revokedAt`, and
`revocationReason` constrain acceptance. Named policies can be stored under
`policies` and selected with `--policy <name>`. A JSON policy path is also
accepted.

Trust is local policy, not a catalog claim. AIWG distinguishes:

- publisher claims in the signed provenance envelope;
- catalog observations in a separately signed catalog;
- local trust roots and policy decisions;
- local verification and operation receipts.

Catalog inclusion is never presented as an AIWG endorsement.

## Author and publisher workflow

1. Put a valid root bundle or standalone plugin wrapper in a Git repository.
2. Include an explicit package version, provider matrix, dependency contract,
   and license. An SBOM may be included and bound by path and digest.
3. Commit the exact bytes and create the intended release tag.
4. Keep the Ed25519 private key outside the repository.
5. Publish the signed envelope and Fortemi evidence.

```bash
openssl genpkey -algorithm ED25519 -out publisher-private.pem
chmod 600 publisher-private.pem
openssl pkey -in publisher-private.pem -pubout -out publisher-public.pem

aiwg marketplace publish . \
  --package agent-pack \
  --ref v1.2.3 \
  --publisher team.example \
  --key-file /secure/publisher-private.pem \
  --public-key publisher-public.pem \
  --sequence 1
```

Supply multiline private PEM through `--key-stdin`, `--key-file <path>`,
`--key-store <name>`, `--key-env <NAME>`, or masked terminal entry
(`--key-interactive`; finish the paste with an empty line). With no source, a terminal prompts; headless use must
select a source. Files must be regular, owned by the current user, have no
group/other access, and have no symlink or extra hard link. `--key <path>`
remains an alias for private-file input. See [supplying sensitive values](../cli/sensitive-values.md)
for source precedence and handling guidance. Private PEM is never printed.

Publication writes an envelope, immutable lock, publish receipt, and
`provenance.full-v1.shard`. Do not commit a private key, credential, private
artifact, or sensitive environment detail into a package, envelope, catalog,
receipt, or portable archive.

The versioned schemas under `schemas/marketplace/` are closed contracts. New
required fields need a new schema version and explicit consumer support;
unknown fields are not silently discarded.

## Catalog operator workflow

A catalog repository contains `aiwg-marketplace-catalog.json` or
`.aiwg/marketplace/catalog.json`. Its signed entries point to publisher
envelopes and immutable locks. Catalog sequence numbers support rollback
detection.

```bash
aiwg marketplace add https://git.example.org/catalogs/community.git \
  --ref 9f8e7d6c5b4a32100123456789abcdef01234567 \
  --project-local

aiwg marketplace search observability --project-local
aiwg marketplace info team/agent-pack --project-local
aiwg marketplace install team/agent-pack@1.2.3 --project-local --verify
```

Multiple catalogs can coexist. Package coordinates are resolved only when
unambiguous. Direct Git and catalog installs produce the same lock when they
identify the same immutable package. Removing a catalog removes discovery
state only; existing package locks, cached bytes, and receipts remain valid:

```bash
aiwg marketplace remove community --project-local
```

## Offline export, mirror, and recovery

Export produces a deterministic JSON package containing the exact envelope,
lock, receipts, Fortemi full-v1 shard, artifact paths, modes, hashes, and
base64-encoded bytes:

```bash
aiwg marketplace export team/agent-pack \
  --project-local \
  --output agent-pack.aiwg.json
```

Move the archive through the approved offline channel, then import and verify
without contacting the publisher or a catalog:

```bash
aiwg marketplace import agent-pack.aiwg.json --project-local
aiwg marketplace verify team/agent-pack --project-local
```

Import validates the complete archive and stages bytes before changing the
local index. Archive/Git divergence, altered files, unsafe paths, malformed
Fortemi evidence, or a lock/envelope mismatch aborts the operation. A mirror
may retain Git objects, signed catalogs, and portable archives, but must not
rewrite them; consumers still verify publisher identity and local trust.

Portable bundle v1 remains the readable legacy marketplace-only format.
Portable bundle v2 is a separate strict format: it carries the adjacent
cross-asset attestation, the exact bytes of every signed material, and nested
bundles for required immutable dependencies. Import requires an already
bootstrapped scoped cross-asset trust root/state, verifies the complete
dependency tree and both evidence paths offline, and only then writes package
bytes, sidecars, material paths, or index entries. A trust root requiring dual
or cross-asset evidence therefore cannot silently accept a v1 dependency.
The v2 API returns the verifier's advanced cross-asset freshness state after
all recursive members; the caller must persist that state atomically with its
trust-state workflow before treating the import as the new channel baseline.
The legacy marketplace publisher signature remains mandatory unless the
authenticated root explicitly enables the cross-asset migration gate.

For recovery, restore the portable archive and scoped `trust.json`, import the
archive, and run offline verification. Catalog availability is not required
when the immutable lock and evidence are present.

## Key rotation and revocation

Rotate keys by delegating a new public key from a currently trusted key,
setting a non-overlapping validity policy where practical, and publishing the
updated trust material through the organization's controlled channel. Test the
new chain before retiring the old key.

When a key is compromised, set `revokedAt` and a reason in every applicable
trust scope. Current verification rejects a revoked signing key even when the
package signature predates discovery of the compromise. Existing locks still
identify bytes, but their trust result changes according to current policy.

The accepted [cross-asset authenticity
contract](../research/asset-authenticity-and-provenance.md) preserves these
marketplace controls. Its migration bridge signs the closed marketplace
envelope as an in-toto subject and links the Fortemi shard, receipt, inventory,
and immutable Git material digests. Both the current marketplace signature and
the cross-asset attestation must verify during the compatibility window.

## Command summary

```text
aiwg install <git-url> --ref <tag-or-sha> [--package <id>] [--project-local|--global]
aiwg marketplace add <catalog-git-url> [--ref <tag-or-sha>]
aiwg marketplace search <query>
aiwg marketplace info <identity[@version]|lock-id>
aiwg marketplace install <git-url|identity[@version]>
aiwg marketplace verify <identity[@version]|lock-id>
aiwg marketplace export <identity[@version]|lock-id> --output <archive.json>
aiwg marketplace import <archive.json>
aiwg marketplace publish <source> --publisher <id> [--key-file <pem> | --key-stdin]
aiwg marketplace remove <catalog-id>
aiwg marketplace list
```

All commands that read or write package state accept `--project-local` or
`--global`; project-local commands also accept `--target <directory>`.
