@x12i/connectix-docs 0.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.
Files changed (45) hide show
  1. package/README.md +77 -0
  2. package/bin/connectix-docs.js +2 -0
  3. package/dist/cli.d.ts +3 -0
  4. package/dist/cli.d.ts.map +1 -0
  5. package/dist/cli.js +56 -0
  6. package/dist/cli.js.map +1 -0
  7. package/dist/generated/bundle.d.ts +7 -0
  8. package/dist/generated/bundle.d.ts.map +1 -0
  9. package/dist/generated/bundle.js +304 -0
  10. package/dist/generated/bundle.js.map +1 -0
  11. package/dist/index.d.ts +6 -0
  12. package/dist/index.d.ts.map +1 -0
  13. package/dist/index.js +13 -0
  14. package/dist/index.js.map +1 -0
  15. package/dist/web/.deploy-ready +1 -0
  16. package/dist/web/agent-manifest.json +102 -0
  17. package/dist/web/agents.html +66 -0
  18. package/dist/web/app.js +164 -0
  19. package/dist/web/assets/book.css +783 -0
  20. package/dist/web/assets/extras.css +137 -0
  21. package/dist/web/assets/site.css +792 -0
  22. package/dist/web/assets/tokens.css +19 -0
  23. package/dist/web/books/00-orient-connectix/developers.html +174 -0
  24. package/dist/web/books/00-orient-connectix.html +56 -0
  25. package/dist/web/books/01-tools-and-simulator/developers.html +197 -0
  26. package/dist/web/books/01-tools-and-simulator.html +56 -0
  27. package/dist/web/catalog.html +83 -0
  28. package/dist/web/catalog.json +59 -0
  29. package/dist/web/docs.html +73 -0
  30. package/dist/web/downloads/books/00-orient-connectix/developers.chapters.json +26 -0
  31. package/dist/web/downloads/books/00-orient-connectix/developers.md +82 -0
  32. package/dist/web/downloads/books/01-tools-and-simulator/developers.chapters.json +32 -0
  33. package/dist/web/downloads/books/01-tools-and-simulator/developers.md +118 -0
  34. package/dist/web/downloads/use-cases/call-connect-tools.md +78 -0
  35. package/dist/web/downloads/use-cases/catalog-extension-overview.md +42 -0
  36. package/dist/web/downloads/use-cases/orient-connectix.md +95 -0
  37. package/dist/web/downloads/use-cases/run-package-simulator.md +48 -0
  38. package/dist/web/getting-started.html +74 -0
  39. package/dist/web/index.html +84 -0
  40. package/dist/web/pages.json +55 -0
  41. package/dist/web/read.html +121 -0
  42. package/dist/web/site.json +28 -0
  43. package/dist/web/use-cases.html +66 -0
  44. package/dist/web/use-cases.json +103 -0
  45. package/package.json +64 -0
package/dist/web/docs.html ADDED
@@ -0,0 +1,73 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Connectix docs</title>
7
+ <link rel="preconnect" href="https://fonts.googleapis.com">
8
+ <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
9
+ <link rel="stylesheet" href="/assets/site.css">
10
+ <link rel="stylesheet" href="/assets/extras.css">
11
+ </head>
12
+ <body class="page-docs-home" style="--accent:#2f6feb;--accent-alt:#1f6e5c" data-page="docs-home">
13
+ <div class="page-shell">
14
+ <header class="site-header">
15
+ <a class="brand" href="/docs">
16
+ <span class="brand-mark" aria-hidden="true"></span>
17
+ <span class="brand-name">connectix</span>
18
+ <span class="brand-badge">docs</span>
19
+ </a>
20
+ <button type="button" class="nav-toggle" aria-label="Menu" data-nav-toggle>Menu</button>
21
+ <nav class="site-nav" data-site-nav>
22
+ <a href="/getting-started">Getting started</a><a href="/use-cases">Use cases</a><a href="/catalog">Catalog</a><a href="/agents">Agents/SDK</a>
23
+
24
+ </nav>
25
+ </header>
26
+ <main>
27
+ <section class="hero">
28
+ <div class="hero-kicker">Documentation</div>
29
+ <h1>Connectix field guides</h1>
30
+ <p class="hero-lead">Orient on the service, expose the four connect tools, run the package simulator, and understand catalog provenance.</p>
31
+ <div class="cta-row"><a class="btn btn-primary" href="/getting-started">Getting started</a><a class="btn btn-secondary" href="/use-cases">Use cases</a></div>
32
+ </section>
33
+ <section class="install-callout" aria-label="Install knowledge package">
34
+ <div class="install-callout-inner">
35
+ <div class="install-kicker">npm</div>
36
+ <h2 class="install-title">Install for agents &amp; tooling</h2>
37
+ <p class="install-lead">Knowledge SDK — install as a <strong>devDependency</strong> only (not a production runtime).</p>
38
+ <pre class="install-cmd install-cmd-primary"><code>npm i -D @x12i/connectix-docs</code></pre>
39
+
40
+ <p class="install-more"><a href="/agents">Agents / SDK details →</a> · <a href="/agent-manifest.json">agent-manifest.json</a></p>
41
+ </div>
42
+ </section>
43
+ <section class="section tracks"><div class="track track-main">
44
+ <div class="tag ">Developers</div>
45
+ <ol class="step-list"><li><span class="step-num">1</span><span class="step-text"><a href="/books/00-orient-connectix">Orient on Connectix</a></span></li><li><span class="step-num">2</span><span class="step-text"><a href="/use-cases">Expose AI tools</a></span></li><li><span class="step-num">3</span><span class="step-text"><a href="/books/01-tools-and-simulator">Run the package simulator</a></span></li></ol>
46
+
47
+ <div class="cta-row"><a class="btn btn-primary" href="/books/00-orient-connectix">Start with orientation</a></div>
48
+ </div></section>
49
+ <section class="section" data-hydrate="use-cases"><div id="use-cases-root"></div></section>
50
+ <section class="section prose"><p>These docs are the human surface for the same content shipped in <code>@x12i/connectix-docs</code>
51
+ for agents. Prefer use cases when you have a concrete job to do.</p>
52
+ </section>
53
+ </main>
54
+ <footer class="site-footer">
55
+ <div class="footer-id">Connectix — internal X12I provider connectivity service.</div>
56
+ <nav class="footer-nav">
57
+ <a href="/docs">Docs home</a><a href="/getting-started">Getting started</a><a href="/use-cases">Use cases</a><a href="/catalog">Catalog</a><a href="/agents">Agents/SDK</a>
58
+ </nav>
59
+ </footer>
60
+ </div>
61
+ <script src="/app.js"></script>
62
+ <script>
63
+ document.querySelectorAll("[data-nav-toggle]").forEach((btn) => {
64
+ btn.addEventListener("click", () => {
65
+ document.querySelector("[data-site-nav]")?.classList.toggle("open");
66
+ });
67
+ });
68
+ </script>
69
+ <script>
70
+ if (typeof hydratePage === "function") hydratePage(document.body.dataset.page);
71
+ </script>
72
+ </body>
73
+ </html>
package/dist/web/downloads/books/00-orient-connectix/developers.chapters.json ADDED
@@ -0,0 +1,26 @@
1
+ [
2
+ {
3
+ "slug": "preamble",
4
+ "title": "Introduction",
5
+ "level": 2,
6
+ "order": 0
7
+ },
8
+ {
9
+ "slug": "1-what-connectix-is",
10
+ "title": "1. What Connectix is",
11
+ "level": 2,
12
+ "order": 1
13
+ },
14
+ {
15
+ "slug": "2-call-styles-and-auth",
16
+ "title": "2. Call styles and auth",
17
+ "level": 2,
18
+ "order": 2
19
+ },
20
+ {
21
+ "slug": "3-ownership-boundaries",
22
+ "title": "3. Ownership boundaries",
23
+ "level": 2,
24
+ "order": 3
25
+ }
26
+ ]
package/dist/web/downloads/books/00-orient-connectix/developers.md ADDED
@@ -0,0 +1,82 @@
1
+ # Orient on Connectix
2
+
3
+ Connectix is the internal X12I **provider connectivity** service. It sits between approved
4
+ internal callers (AI Skills, FuncX, Memorix Pipeline Services, Status UI) and external provider
5
+ APIs. It is not a customer-facing connector product: no signup, no billing, no public OAuth portal.
6
+
7
+ ## 1. What Connectix is
8
+
9
+ Connectix executes **curated provider actions** through one stable contract. Callers never learn
10
+ where an action implementation came from — OpenConnector, an n8n node, Nango-derived native code,
11
+ or Connectix-native code all look identical behind the same envelope.
12
+
13
+ The service exposes exactly four curated operations (never the full upstream provider catalog):
14
+
15
+ | Operation | Purpose |
16
+ |-----------|---------|
17
+ | `connect.listProviders` | List curated providers |
18
+ | `connect.searchActions` | Search curated actions |
19
+ | `connect.getAction` | Fetch one action descriptor |
20
+ | `connect.executeAction` | Run an action (stub or live) |
21
+
22
+ The runtime flow for every execution: validate caller → resolve binding → lease credential →
23
+ run action → observe in Memorix.
24
+
25
+ Key packages:
26
+
27
+ | Package | Role |
28
+ |---------|------|
29
+ | `@x12i/connectix-contracts` | Shared types and envelopes (`ConnectActionRequest`, `PipelineRequest`, error codes) |
30
+ | `@x12i/connectix-client` | Typed HTTP client for the service |
31
+ | `@x12i/connectix-tools` | The four operations as machine-usable LLM tool definitions + runners |
32
+ | `@x12i/connectix-simulator` | Package simulator for local development (no service required) |
33
+ | `@x12i/connectix-docs` | This knowledge package |
34
+
35
+ ## 2. Call styles and auth
36
+
37
+ Every non-probe route requires two headers:
38
+
39
+ ```http
40
+ Authorization: Bearer <caller-token>
41
+ x-connectix-caller-id: service:ai-skills
42
+ ```
43
+
44
+ Caller identity always comes from headers. A `callerId` in the request body is overwritten by
45
+ the service. Public routes (no auth): `GET /health`, `GET /ready`, `GET /metadata`.
46
+
47
+ There are two equivalent call styles sharing one runtime:
48
+
49
+ 1. **Canonical execute** — `POST /v1/actions/execute` with a full `ConnectActionRequest`
50
+ (contractVersion `"1"`, explicit `execution.mode` of `stub` or `live`).
51
+ 2. **Pipeline step** — `POST /pipeline` with `serviceId`, `serviceType` (one of the four
52
+ operations), `input`, and optional `stub.enabled`. Preferred for Memorix Pipeline Services,
53
+ the Status UI Try panel, and AI tools.
54
+
55
+ Discovery routes: `GET /v1/providers`, `GET /v1/actions/search?query=`, and
56
+ `GET /v1/actions/:actionId`. Operation metadata (including example envelopes) is served by
57
+ `GET /metadata` — UIs and tools must load catalogs from there, never hardcode them.
58
+
59
+ Failures use stable error codes such as `ACTION_NOT_FOUND`, `ACTION_NOT_ALLOWED`,
60
+ `CONNECTION_BINDING_NOT_FOUND`, `CREDENTIAL_NOT_AVAILABLE`, and
61
+ `ACTION_IMPLEMENTATION_UNAVAILABLE`.
62
+
63
+ ## 3. Ownership boundaries
64
+
65
+ Each fact has exactly one owner. Violating these boundaries is the primary review blocker:
66
+
67
+ | Fact | Owner |
68
+ |------|-------|
69
+ | Provider secrets and OAuth refresh | **Credorix** — never stored in Connectix or Memorix |
70
+ | Connection bindings and execution records | **Memorix adapter** (in-memory stub today) |
71
+ | Action implementations and provenance | **Connectix executor registry** |
72
+ | Provider definitions (catalog source) | `vendor/open-connector` (pinned engine) |
73
+
74
+ Callers send a `bindingRef`, never a credential. A binding points at a Credorix
75
+ `credentialRef` plus allowlisted action patterns for one provider. The runtime enforces:
76
+ binding exists and is enabled → binding provider matches the action provider → the action id
77
+ matches the binding's allowed patterns → only then lease a credential (live mode only).
78
+
79
+ Execution mode is always explicit. **Stub** returns the deterministic fixture published with the
80
+ action and records `mode=stub` in Memorix; **live** leases a credential and calls the provider.
81
+ Every published action must ship a schema-valid stub fixture, which is what makes local and CI
82
+ development safe by default.
package/dist/web/downloads/books/01-tools-and-simulator/developers.chapters.json ADDED
@@ -0,0 +1,32 @@
1
+ [
2
+ {
3
+ "slug": "preamble",
4
+ "title": "Introduction",
5
+ "level": 2,
6
+ "order": 0
7
+ },
8
+ {
9
+ "slug": "1-the-four-connect-tools",
10
+ "title": "1. The four connect tools",
11
+ "level": 2,
12
+ "order": 1
13
+ },
14
+ {
15
+ "slug": "2-run-the-package-simulator",
16
+ "title": "2. Run the package simulator",
17
+ "level": 2,
18
+ "order": 2
19
+ },
20
+ {
21
+ "slug": "3-stub-and-live-execution",
22
+ "title": "3. Stub and live execution",
23
+ "level": 2,
24
+ "order": 3
25
+ },
26
+ {
27
+ "slug": "4-catalog-extension-overview",
28
+ "title": "4. Catalog extension overview",
29
+ "level": 2,
30
+ "order": 4
31
+ }
32
+ ]
package/dist/web/downloads/books/01-tools-and-simulator/developers.md ADDED
@@ -0,0 +1,118 @@
1
+ # AI Tools and the Package Simulator
2
+
3
+ How to expose Connectix to LLMs as tools, develop against local fixtures, and understand where
4
+ catalog implementations come from.
5
+
6
+ ## 1. The four connect tools
7
+
8
+ `@x12i/connectix-tools` publishes the four curated operations as machine-usable tool
9
+ definitions with JSON Schema inputs and outputs:
10
+
11
+ | Tool name | Operation |
12
+ |-----------|-----------|
13
+ | `connect_list_providers` | `connect.listProviders` |
14
+ | `connect_search_actions` | `connect.searchActions` |
15
+ | `connect_get_action` | `connect.getAction` |
16
+ | `connect_execute_action` | `connect.executeAction` |
17
+
18
+ Register the definitions in your LLM tool registry, then route tool calls through a runner:
19
+
20
+ ```ts
21
+ import { CONNECT_TOOLS, createHttpConnectToolRunner } from "@x12i/connectix-tools";
22
+
23
+ const runner = createHttpConnectToolRunner({
24
+ baseUrl: "http://127.0.0.1:9400",
25
+ callerId: "service:ai-skills",
26
+ callerToken: process.env.CONNECTIX_AI_SKILLS_TOKEN ?? "change-me-caller",
27
+ });
28
+
29
+ const result = await runner.run({
30
+ tool: "connect_execute_action",
31
+ input: {
32
+ actionId: "example.echo",
33
+ bindingRef: "demo-echo",
34
+ input: { message: "hello" },
35
+ stubEnabled: true,
36
+ },
37
+ });
38
+ ```
39
+
40
+ Rules for tool callers:
41
+
42
+ - The recommended flow is discover → describe → execute: search actions, fetch the descriptor,
43
+ read its `inputSchema`, then execute.
44
+ - Pass a `bindingRef`, never a credential. `stubEnabled: true` gives deterministic fixtures.
45
+ - Never add executor-source branches (n8n, Nango, OpenConnector) to caller code. Provenance is
46
+ internal to the service.
47
+
48
+ ## 2. Run the package simulator
49
+
50
+ `@x12i/connectix-simulator` is a package simulator built on `@x12i/api-simulator`. It mirrors
51
+ the Connectix HTTP surface with deterministic fixtures so you can develop tools, callers, and
52
+ tests without the service, Credorix, or providers:
53
+
54
+ ```ts
55
+ import { createConnectToolRunner } from "@x12i/connectix-tools";
56
+ import { createSimulatorPipelineCaller, createConnectixSimulator } from "@x12i/connectix-simulator";
57
+
58
+ // In-process pipeline caller for tool runners:
59
+ const runner = createConnectToolRunner(createSimulatorPipelineCaller());
60
+
61
+ // Or raw HTTP-shaped dispatch:
62
+ const { simulator } = createConnectixSimulator();
63
+ await simulator.dispatch({ method: "GET", path: "/metadata" });
64
+ ```
65
+
66
+ Simulated fixtures mirror the service foundation: actions `example.echo`,
67
+ `hackernews.get_item`, `hackernews.list_top_stories`, `github.issue.create` and bindings
68
+ `demo-echo`, `demo-hackernews`, `demo-github`.
69
+
70
+ An optional HTTP entry (`startConnectixSimulatorServer`) binds `127.0.0.1:5524` in the
71
+ api-simulator port zone (5520–5539) when a caller needs a real URL. Prefer in-process
72
+ `dispatch()` for tests.
73
+
74
+ The simulator supports **stub mode only**. Live requests return
75
+ `ACTION_IMPLEMENTATION_UNAVAILABLE` — switch `baseUrl` to the real service for live execution.
76
+ Because envelopes are identical, no caller code changes.
77
+
78
+ ## 3. Stub and live execution
79
+
80
+ Both call styles make execution mode explicit:
81
+
82
+ - Pipeline style: `stub: { enabled: true }` → stub; omitted or `false` → live.
83
+ - Canonical style: `execution: { mode: "stub" | "live" }`.
84
+
85
+ Stub execution validates binding policy exactly like live (unknown binding, provider mismatch,
86
+ and disallowed patterns are still rejected), returns the deterministic fixture published with
87
+ the action, and records `mode=stub` in the Memorix execution record. It never leases a
88
+ credential.
89
+
90
+ Live execution resolves the binding's `credentialRef` through Credorix (or the dev credential
91
+ resolver when Credorix env is unset) and runs the registered executor.
92
+
93
+ Development default: stub everywhere — simulator, CI, and Status UI Try. Live is opt-in per
94
+ request and per binding.
95
+
96
+ ## 4. Catalog extension overview
97
+
98
+ The catalog grows from three sources, all published behind the same caller contract:
99
+
100
+ | Source kind | What it is |
101
+ |-------------|------------|
102
+ | `openconnector` | Curated actions executed by the pinned `vendor/open-connector` engine |
103
+ | `n8n-node` | Selected n8n node resource/operations from an allowlisted, pinned package set |
104
+ | `nango-derived` | Native Connectix/OpenConnector code adapted from offline Nango knowledge |
105
+ | `connectix-native` | First-party executors (for example `example.echo`) |
106
+
107
+ Non-negotiables:
108
+
109
+ - Nango is **offline catalog intelligence only** — never a runtime dependency.
110
+ - Executor selection happens in the executor registry by descriptor; callers never choose a
111
+ backend.
112
+ - Every published action carries provenance (`sourceId`, `sourceVersion`, `fingerprint`,
113
+ license) which flows into Memorix execution records — but never secrets.
114
+ - Offline tooling: `npm run n8n:catalog`, `npm run nango:catalog`, `npm run catalog:gaps`,
115
+ `npm run catalog:review`, `npm run catalog:publish` (writes the reviewed publish list under
116
+ `generated/catalog-candidates/`).
117
+
118
+ Full design: `docs/Connectix-Catalog-Extension-Specification.md` in the Connectix repository.
package/dist/web/downloads/use-cases/call-connect-tools.md ADDED
@@ -0,0 +1,78 @@
1
+ # Expose Connectix as AI tools
2
+
3
+ > **Use case id:** `call-connect-tools`
4
+ > **Goal:** Register the four connect tools from @x12i/connectix-tools in an LLM tool registry and run them against a live service or the simulator.
5
+ > **Audiences:** developers
6
+ > **Tags:** ai-tools, agents
7
+
8
+ ## Reading path
9
+
10
+ 1. **AI Tools and the Package Simulator** (developers) → chapters: `1-the-four-connect-tools`, `3-stub-and-live-execution`
11
+
12
+ ## From: AI Tools and the Package Simulator — 1. The four connect tools
13
+
14
+ `@x12i/connectix-tools` publishes the four curated operations as machine-usable tool
15
+ definitions with JSON Schema inputs and outputs:
16
+
17
+ | Tool name | Operation |
18
+ |-----------|-----------|
19
+ | `connect_list_providers` | `connect.listProviders` |
20
+ | `connect_search_actions` | `connect.searchActions` |
21
+ | `connect_get_action` | `connect.getAction` |
22
+ | `connect_execute_action` | `connect.executeAction` |
23
+
24
+ Register the definitions in your LLM tool registry, then route tool calls through a runner:
25
+
26
+ ```ts
27
+ import { CONNECT_TOOLS, createHttpConnectToolRunner } from "@x12i/connectix-tools";
28
+
29
+ const runner = createHttpConnectToolRunner({
30
+ baseUrl: "http://127.0.0.1:9400",
31
+ callerId: "service:ai-skills",
32
+ callerToken: process.env.CONNECTIX_AI_SKILLS_TOKEN ?? "change-me-caller",
33
+ });
34
+
35
+ const result = await runner.run({
36
+ tool: "connect_execute_action",
37
+ input: {
38
+ actionId: "example.echo",
39
+ bindingRef: "demo-echo",
40
+ input: { message: "hello" },
41
+ stubEnabled: true,
42
+ },
43
+ });
44
+ ```
45
+
46
+ Rules for tool callers:
47
+
48
+ - The recommended flow is discover → describe → execute: search actions, fetch the descriptor,
49
+ read its `inputSchema`, then execute.
50
+ - Pass a `bindingRef`, never a credential. `stubEnabled: true` gives deterministic fixtures.
51
+ - Never add executor-source branches (n8n, Nango, OpenConnector) to caller code. Provenance is
52
+ internal to the service.
53
+
54
+ ## From: AI Tools and the Package Simulator — 3. Stub and live execution
55
+
56
+ Both call styles make execution mode explicit:
57
+
58
+ - Pipeline style: `stub: { enabled: true }` → stub; omitted or `false` → live.
59
+ - Canonical style: `execution: { mode: "stub" | "live" }`.
60
+
61
+ Stub execution validates binding policy exactly like live (unknown binding, provider mismatch,
62
+ and disallowed patterns are still rejected), returns the deterministic fixture published with
63
+ the action, and records `mode=stub` in the Memorix execution record. It never leases a
64
+ credential.
65
+
66
+ Live execution resolves the binding's `credentialRef` through Credorix (or the dev credential
67
+ resolver when Credorix env is unset) and runs the registered executor.
68
+
69
+ Development default: stub everywhere — simulator, CI, and Status UI Try. Live is opt-in per
70
+ request and per binding.
71
+
72
+ ## Also see
73
+
74
+ - **run-package-simulator** (`run-package-simulator`) —
75
+
76
+ ---
77
+
78
+ _Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._
package/dist/web/downloads/use-cases/catalog-extension-overview.md ADDED
@@ -0,0 +1,42 @@
1
+ # Understand catalog extension provenance
2
+
3
+ > **Use case id:** `catalog-extension-overview`
4
+ > **Goal:** Know how OpenConnector, n8n-node, and Nango-derived implementations reach the catalog while callers stay source-agnostic.
5
+ > **Audiences:** developers
6
+ > **Tags:** catalog, provenance
7
+
8
+ ## Reading path
9
+
10
+ 1. **AI Tools and the Package Simulator** (developers) → chapters: `4-catalog-extension-overview`
11
+
12
+ ## From: AI Tools and the Package Simulator — 4. Catalog extension overview
13
+
14
+ The catalog grows from three sources, all published behind the same caller contract:
15
+
16
+ | Source kind | What it is |
17
+ |-------------|------------|
18
+ | `openconnector` | Curated actions executed by the pinned `vendor/open-connector` engine |
19
+ | `n8n-node` | Selected n8n node resource/operations from an allowlisted, pinned package set |
20
+ | `nango-derived` | Native Connectix/OpenConnector code adapted from offline Nango knowledge |
21
+ | `connectix-native` | First-party executors (for example `example.echo`) |
22
+
23
+ Non-negotiables:
24
+
25
+ - Nango is **offline catalog intelligence only** — never a runtime dependency.
26
+ - Executor selection happens in the executor registry by descriptor; callers never choose a
27
+ backend.
28
+ - Every published action carries provenance (`sourceId`, `sourceVersion`, `fingerprint`,
29
+ license) which flows into Memorix execution records — but never secrets.
30
+ - Offline tooling: `npm run n8n:catalog`, `npm run nango:catalog`, `npm run catalog:gaps`,
31
+ `npm run catalog:review`, `npm run catalog:publish` (writes the reviewed publish list under
32
+ `generated/catalog-candidates/`).
33
+
34
+ Full design: `docs/Connectix-Catalog-Extension-Specification.md` in the Connectix repository.
35
+
36
+ ## Also see
37
+
38
+ - **orient-connectix** (`orient-connectix`) —
39
+
40
+ ---
41
+
42
+ _Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._
package/dist/web/downloads/use-cases/orient-connectix.md ADDED
@@ -0,0 +1,95 @@
1
+ # Orient on Connectix
2
+
3
+ > **Use case id:** `orient-connectix`
4
+ > **Goal:** Understand what Connectix is, the four curated operations, and the caller contract before writing any integration code.
5
+ > **Audiences:** developers
6
+ > **Tags:** orientation, getting-started
7
+
8
+ ## Reading path
9
+
10
+ 1. **Orient on Connectix** (developers) → chapters: `1-what-connectix-is`, `2-call-styles-and-auth`, `3-ownership-boundaries`
11
+
12
+ ## From: Orient on Connectix — 1. What Connectix is
13
+
14
+ Connectix executes **curated provider actions** through one stable contract. Callers never learn
15
+ where an action implementation came from — OpenConnector, an n8n node, Nango-derived native code,
16
+ or Connectix-native code all look identical behind the same envelope.
17
+
18
+ The service exposes exactly four curated operations (never the full upstream provider catalog):
19
+
20
+ | Operation | Purpose |
21
+ |-----------|---------|
22
+ | `connect.listProviders` | List curated providers |
23
+ | `connect.searchActions` | Search curated actions |
24
+ | `connect.getAction` | Fetch one action descriptor |
25
+ | `connect.executeAction` | Run an action (stub or live) |
26
+
27
+ The runtime flow for every execution: validate caller → resolve binding → lease credential →
28
+ run action → observe in Memorix.
29
+
30
+ Key packages:
31
+
32
+ | Package | Role |
33
+ |---------|------|
34
+ | `@x12i/connectix-contracts` | Shared types and envelopes (`ConnectActionRequest`, `PipelineRequest`, error codes) |
35
+ | `@x12i/connectix-client` | Typed HTTP client for the service |
36
+ | `@x12i/connectix-tools` | The four operations as machine-usable LLM tool definitions + runners |
37
+ | `@x12i/connectix-simulator` | Package simulator for local development (no service required) |
38
+ | `@x12i/connectix-docs` | This knowledge package |
39
+
40
+ ## From: Orient on Connectix — 2. Call styles and auth
41
+
42
+ Every non-probe route requires two headers:
43
+
44
+ ```http
45
+ Authorization: Bearer <caller-token>
46
+ x-connectix-caller-id: service:ai-skills
47
+ ```
48
+
49
+ Caller identity always comes from headers. A `callerId` in the request body is overwritten by
50
+ the service. Public routes (no auth): `GET /health`, `GET /ready`, `GET /metadata`.
51
+
52
+ There are two equivalent call styles sharing one runtime:
53
+
54
+ 1. **Canonical execute** — `POST /v1/actions/execute` with a full `ConnectActionRequest`
55
+ (contractVersion `"1"`, explicit `execution.mode` of `stub` or `live`).
56
+ 2. **Pipeline step** — `POST /pipeline` with `serviceId`, `serviceType` (one of the four
57
+ operations), `input`, and optional `stub.enabled`. Preferred for Memorix Pipeline Services,
58
+ the Status UI Try panel, and AI tools.
59
+
60
+ Discovery routes: `GET /v1/providers`, `GET /v1/actions/search?query=`, and
61
+ `GET /v1/actions/:actionId`. Operation metadata (including example envelopes) is served by
62
+ `GET /metadata` — UIs and tools must load catalogs from there, never hardcode them.
63
+
64
+ Failures use stable error codes such as `ACTION_NOT_FOUND`, `ACTION_NOT_ALLOWED`,
65
+ `CONNECTION_BINDING_NOT_FOUND`, `CREDENTIAL_NOT_AVAILABLE`, and
66
+ `ACTION_IMPLEMENTATION_UNAVAILABLE`.
67
+
68
+ ## From: Orient on Connectix — 3. Ownership boundaries
69
+
70
+ Each fact has exactly one owner. Violating these boundaries is the primary review blocker:
71
+
72
+ | Fact | Owner |
73
+ |------|-------|
74
+ | Provider secrets and OAuth refresh | **Credorix** — never stored in Connectix or Memorix |
75
+ | Connection bindings and execution records | **Memorix adapter** (in-memory stub today) |
76
+ | Action implementations and provenance | **Connectix executor registry** |
77
+ | Provider definitions (catalog source) | `vendor/open-connector` (pinned engine) |
78
+
79
+ Callers send a `bindingRef`, never a credential. A binding points at a Credorix
80
+ `credentialRef` plus allowlisted action patterns for one provider. The runtime enforces:
81
+ binding exists and is enabled → binding provider matches the action provider → the action id
82
+ matches the binding's allowed patterns → only then lease a credential (live mode only).
83
+
84
+ Execution mode is always explicit. **Stub** returns the deterministic fixture published with the
85
+ action and records `mode=stub` in Memorix; **live** leases a credential and calls the provider.
86
+ Every published action must ship a schema-valid stub fixture, which is what makes local and CI
87
+ development safe by default.
88
+
89
+ ## Also see
90
+
91
+ - **call-connect-tools** (`call-connect-tools`) —
92
+
93
+ ---
94
+
95
+ _Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._
package/dist/web/downloads/use-cases/run-package-simulator.md ADDED
@@ -0,0 +1,48 @@
1
+ # Develop against the package simulator
2
+
3
+ > **Use case id:** `run-package-simulator`
4
+ > **Goal:** Use @x12i/connectix-simulator for deterministic local development and tests without the service, Credorix, or providers.
5
+ > **Audiences:** developers
6
+ > **Tags:** simulator, testing
7
+
8
+ ## Reading path
9
+
10
+ 1. **AI Tools and the Package Simulator** (developers) → chapters: `2-run-the-package-simulator`
11
+
12
+ ## From: AI Tools and the Package Simulator — 2. Run the package simulator
13
+
14
+ `@x12i/connectix-simulator` is a package simulator built on `@x12i/api-simulator`. It mirrors
15
+ the Connectix HTTP surface with deterministic fixtures so you can develop tools, callers, and
16
+ tests without the service, Credorix, or providers:
17
+
18
+ ```ts
19
+ import { createConnectToolRunner } from "@x12i/connectix-tools";
20
+ import { createSimulatorPipelineCaller, createConnectixSimulator } from "@x12i/connectix-simulator";
21
+
22
+ // In-process pipeline caller for tool runners:
23
+ const runner = createConnectToolRunner(createSimulatorPipelineCaller());
24
+
25
+ // Or raw HTTP-shaped dispatch:
26
+ const { simulator } = createConnectixSimulator();
27
+ await simulator.dispatch({ method: "GET", path: "/metadata" });
28
+ ```
29
+
30
+ Simulated fixtures mirror the service foundation: actions `example.echo`,
31
+ `hackernews.get_item`, `hackernews.list_top_stories`, `github.issue.create` and bindings
32
+ `demo-echo`, `demo-hackernews`, `demo-github`.
33
+
34
+ An optional HTTP entry (`startConnectixSimulatorServer`) binds `127.0.0.1:5524` in the
35
+ api-simulator port zone (5520–5539) when a caller needs a real URL. Prefer in-process
36
+ `dispatch()` for tests.
37
+
38
+ The simulator supports **stub mode only**. Live requests return
39
+ `ACTION_IMPLEMENTATION_UNAVAILABLE` — switch `baseUrl` to the real service for live execution.
40
+ Because envelopes are identical, no caller code changes.
41
+
42
+ ## Also see
43
+
44
+ - **call-connect-tools** (`call-connect-tools`) —
45
+
46
+ ---
47
+
48
+ _Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._