# Use Ginse from Codex

Ginse is the app store and fake transaction layer used by the human's agent. It is not a chat participant and it does not host builder code.

## Install the pinned CLI

1. Fetch `https://app.ginse.ai/versions.json`.
2. Download the exact `cli.url` to a local temporary `.tgz` and verify that local file against `cli.sha256`.
3. Install the same verified local file. Do not give the URL to npm, because that would download a different copy after verification:

```sh
CLI_ARCHIVE="$(mktemp -t ginse-cli.XXXXXX.tgz)"
curl --fail --location "$CLI_URL" --output "$CLI_ARCHIVE"
printf '%s  %s\n' "$CLI_SHA256" "$CLI_ARCHIVE" | shasum -a 256 --check
npm install --global "$CLI_ARCHIVE"
ginse doctor --json
```

Set `CLI_URL` and `CLI_SHA256` from the parsed `versions.json` fields before running these commands.

Do not substitute a similarly named npm registry package. The marketplace tarball is the hackathon release channel.

## Install the focused skills

Copy the current `SKILL.md` files from these versioned URLs into the repository's `.agents/skills/<name>/SKILL.md` paths:

- `https://app.ginse.ai/skills/0.2.0/ginse-account/SKILL.md`
- `https://app.ginse.ai/skills/0.2.0/ginse-use/SKILL.md`
- `https://app.ginse.ai/skills/0.2.0/ginse-publish/SKILL.md`

Verify each file against its digest in `versions.json`. Read only the skill that matches the current task. Codex discovers repository skills automatically; restart Codex only if a new skill does not appear.

## Create or connect the first account and wallet

```sh
ginse auth status --json
```

If status has `data.pending_authorization`, resume it with `ginse auth complete --json`; do not start another login. Only when status is unauthenticated and has no pending authorization, run `ginse auth login --no-wait --json`. Give the human `data.human_action.url`. They sign in with an allowlisted email and approve Codex. That first magic-link sign-in atomically creates the account and fake EUR wallet with €10 of hackathon test balance; no card, Stripe step, or initial deposit exists. After approval:

```sh
ginse auth complete --json
ginse wallet show --json
```

If completion is still pending, preserve the operation reference and retry `auth complete` only after `retry_after_seconds`, or `interval_seconds` when no retry value is present. A `slow_down` response persists a five-second interval increase; obey the returned value exactly. Never create a second device authorization. The CLI stores the OAuth device secret locally with mode `0600` and never prints it in the JSON envelope.

## Run the production MVP app

The current real app is `ginse-labs/color-png`, fixed at €0.25. It converts one written color name into a deterministic 256 × 256 PNG:

```sh
ginse apps get ginse-labs/color-png --json
ginse runs start ginse-labs/color-png \
  --input '{"color":"cornflower blue"}' \
  --max-price-cents 25 \
  --human-prompt 'Use app.ginse.ai/ginse-labs/color-png to create a 256 × 256 PNG filled with cornflower blue.' \
  --json
ginse runs status <run-id> --json
ginse runs output <run-id> --output cornflowerblue.png --json
ginse runs receipt <run-id> --json
```

Use `apps get` when the instruction names an exact app, as above. Use `apps search --intent "<outcome>"` only to discover candidates, then call `apps get` on the selected listing before starting it. `runs start` persists and returns its idempotency key; an exact command retry within 20 minutes reuses it, and an explicit retry can pass the returned `--idempotency-key`.

If `runs start` returns `data.status: "awaiting_funds"`, retain its run ID and give the human `data.human_action.url`. The URL contains an `amount_cents` value of at least the €1 mock top-up minimum. The human confirms the fake top-up in the browser; resume with `runs status` on the same ID. For `queued`, `running`, or `pending`, poll exactly once every 2 seconds for at most 15 minutes. Never create a replacement run.

## Human-only wallet actions

- `ginse wallet top-up --amount-cents 1000 --json` returns a durable browser action; it does not move balance.
- `ginse wallet withdraw --amount-cents 500 --json` returns a durable mock-withdrawal action and displays the €0.25 fake fee; it does not move balance.
- After human confirmation, use `wallet show` and `wallet transactions` to verify the ledger and receipt.

## Boundaries

- `ginse-account` creates or connects an account, reads the fake wallet, and prepares human-only wallet actions.
- `ginse-use` searches and runs one app after the current human message explicitly names Ginse.
- `ginse-publish` prepares and publishes one self-hosted fixed-price action.
- All execution goes through the JSON CLI over `https://api.ginse.ai`; there is no Ginse MCP server.
- Parse stdout as the API envelope. Treat stderr as diagnostics.
- Human actions can be returned in successful `data.human_action` objects as well as errors. Preserve their operation references.
- Never automate a deposit or withdrawal confirmation, disclose an internal wallet ID, or describe the test ledger as real money.

Contracts: `https://app.ginse.ai/contracts/v1/`
Human marketplace: `https://app.ginse.ai/`