@x12i/connectix-docs 0.1.0 → 0.1.2

package/dist/web/agent/agent-manifest.json

@@ -0,0 +1,120 @@
+{
+  "version": 1,
+  "product": "Connectix",
+  "site": "https://docs.connectix.x12i.com",
+  "knowledgePackage": "@x12i/connectix-docs",
+  "roles": [
+    "developers"
+  ],
+  "books": [
+    {
+      "id": "00-orient-connectix",
+      "audiences": [
+        "developers"
+      ],
+      "md": {
+        "developers": "downloads/books/00-orient-connectix/developers.md"
+      },
+      "pdf": {
+        "developers": null
+      },
+      "chapters": {
+        "developers": "downloads/books/00-orient-connectix/developers.chapters.json"
+      }
+    },
+    {
+      "id": "01-tools-and-simulator",
+      "audiences": [
+        "developers"
+      ],
+      "md": {
+        "developers": "downloads/books/01-tools-and-simulator/developers.md"
+      },
+      "pdf": {
+        "developers": null
+      },
+      "chapters": {
+        "developers": "downloads/books/01-tools-and-simulator/developers.chapters.json"
+      }
+    }
+  ],
+  "useCases": [
+    {
+      "id": "orient-connectix",
+      "title": "Orient on Connectix",
+      "md": "downloads/use-cases/orient-connectix.md",
+      "path": [
+        {
+          "bookId": "00-orient-connectix",
+          "audience": "developers",
+          "chapters": [
+            "1-what-connectix-is",
+            "2-call-styles-and-auth",
+            "3-ownership-boundaries"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "call-connect-tools",
+      "title": "Expose Connectix as AI tools",
+      "md": "downloads/use-cases/call-connect-tools.md",
+      "path": [
+        {
+          "bookId": "01-tools-and-simulator",
+          "audience": "developers",
+          "chapters": [
+            "1-the-four-connect-tools",
+            "3-stub-and-live-execution"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "run-package-simulator",
+      "title": "Develop against the package simulator",
+      "md": "downloads/use-cases/run-package-simulator.md",
+      "path": [
+        {
+          "bookId": "01-tools-and-simulator",
+          "audience": "developers",
+          "chapters": [
+            "2-run-the-package-simulator"
+          ]
+        }
+      ]
+    },
+    {
+      "id": "catalog-extension-overview",
+      "title": "Understand catalog extension provenance",
+      "md": "downloads/use-cases/catalog-extension-overview.md",
+      "path": [
+        {
+          "bookId": "01-tools-and-simulator",
+          "audience": "developers",
+          "chapters": [
+            "4-catalog-extension-overview"
+          ]
+        }
+      ]
+    }
+  ],
+  "indexes": {
+    "indexMd": "INDEX.md",
+    "searchJson": "SEARCH.json"
+  },
+  "concepts": [],
+  "guides": [],
+  "scenarios": [],
+  "decisions": [],
+  "glossary": [],
+  "visuals": [],
+  "diagrams": [],
+  "relationships": [],
+  "tutorials": [],
+  "examples": [],
+  "sampleData": [],
+  "uiClients": [],
+  "apis": [],
+  "packs": []
+}

package/dist/web/agent/indexes/books.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "00-orient-connectix",
+      "title": "Orient on Connectix",
+      "summary": "The Connectix mental model: curated operations, bindings instead of secrets, stub versus live execution, and the Credorix/Memorix ownership boundaries.",
+      "path": "books/00-orient-connectix/"
+    },
+    {
+      "id": "01-tools-and-simulator",
+      "title": "AI Tools and the Package Simulator",
+      "summary": "How to expose Connectix as LLM tools with @x12i/connectix-tools, run the @x12i/connectix-simulator package simulator, and understand catalog extension provenance.",
+      "path": "books/01-tools-and-simulator/"
+    }
+  ]
+}

package/dist/web/agent/indexes/books.md

@@ -0,0 +1,4 @@
+# books
+
+- `00-orient-connectix` — Orient on Connectix — The Connectix mental model: curated operations, bindings instead of secrets, stub versus live execution, and the Credorix/Memorix ownership boundaries.
+- `01-tools-and-simulator` — AI Tools and the Package Simulator — How to expose Connectix as LLM tools with @x12i/connectix-tools, run the @x12i/connectix-simulator package simulator, and understand catalog extension provenance.

package/dist/web/agent/indexes/concepts.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/dist/web/agent/indexes/concepts.md

@@ -0,0 +1,3 @@
+# concepts
+
+

package/dist/web/agent/indexes/diagrams.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/dist/web/agent/indexes/diagrams.md

@@ -0,0 +1,3 @@
+# diagrams
+
+

package/dist/web/agent/indexes/guides.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/dist/web/agent/indexes/guides.md

@@ -0,0 +1,3 @@
+# guides
+
+

package/dist/web/agent/indexes/scenarios.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/dist/web/agent/indexes/scenarios.md

@@ -0,0 +1,3 @@
+# scenarios
+
+

package/dist/web/agent/indexes/tutorials.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "items": []
+}

package/dist/web/agent/indexes/tutorials.md

@@ -0,0 +1,3 @@
+# tutorials
+
+

package/dist/web/agent/indexes/use-cases.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "items": [
+    {
+      "id": "orient-connectix",
+      "title": "Orient on Connectix",
+      "summary": "Understand what Connectix is, the four curated operations, and the caller contract before writing any integration code.",
+      "path": "use-cases/orient-connectix.md"
+    },
+    {
+      "id": "call-connect-tools",
+      "title": "Expose Connectix as AI tools",
+      "summary": "Register the four connect tools from @x12i/connectix-tools in an LLM tool registry and run them against a live service or the simulator.",
+      "path": "use-cases/call-connect-tools.md"
+    },
+    {
+      "id": "run-package-simulator",
+      "title": "Develop against the package simulator",
+      "summary": "Use @x12i/connectix-simulator for deterministic local development and tests without the service, Credorix, or providers.",
+      "path": "use-cases/run-package-simulator.md"
+    },
+    {
+      "id": "catalog-extension-overview",
+      "title": "Understand catalog extension provenance",
+      "summary": "Know how OpenConnector, n8n-node, and Nango-derived implementations reach the catalog while callers stay source-agnostic.",
+      "path": "use-cases/catalog-extension-overview.md"
+    }
+  ]
+}

package/dist/web/agent/indexes/use-cases.md

@@ -0,0 +1,6 @@
+# use-cases
+
+- `orient-connectix` — Orient on Connectix — Understand what Connectix is, the four curated operations, and the caller contract before writing any integration code.
+- `call-connect-tools` — Expose Connectix as AI tools — Register the four connect tools from @x12i/connectix-tools in an LLM tool registry and run them against a live service or the simulator.
+- `run-package-simulator` — Develop against the package simulator — Use @x12i/connectix-simulator for deterministic local development and tests without the service, Credorix, or providers.
+- `catalog-extension-overview` — Understand catalog extension provenance — Know how OpenConnector, n8n-node, and Nango-derived implementations reach the catalog while callers stay source-agnostic.

package/dist/web/agent/use-cases/call-connect-tools.md

@@ -0,0 +1,78 @@
+# Expose Connectix as AI tools
+
+> **Use case id:** `call-connect-tools`
+> **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.
+> **Audiences:** developers
+> **Tags:** ai-tools, agents
+
+## Reading path
+
+1. **AI Tools and the Package Simulator** (developers) → chapters: `1-the-four-connect-tools`, `3-stub-and-live-execution`
+
+## From: AI Tools and the Package Simulator — 1. The four connect tools
+
+`@x12i/connectix-tools` publishes the four curated operations as machine-usable tool
+definitions with JSON Schema inputs and outputs:
+
+| Tool name | Operation |
+|-----------|-----------|
+| `connect_list_providers` | `connect.listProviders` |
+| `connect_search_actions` | `connect.searchActions` |
+| `connect_get_action` | `connect.getAction` |
+| `connect_execute_action` | `connect.executeAction` |
+
+Register the definitions in your LLM tool registry, then route tool calls through a runner:
+
+```ts
+import { CONNECT_TOOLS, createHttpConnectToolRunner } from "@x12i/connectix-tools";
+
+const runner = createHttpConnectToolRunner({
+  baseUrl: "http://127.0.0.1:9400",
+  callerId: "service:ai-skills",
+  callerToken: process.env.CONNECTIX_AI_SKILLS_TOKEN ?? "change-me-caller",
+});
+
+const result = await runner.run({
+  tool: "connect_execute_action",
+  input: {
+    actionId: "example.echo",
+    bindingRef: "demo-echo",
+    input: { message: "hello" },
+    stubEnabled: true,
+  },
+});
+```
+
+Rules for tool callers:
+
+- The recommended flow is discover → describe → execute: search actions, fetch the descriptor,
+  read its `inputSchema`, then execute.
+- Pass a `bindingRef`, never a credential. `stubEnabled: true` gives deterministic fixtures.
+- Never add executor-source branches (n8n, Nango, OpenConnector) to caller code. Provenance is
+  internal to the service.
+
+## From: AI Tools and the Package Simulator — 3. Stub and live execution
+
+Both call styles make execution mode explicit:
+
+- Pipeline style: `stub: { enabled: true }` → stub; omitted or `false` → live.
+- Canonical style: `execution: { mode: "stub" | "live" }`.
+
+Stub execution validates binding policy exactly like live (unknown binding, provider mismatch,
+and disallowed patterns are still rejected), returns the deterministic fixture published with
+the action, and records `mode=stub` in the Memorix execution record. It never leases a
+credential.
+
+Live execution resolves the binding's `credentialRef` through Credorix (or the dev credential
+resolver when Credorix env is unset) and runs the registered executor.
+
+Development default: stub everywhere — simulator, CI, and Status UI Try. Live is opt-in per
+request and per binding.
+
+## Also see
+
+- **run-package-simulator** (`run-package-simulator`) — 
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/dist/web/agent/use-cases/catalog-extension-overview.md

@@ -0,0 +1,42 @@
+# Understand catalog extension provenance
+
+> **Use case id:** `catalog-extension-overview`
+> **Goal:** Know how OpenConnector, n8n-node, and Nango-derived implementations reach the catalog while callers stay source-agnostic.
+> **Audiences:** developers
+> **Tags:** catalog, provenance
+
+## Reading path
+
+1. **AI Tools and the Package Simulator** (developers) → chapters: `4-catalog-extension-overview`
+
+## From: AI Tools and the Package Simulator — 4. Catalog extension overview
+
+The catalog grows from three sources, all published behind the same caller contract:
+
+| Source kind | What it is |
+|-------------|------------|
+| `openconnector` | Curated actions executed by the pinned `vendor/open-connector` engine |
+| `n8n-node` | Selected n8n node resource/operations from an allowlisted, pinned package set |
+| `nango-derived` | Native Connectix/OpenConnector code adapted from offline Nango knowledge |
+| `connectix-native` | First-party executors (for example `example.echo`) |
+
+Non-negotiables:
+
+- Nango is **offline catalog intelligence only** — never a runtime dependency.
+- Executor selection happens in the executor registry by descriptor; callers never choose a
+  backend.
+- Every published action carries provenance (`sourceId`, `sourceVersion`, `fingerprint`,
+  license) which flows into Memorix execution records — but never secrets.
+- Offline tooling: `npm run n8n:catalog`, `npm run nango:catalog`, `npm run catalog:gaps`,
+  `npm run catalog:review`, `npm run catalog:publish` (writes the reviewed publish list under
+  `generated/catalog-candidates/`).
+
+Full design: `docs/Connectix-Catalog-Extension-Specification.md` in the Connectix repository.
+
+## Also see
+
+- **orient-connectix** (`orient-connectix`) — 
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/dist/web/agent/use-cases/orient-connectix.md

@@ -0,0 +1,95 @@
+# Orient on Connectix
+
+> **Use case id:** `orient-connectix`
+> **Goal:** Understand what Connectix is, the four curated operations, and the caller contract before writing any integration code.
+> **Audiences:** developers
+> **Tags:** orientation, getting-started
+
+## Reading path
+
+1. **Orient on Connectix** (developers) → chapters: `1-what-connectix-is`, `2-call-styles-and-auth`, `3-ownership-boundaries`
+
+## From: Orient on Connectix — 1. What Connectix is
+
+Connectix executes **curated provider actions** through one stable contract. Callers never learn
+where an action implementation came from — OpenConnector, an n8n node, Nango-derived native code,
+or Connectix-native code all look identical behind the same envelope.
+
+The service exposes exactly four curated operations (never the full upstream provider catalog):
+
+| Operation | Purpose |
+|-----------|---------|
+| `connect.listProviders` | List curated providers |
+| `connect.searchActions` | Search curated actions |
+| `connect.getAction` | Fetch one action descriptor |
+| `connect.executeAction` | Run an action (stub or live) |
+
+The runtime flow for every execution: validate caller → resolve binding → lease credential →
+run action → observe in Memorix.
+
+Key packages:
+
+| Package | Role |
+|---------|------|
+| `@x12i/connectix-contracts` | Shared types and envelopes (`ConnectActionRequest`, `PipelineRequest`, error codes) |
+| `@x12i/connectix-client` | Typed HTTP client for the service |
+| `@x12i/connectix-tools` | The four operations as machine-usable LLM tool definitions + runners |
+| `@x12i/connectix-simulator` | Package simulator for local development (no service required) |
+| `@x12i/connectix-docs` | This knowledge package |
+
+## From: Orient on Connectix — 2. Call styles and auth
+
+Every non-probe route requires two headers:
+
+```http
+Authorization: Bearer <caller-token>
+x-connectix-caller-id: service:ai-skills
+```
+
+Caller identity always comes from headers. A `callerId` in the request body is overwritten by
+the service. Public routes (no auth): `GET /health`, `GET /ready`, `GET /metadata`.
+
+There are two equivalent call styles sharing one runtime:
+
+1. **Canonical execute** — `POST /v1/actions/execute` with a full `ConnectActionRequest`
+   (contractVersion `"1"`, explicit `execution.mode` of `stub` or `live`).
+2. **Pipeline step** — `POST /pipeline` with `serviceId`, `serviceType` (one of the four
+   operations), `input`, and optional `stub.enabled`. Preferred for Memorix Pipeline Services,
+   the Status UI Try panel, and AI tools.
+
+Discovery routes: `GET /v1/providers`, `GET /v1/actions/search?query=`, and
+`GET /v1/actions/:actionId`. Operation metadata (including example envelopes) is served by
+`GET /metadata` — UIs and tools must load catalogs from there, never hardcode them.
+
+Failures use stable error codes such as `ACTION_NOT_FOUND`, `ACTION_NOT_ALLOWED`,
+`CONNECTION_BINDING_NOT_FOUND`, `CREDENTIAL_NOT_AVAILABLE`, and
+`ACTION_IMPLEMENTATION_UNAVAILABLE`.
+
+## From: Orient on Connectix — 3. Ownership boundaries
+
+Each fact has exactly one owner. Violating these boundaries is the primary review blocker:
+
+| Fact | Owner |
+|------|-------|
+| Provider secrets and OAuth refresh | **Credorix** — never stored in Connectix or Memorix |
+| Connection bindings and execution records | **Memorix adapter** (in-memory stub today) |
+| Action implementations and provenance | **Connectix executor registry** |
+| Provider definitions (catalog source) | `vendor/open-connector` (pinned engine) |
+
+Callers send a `bindingRef`, never a credential. A binding points at a Credorix
+`credentialRef` plus allowlisted action patterns for one provider. The runtime enforces:
+binding exists and is enabled → binding provider matches the action provider → the action id
+matches the binding's allowed patterns → only then lease a credential (live mode only).
+
+Execution mode is always explicit. **Stub** returns the deterministic fixture published with the
+action and records `mode=stub` in Memorix; **live** leases a credential and calls the provider.
+Every published action must ship a schema-valid stub fixture, which is what makes local and CI
+development safe by default.
+
+## Also see
+
+- **call-connect-tools** (`call-connect-tools`) — 
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/dist/web/agent/use-cases/run-package-simulator.md

@@ -0,0 +1,48 @@
+# Develop against the package simulator
+
+> **Use case id:** `run-package-simulator`
+> **Goal:** Use @x12i/connectix-simulator for deterministic local development and tests without the service, Credorix, or providers.
+> **Audiences:** developers
+> **Tags:** simulator, testing
+
+## Reading path
+
+1. **AI Tools and the Package Simulator** (developers) → chapters: `2-run-the-package-simulator`
+
+## From: AI Tools and the Package Simulator — 2. Run the package simulator
+
+`@x12i/connectix-simulator` is a package simulator built on `@x12i/api-simulator`. It mirrors
+the Connectix HTTP surface with deterministic fixtures so you can develop tools, callers, and
+tests without the service, Credorix, or providers:
+
+```ts
+import { createConnectToolRunner } from "@x12i/connectix-tools";
+import { createSimulatorPipelineCaller, createConnectixSimulator } from "@x12i/connectix-simulator";
+
+// In-process pipeline caller for tool runners:
+const runner = createConnectToolRunner(createSimulatorPipelineCaller());
+
+// Or raw HTTP-shaped dispatch:
+const { simulator } = createConnectixSimulator();
+await simulator.dispatch({ method: "GET", path: "/metadata" });
+```
+
+Simulated fixtures mirror the service foundation: actions `example.echo`,
+`hackernews.get_item`, `hackernews.list_top_stories`, `github.issue.create` and bindings
+`demo-echo`, `demo-hackernews`, `demo-github`.
+
+An optional HTTP entry (`startConnectixSimulatorServer`) binds `127.0.0.1:5524` in the
+api-simulator port zone (5520–5539) when a caller needs a real URL. Prefer in-process
+`dispatch()` for tests.
+
+The simulator supports **stub mode only**. Live requests return
+`ACTION_IMPLEMENTATION_UNAVAILABLE` — switch `baseUrl` to the real service for live execution.
+Because envelopes are identical, no caller code changes.
+
+## Also see
+
+- **call-connect-tools** (`call-connect-tools`) — 
+
+---
+
+_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._

package/dist/web/agent-manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 1,
   "product": "Connectix",
-  "site": "https://docs.x12i.dev/connectix",
+  "site": "https://docs.connectix.x12i.com",
   "knowledgePackage": "@x12i/connectix-docs",
   "roles": [
     "developers"
@@ -98,5 +98,23 @@
         }
       ]
     }
-  ]
+  ],
+  "indexes": {
+    "indexMd": "INDEX.md",
+    "searchJson": "SEARCH.json"
+  },
+  "concepts": [],
+  "guides": [],
+  "scenarios": [],
+  "decisions": [],
+  "glossary": [],
+  "visuals": [],
+  "diagrams": [],
+  "relationships": [],
+  "tutorials": [],
+  "examples": [],
+  "sampleData": [],
+  "uiClients": [],
+  "apis": [],
+  "packs": []
 }

package/dist/web/agents.html

@@ -8,6 +8,40 @@
 <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">
 <link rel="stylesheet" href="/assets/site.css">
 <link rel="stylesheet" href="/assets/extras.css">
+<script data-docify-guard="docify:serve-guard">
+(function () {
+  if (window.location.protocol !== "file:") return;
+  var cmd = "npm run docs";
+  var dir = "";
+  function render() {
+    var host = document.createElement("div");
+    host.setAttribute("role", "alert");
+    host.setAttribute("style", "position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;justify-content:center;padding:24px;margin:0;background:#0b0e14;color:#e6e9ef;font:16px/1.55 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif");
+    host.innerHTML =
+      '<div style="max-width:44rem">' +
+      '<p style="margin:0 0 8px;font-size:13px;letter-spacing:.08em;text-transform:uppercase;color:#8b95a7">Docify</p>' +
+      '<h1 style="margin:0 0 12px;font-size:28px;line-height:1.2">Serve this site to view it</h1>' +
+      '<p style="margin:0 0 16px;color:#b6bfcf">This page was opened from the file system, so its stylesheets and scripts ' +
+      'cannot load and the layout you see is not the real design. Docify sites are served over HTTP.</p>' +
+      '<pre style="margin:0 0 16px;padding:14px 16px;border-radius:10px;background:#151a23;border:1px solid #232a36;overflow:auto;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;color:#e6e9ef"><code>' +
+      (dir ? "cd " + dir + "\n" : "") + cmd + '</code></pre>' +
+      '<p style="margin:0;color:#8b95a7;font-size:14px">The command builds the bundle, starts the local server, and opens the correct URL.</p>' +
+      "</div>";
+    document.documentElement.style.background = "#0b0e14";
+    if (document.body) {
+      document.body.innerHTML = "";
+      document.body.appendChild(host);
+    } else {
+      document.documentElement.appendChild(host);
+    }
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", render);
+  } else {
+    render();
+  }
+})();
+</script>
 </head>
 <body class="page-agents" style="--accent:#2f6feb;--accent-alt:#1f6e5c" data-page="agents">
 <div class="page-shell">
@@ -37,9 +71,13 @@
     <p class="install-lead">Never add this package to production service dependencies.</p>
     <pre class="install-cmd install-cmd-primary"><code>npm i -D @x12i/connectix-docs</code></pre>
     
+    
+    
+    
     <p class="install-more"><a href="/agents">Agents / SDK details →</a> · <a href="/agent-manifest.json">agent-manifest.json</a></p>
   </div>
 </section>
+
 <section class="section"><div class="note"><div class="note-title">CLI</div><div class="note-body">npx connectix-docs list-use-cases · npx connectix-docs use-case orient-connectix · npx connectix-docs book 00-orient-connectix developers</div></div></section>
 <section class="section prose"><p>The agent manifest (<code>agent-manifest.json</code>) is part of every built bundle and the published knowledge SDK.</p>
 </section>