# AHCP Vendor Engineering Handbook (v1)

> Public engineering guide: ship software that agents can use at human parity depth.
> Pairs with **AGPK** (how binaries land on disk).

## 1. Goal

**AHCP axiom:** Whatever depth a human can reach in the software, an agent can reach via commands.

This handbook is the **turnkey** path: surface declaration → scaffold → host register → optional AGPK packaging → badge.

## 2. Deliverables checklist

| Artifact | Required | Notes |
|---|---|---|
| `surface.json` | Yes for parity claims | Schema: `schema/ahcp.surface.schema.json` |
| Commands table | Yes | Stable command ids agents call |
| Parity tasks | Yes for Full | Human path ↔ agent command |
| Conformance run | Yes for Full | `validate_surface.py` |
| AGPK package | Recommended | So agents install with `agpk install` |
| Signature | Recommended | Unsigned installs need human `y` / checkbox |

## 3. Scaffold

```bash
# Via AgentOS X CLI
agentx agpk surface-scaffold ./my-app --software org.example.App --vendor "Example Inc"
agentx agpk scaffold ./my-agpk --id org.example.app --name "Example App"
# Place surface.json into package root; set ahcp.signed + badge when ready
agentx agpk pack ./my-agpk
agentx agpk validate ./my-agpk
```

SDK (Rust host helpers): `product_agentx::agpk::host::sdk::{surface_skeleton, write_surface_scaffold, manifest_template}`.

## 4. Host load / register

On AgentOS X after `agpk install`:

1. Host reads package `ahcp.surface` path.
2. Validates JSON has `ahcp_version`.
3. Copies to `$AGENTX_HOME/agpk/surfaces/<package_id>.surface.json`.
4. Indexes in `surfaces/registry.json`.
5. Uninstall unregisters surface.

Errors: missing surface → skip register (warn); invalid JSON → fail register; Full badge without surface → validate fails at pack time.

## 5. Badge rules (protocol)

- **full**: no uncovered features; every command shipped; parity coverage; schema + dispatch aligned  
- **partial / experimental**: honest gaps allowed  
- Never claim Full for a narrowed toy object without declaring the software boundary

## 6. Security & install UX

- AGPK does **not** block unsigned packages.
- Host **must** show security prompt and require explicit human ack (`y` / checkbox) when `ahcp.signed=false`.
- No sensitivity tiers on install — human chooses options the model/agent presents.

## 7. Publish surfaces

- Machine-readable protocol: public docs `/ahcp/v1/*`
- Human docs: website AHCP section + this handbook
- Sample: Chromium Full package under `samples/browser.surface.json`

## 8. Non-goals

- AHCP is not the package channel (that's AGPK).
- MCP market is not application install.
- Do not publish control-plane secrets or key derivation.