# Ferrite Agent Plugin

Install the Ferrite skill, CLI, and stateless MCP configuration as one versioned agent bundle.

The Ferrite Agent Plugin gives an agent three coordinated tools: a skill that
explains the correct workflow, a pinned Ferrite CLI, and a stateless HTTP MCP
connection for remote platform operations.

## Install the plugin

```bash
codex plugin marketplace add iGentAI/ferrite-labs
codex plugin add ferrite@ferrite-labs
```

That installs the Ferrite skill and MCP connection from the company
marketplace. The skill installs its checksum-pinned CLI the first time a local
workflow needs it, after asking for permission to write the user-owned binary.

For a single command:

```bash
codex plugin marketplace add iGentAI/ferrite-labs && codex plugin add ferrite@ferrite-labs
```

Then configure an account without placing a bearer token in the plugin:

```bash
ferrite login --ephemeral
ferrite account
```

You can also [download the portable plugin bundle](https://docs.ferrite.dev.aws.igent.ai/downloads/ferrite-agent-plugin.tar.gz)
and inspect its [checksum ledger](https://docs.ferrite.dev.aws.igent.ai/downloads/ferrite-agent-plugin.sha256).

Open the [Ferrite Dashboard](https://dashboard.ferrite.dev.aws.igent.ai) to see
the apps and deployments created by the CLI or MCP.

## What the plugin configures

| Part | Purpose |
| --- | --- |
| Ferrite skill | Routes local development to the CLI and compact remote work to MCP |
| `mcp.json` | Connects to the streamable HTTP Ferrite MCP endpoint |
| CLI archive | Installs a pinned platform-compatible binary without root access |
| Install scripts | Verify checksum, version, archive paths, and ownership before writing |

The installer writes atomically to a user-owned bin directory. Uninstall removes
only a binary recorded as plugin-owned; it will not delete an unrelated
`ferrite` executable.

## How agents should use it

- Use the CLI for `new`, `add`, source edits, `check`, `test`, `dev`, preview,
  deploy, logs, and multi-step lifecycle operations.
- Use MCP for account and app discovery, focused remote reads, and one bounded
  control-plane mutation.
- Do not rebuild a CLI workflow as a long chain of MCP calls.
- Treat missing CLI, version mismatch, missing login, and denied authority as
  different errors with different recovery commands.

## Verify an installation

```bash
node scripts/validate-ferrite-plugin.mjs plugins/ferrite
scripts/test-ferrite-plugin.sh
devx-eval plugin-check --marketplace iGentAI/ferrite-labs \
  --output plugin-check.json
```

The validation checks schema, checksums, archive containment, supported
platforms, repeat installation, safe uninstall, authentication behavior, and
fresh-client discovery. A valid bundle does not imply a successful account
login or application deployment; verify those separately.