# Container skill packaging (v1 pilot)

Signature: ♾️  
Live product: https://lvlltd.com  
Schema: `/schemas/container-skill-packaging.v1.schema.json` (repo)  
Pilot: `data/packaging-pilot.json`  
Examples: `packaging/container-skill/`

## Why (aligned to industry findings, not hype)

Agentic AI is past pure experiments for many orgs, but **sharing and packaging agents/skills remains the least mature leg**. Containers are already the default substrate for agent work; security/compliance and orchestration complexity remain the top scaling barriers. lvlltd.com already solves discovery + x402 pay + on-chain verified unlock. This pilot closes the **portable packaging** gap **without rewriting** the payment spine.

## Evolutionary model (not a rewrite)

```
Free outline/sample
  → GET /api/pay?skill=…  (HTTP 402)
  → USDC on Base
  → POST /api/pay  (verified unlock)
  → sealed_pack.files          ← remains primary
  → optional: docker build     ← additive isolation/portability
```

| Layer | Role |
|-------|------|
| Sealed pack | Canonical post-pay artifact (grandfathered) |
| Reference Dockerfile | Documented, buildable packaging for flagships |
| Scan + detached sign | Later maturity rung — **not claimed in Phase 1** |
| OCI registry publish | Later maturity rung — **not claimed** |

## Maturity ladder (honest only)

Strict pilot ladder for dual harden:

`reference_dockerfile` → `scanned` → `signed` → **`scanned_and_signed`**

| Level | Meaning |
|-------|---------|
| `sealed_pack_only` | Default for most catalog skills |
| `reference_dockerfile` | Pilot Dockerfiles exist in-repo |
| `buildable_local` | Verified `docker build` on CI or operator machine |
| `image_published` | Real public/private image ref (**not claimed in pilot**) |
| `signed` | Detached signature exists (verify may still be pending) |
| `scanned` | Scan status `pass` (policy/lint or scanner) |
| **`scanned_and_signed`** | **Both** `scan.status=pass` **and** `signature.status=verified` |
| `enterprise_ready` | **Never emitted** by this pilot |

**Never emit higher badges than maturity + security fields justify.**

## Status field dictionary

### Nested (schema / pilot JSON)

| Field | Values | Meaning |
|-------|--------|---------|
| `security.scan.status` | `none` `planned` `pass` `fail` `manual` | Schema uses **`pass`**, not `passed` |
| `security.scan.tool` | string | e.g. `lvl-dockerfile-lint-v1` |
| `security.scan.summary` | string | Human-readable one-liner |
| `security.signature.status` | `none` `planned` `detached` `verified` `cosign` `other` | **`verified`** only after `verify-skill` succeeds |
| `security.signature.key_id` | string | e.g. `lvl-packaging-pilot-ed25519-v1` |
| `security.signature.public_key_uri` | path | Public key location |
| `maturity` | ladder enum | Dual harden → `scanned_and_signed` |

### Compact (catalog `packaging` object)

| Catalog field | Source |
|---------------|--------|
| `scan_status` | `security.scan.status` |
| `scan_summary` | `security.scan.summary` |
| `scan_tool` | `security.scan.tool` |
| `signature_status` | `security.signature.status` |
| `signature_key_id` | `security.signature.key_id` |
| `maturity` | `maturity` |

## Catalog / API fields

On public catalog skill objects (when pilot data applies):

```json
{
  "id": "seller-agent",
  "packaging": {
    "schema": "lvl-container-skill-packaging-v1",
    "maturity": "reference_dockerfile",
    "dockerfile": "packaging/container-skill/examples/seller-agent/Dockerfile",
    "isolation": "container_recommended",
    "mcp_posture": "not_required",
    "scan_status": "planned",
    "signature_status": "planned",
    "sbom_status": "planned",
    "primary_distribution": "sealed_pack"
  },
  "trust_badges": [
    "sealed_pack",
    "reference_dockerfile",
    "x402_unlock",
    "onchain_proof"
  ]
}
```

**Phase 1 production:** maturity is **`reference_dockerfile` only**.  
Allowed badges only: `sealed_pack` · `reference_dockerfile` · `x402_unlock` · `onchain_proof`.  
Scan / signature / SBOM remain **`planned`** — not claimed pass/verified. No `enterprise_ready`.

Full packaging records stay in `data/packaging-pilot.json` and are copied to `public/packaging-pilot.json` at build.

## Signature / scan (not claimed in Phase 1)

Optional local scripts under `packaging/container-skill/scripts/` may exist for future harden work.  
**Phase 1 production does not claim scan pass, signatures, or enterprise certification.**

| Script | Role |
|--------|------|
| `scan-skill.sh` | trivy/hadolint if present; else `dockerfile-lint.mjs` |
| `sign-skill.sh` | openssl Ed25519 detached sign |
| `verify-skill.sh` | openssl verify |
| `harden-pilot.mjs` | all five pilots + pilot JSON update |

## Secure-by-default (architecture notes)

For every skill (pilot + future uploads):

1. **Isolation** — recommend container; never require privileged host access.  
2. **Least privilege** — drop capabilities; no Docker socket.  
3. **Credentials** — env / wallet signatures only; no long-lived keys in packs.  
4. **Non-goals** — documented per skill (e.g. no unconstrained host FS).  
5. **MCP** — optional wrapper only until isolation + credential controls mature.  
6. **Revenue honesty** — packaging never invents unlocks, volume, or conversion lift.

## Open-market uploads (policy direction)

| Phase | Policy |
|-------|--------|
| Now | Sealed packs accepted; container optional |
| Next | Strongly incentivize reference Dockerfile + ranking boost |
| Later | Auto-scan on upload; signed digests for enterprise shelf |

Grandfather: existing sealed packs keep selling; migration tooling is additive.

## Enterprise pitch (truthful language)

Use:

> **Container-ready, signed-ready agent skills with on-chain x402 proof.**  
> Free samples → Base USDC unlock → sealed packs you can re-download.  
> Pilot skills ship reference Dockerfiles for local isolation; SBOM/scan/sign land as maturity advances.  
> Multi-model, multi-cloud friendly — skills are portable Node packages, not a single-vendor runtime lock-in.

Avoid:

- “Fully enterprise certified” without scans/SLAs  
- “Autonomous swarm runs itself on Pages”  
- Invented adoption or conversion percentages  

## Pilot skill set (Phase 1)

| Skill | Why |
|-------|-----|
| `agent-x402-first-buy` | Starter commerce path |
| `seller-agent` / `buyer-agent` | High-ticket commerce agents |
| `agent-orchestration` | Orchestration pain |
| `revenue-truth-ledger` | Finance trust / confirmed-only discipline |

**All five:** `maturity: reference_dockerfile`. Badges: sealed_pack · reference_dockerfile · x402_unlock · onchain_proof only.

## Current maturity limits (honest — Phase 1 production)

| Claim | Status |
|-------|--------|
| Reference Dockerfile per pilot | ✅ |
| Catalog `packaging` fragment + four badges | ✅ |
| Sealed pack primary unlock (x402) | ✅ unchanged |
| Scan pass / signature verified | ❌ not claimed (status `planned`) |
| Image published to registry | ❌ |
| Cosign / Sigstore / Trivy | ❌ not claimed |
| SBOM published | ❌ planned |
| `enterprise_ready` | ❌ never |

## Operator commands

```bash
# Build catalog (merges packaging into public skills)
node scripts/build-catalog.js

# Optional local image (Docker required) — build only, not publish
docker build -f packaging/container-skill/examples/seller-agent/Dockerfile \
  -t lvlltd/seller-agent:local goods/sealed/seller-agent
```

## Measurement (no fake baselines)

Track only real ledger/events when available:

- Unlock rate for pilot vs non-pilot (from confirmed `/api/revenue` by_skill when present)  
- Support tickets about install friction  
- Count of skills with packaging maturity `reference_dockerfile` (Phase 1)

Do not publish estimated conversion lift until A/B exists.

## Open pipeline (Phase 4)

```bash
# Register a skill that has packaging/container-skill/examples/<id>/Dockerfile
node packaging/container-skill/scripts/harden-skill.mjs --register <skill-id>

# Harden all packaging-registered skills + rebuild catalog + trust summary
node packaging/container-skill/scripts/harden-skill.mjs --all --catalog

# Public trust surfaces
#   /trust/packaging.json  /trust/packaging/  /api/packaging?skill=<id>
```

Upload QC rejects self-attested `scanned` / `signed` / `scanned_and_signed` and any “enterprise-ready” packaging claim. Higher badges only after pipeline tools report pass/verified.

## Roadmap hook

| Window | Work |
|--------|------|
| Phase 1 | ✅ Schema + pilot Dockerfiles + catalog merge + docs |
| Phase 4 | ✅ Open pipeline beyond pilots · public trust surface · productized Catalog Scanner / Trust Reporter |
| Later | trivy/cosign when installed; upload-path auto-register on packaging fields |
| Later | Continuous Trust Fleet apply mode with human quarantine gate |

## Related

- `docs/X402-UNLOCK.md` — payment unlock  
- `docs/A2A-SWARM.md` — orchestration plans  
- `docs/CATALOG-CLEANUP.md` — listing quality  
- `SECURITY.md` — platform security baseline