# Catalox FAQ

Answers to common questions about installing, configuring, operating, and integrating Catalox. For step-by-step setup see [onboarding-happy-path.md](./onboarding-happy-path.md). For deployment see [DEPLOYMENT.md](./DEPLOYMENT.md).

---

## General

### Where should I start from a product perspective?

Read [overview.md](./overview.md) for why Catalox exists and [app-content-backend.md](./app-content-backend.md) for the recommended pattern: web apps and agent backends using Catalox as their content/metadata API instead of custom CRUD per entity.

### What is Catalox?

Catalox is **catalog platform infrastructure**: a reusable way to define catalogs once, bind them to apps, expose consistent discovery/list/get/write APIs, and avoid rebuilding catalog plumbing in every product. It runs as a **library** you embed, an **operator CLI**, and optionally an **HTTP service**.

### Is Catalox a hosted service?

No. Catalox is packages you install and wire to **your** Firestore (or MongoDB). The optional `catalox-service` app is a deployable you run on **your** infrastructure (private network or public with Authix).

### When should I use Catalox vs a database table?

**Use Catalox** for governed, discoverable **catalogs**: product definitions, routing rules, templates, lookup tables, configuration-as-data that many services read with descriptors and bindings.

**Do not use Catalox** as OLTP: orders, payments, live execution state, queues, balances, high-write operational events. Store the **transaction** in your host; store the **selectable definition** in Catalox.

→ [USE-CASES.md](./USE-CASES.md)

### What is the difference between `@x12i/catalox` and `@x12i/catalox-engine`?

In this monorepo, **`@x12i/catalox-engine`** is the engine package. The root **`@x12i/catalox`** npm package re-exports the engine and registers the `catalox` CLI bin for single-package installs. Workspace development uses both; consumers typically install `@x12i/catalox` or individual `@x12i/catalox-*` packages.

---

## Identity & access

### What is `appId`?

Catalox **`appId`** is a **catalog tenant** in your product world (which app sees which catalogs). It is **not** the Firebase/GCP project id. Confusing the two is a common setup mistake — see [environment.md](./environment.md).

### Why does `listCatalogItems` return empty with `listOutcome: "ok"`?

An empty list with **`listOutcome: "ok"`** means the query ran successfully and matched **zero rows**. That is different from **`mapping_blocked`** (mapping validation failed) or authorization denial. Check filters, bindings, and whether items have correct **`indexed.*`** fields for equality filters.

### Why do I get denied access even though the catalog exists?

Runtime reads require an **active `catalogBindings`** row linking your `appId` to `catalogId`. Use:

```bash
catalox toolbox check-access --app <appId> --catalog <catalogId>
```

→ [cli-toolbox.md](./cli-toolbox.md) · [authorization.md](./authorization.md)

### What is `superAdmin`?

A **`CataloxContext`** flag that bypasses normal binding checks for operator/provisioning flows. In **open-mode HTTP API** (5.9.x internal), it may default on — **never** expose that publicly. In **6.0.0**, `superAdmin` comes only from Authix `catalox.operator.super` on trusted service identities.

### What is the difference between empty, denied, and misconfigured?

See [outcomes.md](./outcomes.md). Summary:

| Situation | Typical signal |
|-----------|----------------|
| No binding / no read access | denied |
| Catalog or mapping not set up | misconfigured |
| Valid access, zero matching items | ok + empty items |

---

## Data model & storage

### Native vs mapped catalogs?

| Mode | Storage | Best for |
|------|---------|----------|
| **native** | Firestore `catalogData-{catalogId}-items` | Catalogs you own and write through Catalox |
| **mapped** | Normalized from MongoDB or HTTP API | Existing external data you expose as a catalog |

Mapped catalogs need **definition + adapter + mapping** in addition to descriptor + binding.

### What is a catalog descriptor?

Persisted metadata at `catalogDescriptors/{catalogId}`: capabilities (`canList`, `canEdit`, …), **queryable fields**, **identity rules** (how `itemId` is derived), optional smart properties, relation rules, and UI hints. Generic clients consume descriptors so they need no hardcoded catalog registrations.

→ [catalog-format.md](./catalog-format.md)

### What is `indexed` on native items?

**`indexed`** is reserved top-level metadata for query performance (equality filters, sorts). It is derived from descriptor fields marked `indexed: true` if omitted on write. It must **not** be duplicated inside `item.data`. Wrong or missing `indexed` causes incomplete filter results.

→ [native-catalog-storage-and-api.md](./native-catalog-storage-and-api.md)

### Why do I still see `catalogData/{catalogId}/items` in Firestore?

That is the **legacy layout**. Current native storage uses flat **`catalogData-{catalogId}-items`**. Migrate with:

```bash
catalox firestore report-native-layout --app <appId>
catalox firestore migrate-native-catalog-data --app <appId>
```

→ [migration-native-catalog-data.md](./migration-native-catalog-data.md)

### Can I use MongoDB instead of Firestore?

Yes, for **embedder primary persistence** via `@x12i/catalox/mongo` and `createCataloxFromMongoEnv()`. Operator features (GCS backup, record history) remain Firestore-oriented in 5.9.x.

→ [mongo-persistence.md](./mongo-persistence.md)

### Can I run offline without Firebase?

Yes, read-only via **`LocalFileStore`** and a `catalox.catalog.local.v1` snapshot on disk.

→ [local-file-store.md](./local-file-store.md)

---

## Credentials & environment

### Which env var do I set for Firebase?

Recommended for CI and scripts:

```bash
export GOOGLE_SERVICE_ACCOUNT_BASE64="<base64 of standard Google service account JSON>"
export FIREBASE_PROJECT_ID="<gcp-project-id>"
```

Precedence: **`GOOGLE_SERVICE_ACCOUNT_BASE64`** → optional **`serviceAccountPath`** (code option only) → Application Default Credentials.

The library does **not** load `.env` automatically; the **CLI** loads `.env` via dotenv.

→ [environment.md](./environment.md)

### How do I smoke-test Firestore connectivity?

```bash
catalox firestore probe
```

Or `testFirestoreConnectionFromEnv()` from `@x12i/catalox/firebase`.

### What is `CATALOX_APP_ID` vs `FIREBASE_PROJECT_ID`?

| Variable | Meaning |
|----------|---------|
| `CATALOX_APP_ID` | Default catalog tenant for CLI when `--app` omitted |
| `FIREBASE_PROJECT_ID` | GCP/Firebase project backing Firestore |

---

## CLI & provisioning

### `seed apply` vs `items batch-upsert`?

| Tool | Use when |
|------|----------|
| **`seed apply`** | Idempotent manifest: catalogs, bindings, descriptors, initial items in one file |
| **`items batch-upsert`** | Operating on an existing catalog’s items only |

Always run **`seed validate`** before **`seed apply`** on new manifests.

→ [onboarding-happy-path.md](./onboarding-happy-path.md) · [cli-items.md](./cli-items.md)

### Why does `seed apply` require `--god`?

Manifest sections that write **descriptors** require super-admin context. `--god` sets that on the CLI context.

### How do I run `catalox` from this repo without global install?

```bash
npm run build
npm run cli -- <subcommand> …
```

### Where is the CLI when I `npm install @x12i/catalox`?

The `catalox` binary is at `node_modules/.bin/catalox` (or global if installed with `-g`).

---

## HTTP API & Authix (v6)

### Open mode vs Authix mode?

| Mode | When |
|------|------|
| **`open`** | Private internal network only (5.9.x dev/staging) |
| **`authix`** | Production public API (6.0.0) — Bearer `ax1.*` tokens required |

→ [catalox-v6/6.0.0/README.md](./catalox-v6/6.0.0/README.md)

### Is Authix my login system?

No. Your SSO/IdP authenticates users; **your backend** calls Authix `POST /v1/tokens/issue`; clients present the token to Catalox API.

### Can I embed the engine and skip HTTP?

Yes — recommended for low-latency BFFs. Use `mapAuthixToCataloxContext()` from `@x12i/catalox-authix-bridge` then call `catalox` methods in-process.

---

## UI & rendering

### Does Catalox render UI?

No. Catalox returns **descriptors**, **render maps**, **presentation bindings**, and optional **renderer snippet refs**. Your React (or other) layer mounts registry components or compiles snippets.

→ [catalog-custom-ui.md](./catalog-custom-ui.md) · [catalox-ui-contract.md](./catalox-ui-contract.md)

### What are smart properties?

Descriptor-driven **foreign keys**: fields on `item.data` that resolve to rows in target catalogs (with optional auto-create and usage metadata).

→ [smart-properties.md](./smart-properties.md)

---

## Testing & publishing

### How do I run tests safely?

Use a **dedicated Firebase test project**, never production credentials. Set `FIRESTORE_LIVE_TESTS=1` only when intentional.

### What gets published to npm?

Root `@x12i/catalox` publishes engine `dist/`, presets, schemas, README, LICENSE, CHANGELOG. Workspace packages publish independently under `@x12i/catalox-*`.

`prepublishOnly` runs build + unit tests.

---

## Troubleshooting checklist

1. **`firestore probe`** — credentials and project ok?
2. **`toolbox check-access`** — binding active with read access?
3. **Descriptor** — `queryableFields` with `indexed: true` for filtered fields?
4. **Native layout** — flat `catalogData-*-items` not legacy subcollection?
5. **Context** — correct `appId`, scope, and not assuming `superAdmin` in production?
6. **Outcomes** — read `listOutcome` / `outcome` instead of assuming null means “not found”?

Still stuck? Check [Known-Gaps](../Known-Gaps/README.md) for documented limitations.