# ADR-0048: OSHUN Studio SDK and Documentation Integration

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN BFF
Engineering, OSHUN Developer Experience, OSHUN Security Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design, Compliance

## Context and Problem Statement

Studio now exposes a growing set of governance and execution capabilities across
Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian. Teams need a single
integration surface where:

- API contracts are discoverable and versioned.
- SDKs are generated and distributed with consistent behavior.
- Documentation and runnable examples stay synchronized with contracts.
- Policy, audit, and release controls remain enforceable.

Without a canonical SDK/documentation integration model, Studio risks:

- divergent SDK quality and language support across domains
- stale or conflicting documentation relative to runtime contracts
- increased integration failures from contract/SDK version drift
- weaker governance traceability for sensitive integration changes

## Decision Drivers

- **Contract integrity**: one authoritative contract source for docs and SDKs.
- **Developer ergonomics**: consistent onboarding and usage across domains.
- **Governance**: explicit policy and audit controls for integration artifacts.
- **Reliability**: deterministic SDK/doc publishing and rollback behavior.
- **Scale**: support for multi-domain, multi-language integration growth.

## Considered Options

### Option 1: Domain-Local SDK and Docs Pipelines

Each domain owns independent spec, SDK, docs generation, and publication.

**Pros**:

- High local autonomy and rapid domain-specific iteration.

**Cons**:

- Inconsistent SDK quality and documentation format.
- Cross-domain integrations become difficult to reason about and govern.

### Option 2: Documentation-Only Portal With Manual SDK Guidance

Publish unified docs but keep SDK generation/manual examples outside Studio.

**Pros**:

- Lower implementation effort in the short term.

**Cons**:

- SDK drift and hand-maintained examples create reliability issues.
- Weak enforceability for version compatibility and governance controls.

### Option 3: Canonical Studio SDK + Documentation Integration Framework (Chosen)

Adopt one integration framework where typed contracts drive SDK generation,
documentation assembly, sample validation, and governance evidence.

**Pros**:

- Deterministic docs/SDK alignment with clear version semantics.
- Better onboarding, reliability, and cross-domain integration consistency.
- Stronger policy/audit controls for integration lifecycle changes.

**Cons**:

- Requires central governance and release orchestration discipline.

## Decision Outcome

**Chosen option**: Option 3.

Studio SDK/documentation integration requirements:

1. **Contract-first lifecycle** for OpenAPI/typed schemas and compatibility
   policies.
2. **Generated SDK surfaces** with standardized auth, errors, retries, and
   telemetry hooks.
3. **Integrated documentation portal** with synchronized API reference, guides,
   and code samples.
4. **Governed release workflow** with policy checks, audit evidence, and
   rollback readiness.
5. **Cross-domain coverage** for Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Normative Rules

### Contract Source of Truth Rule

- Contract artifacts (OpenAPI/schemas) are authoritative for SDK/doc generation.
- Breaking changes require explicit version migration strategy and approvals.
- Generated docs and SDKs must reference the same contract digest/version.

### SDK Generation and Runtime Behavior Rule

- SDKs must expose consistent auth, request/response typing, error envelopes,
  retry/idempotency semantics, and correlation metadata.
- SDK lifecycle must include deterministic publish/rollback channels.
- Generated SDK metadata must include source contract version and generated-at
  timestamp.

### Documentation Assembly Rule

- API reference, guides, code samples, and policy notes must be published from
  the same release context as SDK artifacts.
- Example snippets must be contract-validated and runnable in CI validation
  suites.
- Deprecated endpoints/contracts must include migration guidance and timelines.

### Governance and Security Rule

- Sensitive integration changes require role/tier/approval controls.
- SDK/doc publication and policy decisions must emit audit events.
- Production releases must preserve traceability across actor, artifact, and
  contract version.

### Observability and Reliability Rule

- Integration workflow telemetry must include generation, validation, publish,
  and rollback outcomes.
- SLOs must cover generation success rate, publication latency, and doc/sdk
  consistency health.
- Degraded observability states must block production promotion until resolved.

## Architecture Implications

- Studio adds first-class SDK/documentation integration workspace surfaces.
- BFF contract artifacts become primary inputs for SDK/doc pipelines.
- Domain teams align integration artifacts to centralized contract governance.
- Documentation publishing and SDK distribution workflows require shared policy
  and telemetry hooks.

## Acceptance Criteria (OST-00281)

`OST-00281` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0054-oshun-studio-sdk-and-documentation-integration.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines contract-source, SDK generation, documentation assembly,
   governance/security, and observability/reliability rules.
4. ADR aligns with `ADR-0007` through `ADR-0047`, especially `ADR-0007`,
   `ADR-0012`, `ADR-0046`, and `ADR-0047`.
5. ADR aligns with existing contract and SDK/documentation implementation
   surfaces.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Unified developer experience for Studio integrations.
- Higher confidence in SDK/doc consistency and contract safety.
- Stronger operational governance for integration lifecycle changes.

### Negative

- Additional operational overhead for centralized release governance.
- Requires coordinated contract/version discipline across all domain teams.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0052-oshun-studio-api-gateway-and-bff-composition.md`
- `docs/adr/ADR-0053-oshun-studio-webhooks-and-external-automation.md`

## References

- `apps/oshun/bff/openapi/oshun-bff.openapi.yaml`
- `apps/oshun/bff/README.md`
- `apps/iris/api/src/docs/index.ts`
- `apps/isis/cli/src/commands/generate.ts`
- `apps/lilith/svc-ai/src/integration-api/index.ts`
- `libs/nyx/client-python/README.md`
- `docs/releases/v1/runbooks/on-call-runbook.md`