@x12i/catalox-docs 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -0
- package/bin/catalox-docs.js +2 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +56 -0
- package/dist/cli.js.map +1 -0
- package/dist/generated/bundle.d.ts +749 -0
- package/dist/generated/bundle.d.ts.map +1 -0
- package/dist/generated/bundle.js +1205 -0
- package/dist/generated/bundle.js.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/package.json +56 -0
|
@@ -0,0 +1,1205 @@
|
|
|
1
|
+
/* Auto-generated by scripts/build-knowledge.mjs — do not edit */
|
|
2
|
+
export const catalog = {
|
|
3
|
+
"roles": [
|
|
4
|
+
{
|
|
5
|
+
"id": "developers",
|
|
6
|
+
"label": "Developers",
|
|
7
|
+
"tagline": "Embed, operate, integrate",
|
|
8
|
+
"description": "Engineers who embed Catalox, run the CLI, deploy catalox-service, and wire Authix or host context."
|
|
9
|
+
}
|
|
10
|
+
],
|
|
11
|
+
"families": [
|
|
12
|
+
{
|
|
13
|
+
"id": "catalox",
|
|
14
|
+
"name": "Catalox",
|
|
15
|
+
"tagline": "Governed catalogs as platform infrastructure.",
|
|
16
|
+
"description": "Reusable item inventories that apps discover, render, search, and validate — without rebuilding catalog plumbing.",
|
|
17
|
+
"color": "#1a3a52"
|
|
18
|
+
}
|
|
19
|
+
],
|
|
20
|
+
"books": [
|
|
21
|
+
{
|
|
22
|
+
"id": "00-overview",
|
|
23
|
+
"familyId": "catalox",
|
|
24
|
+
"audiences": [
|
|
25
|
+
"developers"
|
|
26
|
+
],
|
|
27
|
+
"status": "available",
|
|
28
|
+
"kicker": "CASE FILE · CAT-00",
|
|
29
|
+
"title": "Overview",
|
|
30
|
+
"subtitle": "Why Catalox exists",
|
|
31
|
+
"blurb": "Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.",
|
|
32
|
+
"tags": [
|
|
33
|
+
"platform",
|
|
34
|
+
"start-here",
|
|
35
|
+
"overview"
|
|
36
|
+
],
|
|
37
|
+
"color": "#1a3a52",
|
|
38
|
+
"dir": "00-overview"
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": "01-content-backend",
|
|
42
|
+
"familyId": "catalox",
|
|
43
|
+
"audiences": [
|
|
44
|
+
"developers"
|
|
45
|
+
],
|
|
46
|
+
"status": "available",
|
|
47
|
+
"kicker": "CASE FILE · CAT-01",
|
|
48
|
+
"title": "Content Backend",
|
|
49
|
+
"subtitle": "Apps and agents on one catalog layer",
|
|
50
|
+
"blurb": "Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.",
|
|
51
|
+
"tags": [
|
|
52
|
+
"integration",
|
|
53
|
+
"bff",
|
|
54
|
+
"agents"
|
|
55
|
+
],
|
|
56
|
+
"color": "#1f5c4a",
|
|
57
|
+
"dir": "01-content-backend"
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"id": "02-persistence",
|
|
61
|
+
"familyId": "catalox",
|
|
62
|
+
"audiences": [
|
|
63
|
+
"developers"
|
|
64
|
+
],
|
|
65
|
+
"status": "available",
|
|
66
|
+
"kicker": "CASE FILE · CAT-02",
|
|
67
|
+
"title": "Persistence",
|
|
68
|
+
"subtitle": "MongoDB as primary store",
|
|
69
|
+
"blurb": "createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.",
|
|
70
|
+
"tags": [
|
|
71
|
+
"mongo",
|
|
72
|
+
"storage",
|
|
73
|
+
"ops"
|
|
74
|
+
],
|
|
75
|
+
"color": "#8a5a12",
|
|
76
|
+
"dir": "02-persistence"
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"id": "03-deploy-ops",
|
|
80
|
+
"familyId": "catalox",
|
|
81
|
+
"audiences": [
|
|
82
|
+
"developers"
|
|
83
|
+
],
|
|
84
|
+
"status": "available",
|
|
85
|
+
"kicker": "CASE FILE · CAT-03",
|
|
86
|
+
"title": "Deploy & Ops",
|
|
87
|
+
"subtitle": "Embed, CLI, HTTP, onboard",
|
|
88
|
+
"blurb": "Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.",
|
|
89
|
+
"tags": [
|
|
90
|
+
"deploy",
|
|
91
|
+
"http",
|
|
92
|
+
"onboarding"
|
|
93
|
+
],
|
|
94
|
+
"color": "#8b3a28",
|
|
95
|
+
"dir": "03-deploy-ops"
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"id": "04-auth-identity",
|
|
99
|
+
"familyId": "catalox",
|
|
100
|
+
"audiences": [
|
|
101
|
+
"developers"
|
|
102
|
+
],
|
|
103
|
+
"status": "available",
|
|
104
|
+
"kicker": "CASE FILE · CAT-04",
|
|
105
|
+
"title": "Auth & Identity",
|
|
106
|
+
"subtitle": "Context, bindings, outcomes",
|
|
107
|
+
"blurb": "Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.",
|
|
108
|
+
"tags": [
|
|
109
|
+
"auth",
|
|
110
|
+
"identity",
|
|
111
|
+
"bindings"
|
|
112
|
+
],
|
|
113
|
+
"color": "#4a3a6e",
|
|
114
|
+
"dir": "04-auth-identity"
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"id": "05-cli-toolbox",
|
|
118
|
+
"familyId": "catalox",
|
|
119
|
+
"audiences": [
|
|
120
|
+
"developers"
|
|
121
|
+
],
|
|
122
|
+
"status": "available",
|
|
123
|
+
"kicker": "CASE FILE · CAT-05",
|
|
124
|
+
"title": "CLI & Toolbox",
|
|
125
|
+
"subtitle": "Operator commands",
|
|
126
|
+
"blurb": "Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.",
|
|
127
|
+
"tags": [
|
|
128
|
+
"cli",
|
|
129
|
+
"ops",
|
|
130
|
+
"seed"
|
|
131
|
+
],
|
|
132
|
+
"color": "#2a4a62",
|
|
133
|
+
"dir": "05-cli-toolbox"
|
|
134
|
+
}
|
|
135
|
+
]
|
|
136
|
+
};
|
|
137
|
+
export const useCases = {
|
|
138
|
+
"useCases": [
|
|
139
|
+
{
|
|
140
|
+
"id": "orient-catalox",
|
|
141
|
+
"title": "Orient on Catalox",
|
|
142
|
+
"goal": "Understand why Catalox exists, what it owns, and when not to use it.",
|
|
143
|
+
"audiences": [
|
|
144
|
+
"developers"
|
|
145
|
+
],
|
|
146
|
+
"tags": [
|
|
147
|
+
"platform",
|
|
148
|
+
"start-here"
|
|
149
|
+
],
|
|
150
|
+
"path": [
|
|
151
|
+
{
|
|
152
|
+
"bookId": "00-overview",
|
|
153
|
+
"audience": "developers",
|
|
154
|
+
"chapters": [
|
|
155
|
+
"1-why-catalox-exists",
|
|
156
|
+
"2-what-catalox-is",
|
|
157
|
+
"3-fit-vs-misfit"
|
|
158
|
+
]
|
|
159
|
+
}
|
|
160
|
+
],
|
|
161
|
+
"alsoSee": [
|
|
162
|
+
"01-content-backend"
|
|
163
|
+
],
|
|
164
|
+
"prerequisites": [],
|
|
165
|
+
"successCriteria": [],
|
|
166
|
+
"nextUseCases": [],
|
|
167
|
+
"scenarioIds": [],
|
|
168
|
+
"guideIds": [],
|
|
169
|
+
"troubleshooting": []
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
"id": "embed-content-backend",
|
|
173
|
+
"title": "Embed as content backend",
|
|
174
|
+
"goal": "Wire a BFF and agent runtime so humans and agents share one catalog layer.",
|
|
175
|
+
"audiences": [
|
|
176
|
+
"developers"
|
|
177
|
+
],
|
|
178
|
+
"tags": [
|
|
179
|
+
"integration",
|
|
180
|
+
"bff",
|
|
181
|
+
"agents"
|
|
182
|
+
],
|
|
183
|
+
"path": [
|
|
184
|
+
{
|
|
185
|
+
"bookId": "01-content-backend",
|
|
186
|
+
"audience": "developers",
|
|
187
|
+
"chapters": [
|
|
188
|
+
"1-the-pattern",
|
|
189
|
+
"2-architecture",
|
|
190
|
+
"3-product-use-cases"
|
|
191
|
+
]
|
|
192
|
+
}
|
|
193
|
+
],
|
|
194
|
+
"alsoSee": [
|
|
195
|
+
"00-overview",
|
|
196
|
+
"04-auth-identity"
|
|
197
|
+
],
|
|
198
|
+
"prerequisites": [],
|
|
199
|
+
"successCriteria": [],
|
|
200
|
+
"nextUseCases": [],
|
|
201
|
+
"scenarioIds": [],
|
|
202
|
+
"guideIds": [],
|
|
203
|
+
"troubleshooting": []
|
|
204
|
+
},
|
|
205
|
+
{
|
|
206
|
+
"id": "mongo-onboard",
|
|
207
|
+
"title": "Onboard with Mongo",
|
|
208
|
+
"goal": "Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.",
|
|
209
|
+
"audiences": [
|
|
210
|
+
"developers"
|
|
211
|
+
],
|
|
212
|
+
"tags": [
|
|
213
|
+
"mongo",
|
|
214
|
+
"onboarding",
|
|
215
|
+
"ops"
|
|
216
|
+
],
|
|
217
|
+
"path": [
|
|
218
|
+
{
|
|
219
|
+
"bookId": "02-persistence",
|
|
220
|
+
"audience": "developers",
|
|
221
|
+
"chapters": [
|
|
222
|
+
"1-mongo-quick-start",
|
|
223
|
+
"2-environment"
|
|
224
|
+
]
|
|
225
|
+
},
|
|
226
|
+
{
|
|
227
|
+
"bookId": "03-deploy-ops",
|
|
228
|
+
"audience": "developers",
|
|
229
|
+
"chapters": [
|
|
230
|
+
"4-onboarding-happy-path"
|
|
231
|
+
]
|
|
232
|
+
}
|
|
233
|
+
],
|
|
234
|
+
"alsoSee": [
|
|
235
|
+
"05-cli-toolbox"
|
|
236
|
+
],
|
|
237
|
+
"prerequisites": [],
|
|
238
|
+
"successCriteria": [],
|
|
239
|
+
"nextUseCases": [],
|
|
240
|
+
"scenarioIds": [],
|
|
241
|
+
"guideIds": [],
|
|
242
|
+
"troubleshooting": []
|
|
243
|
+
},
|
|
244
|
+
{
|
|
245
|
+
"id": "auth-context",
|
|
246
|
+
"title": "Map host auth to Catalox context",
|
|
247
|
+
"goal": "Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.",
|
|
248
|
+
"audiences": [
|
|
249
|
+
"developers"
|
|
250
|
+
],
|
|
251
|
+
"tags": [
|
|
252
|
+
"auth",
|
|
253
|
+
"identity"
|
|
254
|
+
],
|
|
255
|
+
"path": [
|
|
256
|
+
{
|
|
257
|
+
"bookId": "04-auth-identity",
|
|
258
|
+
"audience": "developers",
|
|
259
|
+
"chapters": [
|
|
260
|
+
"1-identity-axes",
|
|
261
|
+
"2-super-admin",
|
|
262
|
+
"3-catalog-and-item-visibility",
|
|
263
|
+
"4-empty-vs-denied"
|
|
264
|
+
]
|
|
265
|
+
}
|
|
266
|
+
],
|
|
267
|
+
"alsoSee": [
|
|
268
|
+
"01-content-backend"
|
|
269
|
+
],
|
|
270
|
+
"prerequisites": [],
|
|
271
|
+
"successCriteria": [],
|
|
272
|
+
"nextUseCases": [],
|
|
273
|
+
"scenarioIds": [],
|
|
274
|
+
"guideIds": [],
|
|
275
|
+
"troubleshooting": []
|
|
276
|
+
},
|
|
277
|
+
{
|
|
278
|
+
"id": "cli-seed-items",
|
|
279
|
+
"title": "Operate with CLI items and seed",
|
|
280
|
+
"goal": "Use elevated CLI access, items commands, and seed manifests safely.",
|
|
281
|
+
"audiences": [
|
|
282
|
+
"developers"
|
|
283
|
+
],
|
|
284
|
+
"tags": [
|
|
285
|
+
"cli",
|
|
286
|
+
"seed",
|
|
287
|
+
"ops"
|
|
288
|
+
],
|
|
289
|
+
"path": [
|
|
290
|
+
{
|
|
291
|
+
"bookId": "05-cli-toolbox",
|
|
292
|
+
"audience": "developers",
|
|
293
|
+
"chapters": [
|
|
294
|
+
"1-cli-access",
|
|
295
|
+
"2-items-commands",
|
|
296
|
+
"4-seed-workflow"
|
|
297
|
+
]
|
|
298
|
+
}
|
|
299
|
+
],
|
|
300
|
+
"alsoSee": [
|
|
301
|
+
"03-deploy-ops"
|
|
302
|
+
],
|
|
303
|
+
"prerequisites": [],
|
|
304
|
+
"successCriteria": [],
|
|
305
|
+
"nextUseCases": [],
|
|
306
|
+
"scenarioIds": [],
|
|
307
|
+
"guideIds": [],
|
|
308
|
+
"troubleshooting": []
|
|
309
|
+
}
|
|
310
|
+
]
|
|
311
|
+
};
|
|
312
|
+
export const site = {
|
|
313
|
+
"product": "catalox",
|
|
314
|
+
"brand": "x12i · catalox",
|
|
315
|
+
"brandAccent": "catalox",
|
|
316
|
+
"siteUrl": "https://docs.catalox.x12i.com",
|
|
317
|
+
"knowledgePackage": "@x12i/catalox-docs",
|
|
318
|
+
"footer": "x12i · Catalox",
|
|
319
|
+
"accent": "oklch(45% 0.08 230)",
|
|
320
|
+
"accentAlt": "oklch(55% 0.12 160)",
|
|
321
|
+
"productUrl": "https://github.com/x12i/catalox",
|
|
322
|
+
"nav": [
|
|
323
|
+
{
|
|
324
|
+
"label": "Getting started",
|
|
325
|
+
"href": "/getting-started"
|
|
326
|
+
},
|
|
327
|
+
{
|
|
328
|
+
"label": "Use cases",
|
|
329
|
+
"href": "/use-cases"
|
|
330
|
+
},
|
|
331
|
+
{
|
|
332
|
+
"label": "Catalog",
|
|
333
|
+
"href": "/catalog"
|
|
334
|
+
}
|
|
335
|
+
],
|
|
336
|
+
"footerLinks": [
|
|
337
|
+
{
|
|
338
|
+
"label": "Docs home",
|
|
339
|
+
"href": "/docs"
|
|
340
|
+
},
|
|
341
|
+
{
|
|
342
|
+
"label": "Getting started",
|
|
343
|
+
"href": "/getting-started"
|
|
344
|
+
},
|
|
345
|
+
{
|
|
346
|
+
"label": "Use cases",
|
|
347
|
+
"href": "/use-cases"
|
|
348
|
+
},
|
|
349
|
+
{
|
|
350
|
+
"label": "Catalog",
|
|
351
|
+
"href": "/catalog"
|
|
352
|
+
},
|
|
353
|
+
{
|
|
354
|
+
"label": "Agents/SDK",
|
|
355
|
+
"href": "/agents"
|
|
356
|
+
},
|
|
357
|
+
{
|
|
358
|
+
"label": "Repo",
|
|
359
|
+
"href": "https://github.com/x12i/catalox"
|
|
360
|
+
}
|
|
361
|
+
]
|
|
362
|
+
};
|
|
363
|
+
export const manifest = {
|
|
364
|
+
"version": 1,
|
|
365
|
+
"product": "catalox",
|
|
366
|
+
"site": "https://docs.catalox.x12i.com",
|
|
367
|
+
"knowledgePackage": "@x12i/catalox-docs",
|
|
368
|
+
"roles": [
|
|
369
|
+
"developers"
|
|
370
|
+
],
|
|
371
|
+
"books": [
|
|
372
|
+
{
|
|
373
|
+
"id": "00-overview",
|
|
374
|
+
"audiences": [
|
|
375
|
+
"developers"
|
|
376
|
+
],
|
|
377
|
+
"md": {
|
|
378
|
+
"developers": "downloads/books/00-overview/developers.md"
|
|
379
|
+
},
|
|
380
|
+
"pdf": {
|
|
381
|
+
"developers": null
|
|
382
|
+
},
|
|
383
|
+
"chapters": {
|
|
384
|
+
"developers": "downloads/books/00-overview/developers.chapters.json"
|
|
385
|
+
}
|
|
386
|
+
},
|
|
387
|
+
{
|
|
388
|
+
"id": "01-content-backend",
|
|
389
|
+
"audiences": [
|
|
390
|
+
"developers"
|
|
391
|
+
],
|
|
392
|
+
"md": {
|
|
393
|
+
"developers": "downloads/books/01-content-backend/developers.md"
|
|
394
|
+
},
|
|
395
|
+
"pdf": {
|
|
396
|
+
"developers": null
|
|
397
|
+
},
|
|
398
|
+
"chapters": {
|
|
399
|
+
"developers": "downloads/books/01-content-backend/developers.chapters.json"
|
|
400
|
+
}
|
|
401
|
+
},
|
|
402
|
+
{
|
|
403
|
+
"id": "02-persistence",
|
|
404
|
+
"audiences": [
|
|
405
|
+
"developers"
|
|
406
|
+
],
|
|
407
|
+
"md": {
|
|
408
|
+
"developers": "downloads/books/02-persistence/developers.md"
|
|
409
|
+
},
|
|
410
|
+
"pdf": {
|
|
411
|
+
"developers": null
|
|
412
|
+
},
|
|
413
|
+
"chapters": {
|
|
414
|
+
"developers": "downloads/books/02-persistence/developers.chapters.json"
|
|
415
|
+
}
|
|
416
|
+
},
|
|
417
|
+
{
|
|
418
|
+
"id": "03-deploy-ops",
|
|
419
|
+
"audiences": [
|
|
420
|
+
"developers"
|
|
421
|
+
],
|
|
422
|
+
"md": {
|
|
423
|
+
"developers": "downloads/books/03-deploy-ops/developers.md"
|
|
424
|
+
},
|
|
425
|
+
"pdf": {
|
|
426
|
+
"developers": null
|
|
427
|
+
},
|
|
428
|
+
"chapters": {
|
|
429
|
+
"developers": "downloads/books/03-deploy-ops/developers.chapters.json"
|
|
430
|
+
}
|
|
431
|
+
},
|
|
432
|
+
{
|
|
433
|
+
"id": "04-auth-identity",
|
|
434
|
+
"audiences": [
|
|
435
|
+
"developers"
|
|
436
|
+
],
|
|
437
|
+
"md": {
|
|
438
|
+
"developers": "downloads/books/04-auth-identity/developers.md"
|
|
439
|
+
},
|
|
440
|
+
"pdf": {
|
|
441
|
+
"developers": null
|
|
442
|
+
},
|
|
443
|
+
"chapters": {
|
|
444
|
+
"developers": "downloads/books/04-auth-identity/developers.chapters.json"
|
|
445
|
+
}
|
|
446
|
+
},
|
|
447
|
+
{
|
|
448
|
+
"id": "05-cli-toolbox",
|
|
449
|
+
"audiences": [
|
|
450
|
+
"developers"
|
|
451
|
+
],
|
|
452
|
+
"md": {
|
|
453
|
+
"developers": "downloads/books/05-cli-toolbox/developers.md"
|
|
454
|
+
},
|
|
455
|
+
"pdf": {
|
|
456
|
+
"developers": null
|
|
457
|
+
},
|
|
458
|
+
"chapters": {
|
|
459
|
+
"developers": "downloads/books/05-cli-toolbox/developers.chapters.json"
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
],
|
|
463
|
+
"useCases": [
|
|
464
|
+
{
|
|
465
|
+
"id": "orient-catalox",
|
|
466
|
+
"title": "Orient on Catalox",
|
|
467
|
+
"md": "downloads/use-cases/orient-catalox.md",
|
|
468
|
+
"path": [
|
|
469
|
+
{
|
|
470
|
+
"bookId": "00-overview",
|
|
471
|
+
"audience": "developers",
|
|
472
|
+
"chapters": [
|
|
473
|
+
"1-why-catalox-exists",
|
|
474
|
+
"2-what-catalox-is",
|
|
475
|
+
"3-fit-vs-misfit"
|
|
476
|
+
]
|
|
477
|
+
}
|
|
478
|
+
]
|
|
479
|
+
},
|
|
480
|
+
{
|
|
481
|
+
"id": "embed-content-backend",
|
|
482
|
+
"title": "Embed as content backend",
|
|
483
|
+
"md": "downloads/use-cases/embed-content-backend.md",
|
|
484
|
+
"path": [
|
|
485
|
+
{
|
|
486
|
+
"bookId": "01-content-backend",
|
|
487
|
+
"audience": "developers",
|
|
488
|
+
"chapters": [
|
|
489
|
+
"1-the-pattern",
|
|
490
|
+
"2-architecture",
|
|
491
|
+
"3-product-use-cases"
|
|
492
|
+
]
|
|
493
|
+
}
|
|
494
|
+
]
|
|
495
|
+
},
|
|
496
|
+
{
|
|
497
|
+
"id": "mongo-onboard",
|
|
498
|
+
"title": "Onboard with Mongo",
|
|
499
|
+
"md": "downloads/use-cases/mongo-onboard.md",
|
|
500
|
+
"path": [
|
|
501
|
+
{
|
|
502
|
+
"bookId": "02-persistence",
|
|
503
|
+
"audience": "developers",
|
|
504
|
+
"chapters": [
|
|
505
|
+
"1-mongo-quick-start",
|
|
506
|
+
"2-environment"
|
|
507
|
+
]
|
|
508
|
+
},
|
|
509
|
+
{
|
|
510
|
+
"bookId": "03-deploy-ops",
|
|
511
|
+
"audience": "developers",
|
|
512
|
+
"chapters": [
|
|
513
|
+
"4-onboarding-happy-path"
|
|
514
|
+
]
|
|
515
|
+
}
|
|
516
|
+
]
|
|
517
|
+
},
|
|
518
|
+
{
|
|
519
|
+
"id": "auth-context",
|
|
520
|
+
"title": "Map host auth to Catalox context",
|
|
521
|
+
"md": "downloads/use-cases/auth-context.md",
|
|
522
|
+
"path": [
|
|
523
|
+
{
|
|
524
|
+
"bookId": "04-auth-identity",
|
|
525
|
+
"audience": "developers",
|
|
526
|
+
"chapters": [
|
|
527
|
+
"1-identity-axes",
|
|
528
|
+
"2-super-admin",
|
|
529
|
+
"3-catalog-and-item-visibility",
|
|
530
|
+
"4-empty-vs-denied"
|
|
531
|
+
]
|
|
532
|
+
}
|
|
533
|
+
]
|
|
534
|
+
},
|
|
535
|
+
{
|
|
536
|
+
"id": "cli-seed-items",
|
|
537
|
+
"title": "Operate with CLI items and seed",
|
|
538
|
+
"md": "downloads/use-cases/cli-seed-items.md",
|
|
539
|
+
"path": [
|
|
540
|
+
{
|
|
541
|
+
"bookId": "05-cli-toolbox",
|
|
542
|
+
"audience": "developers",
|
|
543
|
+
"chapters": [
|
|
544
|
+
"1-cli-access",
|
|
545
|
+
"2-items-commands",
|
|
546
|
+
"4-seed-workflow"
|
|
547
|
+
]
|
|
548
|
+
}
|
|
549
|
+
]
|
|
550
|
+
}
|
|
551
|
+
],
|
|
552
|
+
"indexes": {
|
|
553
|
+
"indexMd": "INDEX.md",
|
|
554
|
+
"searchJson": "SEARCH.json"
|
|
555
|
+
},
|
|
556
|
+
"concepts": [
|
|
557
|
+
{
|
|
558
|
+
"id": "catalog-as-platform",
|
|
559
|
+
"title": "Catalog as platform",
|
|
560
|
+
"md": "concepts/catalog-as-platform.md"
|
|
561
|
+
},
|
|
562
|
+
{
|
|
563
|
+
"id": "mongo-primary",
|
|
564
|
+
"title": "MongoDB is primary persistence",
|
|
565
|
+
"md": "concepts/mongo-primary.md"
|
|
566
|
+
}
|
|
567
|
+
],
|
|
568
|
+
"guides": [
|
|
569
|
+
{
|
|
570
|
+
"id": "embed-catalox",
|
|
571
|
+
"title": "Embed Catalox from env",
|
|
572
|
+
"md": "guides/embed-catalox.md"
|
|
573
|
+
}
|
|
574
|
+
],
|
|
575
|
+
"scenarios": [
|
|
576
|
+
{
|
|
577
|
+
"id": "choose-deploy-mode",
|
|
578
|
+
"title": "Choose embed vs HTTP service",
|
|
579
|
+
"md": "scenarios/choose-deploy-mode.md"
|
|
580
|
+
}
|
|
581
|
+
],
|
|
582
|
+
"decisions": [],
|
|
583
|
+
"glossary": [],
|
|
584
|
+
"visuals": [],
|
|
585
|
+
"diagrams": [],
|
|
586
|
+
"relationships": [],
|
|
587
|
+
"tutorials": [],
|
|
588
|
+
"examples": [],
|
|
589
|
+
"sampleData": [],
|
|
590
|
+
"uiClients": [],
|
|
591
|
+
"apis": [],
|
|
592
|
+
"packs": [
|
|
593
|
+
{
|
|
594
|
+
"id": "concept/catalog-as-platform",
|
|
595
|
+
"type": "concept",
|
|
596
|
+
"path": "packs/concept/catalog-as-platform"
|
|
597
|
+
},
|
|
598
|
+
{
|
|
599
|
+
"id": "concept/mongo-primary",
|
|
600
|
+
"type": "concept",
|
|
601
|
+
"path": "packs/concept/mongo-primary"
|
|
602
|
+
},
|
|
603
|
+
{
|
|
604
|
+
"id": "guide/embed-catalox",
|
|
605
|
+
"type": "guide",
|
|
606
|
+
"path": "packs/guide/embed-catalox"
|
|
607
|
+
},
|
|
608
|
+
{
|
|
609
|
+
"id": "scenario/choose-deploy-mode",
|
|
610
|
+
"type": "scenario",
|
|
611
|
+
"path": "packs/scenario/choose-deploy-mode"
|
|
612
|
+
}
|
|
613
|
+
]
|
|
614
|
+
};
|
|
615
|
+
export const knowledge = {
|
|
616
|
+
"concepts": [
|
|
617
|
+
{
|
|
618
|
+
"summary": "Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.",
|
|
619
|
+
"problem": "Every app reinvents schemas, list/get APIs, admin field metadata, access rules, and agent-readable descriptors.",
|
|
620
|
+
"why": "Shared catalogs keep discovery, visibility, and validation consistent across web BFFs and agent runtimes.",
|
|
621
|
+
"mentalModel": "Catalox stores the selectable definition; the host stores the transaction, run, or event that uses it.",
|
|
622
|
+
"audiences": [
|
|
623
|
+
"developers"
|
|
624
|
+
],
|
|
625
|
+
"whenItMatters": [],
|
|
626
|
+
"whenNotToUse": [],
|
|
627
|
+
"prerequisites": [],
|
|
628
|
+
"related": [
|
|
629
|
+
"mongo-primary"
|
|
630
|
+
],
|
|
631
|
+
"next": [
|
|
632
|
+
"embed-catalox"
|
|
633
|
+
],
|
|
634
|
+
"exampleIds": [],
|
|
635
|
+
"commonMistakes": [],
|
|
636
|
+
"successCriteria": [],
|
|
637
|
+
"invariants": [],
|
|
638
|
+
"alternatives": [],
|
|
639
|
+
"tags": [],
|
|
640
|
+
"id": "catalog-as-platform",
|
|
641
|
+
"type": "concept",
|
|
642
|
+
"title": "Catalog as platform",
|
|
643
|
+
"visualIds": [],
|
|
644
|
+
"diagramIds": [],
|
|
645
|
+
"referenceIds": []
|
|
646
|
+
},
|
|
647
|
+
{
|
|
648
|
+
"summary": "Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.",
|
|
649
|
+
"problem": "Dual-write or Firestore-first assumptions break onboarding and ops scripts.",
|
|
650
|
+
"why": "One primary store simplifies estate layout, CLI probes, and production deploys.",
|
|
651
|
+
"mentalModel": "createCataloxFromEnv → Mongo collections; R2 is optional object history, not the catalog DB.",
|
|
652
|
+
"audiences": [
|
|
653
|
+
"developers"
|
|
654
|
+
],
|
|
655
|
+
"whenItMatters": [],
|
|
656
|
+
"whenNotToUse": [],
|
|
657
|
+
"prerequisites": [
|
|
658
|
+
"catalog-as-platform"
|
|
659
|
+
],
|
|
660
|
+
"related": [],
|
|
661
|
+
"next": [
|
|
662
|
+
"embed-catalox"
|
|
663
|
+
],
|
|
664
|
+
"exampleIds": [],
|
|
665
|
+
"commonMistakes": [],
|
|
666
|
+
"successCriteria": [],
|
|
667
|
+
"invariants": [],
|
|
668
|
+
"alternatives": [],
|
|
669
|
+
"tags": [],
|
|
670
|
+
"id": "mongo-primary",
|
|
671
|
+
"type": "concept",
|
|
672
|
+
"title": "MongoDB is primary persistence",
|
|
673
|
+
"visualIds": [],
|
|
674
|
+
"diagramIds": [],
|
|
675
|
+
"referenceIds": []
|
|
676
|
+
}
|
|
677
|
+
],
|
|
678
|
+
"guides": [
|
|
679
|
+
{
|
|
680
|
+
"summary": "Create an in-process Catalox client from environment variables and verify Mongo connectivity.",
|
|
681
|
+
"why": "Embedding is the default integration — HTTP service is optional.",
|
|
682
|
+
"audiences": [
|
|
683
|
+
"developers"
|
|
684
|
+
],
|
|
685
|
+
"whenItMatters": [],
|
|
686
|
+
"whenNotToUse": [],
|
|
687
|
+
"prerequisites": [
|
|
688
|
+
"catalog-as-platform",
|
|
689
|
+
"mongo-primary"
|
|
690
|
+
],
|
|
691
|
+
"related": [
|
|
692
|
+
"choose-deploy-mode"
|
|
693
|
+
],
|
|
694
|
+
"next": [],
|
|
695
|
+
"exampleIds": [],
|
|
696
|
+
"commonMistakes": [],
|
|
697
|
+
"successCriteria": [],
|
|
698
|
+
"invariants": [
|
|
699
|
+
"Mongo is the primary store",
|
|
700
|
+
"appId selects the catalog tenant, not the cloud project id"
|
|
701
|
+
],
|
|
702
|
+
"alternatives": [],
|
|
703
|
+
"confirmationRequired": false,
|
|
704
|
+
"tags": [],
|
|
705
|
+
"id": "embed-catalox",
|
|
706
|
+
"type": "guide",
|
|
707
|
+
"title": "Embed Catalox from env",
|
|
708
|
+
"useWhen": [],
|
|
709
|
+
"doNotUseWhen": [],
|
|
710
|
+
"inputs": [],
|
|
711
|
+
"permissions": [],
|
|
712
|
+
"steps": [],
|
|
713
|
+
"verification": [],
|
|
714
|
+
"recovery": [],
|
|
715
|
+
"tutorialIds": [],
|
|
716
|
+
"referenceIds": [],
|
|
717
|
+
"scenarioIds": []
|
|
718
|
+
}
|
|
719
|
+
],
|
|
720
|
+
"scenarios": [
|
|
721
|
+
{
|
|
722
|
+
"summary": "Decide whether to embed Catalox in-process or expose catalox-service.",
|
|
723
|
+
"audiences": [
|
|
724
|
+
"developers"
|
|
725
|
+
],
|
|
726
|
+
"whenItMatters": [],
|
|
727
|
+
"whenNotToUse": [],
|
|
728
|
+
"prerequisites": [],
|
|
729
|
+
"related": [],
|
|
730
|
+
"next": [],
|
|
731
|
+
"exampleIds": [],
|
|
732
|
+
"commonMistakes": [],
|
|
733
|
+
"successCriteria": [],
|
|
734
|
+
"invariants": [
|
|
735
|
+
"Same Mongo estate either way",
|
|
736
|
+
"Authix gates public HTTP; embed still needs host context"
|
|
737
|
+
],
|
|
738
|
+
"alternatives": [],
|
|
739
|
+
"tags": [],
|
|
740
|
+
"id": "choose-deploy-mode",
|
|
741
|
+
"type": "scenario",
|
|
742
|
+
"title": "Choose embed vs HTTP service",
|
|
743
|
+
"situation": "You are integrating Catalox into a product and must pick embed vs HTTP service.",
|
|
744
|
+
"preconditions": [],
|
|
745
|
+
"signals": [],
|
|
746
|
+
"decisionQuestion": "Should this product embed Catalox or deploy catalox-service?",
|
|
747
|
+
"paths": [
|
|
748
|
+
{
|
|
749
|
+
"id": "embed",
|
|
750
|
+
"label": "Embed in-process",
|
|
751
|
+
"when": "One Node service owns catalog access and host identity.",
|
|
752
|
+
"rationale": "Prefer createCataloxFromEnv and CataloxContext inside the BFF.",
|
|
753
|
+
"guideIds": [
|
|
754
|
+
"embed-catalox"
|
|
755
|
+
]
|
|
756
|
+
},
|
|
757
|
+
{
|
|
758
|
+
"id": "http-service",
|
|
759
|
+
"label": "HTTP service",
|
|
760
|
+
"when": "Other runtimes or networks must call Catalox over HTTP.",
|
|
761
|
+
"rationale": "Deploy catalox-service against the same Mongo estate; gate public routes with Authix.",
|
|
762
|
+
"guideIds": [
|
|
763
|
+
"embed-catalox"
|
|
764
|
+
]
|
|
765
|
+
}
|
|
766
|
+
],
|
|
767
|
+
"verification": [],
|
|
768
|
+
"recovery": []
|
|
769
|
+
}
|
|
770
|
+
],
|
|
771
|
+
"decisions": [],
|
|
772
|
+
"glossary": [],
|
|
773
|
+
"visuals": [],
|
|
774
|
+
"diagrams": [],
|
|
775
|
+
"relationships": [],
|
|
776
|
+
"tutorials": [],
|
|
777
|
+
"examples": [],
|
|
778
|
+
"sampleData": [],
|
|
779
|
+
"uiClients": [],
|
|
780
|
+
"apis": []
|
|
781
|
+
};
|
|
782
|
+
export const search = {
|
|
783
|
+
"version": 1,
|
|
784
|
+
"product": "catalox",
|
|
785
|
+
"generatedAt": "2026-07-26T13:09:13.535Z",
|
|
786
|
+
"records": [
|
|
787
|
+
{
|
|
788
|
+
"id": "catalog-as-platform",
|
|
789
|
+
"type": "concept",
|
|
790
|
+
"title": "Catalog as platform",
|
|
791
|
+
"summary": "Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.",
|
|
792
|
+
"aliases": [],
|
|
793
|
+
"audiences": [
|
|
794
|
+
"developers"
|
|
795
|
+
],
|
|
796
|
+
"tags": [],
|
|
797
|
+
"goals": [],
|
|
798
|
+
"path": "concepts/catalog-as-platform.md",
|
|
799
|
+
"webPath": "/concepts/catalog-as-platform",
|
|
800
|
+
"prerequisites": [],
|
|
801
|
+
"related": [
|
|
802
|
+
"mongo-primary"
|
|
803
|
+
],
|
|
804
|
+
"packIds": [
|
|
805
|
+
"concept/catalog-as-platform"
|
|
806
|
+
]
|
|
807
|
+
},
|
|
808
|
+
{
|
|
809
|
+
"id": "mongo-primary",
|
|
810
|
+
"type": "concept",
|
|
811
|
+
"title": "MongoDB is primary persistence",
|
|
812
|
+
"summary": "Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.",
|
|
813
|
+
"aliases": [],
|
|
814
|
+
"audiences": [
|
|
815
|
+
"developers"
|
|
816
|
+
],
|
|
817
|
+
"tags": [],
|
|
818
|
+
"goals": [],
|
|
819
|
+
"path": "concepts/mongo-primary.md",
|
|
820
|
+
"webPath": "/concepts/mongo-primary",
|
|
821
|
+
"prerequisites": [
|
|
822
|
+
"catalog-as-platform"
|
|
823
|
+
],
|
|
824
|
+
"related": [],
|
|
825
|
+
"packIds": [
|
|
826
|
+
"concept/mongo-primary"
|
|
827
|
+
]
|
|
828
|
+
},
|
|
829
|
+
{
|
|
830
|
+
"id": "embed-catalox",
|
|
831
|
+
"type": "guide",
|
|
832
|
+
"title": "Embed Catalox from env",
|
|
833
|
+
"summary": "Create an in-process Catalox client from environment variables and verify Mongo connectivity.",
|
|
834
|
+
"aliases": [],
|
|
835
|
+
"audiences": [
|
|
836
|
+
"developers"
|
|
837
|
+
],
|
|
838
|
+
"tags": [],
|
|
839
|
+
"goals": [],
|
|
840
|
+
"path": "guides/embed-catalox.md",
|
|
841
|
+
"webPath": "/guides/embed-catalox",
|
|
842
|
+
"prerequisites": [
|
|
843
|
+
"catalog-as-platform",
|
|
844
|
+
"mongo-primary"
|
|
845
|
+
],
|
|
846
|
+
"related": [
|
|
847
|
+
"choose-deploy-mode"
|
|
848
|
+
],
|
|
849
|
+
"packIds": [
|
|
850
|
+
"guide/embed-catalox"
|
|
851
|
+
]
|
|
852
|
+
},
|
|
853
|
+
{
|
|
854
|
+
"id": "choose-deploy-mode",
|
|
855
|
+
"type": "scenario",
|
|
856
|
+
"title": "Choose embed vs HTTP service",
|
|
857
|
+
"summary": "Decide whether to embed Catalox in-process or expose catalox-service.",
|
|
858
|
+
"aliases": [],
|
|
859
|
+
"audiences": [
|
|
860
|
+
"developers"
|
|
861
|
+
],
|
|
862
|
+
"tags": [],
|
|
863
|
+
"goals": [
|
|
864
|
+
"Should this product embed Catalox or deploy catalox-service?"
|
|
865
|
+
],
|
|
866
|
+
"path": "scenarios/choose-deploy-mode.md",
|
|
867
|
+
"webPath": "/scenarios/choose-deploy-mode",
|
|
868
|
+
"prerequisites": [],
|
|
869
|
+
"related": [],
|
|
870
|
+
"packIds": [
|
|
871
|
+
"scenario/choose-deploy-mode"
|
|
872
|
+
]
|
|
873
|
+
},
|
|
874
|
+
{
|
|
875
|
+
"id": "orient-catalox",
|
|
876
|
+
"type": "use-case",
|
|
877
|
+
"title": "Orient on Catalox",
|
|
878
|
+
"summary": "Understand why Catalox exists, what it owns, and when not to use it.",
|
|
879
|
+
"aliases": [],
|
|
880
|
+
"audiences": [
|
|
881
|
+
"developers"
|
|
882
|
+
],
|
|
883
|
+
"tags": [
|
|
884
|
+
"platform",
|
|
885
|
+
"start-here"
|
|
886
|
+
],
|
|
887
|
+
"goals": [
|
|
888
|
+
"Understand why Catalox exists, what it owns, and when not to use it."
|
|
889
|
+
],
|
|
890
|
+
"path": "use-cases/orient-catalox.md",
|
|
891
|
+
"webPath": "/use-cases#orient-catalox",
|
|
892
|
+
"prerequisites": [],
|
|
893
|
+
"related": [
|
|
894
|
+
"01-content-backend"
|
|
895
|
+
],
|
|
896
|
+
"packIds": [
|
|
897
|
+
"use-case/orient-catalox"
|
|
898
|
+
]
|
|
899
|
+
},
|
|
900
|
+
{
|
|
901
|
+
"id": "embed-content-backend",
|
|
902
|
+
"type": "use-case",
|
|
903
|
+
"title": "Embed as content backend",
|
|
904
|
+
"summary": "Wire a BFF and agent runtime so humans and agents share one catalog layer.",
|
|
905
|
+
"aliases": [],
|
|
906
|
+
"audiences": [
|
|
907
|
+
"developers"
|
|
908
|
+
],
|
|
909
|
+
"tags": [
|
|
910
|
+
"integration",
|
|
911
|
+
"bff",
|
|
912
|
+
"agents"
|
|
913
|
+
],
|
|
914
|
+
"goals": [
|
|
915
|
+
"Wire a BFF and agent runtime so humans and agents share one catalog layer."
|
|
916
|
+
],
|
|
917
|
+
"path": "use-cases/embed-content-backend.md",
|
|
918
|
+
"webPath": "/use-cases#embed-content-backend",
|
|
919
|
+
"prerequisites": [],
|
|
920
|
+
"related": [
|
|
921
|
+
"00-overview",
|
|
922
|
+
"04-auth-identity"
|
|
923
|
+
],
|
|
924
|
+
"packIds": [
|
|
925
|
+
"use-case/embed-content-backend"
|
|
926
|
+
]
|
|
927
|
+
},
|
|
928
|
+
{
|
|
929
|
+
"id": "mongo-onboard",
|
|
930
|
+
"type": "use-case",
|
|
931
|
+
"title": "Onboard with Mongo",
|
|
932
|
+
"summary": "Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.",
|
|
933
|
+
"aliases": [],
|
|
934
|
+
"audiences": [
|
|
935
|
+
"developers"
|
|
936
|
+
],
|
|
937
|
+
"tags": [
|
|
938
|
+
"mongo",
|
|
939
|
+
"onboarding",
|
|
940
|
+
"ops"
|
|
941
|
+
],
|
|
942
|
+
"goals": [
|
|
943
|
+
"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId."
|
|
944
|
+
],
|
|
945
|
+
"path": "use-cases/mongo-onboard.md",
|
|
946
|
+
"webPath": "/use-cases#mongo-onboard",
|
|
947
|
+
"prerequisites": [],
|
|
948
|
+
"related": [
|
|
949
|
+
"05-cli-toolbox"
|
|
950
|
+
],
|
|
951
|
+
"packIds": [
|
|
952
|
+
"use-case/mongo-onboard"
|
|
953
|
+
]
|
|
954
|
+
},
|
|
955
|
+
{
|
|
956
|
+
"id": "auth-context",
|
|
957
|
+
"type": "use-case",
|
|
958
|
+
"title": "Map host auth to Catalox context",
|
|
959
|
+
"summary": "Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.",
|
|
960
|
+
"aliases": [],
|
|
961
|
+
"audiences": [
|
|
962
|
+
"developers"
|
|
963
|
+
],
|
|
964
|
+
"tags": [
|
|
965
|
+
"auth",
|
|
966
|
+
"identity"
|
|
967
|
+
],
|
|
968
|
+
"goals": [
|
|
969
|
+
"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured."
|
|
970
|
+
],
|
|
971
|
+
"path": "use-cases/auth-context.md",
|
|
972
|
+
"webPath": "/use-cases#auth-context",
|
|
973
|
+
"prerequisites": [],
|
|
974
|
+
"related": [
|
|
975
|
+
"01-content-backend"
|
|
976
|
+
],
|
|
977
|
+
"packIds": [
|
|
978
|
+
"use-case/auth-context"
|
|
979
|
+
]
|
|
980
|
+
},
|
|
981
|
+
{
|
|
982
|
+
"id": "cli-seed-items",
|
|
983
|
+
"type": "use-case",
|
|
984
|
+
"title": "Operate with CLI items and seed",
|
|
985
|
+
"summary": "Use elevated CLI access, items commands, and seed manifests safely.",
|
|
986
|
+
"aliases": [],
|
|
987
|
+
"audiences": [
|
|
988
|
+
"developers"
|
|
989
|
+
],
|
|
990
|
+
"tags": [
|
|
991
|
+
"cli",
|
|
992
|
+
"seed",
|
|
993
|
+
"ops"
|
|
994
|
+
],
|
|
995
|
+
"goals": [
|
|
996
|
+
"Use elevated CLI access, items commands, and seed manifests safely."
|
|
997
|
+
],
|
|
998
|
+
"path": "use-cases/cli-seed-items.md",
|
|
999
|
+
"webPath": "/use-cases#cli-seed-items",
|
|
1000
|
+
"prerequisites": [],
|
|
1001
|
+
"related": [
|
|
1002
|
+
"03-deploy-ops"
|
|
1003
|
+
],
|
|
1004
|
+
"packIds": [
|
|
1005
|
+
"use-case/cli-seed-items"
|
|
1006
|
+
]
|
|
1007
|
+
},
|
|
1008
|
+
{
|
|
1009
|
+
"id": "00-overview",
|
|
1010
|
+
"type": "book",
|
|
1011
|
+
"title": "Overview",
|
|
1012
|
+
"summary": "Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.",
|
|
1013
|
+
"aliases": [
|
|
1014
|
+
"CASE FILE · CAT-00"
|
|
1015
|
+
],
|
|
1016
|
+
"audiences": [
|
|
1017
|
+
"developers"
|
|
1018
|
+
],
|
|
1019
|
+
"tags": [
|
|
1020
|
+
"platform",
|
|
1021
|
+
"start-here",
|
|
1022
|
+
"overview"
|
|
1023
|
+
],
|
|
1024
|
+
"goals": [],
|
|
1025
|
+
"path": "books/00-overview/",
|
|
1026
|
+
"webPath": "/books/00-overview",
|
|
1027
|
+
"prerequisites": [],
|
|
1028
|
+
"related": [],
|
|
1029
|
+
"packIds": []
|
|
1030
|
+
},
|
|
1031
|
+
{
|
|
1032
|
+
"id": "01-content-backend",
|
|
1033
|
+
"type": "book",
|
|
1034
|
+
"title": "Content Backend",
|
|
1035
|
+
"summary": "Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.",
|
|
1036
|
+
"aliases": [
|
|
1037
|
+
"CASE FILE · CAT-01"
|
|
1038
|
+
],
|
|
1039
|
+
"audiences": [
|
|
1040
|
+
"developers"
|
|
1041
|
+
],
|
|
1042
|
+
"tags": [
|
|
1043
|
+
"integration",
|
|
1044
|
+
"bff",
|
|
1045
|
+
"agents"
|
|
1046
|
+
],
|
|
1047
|
+
"goals": [],
|
|
1048
|
+
"path": "books/01-content-backend/",
|
|
1049
|
+
"webPath": "/books/01-content-backend",
|
|
1050
|
+
"prerequisites": [],
|
|
1051
|
+
"related": [],
|
|
1052
|
+
"packIds": []
|
|
1053
|
+
},
|
|
1054
|
+
{
|
|
1055
|
+
"id": "02-persistence",
|
|
1056
|
+
"type": "book",
|
|
1057
|
+
"title": "Persistence",
|
|
1058
|
+
"summary": "createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.",
|
|
1059
|
+
"aliases": [
|
|
1060
|
+
"CASE FILE · CAT-02"
|
|
1061
|
+
],
|
|
1062
|
+
"audiences": [
|
|
1063
|
+
"developers"
|
|
1064
|
+
],
|
|
1065
|
+
"tags": [
|
|
1066
|
+
"mongo",
|
|
1067
|
+
"storage",
|
|
1068
|
+
"ops"
|
|
1069
|
+
],
|
|
1070
|
+
"goals": [],
|
|
1071
|
+
"path": "books/02-persistence/",
|
|
1072
|
+
"webPath": "/books/02-persistence",
|
|
1073
|
+
"prerequisites": [],
|
|
1074
|
+
"related": [],
|
|
1075
|
+
"packIds": []
|
|
1076
|
+
},
|
|
1077
|
+
{
|
|
1078
|
+
"id": "03-deploy-ops",
|
|
1079
|
+
"type": "book",
|
|
1080
|
+
"title": "Deploy & Ops",
|
|
1081
|
+
"summary": "Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.",
|
|
1082
|
+
"aliases": [
|
|
1083
|
+
"CASE FILE · CAT-03"
|
|
1084
|
+
],
|
|
1085
|
+
"audiences": [
|
|
1086
|
+
"developers"
|
|
1087
|
+
],
|
|
1088
|
+
"tags": [
|
|
1089
|
+
"deploy",
|
|
1090
|
+
"http",
|
|
1091
|
+
"onboarding"
|
|
1092
|
+
],
|
|
1093
|
+
"goals": [],
|
|
1094
|
+
"path": "books/03-deploy-ops/",
|
|
1095
|
+
"webPath": "/books/03-deploy-ops",
|
|
1096
|
+
"prerequisites": [],
|
|
1097
|
+
"related": [],
|
|
1098
|
+
"packIds": []
|
|
1099
|
+
},
|
|
1100
|
+
{
|
|
1101
|
+
"id": "04-auth-identity",
|
|
1102
|
+
"type": "book",
|
|
1103
|
+
"title": "Auth & Identity",
|
|
1104
|
+
"summary": "Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.",
|
|
1105
|
+
"aliases": [
|
|
1106
|
+
"CASE FILE · CAT-04"
|
|
1107
|
+
],
|
|
1108
|
+
"audiences": [
|
|
1109
|
+
"developers"
|
|
1110
|
+
],
|
|
1111
|
+
"tags": [
|
|
1112
|
+
"auth",
|
|
1113
|
+
"identity",
|
|
1114
|
+
"bindings"
|
|
1115
|
+
],
|
|
1116
|
+
"goals": [],
|
|
1117
|
+
"path": "books/04-auth-identity/",
|
|
1118
|
+
"webPath": "/books/04-auth-identity",
|
|
1119
|
+
"prerequisites": [],
|
|
1120
|
+
"related": [],
|
|
1121
|
+
"packIds": []
|
|
1122
|
+
},
|
|
1123
|
+
{
|
|
1124
|
+
"id": "05-cli-toolbox",
|
|
1125
|
+
"type": "book",
|
|
1126
|
+
"title": "CLI & Toolbox",
|
|
1127
|
+
"summary": "Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.",
|
|
1128
|
+
"aliases": [
|
|
1129
|
+
"CASE FILE · CAT-05"
|
|
1130
|
+
],
|
|
1131
|
+
"audiences": [
|
|
1132
|
+
"developers"
|
|
1133
|
+
],
|
|
1134
|
+
"tags": [
|
|
1135
|
+
"cli",
|
|
1136
|
+
"ops",
|
|
1137
|
+
"seed"
|
|
1138
|
+
],
|
|
1139
|
+
"goals": [],
|
|
1140
|
+
"path": "books/05-cli-toolbox/",
|
|
1141
|
+
"webPath": "/books/05-cli-toolbox",
|
|
1142
|
+
"prerequisites": [],
|
|
1143
|
+
"related": [],
|
|
1144
|
+
"packIds": []
|
|
1145
|
+
}
|
|
1146
|
+
]
|
|
1147
|
+
};
|
|
1148
|
+
export const files = {
|
|
1149
|
+
"downloads/books/00-overview/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-why-catalox-exists\",\n \"title\": \"1. Why Catalox exists\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-what-catalox-is\",\n \"title\": \"2. What Catalox is\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-fit-vs-misfit\",\n \"title\": \"3. Fit vs misfit\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-faq-highlights\",\n \"title\": \"4. FAQ highlights\",\n \"level\": 2,\n \"order\": 4\n }\n]",
|
|
1150
|
+
"downloads/books/00-overview/developers.md": "# Overview — Developers\n\n**Audience:** Engineers and architects deciding whether to build on Catalox. \n**Related:** [Content Backend](../../01-content-backend/developers/BOOK.md) · flat docs under `docs/`\n\n---\n\n## 1. Why Catalox exists\n\nEvery x12i product eventually needs the same thing:\n\n- A **catalog of things** users can browse, pick, configure, or reference — plans, skills, templates, policies, vocabulary, feature matrices, routing rules, prompt libraries.\n- A way for **multiple apps and agents** to discover those catalogs without hardcoding catalog ids, field lists, or CRUD endpoints.\n- **Governance** — who can see which catalog, which items apply to which account/domain/agent, and explicit outcomes when access or configuration is wrong.\n\nWithout a shared layer, each team rebuilds schemas, list/get APIs, admin field metadata, access rules, seed tooling, and agent-readable metadata. Catalox does that work **once**, with a stable contract, so product backends spend budget on checkout, workflows, execution, and billing — not catalog plumbing.\n\n---\n\n## 2. What Catalox is\n\n**Catalox is the metadata and content backend for governed catalogs** — the layer where you store *what can be selected or configured*, expose it consistently to web apps and agent runtimes, and keep operational transactions in your own services.\n\nIt is **not**:\n\n- A CMS for marketing pages\n- An OLTP database for orders, runs, or events\n- A UI framework (it returns descriptors and render hints; you render)\n- A login system (SSO stays in your SaaS; Authix gates the public HTTP API)\n\nIt ships as a **library + CLI + optional HTTP service** you embed or deploy against **MongoDB** (primary), with optional **Cloudflare R2** for record history and a one-time Firestore → Mongo import for migrating estates.\n\n**Rule of thumb:** Catalox stores the **definition or selectable item**; your host stores the **transaction, run, or event** that uses it.\n\n---\n\n## 3. Fit vs misfit\n\n### Good fits\n\n| Domain | Example catalogs |\n|--------|------------------|\n| Product & pricing | Plans, SKUs, feature bundles |\n| Routing & policy | Rules, feature flags, lookup tables |\n| Templates | Graph templates, prompt templates, execution matrices |\n| Knowledge & vocabulary | Skills, roles, use cases (smart properties) |\n| Configuration-as-data | Mappings, enums, design token refs |\n\n### Poor fits\n\n| Domain | Why not Catalox |\n|--------|-----------------|\n| Orders & payments | OLTP transaction state |\n| Live execution runs | High-churn operational state |\n| Event/audit streams | Append-heavy mutable logs |\n| Secret storage | Use a secrets manager; store refs only |\n\n---\n\n## 4. FAQ highlights\n\n- **Start here:** this overview, then Content Backend for the recommended integration pattern.\n- **Hosted SaaS?** No — packages you install on your infrastructure.\n- **`appId`:** Catalox catalog tenant (which app sees which catalogs) — **not** the Firebase/GCP project id.\n- **`@x12i/catalox` vs engine:** root package re-exports the engine and registers the `catalox` CLI; workspace development uses both.\n- **Persistence:** MongoDB is primary; Firestore operators are retired except migration import paths.\n",
|
|
1151
|
+
"downloads/books/01-content-backend/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-the-pattern\",\n \"title\": \"1. The pattern\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-architecture\",\n \"title\": \"2. Architecture\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-product-use-cases\",\n \"title\": \"3. Product use cases\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-consumers\",\n \"title\": \"4. Consumers\",\n \"level\": 2,\n \"order\": 4\n }\n]",
|
|
1152
|
+
"downloads/books/01-content-backend/developers.md": "# Content Backend — Developers\n\n**Audience:** Teams building web apps, dashboards, and agent platforms on x12i. \n**Prerequisite:** [Overview](../../00-overview/developers/BOOK.md)\n\nThis is the **recommended integration pattern**: your product’s backend and agents use Catalox as the API for content and metadata — catalogs purpose-built for that app — so you do not implement custom CRUD, discovery, or parallel “agent config” stores for every entity.\n\n---\n\n## 1. The pattern\n\nDefine catalogs (skills, templates, plans, vocabulary, policies) in Catalox with **descriptors** and **bindings** to your `appId`. Your web app’s BFF calls **bootstrap** and **items** APIs (embedded engine or HTTP client). Your agent runtime reads the **same items**, scoped by token or context. Your product backend owns **users, workflows, and transactions**; Catalox owns **what exists in the catalog and who can see it**.\n\n### Problem: two backends that drift\n\n```text\nAdmin UI ──► Postgres \"skills\" table ──► human-edited metadata\nAgent API ──► Redis / JSON files ──► agent-edited metadata ❌ drift\n```\n\n### Solution: one catalog layer, many consumers\n\n```text\n ┌──────────────┐\n Admin UI / SPA ──►│ │\n Mobile app ──►│ Your BFF │──► Catalox (skills, templates, …)\n Agent runtime ──►│ (thin) │\n CI seed job ──►│ │\n └──────────────┘\n │\n Workflows / runs / orders stay in YOUR services\n```\n\n**Why it works:** single source of truth; descriptors drive UI; bindings enforce product boundaries; scope narrows exposure; no per-entity Express routes for every catalog.\n\n| Catalox owns | Your app owns |\n|--------------|---------------|\n| Catalog records, descriptors, bindings | User authentication (SSO) |\n| Item storage (`item.data` + `indexed`) | Sessions, billing, entitlements |\n| List/get/filter/search by descriptor rules | Workflow state, execution runs |\n| Access outcomes (ok / denied / misconfigured) | Business logic that *uses* an item |\n\n**Rule:** If the question is “**what options exist?**” → Catalox. If “**what happened when the user clicked run?**” → your backend.\n\n---\n\n## 2. Architecture\n\n### Web app with admin + picker UI\n\n```text\nBrowser (React)\n │ SSO cookie / session\n ▼\nYour BFF (Node)\n │ 1. Authenticate user (your IdP)\n │ 2. Issue Authix token OR map user → CataloxContext\n │ 3. Call Catalox (embed or HTTP)\n ▼\nCatalox engine / catalox-service\n ▼\nMongoDB (native items + metadata collections)\n```\n\n**BFF:** map user → `accountId` / `domainId` / roles; least-privilege Authix or context; proxy Catalox — do **not** reimplement list/filter SQL per catalog.\n\n**SPA:** bootstrap + list items from descriptors (or catalox-ui); submit writes as item payloads.\n\n### Agent platform\n\nAgent runtimes use the same catalogs with a scoped token (`domainIds`, `agentIds`) or embedded `CataloxContext`. Humans and agents must not maintain separate config stores for the same vocabulary.\n\n---\n\n## 3. Product use cases\n\n| Use case | Goal |\n|----------|------|\n| Bootstrap a new app | Seed descriptors, bindings, and items for an `appId` |\n| Content API for SPA + agents | Shared read/write path without dual stores |\n| Operator seed / CI | Manifest validate + apply; batch upsert |\n| Private HTTP | Internal services via `catalox-service` (`open` mode on private network) |\n| Public Authix API | Partner / browser access (**6.1.0**) |\n\nSee also flat `docs/USE-CASES.md` for longer flow narratives.\n\n---\n\n## 4. Consumers\n\n| Consumer | Integration | Typical access |\n|----------|-------------|----------------|\n| Product BFF | Embed `@x12i/catalox` / engine | `createCatalox` + host auth → `CataloxContext` |\n| catalox-ui | BFF + optional HTTP client | Discovery + item read/write |\n| Agent runtimes | HTTP or embedder | Scoped token / context |\n| CI / seed workers | CLI or embedder | `seed apply`, `items batch-upsert` |\n| Platform ops | CLI | mongo probe, toolbox, history |\n| Partners | Public HTTP (6.1.0) | Authix via partner BFF |\n",
|
|
1153
|
+
"downloads/books/02-persistence/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-mongo-quick-start\",\n \"title\": \"1. Mongo quick start\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-environment\",\n \"title\": \"2. Environment\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-collection-layout\",\n \"title\": \"3. Collection layout\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-operator-notes\",\n \"title\": \"4. Operator notes\",\n \"level\": 2,\n \"order\": 4\n }\n]",
|
|
1154
|
+
"downloads/books/02-persistence/developers.md": "# Persistence — Developers\n\n**Audience:** Engineers wiring Mongo persistence and operators migrating estates. \n**Related:** [Deploy & Ops](../../03-deploy-ops/developers/BOOK.md) · flat `docs/mongo-persistence.md`\n\nCatalox uses **MongoDB** as the primary metadata + native-item backend. Collection names mirror the historical Firestore logical model.\n\n---\n\n## 1. Mongo quick start\n\n```ts\nimport { createCataloxFromEnv } from \"@x12i/catalox/mongo\";\n\nconst { catalox, mongoStore } = await createCataloxFromEnv({\n mongoUri: process.env.MONGO_URI, // optional when MONGO_URI / MONGODB_URI is set\n // dbName defaults to \"catalox\" when MONGO_DB_NAME / MONGODB_DB unset\n});\n\nconst scoped = catalox.withContext({ appId: \"myApp\", superAdmin: true });\nconst page = await scoped.listCatalogItems(\"myCatalog\", { limit: 50 });\n```\n\nWhen you already hold a connected client from `@x12i/helpers/mongo`, wrap it:\n\n```ts\nimport { initMongoDb } from \"@x12i/helpers/mongo\";\nimport { createCatalox, MongoStore } from \"@x12i/catalox/embedder\";\n\nconst api = await initMongoDb({ mongoUri: \"mongodb://127.0.0.1:27017\", dbName: \"catalox\" });\nconst catalox = createCatalox({ mongo: new MongoStore(api) });\n```\n\nNo Firebase Admin SDK is required for normal CRUD. `LocalFileStore` remains for offline fixtures/tests only.\n\nConnectivity probe:\n\n```ts\nimport { testMongoConnectionFromEnv } from \"@x12i/catalox/mongo\";\nconst probe = await testMongoConnectionFromEnv();\nif (!probe.ok) throw probe.error;\n```\n\n```bash\ncatalox mongo probe\n```\n\n---\n\n## 2. Environment\n\n| Variable | Purpose |\n|----------|---------|\n| **`MONGO_URI`** or **`MONGODB_URI`** | Required connection string for primary Mongo persistence |\n| **`MONGO_DB_NAME`** or **`MONGODB_DB`** | Database name (default **`catalox`**) |\n| **`CATALOX_MONGO_URI`** | Optional mapped-catalog adapter URI override |\n\nObject store (record history after 6.0.0 R2 cutover): `S3_*` / `CATALOX_BUCKET`. Google SA vars are **migration only** (`mongo import-from-firestore`, `storage migrate-from-gcs`).\n\n---\n\n## 3. Collection layout\n\n| Collection | Content |\n|------------|---------|\n| `apps` | App records |\n| `catalogs` | Catalog metadata |\n| `catalogBindings` | App ↔ catalog access |\n| `catalogDescriptors` | Descriptor documents |\n| `catalogData-{catalogId}-items` | Native item rows |\n| `catalogSnapshots/{catalogId}/items` | Snapshot rows |\n| … | Registry stores (`catalogDefinitions`, `catalogMappings`, `catalogReferences`, …) |\n\n---\n\n## 4. Operator notes\n\n- **CRUD / seed / snapshot export / history** (default R2 bucket `catalox`) / catalog delete·rename work on Mongo.\n- **Retired Firestore operators** (`catalox firestore backup|export-gcs|migrate-*`, etc.) exit with a clear error.\n- **One-time document migration:** `catalox mongo import-from-firestore` (Firestore credentials + `MONGO_URI`).\n- **One-time object migration:** `catalox storage migrate-from-gcs` (GCS → R2).\n\n```bash\ncatalox mongo probe\ncatalox mongo import-from-firestore --db catalox\ncatalox mongo import-from-firestore --dry-run\n```\n\nLive integration tests: set `MONGO_LIVE_TESTS=1` and a reachable `MONGO_URI`.\n",
|
|
1155
|
+
"downloads/books/03-deploy-ops/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-deployment-modes\",\n \"title\": \"1. Deployment modes\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-embedder\",\n \"title\": \"2. Embedder\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-private-and-public-http\",\n \"title\": \"3. Private and public HTTP\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-onboarding-happy-path\",\n \"title\": \"4. Onboarding happy path\",\n \"level\": 2,\n \"order\": 4\n },\n {\n \"slug\": \"5-environment-variables\",\n \"title\": \"5. Environment variables\",\n \"level\": 2,\n \"order\": 5\n }\n]",
|
|
1156
|
+
"downloads/books/03-deploy-ops/developers.md": "# Deploy & Ops — Developers\n\n**Audience:** Engineers embedding Catalox, running the CLI, or deploying catalox-service. \n**Related:** [Persistence](../../02-persistence/developers/BOOK.md) · flat `docs/DEPLOYMENT.md`\n\n---\n\n## 1. Deployment modes\n\n| Mode | Artifact | Network | Auth | When |\n|------|----------|---------|------|------|\n| **Embedder** | `@x12i/catalox` / engine | In-process | Host → `CataloxContext` | BFFs, workers |\n| **CLI** | `catalox` bin | Outbound to Mongo (+ R2) | Service creds | Seed, ops |\n| **Private HTTP** | `catalox-service` | Internal only | `CATALOX_AUTH_MODE=open` | Internal services |\n| **Public HTTP** | same + Authix | HTTPS public | `authix` Bearer | **6.1.0** |\n| **Fixtures** | `LocalFileStore` | None | File ACL | Tests only |\n\n**Prerequisites:** Node `>=20`, **`MONGO_URI`**, R2/`S3_*` for history after object cutover, Google SA for migration only, Authix for production public API.\n\n---\n\n## 2. Embedder\n\n```bash\nnpm install @x12i/catalox\n```\n\n```ts\nimport { createCataloxFromEnv } from \"@x12i/catalox/mongo\";\n\nconst { catalox } = await createCataloxFromEnv({\n mongoUri: process.env.MONGO_URI,\n});\n```\n\nMap host auth into `CataloxContext` (see Auth & Identity). Prefer embedder for BFFs that already trust the caller.\n\n---\n\n## 3. Private and public HTTP\n\n### Private (`catalox-service`)\n\n```bash\nexport MONGO_URI=...\nexport CATALOX_AUTH_MODE=open\nexport CATALOX_PRIVATE_MODE=true\n# optional: CATALOX_DEFAULT_SUPER_ADMIN=true (never on a public URL)\n```\n\nBind ClusterIP / private network only. Client: `withContext` + `X-Catalox-Context`.\n\n**Critical:** `open` + `superAdmin` must never be reachable from the public internet.\n\n### Public (6.1.0 + Authix)\n\n| Variable | Value |\n|----------|--------|\n| `CATALOX_AUTH_MODE` | `authix` |\n| `AUTHIX_APP_ID` / `AUTHIX_APP_SECRET_KEY` | Required |\n| `AUTHIX_INTROSPECT_URL` | Required for writes |\n| `CATALOX_CORS_ORIGINS` | Browser allowlist |\n| `MONGO_URI` + R2 | From 6.0.0 |\n\nComplete the 6.0.0 checklist before enabling public Authix.\n\n---\n\n## 4. Onboarding happy path\n\nZero → working catalogs:\n\n```bash\nexport MONGO_URI=\"mongodb://127.0.0.1:27017\"\n# optional:\nexport MONGO_DB_NAME=\"catalox\"\nexport CATALOX_APP_ID=\"<yourCataloxAppId>\"\n\nnpx catalox mongo probe\nnpx catalox seed --app \"$CATALOX_APP_ID\" # or project seed script / npm run seed:pagenti\nnpx catalox items list --app \"$CATALOX_APP_ID\" --catalog <catalogId>\n```\n\nExpect probe `{ \"ok\": true, ... }`. Validate payloads with `catalox items validate` before large batch upserts.\n\n---\n\n## 5. Environment variables\n\n| Prefix | Purpose |\n|--------|--------|\n| **`MONGO_*` / `MONGODB_*`** | Primary persistence |\n| **`S3_*` / `CATALOX_BUCKET`** | R2 object store for record history |\n| **`CATALOX_*`** | Runtime context: `appId`, `storeId`, actor, history options, auth mode |\n| **`GOOGLE_*` / `FIREBASE_*` / `FIRESTORE_*`** | Legacy migration only |\n\nCLI loads `.env` from the working directory via `dotenv`. `CATALOX_RESTRICTED=1` forces `superAdmin: false` (same as `--restricted`).\n",
|
|
1157
|
+
"downloads/books/04-auth-identity/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-identity-axes\",\n \"title\": \"1. Identity axes\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-super-admin\",\n \"title\": \"2. Super admin\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-catalog-and-item-visibility\",\n \"title\": \"3. Catalog and item visibility\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-empty-vs-denied\",\n \"title\": \"4. Empty vs denied\",\n \"level\": 2,\n \"order\": 4\n }\n]",
|
|
1158
|
+
"downloads/books/04-auth-identity/developers.md": "# Auth & Identity — Developers\n\n**Audience:** Embedders mapping host auth into Catalox. \n**Related:** [Content Backend](../../01-content-backend/developers/BOOK.md) · flat `docs/authorization.md`, `docs/identity-model.md`\n\nCatalox does **not** authenticate callers. The host provides coordinates in `CataloxContext`; Catalox evaluates visibility from context + bindings/policy.\n\n---\n\n## 1. Identity axes\n\nCatalox evaluates access using up to three independent axes:\n\n- **App axis:** `appId` and optional `storeId`\n- **Tenant axis:** `accountId`, `groupId`, `userId`, `channelId`, `visitorId`\n- **Agent axis:** `domainId`, `agentId`\n\n```mermaid\nflowchart LR\n subgraph appAxis [App Axis]\n Store --> App\n end\n subgraph tenantAxis [Tenant Axis]\n Account --> Group\n Account --> Channel\n Group --> User\n Channel --> Visitor\n end\n subgraph agentAxis [Agent Axis]\n Domain --> Agent\n end\n```\n\nAxes are **orthogonal** — not a single hierarchy. App/store tenancy stays separate from human/org identity. Store membership may help discovery but does not automatically grant catalog/item permissions unless policy says so.\n\n---\n\n## 2. Super admin\n\n`CataloxContext.superAdmin === true` is an explicit, host-controlled elevation flag.\n\n- May bypass some binding checks (e.g. app↔catalog) for operator workflows.\n- Must **not** be inferred from user-provided headers without host authentication.\n- Even when elevated, writes may still require bindings or explicit “super list” for all physical rows.\n\nCLI contexts are elevated by default; pass `--restricted` or `CATALOX_RESTRICTED=1` to enforce bindings. Authix public mode sets `superAdmin: false` for non-operator tokens.\n\n---\n\n## 3. Catalog and item visibility\n\n### Catalog discovery / bootstrap\n\n- **App-first:** catalogs visible via app↔catalog bindings.\n- **Identity-first:** catalogs visible via identity↔catalog bindings.\n\nWhen both exist, host policy chooses **intersection** (default safe) or **union**.\n\n### Item visibility (native catalogs)\n\nNative catalogs may hold multiple physical rows per logical item id. Tenant-axis and agent-axis scopes are independent — an item may be scoped by tenant, by agent, by both, or by neither (global). Mapped catalogs are currently catalog-scoped only.\n\n---\n\n## 4. Empty vs denied\n\nEmbedders must distinguish:\n\n| Outcome | Meaning |\n|---------|---------|\n| **empty** | Authorized, but zero data for that view |\n| **denied** | Caller not authorized (bindings/policy) |\n| **misconfigured** | Catalog exists but missing required config (descriptor/definition/mapping/adapter) |\n| **mapping_blocked** | Mapping spec invalid; execution refused |\n\nUse `listCatalogItemsWithOutcome` (and toolbox `check-access`) rather than treating empty lists as success when diagnosis matters. See flat `docs/outcomes.md` for taxonomy detail.\n",
|
|
1159
|
+
"downloads/books/05-cli-toolbox/developers.chapters.json": "[\n {\n \"slug\": \"preamble\",\n \"title\": \"Introduction\",\n \"level\": 2,\n \"order\": 0\n },\n {\n \"slug\": \"1-cli-access\",\n \"title\": \"1. CLI access\",\n \"level\": 2,\n \"order\": 1\n },\n {\n \"slug\": \"2-items-commands\",\n \"title\": \"2. Items commands\",\n \"level\": 2,\n \"order\": 2\n },\n {\n \"slug\": \"3-toolbox-diagnostics\",\n \"title\": \"3. Toolbox diagnostics\",\n \"level\": 2,\n \"order\": 3\n },\n {\n \"slug\": \"4-seed-workflow\",\n \"title\": \"4. Seed workflow\",\n \"level\": 2,\n \"order\": 4\n }\n]",
|
|
1160
|
+
"downloads/books/05-cli-toolbox/developers.md": "# CLI & Toolbox — Developers\n\n**Audience:** Operators and CI wiring Catalox CLI. \n**Related:** [Deploy & Ops](../../03-deploy-ops/developers/BOOK.md) · flat `docs/cli-*.md`\n\n---\n\n## 1. CLI access\n\nCatalox CLI contexts are **elevated** unless you explicitly restrict them:\n\n| Mechanism | Effect |\n|-----------|--------|\n| (default) | `superAdmin: true` — full operator access |\n| `--restricted` | `superAdmin: false` — catalog binding checks apply |\n| `CATALOX_RESTRICTED=1` | Same as `--restricted` |\n\n`--god` is **removed / unnecessary**. Library hosts: omit `superAdmin` or set `true` for open access; set **`superAdmin: false`** only when intentionally restricting.\n\n---\n\n## 2. Items commands\n\nOperator commands over the same Catalox APIs your app uses. Prefer `MONGO_URI` + `CATALOX_APP_ID` (or `--app` per command).\n\n| Command | Purpose |\n|--------|---------|\n| `items validate` | Catalog config or item payload/relations/smart properties |\n| `items get` | `getCatalogItem` |\n| `items list` | `listCatalogItemsWithOutcome` |\n| `items upsert` / `patch` / `delete` | Native item mutations (`delete` needs `--confirm`) |\n| `items batch-upsert` / `batch-replace` | JSON array or NDJSON |\n| `items export` | Stable export JSON with pagination caps |\n\nNative upsert body (preferred, matches seed rows):\n\n```json\n{ \"data\": { /* identity + fields */ }, \"scope\": { }, \"relations\": [ ] }\n```\n\nExamples:\n\n```bash\ncatalox mongo probe\ncatalox items list --app my-app --catalog signals\ncatalox items validate --app my-app --catalog entities --item some-id\ncatalox items upsert --app my-app --catalog signals --file item.json\n```\n\nWhen restricted, reads need a **read** binding; writes need **write** access where the API enforces it.\n\n---\n\n## 3. Toolbox diagnostics\n\n`catalox toolbox` answers: **“Can this `appId` read this `catalogId`, and why not?”**\n\n```bash\ncatalox toolbox check-access --app <appId> --catalog <catalogId>\n```\n\nReports binding document presence/fields, catalog existence, and `listCatalogItemsWithOutcome` for the same path embedders use. Use `toolbox ensure-binding` / `repair-binding` to create or fix binding documents when appropriate.\n\nPass `--restricted` when you want binding checks to apply (default CLI is elevated).\n\n---\n\n## 4. Seed workflow\n\nRepeatable manifests beat one-off scripts:\n\n```bash\ncatalox seed validate --file preset.json\ncatalox seed apply --app myApp --file preset.json\n# or project scripts, e.g. npm run seed:pagenti\ncatalox items list --app myApp --catalog signals\n```\n\nValidate before write; apply is idempotent for well-formed manifests. Combine with `items batch-upsert` for incremental CI updates after the initial seed.\n",
|
|
1161
|
+
"downloads/use-cases/auth-context.md": "# Map host auth to Catalox context\n\n> **Use case id:** `auth-context`\n> **Goal:** Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\n> **Audiences:** developers\n> **Tags:** auth, identity\n\n## Reading path\n\n1. **Auth & Identity** (developers) → chapters: `1-identity-axes`, `2-super-admin`, `3-catalog-and-item-visibility`, `4-empty-vs-denied`\n\n## From: Auth & Identity — 1. Identity axes\n\nCatalox evaluates access using up to three independent axes:\n\n- **App axis:** `appId` and optional `storeId`\n- **Tenant axis:** `accountId`, `groupId`, `userId`, `channelId`, `visitorId`\n- **Agent axis:** `domainId`, `agentId`\n\n```mermaid\nflowchart LR\n subgraph appAxis [App Axis]\n Store --> App\n end\n subgraph tenantAxis [Tenant Axis]\n Account --> Group\n Account --> Channel\n Group --> User\n Channel --> Visitor\n end\n subgraph agentAxis [Agent Axis]\n Domain --> Agent\n end\n```\n\nAxes are **orthogonal** — not a single hierarchy. App/store tenancy stays separate from human/org identity. Store membership may help discovery but does not automatically grant catalog/item permissions unless policy says so.\n\n---\n\n## From: Auth & Identity — 2. Super admin\n\n`CataloxContext.superAdmin === true` is an explicit, host-controlled elevation flag.\n\n- May bypass some binding checks (e.g. app↔catalog) for operator workflows.\n- Must **not** be inferred from user-provided headers without host authentication.\n- Even when elevated, writes may still require bindings or explicit “super list” for all physical rows.\n\nCLI contexts are elevated by default; pass `--restricted` or `CATALOX_RESTRICTED=1` to enforce bindings. Authix public mode sets `superAdmin: false` for non-operator tokens.\n\n---\n\n## From: Auth & Identity — 3. Catalog and item visibility\n\n### Catalog discovery / bootstrap\n\n- **App-first:** catalogs visible via app↔catalog bindings.\n- **Identity-first:** catalogs visible via identity↔catalog bindings.\n\nWhen both exist, host policy chooses **intersection** (default safe) or **union**.\n\n### Item visibility (native catalogs)\n\nNative catalogs may hold multiple physical rows per logical item id. Tenant-axis and agent-axis scopes are independent — an item may be scoped by tenant, by agent, by both, or by neither (global). Mapped catalogs are currently catalog-scoped only.\n\n---\n\n## From: Auth & Identity — 4. Empty vs denied\n\nEmbedders must distinguish:\n\n| Outcome | Meaning |\n|---------|---------|\n| **empty** | Authorized, but zero data for that view |\n| **denied** | Caller not authorized (bindings/policy) |\n| **misconfigured** | Catalog exists but missing required config (descriptor/definition/mapping/adapter) |\n| **mapping_blocked** | Mapping spec invalid; execution refused |\n\nUse `listCatalogItemsWithOutcome` (and toolbox `check-access`) rather than treating empty lists as success when diagnosis matters. See flat `docs/outcomes.md` for taxonomy detail.\n\n## Also see\n\n- **Content Backend** (`01-content-backend`) — Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1162
|
+
"downloads/use-cases/cli-seed-items.md": "# Operate with CLI items and seed\n\n> **Use case id:** `cli-seed-items`\n> **Goal:** Use elevated CLI access, items commands, and seed manifests safely.\n> **Audiences:** developers\n> **Tags:** cli, seed, ops\n\n## Reading path\n\n1. **CLI & Toolbox** (developers) → chapters: `1-cli-access`, `2-items-commands`, `4-seed-workflow`\n\n## From: CLI & Toolbox — 1. CLI access\n\nCatalox CLI contexts are **elevated** unless you explicitly restrict them:\n\n| Mechanism | Effect |\n|-----------|--------|\n| (default) | `superAdmin: true` — full operator access |\n| `--restricted` | `superAdmin: false` — catalog binding checks apply |\n| `CATALOX_RESTRICTED=1` | Same as `--restricted` |\n\n`--god` is **removed / unnecessary**. Library hosts: omit `superAdmin` or set `true` for open access; set **`superAdmin: false`** only when intentionally restricting.\n\n---\n\n## From: CLI & Toolbox — 2. Items commands\n\nOperator commands over the same Catalox APIs your app uses. Prefer `MONGO_URI` + `CATALOX_APP_ID` (or `--app` per command).\n\n| Command | Purpose |\n|--------|---------|\n| `items validate` | Catalog config or item payload/relations/smart properties |\n| `items get` | `getCatalogItem` |\n| `items list` | `listCatalogItemsWithOutcome` |\n| `items upsert` / `patch` / `delete` | Native item mutations (`delete` needs `--confirm`) |\n| `items batch-upsert` / `batch-replace` | JSON array or NDJSON |\n| `items export` | Stable export JSON with pagination caps |\n\nNative upsert body (preferred, matches seed rows):\n\n```json\n{ \"data\": { /* identity + fields */ }, \"scope\": { }, \"relations\": [ ] }\n```\n\nExamples:\n\n```bash\ncatalox mongo probe\ncatalox items list --app my-app --catalog signals\ncatalox items validate --app my-app --catalog entities --item some-id\ncatalox items upsert --app my-app --catalog signals --file item.json\n```\n\nWhen restricted, reads need a **read** binding; writes need **write** access where the API enforces it.\n\n---\n\n## From: CLI & Toolbox — 4. Seed workflow\n\nRepeatable manifests beat one-off scripts:\n\n```bash\ncatalox seed validate --file preset.json\ncatalox seed apply --app myApp --file preset.json\n# or project scripts, e.g. npm run seed:pagenti\ncatalox items list --app myApp --catalog signals\n```\n\nValidate before write; apply is idempotent for well-formed manifests. Combine with `items batch-upsert` for incremental CI updates after the initial seed.\n\n## Also see\n\n- **Deploy & Ops** (`03-deploy-ops`) — Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1163
|
+
"downloads/use-cases/embed-content-backend.md": "# Embed as content backend\n\n> **Use case id:** `embed-content-backend`\n> **Goal:** Wire a BFF and agent runtime so humans and agents share one catalog layer.\n> **Audiences:** developers\n> **Tags:** integration, bff, agents\n\n## Reading path\n\n1. **Content Backend** (developers) → chapters: `1-the-pattern`, `2-architecture`, `3-product-use-cases`\n\n## From: Content Backend — 1. The pattern\n\nDefine catalogs (skills, templates, plans, vocabulary, policies) in Catalox with **descriptors** and **bindings** to your `appId`. Your web app’s BFF calls **bootstrap** and **items** APIs (embedded engine or HTTP client). Your agent runtime reads the **same items**, scoped by token or context. Your product backend owns **users, workflows, and transactions**; Catalox owns **what exists in the catalog and who can see it**.\n\n### Problem: two backends that drift\n\n```text\nAdmin UI ──► Postgres \"skills\" table ──► human-edited metadata\nAgent API ──► Redis / JSON files ──► agent-edited metadata ❌ drift\n```\n\n### Solution: one catalog layer, many consumers\n\n```text\n ┌──────────────┐\n Admin UI / SPA ──►│ │\n Mobile app ──►│ Your BFF │──► Catalox (skills, templates, …)\n Agent runtime ──►│ (thin) │\n CI seed job ──►│ │\n └──────────────┘\n │\n Workflows / runs / orders stay in YOUR services\n```\n\n**Why it works:** single source of truth; descriptors drive UI; bindings enforce product boundaries; scope narrows exposure; no per-entity Express routes for every catalog.\n\n| Catalox owns | Your app owns |\n|--------------|---------------|\n| Catalog records, descriptors, bindings | User authentication (SSO) |\n| Item storage (`item.data` + `indexed`) | Sessions, billing, entitlements |\n| List/get/filter/search by descriptor rules | Workflow state, execution runs |\n| Access outcomes (ok / denied / misconfigured) | Business logic that *uses* an item |\n\n**Rule:** If the question is “**what options exist?**” → Catalox. If “**what happened when the user clicked run?**” → your backend.\n\n---\n\n## From: Content Backend — 2. Architecture\n\n### Web app with admin + picker UI\n\n```text\nBrowser (React)\n │ SSO cookie / session\n ▼\nYour BFF (Node)\n │ 1. Authenticate user (your IdP)\n │ 2. Issue Authix token OR map user → CataloxContext\n │ 3. Call Catalox (embed or HTTP)\n ▼\nCatalox engine / catalox-service\n ▼\nMongoDB (native items + metadata collections)\n```\n\n**BFF:** map user → `accountId` / `domainId` / roles; least-privilege Authix or context; proxy Catalox — do **not** reimplement list/filter SQL per catalog.\n\n**SPA:** bootstrap + list items from descriptors (or catalox-ui); submit writes as item payloads.\n\n### Agent platform\n\nAgent runtimes use the same catalogs with a scoped token (`domainIds`, `agentIds`) or embedded `CataloxContext`. Humans and agents must not maintain separate config stores for the same vocabulary.\n\n---\n\n## From: Content Backend — 3. Product use cases\n\n| Use case | Goal |\n|----------|------|\n| Bootstrap a new app | Seed descriptors, bindings, and items for an `appId` |\n| Content API for SPA + agents | Shared read/write path without dual stores |\n| Operator seed / CI | Manifest validate + apply; batch upsert |\n| Private HTTP | Internal services via `catalox-service` (`open` mode on private network) |\n| Public Authix API | Partner / browser access (**6.1.0**) |\n\nSee also flat `docs/USE-CASES.md` for longer flow narratives.\n\n---\n\n## Also see\n\n- **Overview** (`00-overview`) — Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\n- **Auth & Identity** (`04-auth-identity`) — Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1164
|
+
"downloads/use-cases/mongo-onboard.md": "# Onboard with Mongo\n\n> **Use case id:** `mongo-onboard`\n> **Goal:** Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\n> **Audiences:** developers\n> **Tags:** mongo, onboarding, ops\n\n## Reading path\n\n1. **Persistence** (developers) → chapters: `1-mongo-quick-start`, `2-environment`\n1. **Deploy & Ops** (developers) → chapters: `4-onboarding-happy-path`\n\n## From: Persistence — 1. Mongo quick start\n\n```ts\nimport { createCataloxFromEnv } from \"@x12i/catalox/mongo\";\n\nconst { catalox, mongoStore } = await createCataloxFromEnv({\n mongoUri: process.env.MONGO_URI, // optional when MONGO_URI / MONGODB_URI is set\n // dbName defaults to \"catalox\" when MONGO_DB_NAME / MONGODB_DB unset\n});\n\nconst scoped = catalox.withContext({ appId: \"myApp\", superAdmin: true });\nconst page = await scoped.listCatalogItems(\"myCatalog\", { limit: 50 });\n```\n\nWhen you already hold a connected client from `@x12i/helpers/mongo`, wrap it:\n\n```ts\nimport { initMongoDb } from \"@x12i/helpers/mongo\";\nimport { createCatalox, MongoStore } from \"@x12i/catalox/embedder\";\n\nconst api = await initMongoDb({ mongoUri: \"mongodb://127.0.0.1:27017\", dbName: \"catalox\" });\nconst catalox = createCatalox({ mongo: new MongoStore(api) });\n```\n\nNo Firebase Admin SDK is required for normal CRUD. `LocalFileStore` remains for offline fixtures/tests only.\n\nConnectivity probe:\n\n```ts\nimport { testMongoConnectionFromEnv } from \"@x12i/catalox/mongo\";\nconst probe = await testMongoConnectionFromEnv();\nif (!probe.ok) throw probe.error;\n```\n\n```bash\ncatalox mongo probe\n```\n\n---\n\n## From: Persistence — 2. Environment\n\n| Variable | Purpose |\n|----------|---------|\n| **`MONGO_URI`** or **`MONGODB_URI`** | Required connection string for primary Mongo persistence |\n| **`MONGO_DB_NAME`** or **`MONGODB_DB`** | Database name (default **`catalox`**) |\n| **`CATALOX_MONGO_URI`** | Optional mapped-catalog adapter URI override |\n\nObject store (record history after 6.0.0 R2 cutover): `S3_*` / `CATALOX_BUCKET`. Google SA vars are **migration only** (`mongo import-from-firestore`, `storage migrate-from-gcs`).\n\n---\n\n## From: Deploy & Ops — 4. Onboarding happy path\n\nZero → working catalogs:\n\n```bash\nexport MONGO_URI=\"mongodb://127.0.0.1:27017\"\n# optional:\nexport MONGO_DB_NAME=\"catalox\"\nexport CATALOX_APP_ID=\"<yourCataloxAppId>\"\n\nnpx catalox mongo probe\nnpx catalox seed --app \"$CATALOX_APP_ID\" # or project seed script / npm run seed:pagenti\nnpx catalox items list --app \"$CATALOX_APP_ID\" --catalog <catalogId>\n```\n\nExpect probe `{ \"ok\": true, ... }`. Validate payloads with `catalox items validate` before large batch upserts.\n\n---\n\n## Also see\n\n- **CLI & Toolbox** (`05-cli-toolbox`) — Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1165
|
+
"downloads/use-cases/orient-catalox.md": "# Orient on Catalox\n\n> **Use case id:** `orient-catalox`\n> **Goal:** Understand why Catalox exists, what it owns, and when not to use it.\n> **Audiences:** developers\n> **Tags:** platform, start-here\n\n## Reading path\n\n1. **Overview** (developers) → chapters: `1-why-catalox-exists`, `2-what-catalox-is`, `3-fit-vs-misfit`\n\n## From: Overview — 1. Why Catalox exists\n\nEvery x12i product eventually needs the same thing:\n\n- A **catalog of things** users can browse, pick, configure, or reference — plans, skills, templates, policies, vocabulary, feature matrices, routing rules, prompt libraries.\n- A way for **multiple apps and agents** to discover those catalogs without hardcoding catalog ids, field lists, or CRUD endpoints.\n- **Governance** — who can see which catalog, which items apply to which account/domain/agent, and explicit outcomes when access or configuration is wrong.\n\nWithout a shared layer, each team rebuilds schemas, list/get APIs, admin field metadata, access rules, seed tooling, and agent-readable metadata. Catalox does that work **once**, with a stable contract, so product backends spend budget on checkout, workflows, execution, and billing — not catalog plumbing.\n\n---\n\n## From: Overview — 2. What Catalox is\n\n**Catalox is the metadata and content backend for governed catalogs** — the layer where you store *what can be selected or configured*, expose it consistently to web apps and agent runtimes, and keep operational transactions in your own services.\n\nIt is **not**:\n\n- A CMS for marketing pages\n- An OLTP database for orders, runs, or events\n- A UI framework (it returns descriptors and render hints; you render)\n- A login system (SSO stays in your SaaS; Authix gates the public HTTP API)\n\nIt ships as a **library + CLI + optional HTTP service** you embed or deploy against **MongoDB** (primary), with optional **Cloudflare R2** for record history and a one-time Firestore → Mongo import for migrating estates.\n\n**Rule of thumb:** Catalox stores the **definition or selectable item**; your host stores the **transaction, run, or event** that uses it.\n\n---\n\n## From: Overview — 3. Fit vs misfit\n\n### Good fits\n\n| Domain | Example catalogs |\n|--------|------------------|\n| Product & pricing | Plans, SKUs, feature bundles |\n| Routing & policy | Rules, feature flags, lookup tables |\n| Templates | Graph templates, prompt templates, execution matrices |\n| Knowledge & vocabulary | Skills, roles, use cases (smart properties) |\n| Configuration-as-data | Mappings, enums, design token refs |\n\n### Poor fits\n\n| Domain | Why not Catalox |\n|--------|-----------------|\n| Orders & payments | OLTP transaction state |\n| Live execution runs | High-churn operational state |\n| Event/audit streams | Append-heavy mutable logs |\n| Secret storage | Use a secrets manager; store refs only |\n\n---\n\n## Also see\n\n- **Content Backend** (`01-content-backend`) — Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1166
|
+
"agent/agent-manifest.json": "{\n \"version\": 1,\n \"product\": \"catalox\",\n \"site\": \"https://docs.catalox.x12i.com\",\n \"knowledgePackage\": \"@x12i/catalox-docs\",\n \"roles\": [\n \"developers\"\n ],\n \"books\": [\n {\n \"id\": \"00-overview\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/00-overview/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/00-overview/developers.chapters.json\"\n }\n },\n {\n \"id\": \"01-content-backend\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/01-content-backend/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/01-content-backend/developers.chapters.json\"\n }\n },\n {\n \"id\": \"02-persistence\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/02-persistence/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/02-persistence/developers.chapters.json\"\n }\n },\n {\n \"id\": \"03-deploy-ops\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/03-deploy-ops/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/03-deploy-ops/developers.chapters.json\"\n }\n },\n {\n \"id\": \"04-auth-identity\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/04-auth-identity/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/04-auth-identity/developers.chapters.json\"\n }\n },\n {\n \"id\": \"05-cli-toolbox\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/05-cli-toolbox/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/05-cli-toolbox/developers.chapters.json\"\n }\n }\n ],\n \"useCases\": [\n {\n \"id\": \"orient-catalox\",\n \"title\": \"Orient on Catalox\",\n \"md\": \"downloads/use-cases/orient-catalox.md\",\n \"path\": [\n {\n \"bookId\": \"00-overview\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-why-catalox-exists\",\n \"2-what-catalox-is\",\n \"3-fit-vs-misfit\"\n ]\n }\n ]\n },\n {\n \"id\": \"embed-content-backend\",\n \"title\": \"Embed as content backend\",\n \"md\": \"downloads/use-cases/embed-content-backend.md\",\n \"path\": [\n {\n \"bookId\": \"01-content-backend\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-the-pattern\",\n \"2-architecture\",\n \"3-product-use-cases\"\n ]\n }\n ]\n },\n {\n \"id\": \"mongo-onboard\",\n \"title\": \"Onboard with Mongo\",\n \"md\": \"downloads/use-cases/mongo-onboard.md\",\n \"path\": [\n {\n \"bookId\": \"02-persistence\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-mongo-quick-start\",\n \"2-environment\"\n ]\n },\n {\n \"bookId\": \"03-deploy-ops\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"4-onboarding-happy-path\"\n ]\n }\n ]\n },\n {\n \"id\": \"auth-context\",\n \"title\": \"Map host auth to Catalox context\",\n \"md\": \"downloads/use-cases/auth-context.md\",\n \"path\": [\n {\n \"bookId\": \"04-auth-identity\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-identity-axes\",\n \"2-super-admin\",\n \"3-catalog-and-item-visibility\",\n \"4-empty-vs-denied\"\n ]\n }\n ]\n },\n {\n \"id\": \"cli-seed-items\",\n \"title\": \"Operate with CLI items and seed\",\n \"md\": \"downloads/use-cases/cli-seed-items.md\",\n \"path\": [\n {\n \"bookId\": \"05-cli-toolbox\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-cli-access\",\n \"2-items-commands\",\n \"4-seed-workflow\"\n ]\n }\n ]\n }\n ],\n \"indexes\": {\n \"indexMd\": \"INDEX.md\",\n \"searchJson\": \"SEARCH.json\"\n },\n \"concepts\": [\n {\n \"id\": \"catalog-as-platform\",\n \"title\": \"Catalog as platform\",\n \"md\": \"concepts/catalog-as-platform.md\"\n },\n {\n \"id\": \"mongo-primary\",\n \"title\": \"MongoDB is primary persistence\",\n \"md\": \"concepts/mongo-primary.md\"\n }\n ],\n \"guides\": [\n {\n \"id\": \"embed-catalox\",\n \"title\": \"Embed Catalox from env\",\n \"md\": \"guides/embed-catalox.md\"\n }\n ],\n \"scenarios\": [\n {\n \"id\": \"choose-deploy-mode\",\n \"title\": \"Choose embed vs HTTP service\",\n \"md\": \"scenarios/choose-deploy-mode.md\"\n }\n ],\n \"decisions\": [],\n \"glossary\": [],\n \"visuals\": [],\n \"diagrams\": [],\n \"relationships\": [],\n \"tutorials\": [],\n \"examples\": [],\n \"sampleData\": [],\n \"uiClients\": [],\n \"apis\": [],\n \"packs\": [\n {\n \"id\": \"concept/catalog-as-platform\",\n \"type\": \"concept\",\n \"path\": \"packs/concept/catalog-as-platform\"\n },\n {\n \"id\": \"concept/mongo-primary\",\n \"type\": \"concept\",\n \"path\": \"packs/concept/mongo-primary\"\n },\n {\n \"id\": \"guide/embed-catalox\",\n \"type\": \"guide\",\n \"path\": \"packs/guide/embed-catalox\"\n },\n {\n \"id\": \"scenario/choose-deploy-mode\",\n \"type\": \"scenario\",\n \"path\": \"packs/scenario/choose-deploy-mode\"\n }\n ]\n}",
|
|
1167
|
+
"agent/concepts/catalog-as-platform.md": "---\nid: \"catalog-as-platform\"\ntype: \"concept\"\ntitle: \"Catalog as platform\"\nsummary: \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\"\nproblem: \"Every app reinvents schemas, list/get APIs, admin field metadata, access rules, and agent-readable descriptors.\"\nwhy: \"Shared catalogs keep discovery, visibility, and validation consistent across web BFFs and agent runtimes.\"\nmentalModel: \"Catalox stores the selectable definition; the host stores the transaction, run, or event that uses it.\"\naudiences: [\"developers\"]\nrelated: [\"mongo-primary\"]\nnext: [\"embed-catalox\"]\n---\n# Catalog as platform\n\n# Catalog as platform\n\nCatalox is the metadata and content backend for governed catalogs — plans, skills, templates, policies, vocabulary, and configuration-as-data.\n\n## Answer\n\nInstall Catalox once; product services consume catalogs through a stable contract instead of hardcoding catalog ids and field lists.\n\n## Problem\n\nWithout a shared layer, teams rebuild schemas, CRUD, admin metadata, access rules, seed tooling, and agent descriptors in every product.\n\n## Why\n\nApps and agents must discover the same catalogs with the same visibility rules. Catalox centralizes that contract.\n\n## Mental model\n\nCatalox stores **what can be selected or configured**. Your host stores **the transaction, run, or event** that uses it.\n\n## Example\n\nA pricing BFF and an agent runtime both list plans for `appId=pagenti` via Catalox descriptors — neither embeds plan schemas.\n\n## How it works\n\nCatalogs, items, bindings, and render hints live in Catalox. Host context (`CataloxContext`) scopes visibility. Optional HTTP (`catalox-service`) or in-process embedder exposes the same API.\n\n## Next\n\nFollow the embed guide, then read the Overview and Content Backend books.",
|
|
1168
|
+
"agent/concepts/mongo-primary.md": "---\nid: \"mongo-primary\"\ntype: \"concept\"\ntitle: \"MongoDB is primary persistence\"\nsummary: \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\"\nproblem: \"Dual-write or Firestore-first assumptions break onboarding and ops scripts.\"\nwhy: \"One primary store simplifies estate layout, CLI probes, and production deploys.\"\nmentalModel: \"createCataloxFromEnv → Mongo collections; R2 is optional object history, not the catalog DB.\"\naudiences: [\"developers\"]\nprerequisites: [\"catalog-as-platform\"]\nnext: [\"embed-catalox\"]\n---\n# MongoDB is primary persistence\n\n# MongoDB is primary persistence\n\n## Answer\n\nPoint Catalox at Mongo with `createCataloxFromEnv` (or explicit Mongo operators). Do not treat Firestore as the live store.\n\n## Problem\n\nOlder estates and docs mixed Firestore paths. Teams that keep writing to Firestore miss the 6.x primary path.\n\n## Why\n\nMongo-only primary storage is the supported production shape for Catalox 6. Optional Cloudflare R2 holds record-history objects, not catalog rows.\n\n## Mental model\n\n**Mongo** = catalogs + items + bindings. **R2** = optional NDJSON history. **Firestore** = import/migration only.\n\n## Example\n\nSet `MONGO_URI` / catalog DB env, run `catalox` probe/seed against Mongo, confirm collections for your `appId`.\n\n## How it works\n\nEngine operators open Mongo collections per estate. CLI and embedder share the same env contract documented in Persistence and Environment guides.\n\n## Next\n\nEmbed Catalox from env, then follow Deploy & Ops for service mode.",
|
|
1169
|
+
"agent/guides/embed-catalox.md": "---\nid: \"embed-catalox\"\ntype: \"guide\"\ntitle: \"Embed Catalox from env\"\nsummary: \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\"\nwhy: \"Embedding is the default integration — HTTP service is optional.\"\naudiences: [\"developers\"]\nprerequisites: [\"catalog-as-platform\", \"mongo-primary\"]\nrelated: [\"choose-deploy-mode\"]\ninvariants: [\"Mongo is the primary store\", \"appId selects the catalog tenant, not the cloud project id\"]\nconfirmationRequired: false\n---\n# Embed Catalox from env\n\n# Embed Catalox from env\n\n## Use this when\n\nYou want catalogs inside your Node service without deploying `catalox-service`.\n\n## Do not use this when\n\nYou need a shared multi-language HTTP API in front of Catalox — use deploy modes / catalox-service instead.\n\n## Steps\n\n1. Install `@x12i/catalox` and set Mongo env vars from the Environment / Persistence books.\n2. Call `createCataloxFromEnv()` (or the embedder entry) with your host `appId`.\n3. Probe connectivity and list catalogs for that `appId`.\n4. Seed or validate payloads with the CLI against the same estate.\n5. Wire host identity into `CataloxContext` before serving items to users or agents.\n\n## Verification\n\n- Probe succeeds against Mongo.\n- `list` / bootstrap returns expected catalogs for the `appId`.\n- A denied or empty binding produces an explicit Catalox outcome (not a silent empty UI).\n\n## Recovery\n\nIf probe fails, fix URI/DB name and credentials first. If catalogs are empty, check seed and `appId` mismatch before debugging Authix.",
|
|
1170
|
+
"agent/INDEX.md": "# catalox — knowledge index\n\nPackage: `@x12i/catalox-docs`\n\n## How to choose\n\n- **Concept** — what it is and why it exists\n- **Guide** — bounded task procedure\n- **Scenario** — state + evidence → which path\n- **Use case** — end-to-end outcome\n- **Tutorial** — learn by doing\n- **Decision** — options and recommended default\n- **Reference / API** — exact technical detail\n\n## Manifest and search\n\n- `agent-manifest.json`\n- `SEARCH.json`\n\n## Concepts\n\n- `catalog-as-platform` — **Catalog as platform** — Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing. — [concepts/catalog-as-platform.md](concepts/catalog-as-platform.md)\n- `mongo-primary` — **MongoDB is primary persistence** — Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only. — [concepts/mongo-primary.md](concepts/mongo-primary.md)\n\n## Guides\n\n- `embed-catalox` — **Embed Catalox from env** — Create an in-process Catalox client from environment variables and verify Mongo connectivity. — [guides/embed-catalox.md](guides/embed-catalox.md)\n\n## Scenarios\n\n- `choose-deploy-mode` — **Choose embed vs HTTP service** — Decide whether to embed Catalox in-process or expose catalox-service. — [scenarios/choose-deploy-mode.md](scenarios/choose-deploy-mode.md)\n\n## Diagrams\n\n_None authored yet._\n\n## Tutorials\n\n_None authored yet._\n",
|
|
1171
|
+
"agent/indexes/books.json": "{\n \"version\": 1,\n \"items\": [\n {\n \"id\": \"00-overview\",\n \"title\": \"Overview\",\n \"summary\": \"Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\",\n \"path\": \"books/00-overview/\"\n },\n {\n \"id\": \"01-content-backend\",\n \"title\": \"Content Backend\",\n \"summary\": \"Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\",\n \"path\": \"books/01-content-backend/\"\n },\n {\n \"id\": \"02-persistence\",\n \"title\": \"Persistence\",\n \"summary\": \"createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.\",\n \"path\": \"books/02-persistence/\"\n },\n {\n \"id\": \"03-deploy-ops\",\n \"title\": \"Deploy & Ops\",\n \"summary\": \"Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\",\n \"path\": \"books/03-deploy-ops/\"\n },\n {\n \"id\": \"04-auth-identity\",\n \"title\": \"Auth & Identity\",\n \"summary\": \"Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\",\n \"path\": \"books/04-auth-identity/\"\n },\n {\n \"id\": \"05-cli-toolbox\",\n \"title\": \"CLI & Toolbox\",\n \"summary\": \"Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\",\n \"path\": \"books/05-cli-toolbox/\"\n }\n ]\n}",
|
|
1172
|
+
"agent/indexes/books.md": "# books\n\n- `00-overview` — Overview — Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\n- `01-content-backend` — Content Backend — Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\n- `02-persistence` — Persistence — createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.\n- `03-deploy-ops` — Deploy & Ops — Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\n- `04-auth-identity` — Auth & Identity — Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\n- `05-cli-toolbox` — CLI & Toolbox — Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\n",
|
|
1173
|
+
"agent/indexes/concepts.json": "{\n \"version\": 1,\n \"items\": [\n {\n \"id\": \"catalog-as-platform\",\n \"title\": \"Catalog as platform\",\n \"summary\": \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\",\n \"path\": \"concepts/catalog-as-platform.md\"\n },\n {\n \"id\": \"mongo-primary\",\n \"title\": \"MongoDB is primary persistence\",\n \"summary\": \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\",\n \"path\": \"concepts/mongo-primary.md\"\n }\n ]\n}",
|
|
1174
|
+
"agent/indexes/concepts.md": "# concepts\n\n- `catalog-as-platform` — Catalog as platform — Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\n- `mongo-primary` — MongoDB is primary persistence — Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\n",
|
|
1175
|
+
"agent/indexes/diagrams.json": "{\n \"version\": 1,\n \"items\": []\n}",
|
|
1176
|
+
"agent/indexes/diagrams.md": "# diagrams\n\n\n",
|
|
1177
|
+
"agent/indexes/guides.json": "{\n \"version\": 1,\n \"items\": [\n {\n \"id\": \"embed-catalox\",\n \"title\": \"Embed Catalox from env\",\n \"summary\": \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\",\n \"path\": \"guides/embed-catalox.md\"\n }\n ]\n}",
|
|
1178
|
+
"agent/indexes/guides.md": "# guides\n\n- `embed-catalox` — Embed Catalox from env — Create an in-process Catalox client from environment variables and verify Mongo connectivity.\n",
|
|
1179
|
+
"agent/indexes/scenarios.json": "{\n \"version\": 1,\n \"items\": [\n {\n \"id\": \"choose-deploy-mode\",\n \"title\": \"Choose embed vs HTTP service\",\n \"summary\": \"Decide whether to embed Catalox in-process or expose catalox-service.\",\n \"path\": \"scenarios/choose-deploy-mode.md\"\n }\n ]\n}",
|
|
1180
|
+
"agent/indexes/scenarios.md": "# scenarios\n\n- `choose-deploy-mode` — Choose embed vs HTTP service — Decide whether to embed Catalox in-process or expose catalox-service.\n",
|
|
1181
|
+
"agent/indexes/tutorials.json": "{\n \"version\": 1,\n \"items\": []\n}",
|
|
1182
|
+
"agent/indexes/tutorials.md": "# tutorials\n\n\n",
|
|
1183
|
+
"agent/indexes/use-cases.json": "{\n \"version\": 1,\n \"items\": [\n {\n \"id\": \"orient-catalox\",\n \"title\": \"Orient on Catalox\",\n \"summary\": \"Understand why Catalox exists, what it owns, and when not to use it.\",\n \"path\": \"use-cases/orient-catalox.md\"\n },\n {\n \"id\": \"embed-content-backend\",\n \"title\": \"Embed as content backend\",\n \"summary\": \"Wire a BFF and agent runtime so humans and agents share one catalog layer.\",\n \"path\": \"use-cases/embed-content-backend.md\"\n },\n {\n \"id\": \"mongo-onboard\",\n \"title\": \"Onboard with Mongo\",\n \"summary\": \"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\",\n \"path\": \"use-cases/mongo-onboard.md\"\n },\n {\n \"id\": \"auth-context\",\n \"title\": \"Map host auth to Catalox context\",\n \"summary\": \"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\",\n \"path\": \"use-cases/auth-context.md\"\n },\n {\n \"id\": \"cli-seed-items\",\n \"title\": \"Operate with CLI items and seed\",\n \"summary\": \"Use elevated CLI access, items commands, and seed manifests safely.\",\n \"path\": \"use-cases/cli-seed-items.md\"\n }\n ]\n}",
|
|
1184
|
+
"agent/indexes/use-cases.md": "# use-cases\n\n- `orient-catalox` — Orient on Catalox — Understand why Catalox exists, what it owns, and when not to use it.\n- `embed-content-backend` — Embed as content backend — Wire a BFF and agent runtime so humans and agents share one catalog layer.\n- `mongo-onboard` — Onboard with Mongo — Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\n- `auth-context` — Map host auth to Catalox context — Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\n- `cli-seed-items` — Operate with CLI items and seed — Use elevated CLI access, items commands, and seed manifests safely.\n",
|
|
1185
|
+
"agent/packs/concept/catalog-as-platform/pack.json": "{\n \"id\": \"concept/catalog-as-platform\",\n \"type\": \"concept\",\n \"title\": \"Catalog as platform\",\n \"summary\": \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\",\n \"markdownPath\": \"concepts/catalog-as-platform.md\",\n \"files\": [\n \"concepts/catalog-as-platform.md\"\n ],\n \"related\": [\n \"mongo-primary\"\n ]\n}",
|
|
1186
|
+
"agent/packs/concept/catalog-as-platform/PACK.md": "---\nid: \"concept/catalog-as-platform\"\ntype: \"pack\"\ntitle: \"Catalog as platform\"\nsummary: \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\"\n---\n# Pack: Catalog as platform\n\nCatalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\n\nPrimary markdown: `concepts/catalog-as-platform.md`\n",
|
|
1187
|
+
"agent/packs/concept/mongo-primary/pack.json": "{\n \"id\": \"concept/mongo-primary\",\n \"type\": \"concept\",\n \"title\": \"MongoDB is primary persistence\",\n \"summary\": \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\",\n \"markdownPath\": \"concepts/mongo-primary.md\",\n \"files\": [\n \"concepts/mongo-primary.md\"\n ],\n \"related\": []\n}",
|
|
1188
|
+
"agent/packs/concept/mongo-primary/PACK.md": "---\nid: \"concept/mongo-primary\"\ntype: \"pack\"\ntitle: \"MongoDB is primary persistence\"\nsummary: \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\"\n---\n# Pack: MongoDB is primary persistence\n\nCatalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\n\nPrimary markdown: `concepts/mongo-primary.md`\n",
|
|
1189
|
+
"agent/packs/guide/embed-catalox/pack.json": "{\n \"id\": \"guide/embed-catalox\",\n \"type\": \"guide\",\n \"title\": \"Embed Catalox from env\",\n \"summary\": \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\",\n \"markdownPath\": \"guides/embed-catalox.md\",\n \"files\": [\n \"guides/embed-catalox.md\"\n ],\n \"related\": [\n \"choose-deploy-mode\"\n ]\n}",
|
|
1190
|
+
"agent/packs/guide/embed-catalox/PACK.md": "---\nid: \"guide/embed-catalox\"\ntype: \"pack\"\ntitle: \"Embed Catalox from env\"\nsummary: \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\"\n---\n# Pack: Embed Catalox from env\n\nCreate an in-process Catalox client from environment variables and verify Mongo connectivity.\n\nPrimary markdown: `guides/embed-catalox.md`\n",
|
|
1191
|
+
"agent/packs/scenario/choose-deploy-mode/pack.json": "{\n \"id\": \"scenario/choose-deploy-mode\",\n \"type\": \"scenario\",\n \"title\": \"Choose embed vs HTTP service\",\n \"summary\": \"Decide whether to embed Catalox in-process or expose catalox-service.\",\n \"markdownPath\": \"scenarios/choose-deploy-mode.md\",\n \"files\": [\n \"scenarios/choose-deploy-mode.md\"\n ],\n \"related\": []\n}",
|
|
1192
|
+
"agent/packs/scenario/choose-deploy-mode/PACK.md": "---\nid: \"scenario/choose-deploy-mode\"\ntype: \"pack\"\ntitle: \"Choose embed vs HTTP service\"\nsummary: \"Decide whether to embed Catalox in-process or expose catalox-service.\"\n---\n# Pack: Choose embed vs HTTP service\n\nDecide whether to embed Catalox in-process or expose catalox-service.\n\nPrimary markdown: `scenarios/choose-deploy-mode.md`\n",
|
|
1193
|
+
"agent/scenarios/choose-deploy-mode.md": "---\nid: \"choose-deploy-mode\"\ntype: \"scenario\"\ntitle: \"Choose embed vs HTTP service\"\nsummary: \"Decide whether to embed Catalox in-process or expose catalox-service.\"\naudiences: [\"developers\"]\ninvariants: [\"Same Mongo estate either way\", \"Authix gates public HTTP; embed still needs host context\"]\n---\n# Choose embed vs HTTP service\n\n# Choose embed vs HTTP service\n\n## Situation\n\nYou are integrating Catalox into a product. You can call the engine in-process or run the optional HTTP service.\n\n## Decision\n\nShould this product **embed** Catalox or deploy **catalox-service**?\n\n## Signals\n\n- Single Node BFF that already owns auth and can import `@x12i/catalox`\n- Multiple languages / remote agents that need a stable HTTP catalog API\n- Need for Authix-gated public exposure vs private VPC-only access\n\n## Paths\n\n### Embed in-process\n\n**When:** One Node service owns catalog access and host identity.\n\nGuides: `embed-catalox`\n\nUse `createCataloxFromEnv`, pass `CataloxContext`, keep Mongo private to the service.\n\n### HTTP service\n\n**When:** Other runtimes or networks must call Catalox over HTTP.\n\nGuides: `embed-catalox`\n\nDeploy `catalox-service` against the same Mongo estate; gate public routes with Authix per Deploy & Ops.\n\n## Escalation\n\nIf you need both, embed in the primary BFF and optionally expose a restricted service for agents — do not dual-write two Mongo estates.",
|
|
1194
|
+
"agent/SEARCH.json": "{\n \"version\": 1,\n \"product\": \"catalox\",\n \"generatedAt\": \"2026-07-26T13:09:13.535Z\",\n \"records\": [\n {\n \"id\": \"catalog-as-platform\",\n \"type\": \"concept\",\n \"title\": \"Catalog as platform\",\n \"summary\": \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"concepts/catalog-as-platform.md\",\n \"webPath\": \"/concepts/catalog-as-platform\",\n \"prerequisites\": [],\n \"related\": [\n \"mongo-primary\"\n ],\n \"packIds\": [\n \"concept/catalog-as-platform\"\n ]\n },\n {\n \"id\": \"mongo-primary\",\n \"type\": \"concept\",\n \"title\": \"MongoDB is primary persistence\",\n \"summary\": \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"concepts/mongo-primary.md\",\n \"webPath\": \"/concepts/mongo-primary\",\n \"prerequisites\": [\n \"catalog-as-platform\"\n ],\n \"related\": [],\n \"packIds\": [\n \"concept/mongo-primary\"\n ]\n },\n {\n \"id\": \"embed-catalox\",\n \"type\": \"guide\",\n \"title\": \"Embed Catalox from env\",\n \"summary\": \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"guides/embed-catalox.md\",\n \"webPath\": \"/guides/embed-catalox\",\n \"prerequisites\": [\n \"catalog-as-platform\",\n \"mongo-primary\"\n ],\n \"related\": [\n \"choose-deploy-mode\"\n ],\n \"packIds\": [\n \"guide/embed-catalox\"\n ]\n },\n {\n \"id\": \"choose-deploy-mode\",\n \"type\": \"scenario\",\n \"title\": \"Choose embed vs HTTP service\",\n \"summary\": \"Decide whether to embed Catalox in-process or expose catalox-service.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [\n \"Should this product embed Catalox or deploy catalox-service?\"\n ],\n \"path\": \"scenarios/choose-deploy-mode.md\",\n \"webPath\": \"/scenarios/choose-deploy-mode\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": [\n \"scenario/choose-deploy-mode\"\n ]\n },\n {\n \"id\": \"orient-catalox\",\n \"type\": \"use-case\",\n \"title\": \"Orient on Catalox\",\n \"summary\": \"Understand why Catalox exists, what it owns, and when not to use it.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"platform\",\n \"start-here\"\n ],\n \"goals\": [\n \"Understand why Catalox exists, what it owns, and when not to use it.\"\n ],\n \"path\": \"use-cases/orient-catalox.md\",\n \"webPath\": \"/use-cases#orient-catalox\",\n \"prerequisites\": [],\n \"related\": [\n \"01-content-backend\"\n ],\n \"packIds\": [\n \"use-case/orient-catalox\"\n ]\n },\n {\n \"id\": \"embed-content-backend\",\n \"type\": \"use-case\",\n \"title\": \"Embed as content backend\",\n \"summary\": \"Wire a BFF and agent runtime so humans and agents share one catalog layer.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"integration\",\n \"bff\",\n \"agents\"\n ],\n \"goals\": [\n \"Wire a BFF and agent runtime so humans and agents share one catalog layer.\"\n ],\n \"path\": \"use-cases/embed-content-backend.md\",\n \"webPath\": \"/use-cases#embed-content-backend\",\n \"prerequisites\": [],\n \"related\": [\n \"00-overview\",\n \"04-auth-identity\"\n ],\n \"packIds\": [\n \"use-case/embed-content-backend\"\n ]\n },\n {\n \"id\": \"mongo-onboard\",\n \"type\": \"use-case\",\n \"title\": \"Onboard with Mongo\",\n \"summary\": \"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"mongo\",\n \"onboarding\",\n \"ops\"\n ],\n \"goals\": [\n \"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\"\n ],\n \"path\": \"use-cases/mongo-onboard.md\",\n \"webPath\": \"/use-cases#mongo-onboard\",\n \"prerequisites\": [],\n \"related\": [\n \"05-cli-toolbox\"\n ],\n \"packIds\": [\n \"use-case/mongo-onboard\"\n ]\n },\n {\n \"id\": \"auth-context\",\n \"type\": \"use-case\",\n \"title\": \"Map host auth to Catalox context\",\n \"summary\": \"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"auth\",\n \"identity\"\n ],\n \"goals\": [\n \"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\"\n ],\n \"path\": \"use-cases/auth-context.md\",\n \"webPath\": \"/use-cases#auth-context\",\n \"prerequisites\": [],\n \"related\": [\n \"01-content-backend\"\n ],\n \"packIds\": [\n \"use-case/auth-context\"\n ]\n },\n {\n \"id\": \"cli-seed-items\",\n \"type\": \"use-case\",\n \"title\": \"Operate with CLI items and seed\",\n \"summary\": \"Use elevated CLI access, items commands, and seed manifests safely.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"cli\",\n \"seed\",\n \"ops\"\n ],\n \"goals\": [\n \"Use elevated CLI access, items commands, and seed manifests safely.\"\n ],\n \"path\": \"use-cases/cli-seed-items.md\",\n \"webPath\": \"/use-cases#cli-seed-items\",\n \"prerequisites\": [],\n \"related\": [\n \"03-deploy-ops\"\n ],\n \"packIds\": [\n \"use-case/cli-seed-items\"\n ]\n },\n {\n \"id\": \"00-overview\",\n \"type\": \"book\",\n \"title\": \"Overview\",\n \"summary\": \"Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\",\n \"aliases\": [\n \"CASE FILE · CAT-00\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"platform\",\n \"start-here\",\n \"overview\"\n ],\n \"goals\": [],\n \"path\": \"books/00-overview/\",\n \"webPath\": \"/books/00-overview\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"01-content-backend\",\n \"type\": \"book\",\n \"title\": \"Content Backend\",\n \"summary\": \"Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\",\n \"aliases\": [\n \"CASE FILE · CAT-01\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"integration\",\n \"bff\",\n \"agents\"\n ],\n \"goals\": [],\n \"path\": \"books/01-content-backend/\",\n \"webPath\": \"/books/01-content-backend\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"02-persistence\",\n \"type\": \"book\",\n \"title\": \"Persistence\",\n \"summary\": \"createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.\",\n \"aliases\": [\n \"CASE FILE · CAT-02\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"mongo\",\n \"storage\",\n \"ops\"\n ],\n \"goals\": [],\n \"path\": \"books/02-persistence/\",\n \"webPath\": \"/books/02-persistence\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"03-deploy-ops\",\n \"type\": \"book\",\n \"title\": \"Deploy & Ops\",\n \"summary\": \"Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\",\n \"aliases\": [\n \"CASE FILE · CAT-03\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"deploy\",\n \"http\",\n \"onboarding\"\n ],\n \"goals\": [],\n \"path\": \"books/03-deploy-ops/\",\n \"webPath\": \"/books/03-deploy-ops\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"04-auth-identity\",\n \"type\": \"book\",\n \"title\": \"Auth & Identity\",\n \"summary\": \"Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\",\n \"aliases\": [\n \"CASE FILE · CAT-04\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"auth\",\n \"identity\",\n \"bindings\"\n ],\n \"goals\": [],\n \"path\": \"books/04-auth-identity/\",\n \"webPath\": \"/books/04-auth-identity\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"05-cli-toolbox\",\n \"type\": \"book\",\n \"title\": \"CLI & Toolbox\",\n \"summary\": \"Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\",\n \"aliases\": [\n \"CASE FILE · CAT-05\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"cli\",\n \"ops\",\n \"seed\"\n ],\n \"goals\": [],\n \"path\": \"books/05-cli-toolbox/\",\n \"webPath\": \"/books/05-cli-toolbox\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n }\n ]\n}",
|
|
1195
|
+
"agent/use-cases/auth-context.md": "# Map host auth to Catalox context\n\n> **Use case id:** `auth-context`\n> **Goal:** Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\n> **Audiences:** developers\n> **Tags:** auth, identity\n\n## Reading path\n\n1. **Auth & Identity** (developers) → chapters: `1-identity-axes`, `2-super-admin`, `3-catalog-and-item-visibility`, `4-empty-vs-denied`\n\n## From: Auth & Identity — 1. Identity axes\n\nCatalox evaluates access using up to three independent axes:\n\n- **App axis:** `appId` and optional `storeId`\n- **Tenant axis:** `accountId`, `groupId`, `userId`, `channelId`, `visitorId`\n- **Agent axis:** `domainId`, `agentId`\n\n```mermaid\nflowchart LR\n subgraph appAxis [App Axis]\n Store --> App\n end\n subgraph tenantAxis [Tenant Axis]\n Account --> Group\n Account --> Channel\n Group --> User\n Channel --> Visitor\n end\n subgraph agentAxis [Agent Axis]\n Domain --> Agent\n end\n```\n\nAxes are **orthogonal** — not a single hierarchy. App/store tenancy stays separate from human/org identity. Store membership may help discovery but does not automatically grant catalog/item permissions unless policy says so.\n\n---\n\n## From: Auth & Identity — 2. Super admin\n\n`CataloxContext.superAdmin === true` is an explicit, host-controlled elevation flag.\n\n- May bypass some binding checks (e.g. app↔catalog) for operator workflows.\n- Must **not** be inferred from user-provided headers without host authentication.\n- Even when elevated, writes may still require bindings or explicit “super list” for all physical rows.\n\nCLI contexts are elevated by default; pass `--restricted` or `CATALOX_RESTRICTED=1` to enforce bindings. Authix public mode sets `superAdmin: false` for non-operator tokens.\n\n---\n\n## From: Auth & Identity — 3. Catalog and item visibility\n\n### Catalog discovery / bootstrap\n\n- **App-first:** catalogs visible via app↔catalog bindings.\n- **Identity-first:** catalogs visible via identity↔catalog bindings.\n\nWhen both exist, host policy chooses **intersection** (default safe) or **union**.\n\n### Item visibility (native catalogs)\n\nNative catalogs may hold multiple physical rows per logical item id. Tenant-axis and agent-axis scopes are independent — an item may be scoped by tenant, by agent, by both, or by neither (global). Mapped catalogs are currently catalog-scoped only.\n\n---\n\n## From: Auth & Identity — 4. Empty vs denied\n\nEmbedders must distinguish:\n\n| Outcome | Meaning |\n|---------|---------|\n| **empty** | Authorized, but zero data for that view |\n| **denied** | Caller not authorized (bindings/policy) |\n| **misconfigured** | Catalog exists but missing required config (descriptor/definition/mapping/adapter) |\n| **mapping_blocked** | Mapping spec invalid; execution refused |\n\nUse `listCatalogItemsWithOutcome` (and toolbox `check-access`) rather than treating empty lists as success when diagnosis matters. See flat `docs/outcomes.md` for taxonomy detail.\n\n## Also see\n\n- **Content Backend** (`01-content-backend`) — Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1196
|
+
"agent/use-cases/cli-seed-items.md": "# Operate with CLI items and seed\n\n> **Use case id:** `cli-seed-items`\n> **Goal:** Use elevated CLI access, items commands, and seed manifests safely.\n> **Audiences:** developers\n> **Tags:** cli, seed, ops\n\n## Reading path\n\n1. **CLI & Toolbox** (developers) → chapters: `1-cli-access`, `2-items-commands`, `4-seed-workflow`\n\n## From: CLI & Toolbox — 1. CLI access\n\nCatalox CLI contexts are **elevated** unless you explicitly restrict them:\n\n| Mechanism | Effect |\n|-----------|--------|\n| (default) | `superAdmin: true` — full operator access |\n| `--restricted` | `superAdmin: false` — catalog binding checks apply |\n| `CATALOX_RESTRICTED=1` | Same as `--restricted` |\n\n`--god` is **removed / unnecessary**. Library hosts: omit `superAdmin` or set `true` for open access; set **`superAdmin: false`** only when intentionally restricting.\n\n---\n\n## From: CLI & Toolbox — 2. Items commands\n\nOperator commands over the same Catalox APIs your app uses. Prefer `MONGO_URI` + `CATALOX_APP_ID` (or `--app` per command).\n\n| Command | Purpose |\n|--------|---------|\n| `items validate` | Catalog config or item payload/relations/smart properties |\n| `items get` | `getCatalogItem` |\n| `items list` | `listCatalogItemsWithOutcome` |\n| `items upsert` / `patch` / `delete` | Native item mutations (`delete` needs `--confirm`) |\n| `items batch-upsert` / `batch-replace` | JSON array or NDJSON |\n| `items export` | Stable export JSON with pagination caps |\n\nNative upsert body (preferred, matches seed rows):\n\n```json\n{ \"data\": { /* identity + fields */ }, \"scope\": { }, \"relations\": [ ] }\n```\n\nExamples:\n\n```bash\ncatalox mongo probe\ncatalox items list --app my-app --catalog signals\ncatalox items validate --app my-app --catalog entities --item some-id\ncatalox items upsert --app my-app --catalog signals --file item.json\n```\n\nWhen restricted, reads need a **read** binding; writes need **write** access where the API enforces it.\n\n---\n\n## From: CLI & Toolbox — 4. Seed workflow\n\nRepeatable manifests beat one-off scripts:\n\n```bash\ncatalox seed validate --file preset.json\ncatalox seed apply --app myApp --file preset.json\n# or project scripts, e.g. npm run seed:pagenti\ncatalox items list --app myApp --catalog signals\n```\n\nValidate before write; apply is idempotent for well-formed manifests. Combine with `items batch-upsert` for incremental CI updates after the initial seed.\n\n## Also see\n\n- **Deploy & Ops** (`03-deploy-ops`) — Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1197
|
+
"agent/use-cases/embed-content-backend.md": "# Embed as content backend\n\n> **Use case id:** `embed-content-backend`\n> **Goal:** Wire a BFF and agent runtime so humans and agents share one catalog layer.\n> **Audiences:** developers\n> **Tags:** integration, bff, agents\n\n## Reading path\n\n1. **Content Backend** (developers) → chapters: `1-the-pattern`, `2-architecture`, `3-product-use-cases`\n\n## From: Content Backend — 1. The pattern\n\nDefine catalogs (skills, templates, plans, vocabulary, policies) in Catalox with **descriptors** and **bindings** to your `appId`. Your web app’s BFF calls **bootstrap** and **items** APIs (embedded engine or HTTP client). Your agent runtime reads the **same items**, scoped by token or context. Your product backend owns **users, workflows, and transactions**; Catalox owns **what exists in the catalog and who can see it**.\n\n### Problem: two backends that drift\n\n```text\nAdmin UI ──► Postgres \"skills\" table ──► human-edited metadata\nAgent API ──► Redis / JSON files ──► agent-edited metadata ❌ drift\n```\n\n### Solution: one catalog layer, many consumers\n\n```text\n ┌──────────────┐\n Admin UI / SPA ──►│ │\n Mobile app ──►│ Your BFF │──► Catalox (skills, templates, …)\n Agent runtime ──►│ (thin) │\n CI seed job ──►│ │\n └──────────────┘\n │\n Workflows / runs / orders stay in YOUR services\n```\n\n**Why it works:** single source of truth; descriptors drive UI; bindings enforce product boundaries; scope narrows exposure; no per-entity Express routes for every catalog.\n\n| Catalox owns | Your app owns |\n|--------------|---------------|\n| Catalog records, descriptors, bindings | User authentication (SSO) |\n| Item storage (`item.data` + `indexed`) | Sessions, billing, entitlements |\n| List/get/filter/search by descriptor rules | Workflow state, execution runs |\n| Access outcomes (ok / denied / misconfigured) | Business logic that *uses* an item |\n\n**Rule:** If the question is “**what options exist?**” → Catalox. If “**what happened when the user clicked run?**” → your backend.\n\n---\n\n## From: Content Backend — 2. Architecture\n\n### Web app with admin + picker UI\n\n```text\nBrowser (React)\n │ SSO cookie / session\n ▼\nYour BFF (Node)\n │ 1. Authenticate user (your IdP)\n │ 2. Issue Authix token OR map user → CataloxContext\n │ 3. Call Catalox (embed or HTTP)\n ▼\nCatalox engine / catalox-service\n ▼\nMongoDB (native items + metadata collections)\n```\n\n**BFF:** map user → `accountId` / `domainId` / roles; least-privilege Authix or context; proxy Catalox — do **not** reimplement list/filter SQL per catalog.\n\n**SPA:** bootstrap + list items from descriptors (or catalox-ui); submit writes as item payloads.\n\n### Agent platform\n\nAgent runtimes use the same catalogs with a scoped token (`domainIds`, `agentIds`) or embedded `CataloxContext`. Humans and agents must not maintain separate config stores for the same vocabulary.\n\n---\n\n## From: Content Backend — 3. Product use cases\n\n| Use case | Goal |\n|----------|------|\n| Bootstrap a new app | Seed descriptors, bindings, and items for an `appId` |\n| Content API for SPA + agents | Shared read/write path without dual stores |\n| Operator seed / CI | Manifest validate + apply; batch upsert |\n| Private HTTP | Internal services via `catalox-service` (`open` mode on private network) |\n| Public Authix API | Partner / browser access (**6.1.0**) |\n\nSee also flat `docs/USE-CASES.md` for longer flow narratives.\n\n---\n\n## Also see\n\n- **Overview** (`00-overview`) — Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\n- **Auth & Identity** (`04-auth-identity`) — Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1198
|
+
"agent/use-cases/mongo-onboard.md": "# Onboard with Mongo\n\n> **Use case id:** `mongo-onboard`\n> **Goal:** Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\n> **Audiences:** developers\n> **Tags:** mongo, onboarding, ops\n\n## Reading path\n\n1. **Persistence** (developers) → chapters: `1-mongo-quick-start`, `2-environment`\n1. **Deploy & Ops** (developers) → chapters: `4-onboarding-happy-path`\n\n## From: Persistence — 1. Mongo quick start\n\n```ts\nimport { createCataloxFromEnv } from \"@x12i/catalox/mongo\";\n\nconst { catalox, mongoStore } = await createCataloxFromEnv({\n mongoUri: process.env.MONGO_URI, // optional when MONGO_URI / MONGODB_URI is set\n // dbName defaults to \"catalox\" when MONGO_DB_NAME / MONGODB_DB unset\n});\n\nconst scoped = catalox.withContext({ appId: \"myApp\", superAdmin: true });\nconst page = await scoped.listCatalogItems(\"myCatalog\", { limit: 50 });\n```\n\nWhen you already hold a connected client from `@x12i/helpers/mongo`, wrap it:\n\n```ts\nimport { initMongoDb } from \"@x12i/helpers/mongo\";\nimport { createCatalox, MongoStore } from \"@x12i/catalox/embedder\";\n\nconst api = await initMongoDb({ mongoUri: \"mongodb://127.0.0.1:27017\", dbName: \"catalox\" });\nconst catalox = createCatalox({ mongo: new MongoStore(api) });\n```\n\nNo Firebase Admin SDK is required for normal CRUD. `LocalFileStore` remains for offline fixtures/tests only.\n\nConnectivity probe:\n\n```ts\nimport { testMongoConnectionFromEnv } from \"@x12i/catalox/mongo\";\nconst probe = await testMongoConnectionFromEnv();\nif (!probe.ok) throw probe.error;\n```\n\n```bash\ncatalox mongo probe\n```\n\n---\n\n## From: Persistence — 2. Environment\n\n| Variable | Purpose |\n|----------|---------|\n| **`MONGO_URI`** or **`MONGODB_URI`** | Required connection string for primary Mongo persistence |\n| **`MONGO_DB_NAME`** or **`MONGODB_DB`** | Database name (default **`catalox`**) |\n| **`CATALOX_MONGO_URI`** | Optional mapped-catalog adapter URI override |\n\nObject store (record history after 6.0.0 R2 cutover): `S3_*` / `CATALOX_BUCKET`. Google SA vars are **migration only** (`mongo import-from-firestore`, `storage migrate-from-gcs`).\n\n---\n\n## From: Deploy & Ops — 4. Onboarding happy path\n\nZero → working catalogs:\n\n```bash\nexport MONGO_URI=\"mongodb://127.0.0.1:27017\"\n# optional:\nexport MONGO_DB_NAME=\"catalox\"\nexport CATALOX_APP_ID=\"<yourCataloxAppId>\"\n\nnpx catalox mongo probe\nnpx catalox seed --app \"$CATALOX_APP_ID\" # or project seed script / npm run seed:pagenti\nnpx catalox items list --app \"$CATALOX_APP_ID\" --catalog <catalogId>\n```\n\nExpect probe `{ \"ok\": true, ... }`. Validate payloads with `catalox items validate` before large batch upserts.\n\n---\n\n## Also see\n\n- **CLI & Toolbox** (`05-cli-toolbox`) — Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1199
|
+
"agent/use-cases/orient-catalox.md": "# Orient on Catalox\n\n> **Use case id:** `orient-catalox`\n> **Goal:** Understand why Catalox exists, what it owns, and when not to use it.\n> **Audiences:** developers\n> **Tags:** platform, start-here\n\n## Reading path\n\n1. **Overview** (developers) → chapters: `1-why-catalox-exists`, `2-what-catalox-is`, `3-fit-vs-misfit`\n\n## From: Overview — 1. Why Catalox exists\n\nEvery x12i product eventually needs the same thing:\n\n- A **catalog of things** users can browse, pick, configure, or reference — plans, skills, templates, policies, vocabulary, feature matrices, routing rules, prompt libraries.\n- A way for **multiple apps and agents** to discover those catalogs without hardcoding catalog ids, field lists, or CRUD endpoints.\n- **Governance** — who can see which catalog, which items apply to which account/domain/agent, and explicit outcomes when access or configuration is wrong.\n\nWithout a shared layer, each team rebuilds schemas, list/get APIs, admin field metadata, access rules, seed tooling, and agent-readable metadata. Catalox does that work **once**, with a stable contract, so product backends spend budget on checkout, workflows, execution, and billing — not catalog plumbing.\n\n---\n\n## From: Overview — 2. What Catalox is\n\n**Catalox is the metadata and content backend for governed catalogs** — the layer where you store *what can be selected or configured*, expose it consistently to web apps and agent runtimes, and keep operational transactions in your own services.\n\nIt is **not**:\n\n- A CMS for marketing pages\n- An OLTP database for orders, runs, or events\n- A UI framework (it returns descriptors and render hints; you render)\n- A login system (SSO stays in your SaaS; Authix gates the public HTTP API)\n\nIt ships as a **library + CLI + optional HTTP service** you embed or deploy against **MongoDB** (primary), with optional **Cloudflare R2** for record history and a one-time Firestore → Mongo import for migrating estates.\n\n**Rule of thumb:** Catalox stores the **definition or selectable item**; your host stores the **transaction, run, or event** that uses it.\n\n---\n\n## From: Overview — 3. Fit vs misfit\n\n### Good fits\n\n| Domain | Example catalogs |\n|--------|------------------|\n| Product & pricing | Plans, SKUs, feature bundles |\n| Routing & policy | Rules, feature flags, lookup tables |\n| Templates | Graph templates, prompt templates, execution matrices |\n| Knowledge & vocabulary | Skills, roles, use cases (smart properties) |\n| Configuration-as-data | Mappings, enums, design token refs |\n\n### Poor fits\n\n| Domain | Why not Catalox |\n|--------|-----------------|\n| Orders & payments | OLTP transaction state |\n| Live execution runs | High-churn operational state |\n| Event/audit streams | Append-heavy mutable logs |\n| Secret storage | Use a secrets manager; store refs only |\n\n---\n\n## Also see\n\n- **Content Backend** (`01-content-backend`) — Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\n\n---\n\n_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._\n",
|
|
1200
|
+
"agent-manifest.json": "{\n \"version\": 1,\n \"product\": \"catalox\",\n \"site\": \"https://docs.catalox.x12i.com\",\n \"knowledgePackage\": \"@x12i/catalox-docs\",\n \"roles\": [\n \"developers\"\n ],\n \"books\": [\n {\n \"id\": \"00-overview\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/00-overview/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/00-overview/developers.chapters.json\"\n }\n },\n {\n \"id\": \"01-content-backend\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/01-content-backend/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/01-content-backend/developers.chapters.json\"\n }\n },\n {\n \"id\": \"02-persistence\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/02-persistence/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/02-persistence/developers.chapters.json\"\n }\n },\n {\n \"id\": \"03-deploy-ops\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/03-deploy-ops/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/03-deploy-ops/developers.chapters.json\"\n }\n },\n {\n \"id\": \"04-auth-identity\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/04-auth-identity/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/04-auth-identity/developers.chapters.json\"\n }\n },\n {\n \"id\": \"05-cli-toolbox\",\n \"audiences\": [\n \"developers\"\n ],\n \"md\": {\n \"developers\": \"downloads/books/05-cli-toolbox/developers.md\"\n },\n \"pdf\": {\n \"developers\": null\n },\n \"chapters\": {\n \"developers\": \"downloads/books/05-cli-toolbox/developers.chapters.json\"\n }\n }\n ],\n \"useCases\": [\n {\n \"id\": \"orient-catalox\",\n \"title\": \"Orient on Catalox\",\n \"md\": \"downloads/use-cases/orient-catalox.md\",\n \"path\": [\n {\n \"bookId\": \"00-overview\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-why-catalox-exists\",\n \"2-what-catalox-is\",\n \"3-fit-vs-misfit\"\n ]\n }\n ]\n },\n {\n \"id\": \"embed-content-backend\",\n \"title\": \"Embed as content backend\",\n \"md\": \"downloads/use-cases/embed-content-backend.md\",\n \"path\": [\n {\n \"bookId\": \"01-content-backend\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-the-pattern\",\n \"2-architecture\",\n \"3-product-use-cases\"\n ]\n }\n ]\n },\n {\n \"id\": \"mongo-onboard\",\n \"title\": \"Onboard with Mongo\",\n \"md\": \"downloads/use-cases/mongo-onboard.md\",\n \"path\": [\n {\n \"bookId\": \"02-persistence\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-mongo-quick-start\",\n \"2-environment\"\n ]\n },\n {\n \"bookId\": \"03-deploy-ops\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"4-onboarding-happy-path\"\n ]\n }\n ]\n },\n {\n \"id\": \"auth-context\",\n \"title\": \"Map host auth to Catalox context\",\n \"md\": \"downloads/use-cases/auth-context.md\",\n \"path\": [\n {\n \"bookId\": \"04-auth-identity\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-identity-axes\",\n \"2-super-admin\",\n \"3-catalog-and-item-visibility\",\n \"4-empty-vs-denied\"\n ]\n }\n ]\n },\n {\n \"id\": \"cli-seed-items\",\n \"title\": \"Operate with CLI items and seed\",\n \"md\": \"downloads/use-cases/cli-seed-items.md\",\n \"path\": [\n {\n \"bookId\": \"05-cli-toolbox\",\n \"audience\": \"developers\",\n \"chapters\": [\n \"1-cli-access\",\n \"2-items-commands\",\n \"4-seed-workflow\"\n ]\n }\n ]\n }\n ],\n \"indexes\": {\n \"indexMd\": \"INDEX.md\",\n \"searchJson\": \"SEARCH.json\"\n },\n \"concepts\": [\n {\n \"id\": \"catalog-as-platform\",\n \"title\": \"Catalog as platform\",\n \"md\": \"concepts/catalog-as-platform.md\"\n },\n {\n \"id\": \"mongo-primary\",\n \"title\": \"MongoDB is primary persistence\",\n \"md\": \"concepts/mongo-primary.md\"\n }\n ],\n \"guides\": [\n {\n \"id\": \"embed-catalox\",\n \"title\": \"Embed Catalox from env\",\n \"md\": \"guides/embed-catalox.md\"\n }\n ],\n \"scenarios\": [\n {\n \"id\": \"choose-deploy-mode\",\n \"title\": \"Choose embed vs HTTP service\",\n \"md\": \"scenarios/choose-deploy-mode.md\"\n }\n ],\n \"decisions\": [],\n \"glossary\": [],\n \"visuals\": [],\n \"diagrams\": [],\n \"relationships\": [],\n \"tutorials\": [],\n \"examples\": [],\n \"sampleData\": [],\n \"uiClients\": [],\n \"apis\": [],\n \"packs\": [\n {\n \"id\": \"concept/catalog-as-platform\",\n \"type\": \"concept\",\n \"path\": \"packs/concept/catalog-as-platform\"\n },\n {\n \"id\": \"concept/mongo-primary\",\n \"type\": \"concept\",\n \"path\": \"packs/concept/mongo-primary\"\n },\n {\n \"id\": \"guide/embed-catalox\",\n \"type\": \"guide\",\n \"path\": \"packs/guide/embed-catalox\"\n },\n {\n \"id\": \"scenario/choose-deploy-mode\",\n \"type\": \"scenario\",\n \"path\": \"packs/scenario/choose-deploy-mode\"\n }\n ]\n}",
|
|
1201
|
+
"INDEX.md": "# catalox — knowledge index\n\nPackage: `@x12i/catalox-docs`\n\n## How to choose\n\n- **Concept** — what it is and why it exists\n- **Guide** — bounded task procedure\n- **Scenario** — state + evidence → which path\n- **Use case** — end-to-end outcome\n- **Tutorial** — learn by doing\n- **Decision** — options and recommended default\n- **Reference / API** — exact technical detail\n\n## Manifest and search\n\n- `agent-manifest.json`\n- `SEARCH.json`\n\n## Concepts\n\n- `catalog-as-platform` — **Catalog as platform** — Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing. — [concepts/catalog-as-platform.md](concepts/catalog-as-platform.md)\n- `mongo-primary` — **MongoDB is primary persistence** — Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only. — [concepts/mongo-primary.md](concepts/mongo-primary.md)\n\n## Guides\n\n- `embed-catalox` — **Embed Catalox from env** — Create an in-process Catalox client from environment variables and verify Mongo connectivity. — [guides/embed-catalox.md](guides/embed-catalox.md)\n\n## Scenarios\n\n- `choose-deploy-mode` — **Choose embed vs HTTP service** — Decide whether to embed Catalox in-process or expose catalox-service. — [scenarios/choose-deploy-mode.md](scenarios/choose-deploy-mode.md)\n\n## Diagrams\n\n_None authored yet._\n\n## Tutorials\n\n_None authored yet._\n",
|
|
1202
|
+
"SEARCH.json": "{\n \"version\": 1,\n \"product\": \"catalox\",\n \"generatedAt\": \"2026-07-26T13:09:13.535Z\",\n \"records\": [\n {\n \"id\": \"catalog-as-platform\",\n \"type\": \"concept\",\n \"title\": \"Catalog as platform\",\n \"summary\": \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"concepts/catalog-as-platform.md\",\n \"webPath\": \"/concepts/catalog-as-platform\",\n \"prerequisites\": [],\n \"related\": [\n \"mongo-primary\"\n ],\n \"packIds\": [\n \"concept/catalog-as-platform\"\n ]\n },\n {\n \"id\": \"mongo-primary\",\n \"type\": \"concept\",\n \"title\": \"MongoDB is primary persistence\",\n \"summary\": \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"concepts/mongo-primary.md\",\n \"webPath\": \"/concepts/mongo-primary\",\n \"prerequisites\": [\n \"catalog-as-platform\"\n ],\n \"related\": [],\n \"packIds\": [\n \"concept/mongo-primary\"\n ]\n },\n {\n \"id\": \"embed-catalox\",\n \"type\": \"guide\",\n \"title\": \"Embed Catalox from env\",\n \"summary\": \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [],\n \"path\": \"guides/embed-catalox.md\",\n \"webPath\": \"/guides/embed-catalox\",\n \"prerequisites\": [\n \"catalog-as-platform\",\n \"mongo-primary\"\n ],\n \"related\": [\n \"choose-deploy-mode\"\n ],\n \"packIds\": [\n \"guide/embed-catalox\"\n ]\n },\n {\n \"id\": \"choose-deploy-mode\",\n \"type\": \"scenario\",\n \"title\": \"Choose embed vs HTTP service\",\n \"summary\": \"Decide whether to embed Catalox in-process or expose catalox-service.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [],\n \"goals\": [\n \"Should this product embed Catalox or deploy catalox-service?\"\n ],\n \"path\": \"scenarios/choose-deploy-mode.md\",\n \"webPath\": \"/scenarios/choose-deploy-mode\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": [\n \"scenario/choose-deploy-mode\"\n ]\n },\n {\n \"id\": \"orient-catalox\",\n \"type\": \"use-case\",\n \"title\": \"Orient on Catalox\",\n \"summary\": \"Understand why Catalox exists, what it owns, and when not to use it.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"platform\",\n \"start-here\"\n ],\n \"goals\": [\n \"Understand why Catalox exists, what it owns, and when not to use it.\"\n ],\n \"path\": \"use-cases/orient-catalox.md\",\n \"webPath\": \"/use-cases#orient-catalox\",\n \"prerequisites\": [],\n \"related\": [\n \"01-content-backend\"\n ],\n \"packIds\": [\n \"use-case/orient-catalox\"\n ]\n },\n {\n \"id\": \"embed-content-backend\",\n \"type\": \"use-case\",\n \"title\": \"Embed as content backend\",\n \"summary\": \"Wire a BFF and agent runtime so humans and agents share one catalog layer.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"integration\",\n \"bff\",\n \"agents\"\n ],\n \"goals\": [\n \"Wire a BFF and agent runtime so humans and agents share one catalog layer.\"\n ],\n \"path\": \"use-cases/embed-content-backend.md\",\n \"webPath\": \"/use-cases#embed-content-backend\",\n \"prerequisites\": [],\n \"related\": [\n \"00-overview\",\n \"04-auth-identity\"\n ],\n \"packIds\": [\n \"use-case/embed-content-backend\"\n ]\n },\n {\n \"id\": \"mongo-onboard\",\n \"type\": \"use-case\",\n \"title\": \"Onboard with Mongo\",\n \"summary\": \"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"mongo\",\n \"onboarding\",\n \"ops\"\n ],\n \"goals\": [\n \"Connect Mongo, probe, seed a preset, and validate catalogs for a new appId.\"\n ],\n \"path\": \"use-cases/mongo-onboard.md\",\n \"webPath\": \"/use-cases#mongo-onboard\",\n \"prerequisites\": [],\n \"related\": [\n \"05-cli-toolbox\"\n ],\n \"packIds\": [\n \"use-case/mongo-onboard\"\n ]\n },\n {\n \"id\": \"auth-context\",\n \"type\": \"use-case\",\n \"title\": \"Map host auth to Catalox context\",\n \"summary\": \"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"auth\",\n \"identity\"\n ],\n \"goals\": [\n \"Provide CataloxContext axes correctly and distinguish empty, denied, and misconfigured.\"\n ],\n \"path\": \"use-cases/auth-context.md\",\n \"webPath\": \"/use-cases#auth-context\",\n \"prerequisites\": [],\n \"related\": [\n \"01-content-backend\"\n ],\n \"packIds\": [\n \"use-case/auth-context\"\n ]\n },\n {\n \"id\": \"cli-seed-items\",\n \"type\": \"use-case\",\n \"title\": \"Operate with CLI items and seed\",\n \"summary\": \"Use elevated CLI access, items commands, and seed manifests safely.\",\n \"aliases\": [],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"cli\",\n \"seed\",\n \"ops\"\n ],\n \"goals\": [\n \"Use elevated CLI access, items commands, and seed manifests safely.\"\n ],\n \"path\": \"use-cases/cli-seed-items.md\",\n \"webPath\": \"/use-cases#cli-seed-items\",\n \"prerequisites\": [],\n \"related\": [\n \"03-deploy-ops\"\n ],\n \"packIds\": [\n \"use-case/cli-seed-items\"\n ]\n },\n {\n \"id\": \"00-overview\",\n \"type\": \"book\",\n \"title\": \"Overview\",\n \"summary\": \"Product rationale, what Catalox is and is not, fit vs misfit, and FAQ highlights.\",\n \"aliases\": [\n \"CASE FILE · CAT-00\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"platform\",\n \"start-here\",\n \"overview\"\n ],\n \"goals\": [],\n \"path\": \"books/00-overview/\",\n \"webPath\": \"/books/00-overview\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"01-content-backend\",\n \"type\": \"book\",\n \"title\": \"Content Backend\",\n \"summary\": \"Recommended integration pattern: BFFs and agent runtimes share Catalox as the content/metadata API.\",\n \"aliases\": [\n \"CASE FILE · CAT-01\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"integration\",\n \"bff\",\n \"agents\"\n ],\n \"goals\": [],\n \"path\": \"books/01-content-backend/\",\n \"webPath\": \"/books/01-content-backend\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"02-persistence\",\n \"type\": \"book\",\n \"title\": \"Persistence\",\n \"summary\": \"createCataloxFromEnv, collection layout, env vars, and operator notes for Mongo-backed estates.\",\n \"aliases\": [\n \"CASE FILE · CAT-02\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"mongo\",\n \"storage\",\n \"ops\"\n ],\n \"goals\": [],\n \"path\": \"books/02-persistence/\",\n \"webPath\": \"/books/02-persistence\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"03-deploy-ops\",\n \"type\": \"book\",\n \"title\": \"Deploy & Ops\",\n \"summary\": \"Deployment modes, private vs public HTTP, onboarding happy path, and environment reference.\",\n \"aliases\": [\n \"CASE FILE · CAT-03\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"deploy\",\n \"http\",\n \"onboarding\"\n ],\n \"goals\": [],\n \"path\": \"books/03-deploy-ops/\",\n \"webPath\": \"/books/03-deploy-ops\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"04-auth-identity\",\n \"type\": \"book\",\n \"title\": \"Auth & Identity\",\n \"summary\": \"Orthogonal identity axes, superAdmin, catalog/item visibility, and empty vs denied vs misconfigured.\",\n \"aliases\": [\n \"CASE FILE · CAT-04\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"auth\",\n \"identity\",\n \"bindings\"\n ],\n \"goals\": [],\n \"path\": \"books/04-auth-identity/\",\n \"webPath\": \"/books/04-auth-identity\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n },\n {\n \"id\": \"05-cli-toolbox\",\n \"type\": \"book\",\n \"title\": \"CLI & Toolbox\",\n \"summary\": \"Elevated CLI access, items CRUD, toolbox diagnostics, and seed workflows.\",\n \"aliases\": [\n \"CASE FILE · CAT-05\"\n ],\n \"audiences\": [\n \"developers\"\n ],\n \"tags\": [\n \"cli\",\n \"ops\",\n \"seed\"\n ],\n \"goals\": [],\n \"path\": \"books/05-cli-toolbox/\",\n \"webPath\": \"/books/05-cli-toolbox\",\n \"prerequisites\": [],\n \"related\": [],\n \"packIds\": []\n }\n ]\n}",
|
|
1203
|
+
"knowledge.json": "{\n \"concepts\": [\n {\n \"summary\": \"Catalox owns governed catalog definitions so product backends do not rebuild catalog plumbing.\",\n \"problem\": \"Every app reinvents schemas, list/get APIs, admin field metadata, access rules, and agent-readable descriptors.\",\n \"why\": \"Shared catalogs keep discovery, visibility, and validation consistent across web BFFs and agent runtimes.\",\n \"mentalModel\": \"Catalox stores the selectable definition; the host stores the transaction, run, or event that uses it.\",\n \"audiences\": [\n \"developers\"\n ],\n \"whenItMatters\": [],\n \"whenNotToUse\": [],\n \"prerequisites\": [],\n \"related\": [\n \"mongo-primary\"\n ],\n \"next\": [\n \"embed-catalox\"\n ],\n \"exampleIds\": [],\n \"commonMistakes\": [],\n \"successCriteria\": [],\n \"invariants\": [],\n \"alternatives\": [],\n \"tags\": [],\n \"id\": \"catalog-as-platform\",\n \"type\": \"concept\",\n \"title\": \"Catalog as platform\",\n \"visualIds\": [],\n \"diagramIds\": [],\n \"referenceIds\": []\n },\n {\n \"summary\": \"Catalox 6 stores catalogs and items in MongoDB; Firestore operators are migration-only.\",\n \"problem\": \"Dual-write or Firestore-first assumptions break onboarding and ops scripts.\",\n \"why\": \"One primary store simplifies estate layout, CLI probes, and production deploys.\",\n \"mentalModel\": \"createCataloxFromEnv → Mongo collections; R2 is optional object history, not the catalog DB.\",\n \"audiences\": [\n \"developers\"\n ],\n \"whenItMatters\": [],\n \"whenNotToUse\": [],\n \"prerequisites\": [\n \"catalog-as-platform\"\n ],\n \"related\": [],\n \"next\": [\n \"embed-catalox\"\n ],\n \"exampleIds\": [],\n \"commonMistakes\": [],\n \"successCriteria\": [],\n \"invariants\": [],\n \"alternatives\": [],\n \"tags\": [],\n \"id\": \"mongo-primary\",\n \"type\": \"concept\",\n \"title\": \"MongoDB is primary persistence\",\n \"visualIds\": [],\n \"diagramIds\": [],\n \"referenceIds\": []\n }\n ],\n \"guides\": [\n {\n \"summary\": \"Create an in-process Catalox client from environment variables and verify Mongo connectivity.\",\n \"why\": \"Embedding is the default integration — HTTP service is optional.\",\n \"audiences\": [\n \"developers\"\n ],\n \"whenItMatters\": [],\n \"whenNotToUse\": [],\n \"prerequisites\": [\n \"catalog-as-platform\",\n \"mongo-primary\"\n ],\n \"related\": [\n \"choose-deploy-mode\"\n ],\n \"next\": [],\n \"exampleIds\": [],\n \"commonMistakes\": [],\n \"successCriteria\": [],\n \"invariants\": [\n \"Mongo is the primary store\",\n \"appId selects the catalog tenant, not the cloud project id\"\n ],\n \"alternatives\": [],\n \"confirmationRequired\": false,\n \"tags\": [],\n \"id\": \"embed-catalox\",\n \"type\": \"guide\",\n \"title\": \"Embed Catalox from env\",\n \"useWhen\": [],\n \"doNotUseWhen\": [],\n \"inputs\": [],\n \"permissions\": [],\n \"steps\": [],\n \"verification\": [],\n \"recovery\": [],\n \"tutorialIds\": [],\n \"referenceIds\": [],\n \"scenarioIds\": []\n }\n ],\n \"scenarios\": [\n {\n \"summary\": \"Decide whether to embed Catalox in-process or expose catalox-service.\",\n \"audiences\": [\n \"developers\"\n ],\n \"whenItMatters\": [],\n \"whenNotToUse\": [],\n \"prerequisites\": [],\n \"related\": [],\n \"next\": [],\n \"exampleIds\": [],\n \"commonMistakes\": [],\n \"successCriteria\": [],\n \"invariants\": [\n \"Same Mongo estate either way\",\n \"Authix gates public HTTP; embed still needs host context\"\n ],\n \"alternatives\": [],\n \"tags\": [],\n \"id\": \"choose-deploy-mode\",\n \"type\": \"scenario\",\n \"title\": \"Choose embed vs HTTP service\",\n \"situation\": \"You are integrating Catalox into a product and must pick embed vs HTTP service.\",\n \"preconditions\": [],\n \"signals\": [],\n \"decisionQuestion\": \"Should this product embed Catalox or deploy catalox-service?\",\n \"paths\": [\n {\n \"id\": \"embed\",\n \"label\": \"Embed in-process\",\n \"when\": \"One Node service owns catalog access and host identity.\",\n \"rationale\": \"Prefer createCataloxFromEnv and CataloxContext inside the BFF.\",\n \"guideIds\": [\n \"embed-catalox\"\n ]\n },\n {\n \"id\": \"http-service\",\n \"label\": \"HTTP service\",\n \"when\": \"Other runtimes or networks must call Catalox over HTTP.\",\n \"rationale\": \"Deploy catalox-service against the same Mongo estate; gate public routes with Authix.\",\n \"guideIds\": [\n \"embed-catalox\"\n ]\n }\n ],\n \"verification\": [],\n \"recovery\": []\n }\n ],\n \"decisions\": [],\n \"glossary\": [],\n \"visuals\": [],\n \"diagrams\": [],\n \"relationships\": [],\n \"tutorials\": [],\n \"examples\": [],\n \"sampleData\": [],\n \"uiClients\": [],\n \"apis\": []\n}"
|
|
1204
|
+
};
|
|
1205
|
+
//# sourceMappingURL=bundle.js.map
|