From 183d8a649fef92f028c21da3d726fe8198d08916 Mon Sep 17 00:00:00 2001 From: Dr Shaun Conway Date: Sun, 26 Apr 2026 11:21:34 +0800 Subject: [PATCH] docs: consolidate SDK entrypoint and enforce canonical links Reduce duplicated SDK guide content by making the developer SDK page a workflow entrypoint and normalize internal links to canonical SDK reference routes instead of legacy paths. --- .codex/REDIRECTS_AND_DEPRECATIONS.md | 14 +- guides/dev/ixo-domains.mdx | 4 +- guides/dev/ixo-stack-sdks.mdx | 202 +++++---------------- guides/dev/overview.mdx | 2 +- guides/dev/workflows.mdx | 4 +- platforms/Emerging/domain-registration.mdx | 2 +- platforms/Emerging/energy-systems.mdx | 4 +- platforms/Emerging/intro-emerging.mdx | 2 +- reference/product-and-sdk-map.mdx | 2 +- 9 files changed, 68 insertions(+), 168 deletions(-) diff --git a/.codex/REDIRECTS_AND_DEPRECATIONS.md b/.codex/REDIRECTS_AND_DEPRECATIONS.md index 1016251..100f448 100644 --- a/.codex/REDIRECTS_AND_DEPRECATIONS.md +++ b/.codex/REDIRECTS_AND_DEPRECATIONS.md @@ -4,6 +4,10 @@ Use this file whenever a docs route, page label, or public surface name changes. ## General rules +### Canonical links first +Always update docs content to link directly to the canonical destination route. +Treat redirects and stubs as compatibility layers for legacy/external traffic, not as an internal linking strategy. + ### Prefer stable routes If a misleading page can be corrected by: - changing the H1, @@ -22,7 +26,7 @@ Change a route only if the current route is: ## When a route changes 1. Add an entry to the ledger below. -2. Update all internal links. +2. Update all internal links to the new canonical route. 3. Update `docs.json`. 4. Add a redirect or a short deprecation stub if the platform supports it. 5. Mention the route change in the task summary. @@ -50,19 +54,19 @@ Example: | Status | Old route | New route | Reason | Notes | |---|---|---|---|---| -| changed | `/sdk-reference/oracle-ai-sdk` | `/sdk-reference/oracle-adk` | ADK slug for Personal Agent ADK (`@ixo/assistant-sdk`) | Redirect configured in `docs.json` | +| changed | `/sdk-reference/oracle-ai-sdk` | `/sdk-reference/oracle-adk` | ADK slug for Personal Agent ADK (`@ixo/assistant-sdk`) | Internal links use canonical route; compatibility redirect retained in `docs.json` | | accepted (stable route) | `/mcp/model-context-protocol` | keep existing route | H1 and body fixes are sufficient without slug migration | Prefer stable route first | | changed | `/articles/ixo-protocol` | `/protocols/ixo-protocol` | Protocol concept docs consolidated under canonical `protocols/` directory | Internal links and nav updated | | changed | `/articles/ixo-blockchain` | `/protocols/ixo-protocol` | Duplicate IXO Protocol concept page removed in favor of one canonical protocol page | Internal links and nav updated | | deprecated (stub) | `/api-docs/*` | canonical `api-reference/*` routes | Legacy API docs tree replaced with transitional stubs | Stubs point to closest canonical API or guide route by topic | -| changed | `/spatial-web-stack/*` | `/ixo-stack/*` | Canonical stack route namespace normalized to IXO naming | Directory renamed, internal links updated, and explicit redirects added in `docs.json` | -| changed | `/ixo-stack/sdks/oracle-agent-sdk`, `/spatial-web-stack/sdks/oracle-agent-sdk` | `/sdk-reference/oracles-client-sdk` | Old route represented the client-facing oracle interface, now mapped to the canonical Oracles Client SDK page | Redirects updated in `docs.json`; ADK remains canonical at `/sdk-reference/agentic-oracles-adk` for service-side scaffolding/deployment | +| changed | `/spatial-web-stack/*` | `/ixo-stack/*` | Canonical stack route namespace normalized to IXO naming | Directory renamed, internal links updated to canonical routes, compatibility redirects retained in `docs.json` | +| changed | `/ixo-stack/sdks/oracle-agent-sdk`, `/spatial-web-stack/sdks/oracle-agent-sdk` | `/sdk-reference/oracles-client-sdk` | Old route represented the client-facing oracle interface, now mapped to the canonical Oracles Client SDK page | Internal links use canonical route; ADK remains canonical at `/sdk-reference/agentic-oracles-adk` for service-side scaffolding/deployment | | changed | `/ixo-stack/sdks/ixo-matrix-sdk`, `/spatial-web-stack/sdks/ixo-matrix-sdk` | `/sdk-reference/matrix-client-sdk` | Legacy SDK stub replaced with direct redirect to Matrix Client SDK reference | Internal MDX links updated | | changed | `/ixo-stack/sdks/intro-sdks`, `/spatial-web-stack/sdks/intro-sdks` | `/sdk-reference/index` | Legacy IXO Stack SDK intro stub replaced with direct redirect to SDK reference index | Internal MDX links updated | | changed | `/ixo-stack/sdks/signx-sdk`, `/spatial-web-stack/sdks/signx-sdk` | `/sdk-reference/signx-sdk` | Legacy stub redirected to SignX SDK reference | Stubs retained as pointers | | changed | `/ixo-stack/sdks/jambo-wallet-sdk`, `/spatial-web-stack/sdks/jambo-wallet-sdk` | `/sdk-reference/jambo-wallet-sdk` | Legacy stub redirected to JAMBO PWA SDK reference | Stubs retained as pointers | | changed | `/ixo-stack/sdks/ixo-multiclient-sdk`, `/spatial-web-stack/sdks/ixo-multiclient-sdk` | `/sdk-reference/multiclient-sdk` | Legacy stub redirected to MultiClient SDK reference | Stubs retained as pointers | -| changed | `/guides/dev/spatial-web-sdks` | `/guides/dev/ixo-stack-sdks` | Developer SDK hub slug aligned to IXO Stack naming | Redirect configured in `docs.json`; file renamed to `guides/dev/ixo-stack-sdks.mdx` | +| changed | `/guides/dev/spatial-web-sdks` | `/guides/dev/ixo-stack-sdks` | Developer SDK hub slug aligned to IXO Stack naming | Internal links use canonical route; compatibility redirect retained in `docs.json` | | added | n/a | `/reference/networks-and-endpoints` | Establish canonical home for endpoint and network literals | New reference route | | added | n/a | `/reference/authentication-matrix` | Establish canonical home for auth headers and surface-level auth ownership | New reference route | | added | n/a | `/reference/product-and-sdk-map` | Establish canonical home for product-to-SDK naming and route mapping | New reference route | diff --git a/guides/dev/ixo-domains.mdx b/guides/dev/ixo-domains.mdx index 915d2ae..f2de76d 100644 --- a/guides/dev/ixo-domains.mdx +++ b/guides/dev/ixo-domains.mdx @@ -304,8 +304,8 @@ description: 'Create and manage digital domains for entities on the IXO Stack' Entity module API documentation - - Client SDK implementation guide + + Canonical SDK guide and routing map diff --git a/guides/dev/ixo-stack-sdks.mdx b/guides/dev/ixo-stack-sdks.mdx index 8bfbdf8..8859343 100644 --- a/guides/dev/ixo-stack-sdks.mdx +++ b/guides/dev/ixo-stack-sdks.mdx @@ -1,167 +1,63 @@ --- title: 'IXO Stack SDKs' icon: 'code' -description: 'Build advanced applications on the IXO Stack using the comprehensive suite of IXO development tools' +description: 'Developer entry point to SDK workflows, with the canonical SDK and kit overview in the SDK reference' --- - -The IXO Stack SDKs help you integrate the IXO Protocol, IXO Matrix, and related services from TypeScript. Deployable **gateway tools** extend IXO to offline and mobile channels (including USSD). - + +The canonical SDK and kit overview is now maintained at [IXO and Qi Developer Kits](/sdk-reference/index). +Use this page as a developer workflow entry point. + -## Available SDKs +## Start here - - - Connect with IXO and Cosmos networks for interchain operations - - - - Build secure data rooms and encrypted communication channels - - - - Build oracle and agent services with `@ixo/oracle-agent-sdk` - - - - Integrate conversational AI with `@ixo/assistant-sdk` - - - - Manage digital assets and credentials in JAMBO PWA experiences - - - - Enable secure mobile-to-web authentication and transaction signing - - + + Choose the right SDK or kit, including Oracles Client SDK, Agentic Oracles ADK, and JAMBO PWA SDK. + + + Follow end-to-end implementation patterns for entities, claims, evaluation, and integrations. + + + Understand DID, claim, and credential relationships used across SDK workflows. + + + Review service and infrastructure APIs used by SDK-based implementations. + -## Gateway tools - -Fork or deploy these tools to extend IXO services to additional channels and environments. - - - - - Give any GSM mobile phone access to IXO services — no smartphone or data plan required - - +## SDK quick links + + + + Interchain protocol interactions and entity workflows. + + + Encrypted rooms, messaging, and shared state integrations. + + + Frontend agent-client interfaces for deployed oracles. + + + Scaffold, implement, and deploy oracle services. + + + Personal conversational assistant integrations. + + + JAMBO PWA integrations with wallet-enabled workflows. + + + User authentication and transaction signing flows. + + + Extend IXO services to offline and feature-phone channels. + -## Installation - -```bash -# Install core SDKs -npm install @ixo/impactxclient-sdk @ixo/matrixclient-sdk -npm install @ixo/assistant-sdk @ixo/jambo-wallet-sdk -``` - -## Basic Setup - - - -```typescript IXO MultiClient SDK -import { createClient } from "@ixo/impactxclient-sdk"; - -// Initialize client -const chain = await createClient({ - rpcEndpoint: RPC_ENDPOINT, - chainId: "ixo-5" -}); - -// Create digital twin -const twin = await chain.entity.create({ - type: "DigitalTwin", - controller: "did:ixo:org/123" -}); -``` - -```typescript IXO Matrix Client SDK -import { createMatrixClient } from "@ixo/matrixclient-sdk"; - -// Initialize Matrix client -const matrix = await createMatrixClient({ - baseUrl: MATRIX_ENDPOINT, - accessToken: USER_TOKEN -}); - -// Create secure data room -const room = await matrix.createRoom({ - name: "Secure Data Room", - encryption: true, - visibility: "private" -}); -``` - -```typescript Assistant -import { createAssistant } from "@ixo/assistant-sdk"; - -// Initialize assistant -const assistant = await createAssistant({ - type: "VerificationAgent", - capabilities: ["verification", "analytics"] -}); - -// Process verification request -const result = await assistant.verify({ - data: inputData, - context: verificationContext -}); -``` - -```typescript JAMBO PWA -import { createWallet } from "@ixo/jambo-wallet-sdk"; - -// Initialize wallet -const wallet = await createWallet({ - storageType: "secure", - network: "mainnet" -}); - -// Manage credentials -const credential = await wallet.createCredential({ - type: "VerifiableCredential", - issuer: "did:ixo:issuer/123" -}); -``` - - - -## End-to-end workflows - -For runnable patterns (client setup, entities, claims, evaluation) aligned with [Implementation examples](/guides/dev/examples), read [Developer workflows](/guides/dev/workflows). For DID, claim, and VC relationships, read [Identity and credentials](/guides/dev/identity-and-credentials). - -## Key Features - -### MultiClient SDK -- Interchain transactions and queries -- Digital twin management -- Entity state management -- Blockchain service management - -### Matrix Client SDK -- End-to-end encrypted data rooms -- Secure messaging and file storage -- Access control management -- Real-time data streaming - -### Personal Agent ADK -- AI-powered agent services -- Analytics processing -- Evidence collection -- Proof generation - -### JAMBO PWA SDK -- Credential management -- Digital asset operations -- Secure key storage -- Transaction signing - ## Next steps -- [Developer workflows](/guides/dev/workflows) — SDK patterns for domains, claims, and verification -- [SDK reference](/sdk-reference) — full reference for each SDK -- [API reference](/api-reference) — IXO service APIs -- [Developer overview](/guides/dev/overview) — entry points and task-oriented guides +- [IXO and Qi Developer Kits](/sdk-reference/index) — canonical SDK and kit overview +- [Developer workflows](/guides/dev/workflows) — implementation patterns for domains, claims, and verification +- [API reference](/api-reference/index) — IXO service APIs +- [Developer overview](/guides/dev/overview) — task-oriented entry points diff --git a/guides/dev/overview.mdx b/guides/dev/overview.mdx index f8b235d..b78cb1e 100644 --- a/guides/dev/overview.mdx +++ b/guides/dev/overview.mdx @@ -13,7 +13,7 @@ description: 'Build AI-operable workflows on IXO: SDKs, APIs, and paths from sha ## Choose your starting point - + Browse TypeScript SDKs and deployable gateway tools, including the IXO MultiClient SDK, IXO Matrix Client SDK, and IXO USSD gateway diff --git a/guides/dev/workflows.mdx b/guides/dev/workflows.mdx index 76d802d..282756b 100644 --- a/guides/dev/workflows.mdx +++ b/guides/dev/workflows.mdx @@ -130,8 +130,8 @@ For HTTP-oriented credential flows on Emerging, use the platform API docs ([Emer ## Next steps - - All SDK entry points and gateway tools + + Canonical SDK and kit overview with route selection guidance Module-level features on-chain diff --git a/platforms/Emerging/domain-registration.mdx b/platforms/Emerging/domain-registration.mdx index 7188c2b..ed03e1e 100644 --- a/platforms/Emerging/domain-registration.mdx +++ b/platforms/Emerging/domain-registration.mdx @@ -210,7 +210,7 @@ query DomainStatus($did: String!) { Domain registration endpoints - + Client libraries and tools diff --git a/platforms/Emerging/energy-systems.mdx b/platforms/Emerging/energy-systems.mdx index 71e7614..7b9cbf8 100644 --- a/platforms/Emerging/energy-systems.mdx +++ b/platforms/Emerging/energy-systems.mdx @@ -131,7 +131,7 @@ graph TD ### CDT System Integrations - + Device data streaming and control @@ -159,7 +159,7 @@ graph TD Complete API reference - + Development tools and libraries diff --git a/platforms/Emerging/intro-emerging.mdx b/platforms/Emerging/intro-emerging.mdx index b114280..22d458e 100644 --- a/platforms/Emerging/intro-emerging.mdx +++ b/platforms/Emerging/intro-emerging.mdx @@ -96,7 +96,7 @@ The **Emerging Platform** is the reusable IXO platform layer for digital identit ### Device Integration - + Libraries for device connectivity and data streaming diff --git a/reference/product-and-sdk-map.mdx b/reference/product-and-sdk-map.mdx index 62c20d2..54203f8 100644 --- a/reference/product-and-sdk-map.mdx +++ b/reference/product-and-sdk-map.mdx @@ -37,7 +37,7 @@ Use this page as the canonical naming and routing map for product and SDK surfac - **Package identifier:** `@ixo/assistant-sdk` - **Primary docs route:** [oracle-adk](/sdk-reference/oracle-adk) - - **Notes:** Public docs name for `@ixo/assistant-sdk`; `/sdk-reference/oracle-ai-sdk` redirects here. + - **Notes:** Public docs name for `@ixo/assistant-sdk`; use this canonical route in all docs links.