# Omnorium Local Setup & Catalog Access (Claude Code / Codex)

Follow these steps to start or connect to a local Omnorium instance and read `/consumer/v1/catalog` (`omnorium.catalog` 1.0).

## 1. Detect or Start the Local Server
Check ~/.omnorium/consumer.json first. If missing, start the server in the background from the Omnorium repository root (Node.js >= 22.12) and wait for ~/.omnorium/consumer.json to appear.

```sh
# Live GitHub mode (ask user to sign in at http://127.0.0.1:4411 if no account exists):
pnpm install && pnpm dev

# Or 38-project sample dataset (no GitHub account required):
pnpm install && pnpm dev:sample
```

## 2. Read Discovery Metadata & Verify Instance
Read ~/.omnorium/consumer.json (mode 0600) to obtain baseUrl (default http://127.0.0.1:4410/consumer/v1), sample (true/false), instanceId, and secret (32-byte base64url key for GET /consumer/v1/discovery?challenge=<32-byte-base64url>).

```sh
CHALLENGE=$(node -e "process.stdout.write(require('crypto').randomBytes(32).toString('base64url'))")
curl -fsSL "http://127.0.0.1:4410/consumer/v1/discovery?challenge=$CHALLENGE"
```

## 3. Issue an Idempotent Read-Only Credential & Read Catalog
Never print or log the raw omc_ token. Match OMNORIUM_SAMPLE=small when sample is true in consumer.json, rotate the coding-agent label idempotently, and query GET /consumer/v1/catalog (contract omnorium.catalog 1.0) without Origin or Sec-Fetch-Site headers.

```sh
if grep -q '"sample":true' ~/.omnorium/consumer.json 2>/dev/null; then
  OMNORIUM_SAMPLE=small pnpm -s consumer:revoke coding-agent >/dev/null 2>&1 || true
  TOKEN=$(OMNORIUM_SAMPLE=small pnpm -s consumer:create --label coding-agent)
else
  pnpm -s consumer:revoke coding-agent >/dev/null 2>&1 || true
  TOKEN=$(pnpm -s consumer:create --label coding-agent)
fi
curl -fsSL -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4410/consumer/v1/catalog
```