diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..5ef197b
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,md}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..39d201f
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,27 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: build (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Show toolchain
+        run: |
+          xcodebuild -version || true
+          swift --version    || true
+      - name: Build
+        run: make build
+      - name: Test
+        run: make test
+      - name: Lint
+        run: make lint
diff --git a/.gitignore b/.gitignore
index ceab022..f4ca831 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,54 @@
-.build/
-.swiftpm/
-Package.resolved
-*.xcodeproj/xcuserdata/
-*.xcworkspace/xcuserdata/
-DerivedData/
+# macOS
 .DS_Store
+.AppleDouble
+.LSOverride
+Icon?
+
+# Xcode
+build/
+DerivedData/
+*.xcworkspace/xcuserdata/
+*.xcodeproj/xcuserdata/
+*.xcodeproj/project.xcworkspace/xcuserdata/
+*.xcuserstate
+*.moved-aside
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+
+# SwiftPM
+.build/
+.swiftpm/xcode/
+.swiftpm/configuration/
+Package.resolved
+
+# CocoaPods / Carthage
+Pods/
+Carthage/Build/
+
+# fastlane
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output/
+
+# Coverage
+*.gcno
+*.gcda
+*.profdata
+*.profraw
+coverage/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# Local
+*.local
+secrets.env
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e9c563..0e28f92 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,16 @@
 # Changelog
 
-## 0.1.0 — initial scaffold (Phase 2)
-- Umbrella package with 11 library products re-exporting CxLLM-* siblings.
+All notable changes to this project will be documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Repository scaffolding: README, LICENSE (MIT), .gitignore, Makefile,
+  CONTRIBUTING, SECURITY, CODEOWNERS, .editorconfig, CI workflow.
+
+## [0.1.0] - 2026-05-17
+
+### Added
+- Initial sdk scaffold for CxLLM-SDK.
diff --git a/CODEOWNERS b/CODEOWNERS
new file mode 100644
index 0000000..7e6dfca
--- /dev/null
+++ b/CODEOWNERS
@@ -0,0 +1,6 @@
+# Default owners for everything in this repo.
+* @CxAI-LLM/maintainers
+
+# Build & CI
+/.github/      @CxAI-LLM/devops
+/Makefile      @CxAI-LLM/devops
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a104387
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,23 @@
+# Contributing to CxLLM-SDK
+
+Thanks for taking the time to contribute!
+
+## Workflow
+
+1. Open an issue describing the change before sending a PR for non-trivial work.
+2. Fork / branch off `main`. Use a descriptive branch name (`feat/...`, `fix/...`).
+3. Keep commits scoped and use **Conventional Commits** (`feat:`, `fix:`,
+   `docs:`, `refactor:`, `test:`, `chore:`).
+4. Run `make lint` and `make test` before pushing.
+5. Open a PR — CI must pass before review.
+
+## Coding style
+
+- Swift: `swiftformat` defaults + `swiftlint` rules from the umbrella repo.
+- Objective-C / C / C++: clang-format `-style=Google`.
+- No tabs in Swift; 4-space indent in C/C++.
+
+## Code of conduct
+
+By contributing you agree to abide by the project's Code of Conduct
+(see the umbrella `cxllm-code` repo).
diff --git a/LICENSE b/LICENSE
index 5ffe88a..114f83a 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1 +1,21 @@
-Proprietary — (c) CxAI Project. All rights reserved.
+MIT License
+
+Copyright (c) 2026 CxAI-LLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..211b3e5
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,43 @@
+# Makefile — common entry points for CxLLM-SDK
+SHELL := /bin/bash
+.DEFAULT_GOAL := help
+
+PROJECT := CxLLM-SDK
+SCHEME  ?= $(PROJECT)
+CONFIG  ?= Debug
+DERIVED ?= build
+
+.PHONY: help build test lint clean fmt info
+
+help: ## show this help
+	@grep -E '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | awk -F':.*## ' '{printf "  %-12s %s\n", $$1, $$2}'
+
+info: ## show project info
+	@echo "project : $(PROJECT)"
+	@echo "scheme  : $(SCHEME)"
+	@echo "config  : $(CONFIG)"
+	@echo "derived : $(DERIVED)"
+
+build: ## xcodebuild build (skip if no .xcodeproj)
+	@if ls *.xcodeproj 1>/dev/null 2>&1; then \
+	  xcodebuild -project "$(PROJECT).xcodeproj" -scheme "$(SCHEME)" -configuration "$(CONFIG)" -derivedDataPath "$(DERIVED)" build | xcbeautify || true ; \
+	elif [ -f Package.swift ]; then \
+	  swift build -c $(shell echo "$(CONFIG)" | tr '[:upper:]' '[:lower:]') ; \
+	else echo "no buildable target" ; fi
+
+test: ## xcodebuild test
+	@if ls *.xcodeproj 1>/dev/null 2>&1; then \
+	  xcodebuild -project "$(PROJECT).xcodeproj" -scheme "$(SCHEME)" -configuration "$(CONFIG)" -derivedDataPath "$(DERIVED)" test | xcbeautify || true ; \
+	elif [ -f Package.swift ]; then \
+	  swift test ; \
+	else echo "no testable target" ; fi
+
+lint: ## swiftlint + swiftformat (no-op if missing)
+	@command -v swiftlint   >/dev/null && swiftlint   --quiet || echo "swiftlint not installed"
+	@command -v swiftformat >/dev/null && swiftformat --lint . || echo "swiftformat not installed"
+
+fmt: ## swiftformat in-place
+	@command -v swiftformat >/dev/null && swiftformat . || echo "swiftformat not installed"
+
+clean: ## remove build artifacts
+	rm -rf "$(DERIVED)" .build DerivedData
diff --git a/README.md b/README.md
index 68d494f..319b632 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,53 @@
 # CxLLM-SDK
 
-Umbrella Swift Package for the CxLLM ecosystem. Downstream apps depend on
-this single URL and import any combination of `CxCode`, `CxAWS`, `CxGit`,
-`CxAgent`, `CxMCP`, `CxModels`, `CxChat`, `CxARA`, `CxSPARenderer`,
-`CxLangBridge`, `CxInstrument`.
+> CxLLM-SDK — sdk module
 
-```swift
-.package(url: "https://cxai-studio.com/git/CxAI-Project/CxLLM-SDK.git", branch: "main")
+`CxLLM-SDK` is part of the CxLLM family. This repository hosts the sdk surface and is intentionally narrow so it can compose with sibling modules without dragging in unrelated dependencies.
+
+[![ci](https://cxai-studio.com/git/CxAI-Projects/CxLLM-SDK/actions/workflows/ci.yml/badge.svg)](https://cxai-studio.com/git/CxAI-Projects/CxLLM-SDK/actions)
+[![license](https://img.shields.io/badge/license-MIT-7C3AED)](LICENSE)
+[![category](https://img.shields.io/badge/category-sdk-1F6FEB)](#)
+
+## Overview
+
+`CxLLM-SDK` is part of the **CxLLM** product family — a layered runtime that
+spans Apple kernel extensions, user-space frameworks, host applications, and
+spatial / web surfaces. This module focuses on **sdk** concerns and is
+intentionally narrow so that the CxLLM monorepo can compose targets without
+pulling in unrelated dependencies.
+
+## Repository layout
+
+- `CxLLM-SDK/` — primary source folder (matches the Xcode group / SwiftPM root).
+- `CxLLM-SDK.xcodeproj` — Xcode project (where applicable).
+- `Makefile` — common entry points (`build`, `test`, `lint`, `clean`).
+- `.github/workflows/ci.yml` — CI pipeline (Xcode build + lint).
+- `docs/` — architecture notes and ADRs.
+
+## Quick start
+
+```bash
+# Build (defaults to Debug for the host platform):
+make build
+
+# Run the full test suite (unit + UI where applicable):
+make test
+
+# Static analysis + format check:
+make lint
 ```
 
-Each umbrella product is a thin re-export shim of one or more upstream
-sibling packages (`CxLLM-Kernel`, `CxLLM-LIB`, `CxLLM-PLG`, `CxLLM-Drive`,
-`CxLLM-ARA`, `CxLLM-SPA-RNDR`, `CxLLM-LB-SDK`, `CxLLM-INSTRUMENT-PCKG`).
-This decouples the downstream import surface from the upstream package layout.
+## Versioning
 
-Phase 0 status: seed implementations in upstream packages; real APIs land in
-Phase 3.
+This module follows [Semantic Versioning 2.0](https://semver.org/) and is
+released in lock-step with the umbrella **CxLLM** product line. See
+[`CHANGELOG.md`](CHANGELOG.md) for the user-facing change log.
+
+## Security
+
+Please report security issues per [`SECURITY.md`](SECURITY.md). Do **not**
+open public issues for vulnerabilities.
+
+## License
+
+Released under the [MIT License](LICENSE) © 2026 CxAI-LLM.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..f99ff1f
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,19 @@
+# Security policy for CxLLM-SDK
+
+## Reporting a vulnerability
+
+Please email **security@cxllm-studio.com** with:
+
+- A description of the vulnerability and its impact.
+- Steps to reproduce, ideally with a minimal proof-of-concept.
+- The affected version(s) / commit SHAs.
+
+We aim to acknowledge within **2 business days** and to publish a fix or
+mitigation within **30 days** for high-severity issues.
+
+Do **not** open a public Gitea / GitHub issue for vulnerabilities.
+
+## Supported versions
+
+Only the `main` branch and the most recent tagged release receive security
+updates.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..7cf20f9
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,24 @@
+# Architecture — CxLLM-SDK
+
+> CxLLM-SDK — sdk module
+
+## Goals
+
+- Provide a focused, well-tested sdk surface for the CxLLM family.
+- Stay deployable on its own (no monorepo coupling).
+- Keep the public ABI small and explicitly versioned.
+
+## Boundaries
+
+```text
+              +----------------------+
+   client --> |  CxLLM-SDK  |
+              +----------+-----------+
+                         |
+                         v
+                  CxLLM runtime / kernel
+```
+
+## Decisions
+
+- See `docs/adr/` for Architecture Decision Records.
diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md
new file mode 100644
index 0000000..4fc033a
--- /dev/null
+++ b/docs/adr/0001-record-architecture-decisions.md
@@ -0,0 +1,13 @@
+# 1. Record architecture decisions
+
+## Status
+Accepted
+
+## Context
+We need a lightweight, append-only log of architectural choices.
+
+## Decision
+Use Markdown ADRs in `docs/adr/`, numbered sequentially.
+
+## Consequences
+Future maintainers can read the chain of decisions without spelunking PR history.