# AgentOS X · AGPK Software Build Standard v1.2

Public standard for **Agent Packages** on AgentOS X.  
**Principle:** agent-first packages — command face, install registry, list_commands, invoke (C1–C4). Installing software must not require re-baking the ISO.

## 1. Purpose

How software is **packaged, discovered, installed, used, and removed** on AgentOS X so:

- **Agents are the primary consumers** (command face + invoke)
- Humans choose options and approve installs
- Vendors share one build format — **agentized**, not bare tarballs
- **Installing software does not require re-baking the ISO** (platform hosts discover/register/invoke only)

**Vendor toolkit:** market package `org.agentnet.agpk.sdk` **1.2.0** (AGPK-MARKET release).

## 2. Channels (only two)

| Source | Meaning |
|---|---|
| `preinstall` | Image-baked platform defaults |
| `agent_package` | Packages built to this standard (market / local) |

## 3. Minimal deliverables

| File | Required |
|---|---|
| `agpk.json` | yes |
| `payload/` | yes |
| `DIGESTS` | yes for release |
| `INSTALL` / `UNINSTALL` | yes |
| `agent-commands.json` | **yes** — C1 command face |
| `USAGE.md` or `AGENT_CAPABILITIES.md` | **yes** — usage guidance |
| `surface.json` | recommended; required for badge `full` |

### agent-commands.json (C1 / C4)

- `driver.kind`: `process` \| `script` \| `cli_scripts` \| `package_declared` \| `agentx_chrome_tools` \| `agentx_builtin_family`
- Each command: stable `id`; for process/script-like drivers, non-empty **`entry`** argv (paths relative to install root)
- Market scan **discards/rejects** packages without a valid command face

## 4. Build with SDK

```bash
# after installing org.agentnet.agpk.sdk (or unpacking its release tarball)
./bin/agpk-scaffold ./pkg com.you.app "App"
./bin/agpk-validate ./pkg
./bin/agpk-pack ./pkg
```

AgentOS CLI (when available on the host):

```bash
agentx agpk scaffold ./pkg --id vendor.app --name "App"
agentx agpk pack ./pkg
agentx agpk validate ./pkg
```

## 5. Install / discover / invoke / uninstall (runtime)

```text
agentx agpk list-options [--query Q]
agentx agpk install <id|path|source_ref> --approve [-y]
agentx agpk list-commands [--package-id ID]    # C3 first-class discovery
agentx agpk invoke <command_id> [--args '{}']  # C4 first-class use
agentx agpk list | show | verify
agentx agpk remove <id> --approve [-y]
```

Agent tools (same names): `agpk.list_options`, `agpk.install`, **`agpk.list_commands`**, **`agpk.invoke`**, `agpk.remove`, …

Rules:

- Mutations need **human approval**; unsigned needs **y** / `ack_unsigned`
- Install **writes system registry** (`$AGENTX_HOME/agpk/commands/`)
- Remove unregisters commands/surface
- Human review of results: **`projection.*`**, not GUI primary path

## 6. Catalog

- Index: [`/agpk/v1/catalog.schema.json`](/agpk/v1/catalog.schema.json)
- First-party: [`/agpk/v1/firstparty-catalog.json`](/agpk/v1/firstparty-catalog.json)
- Live market: `GET https://api.agentnet.ink/share/v1/agpk/sources`

## 7. Official AgentNet packages (market · complete)

| package_id | Version | Notes |
|---|---|---|
| `org.chromium.Chromium.runtime` | 1.2.0 | Engine + chrome.* face (sample) |
| `org.agentnet.agpk.sdk` | 1.2.0 | Vendor scaffold/pack/validate |
| `org.actualbudget.Actual.agent` | 1.1.0 | Budget agent |
| `org.bookstack.BookStack.agent` | 1.1.0 | Wiki agent |
| `org.docuseal.DocuSeal.agent` | 1.1.0 | E-sign agent |
| `org.crater.Crater.agent` | 1.1.0 | Invoice agent |
| `org.nextcloud.Nextcloud.agent` | 1.1.0 | Files agent |
| `org.jitsi.JitsiMeet.agent` | 1.1.0 | Meetings agent |
| `org.audacityteam.Audacity.agent` | 1.1.0 | Audio agent |
| `org.kde.Kdenlive.agent` | 1.1.0 | Video agent |

**Office suite and IM are system preinstall — not AGPK market packages.**  
JSON index: [`/agpk/v1/firstparty-catalog.json`](/agpk/v1/firstparty-catalog.json).

## 8. AGIN / AGPK / AHCP

| Code | Role |
|---|---|
| **AGIN** | Who acts |
| **AGPK** | What is installed (and how agents discover/invoke it) |
| **AHCP** | How deep agent can use software after install (surface) |

## 9. Machine-readable

| URL | Content |
|---|---|
| `/agpk/v1/schema.json` | Package manifest schema |
| `/agpk/v1/catalog.schema.json` | Catalog schema |
| `/agpk/v1/builder-standard.md` | This document |
| `/agpk/v1/sdk.md` | SDK guide |
| `/agpk/v1/firstparty-catalog.json` | First-party index |