chore: initial commit (Phase 3 scaffold)

.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

.gitea/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: ci
+on:
+  push:
+    branches: [main, master]
+  pull_request: {}
+  workflow_dispatch: {}
+
+# We run a Linux runner; macOS xcodebuild is not available here.
+# This workflow validates structure (yaml, file presence) and basic Swift.
+jobs:
+  validate:
+    runs-on: cxai-hostinger
+    container: debian:bookworm
+    steps:
+      - name: Install deps
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends git ca-certificates curl python3-yaml >/dev/null
+      - uses: actions/checkout@v4
+      - name: Lint workflow YAML
+        run: |
+          python3 - <<'PY'
+          import sys, yaml, glob
+          for f in glob.glob('.gitea/workflows/*.yml') + glob.glob('.github/workflows/*.yml'):
+              try:
+                  yaml.safe_load(open(f))
+              except Exception as e:
+                  print(f'YAML ERROR {f}: {e}'); sys.exit(1)
+          print('workflows ok')
+          PY
+      - name: Project sanity
+        run: |
+          test -f README.md || (echo "missing README" && exit 1)
+          test -f Makefile  || (echo "missing Makefile" && exit 1)
+          ls *.xcodeproj  >/dev/null 2>&1 && echo "xcodeproj: $(ls -d *.xcodeproj)" || true
+          [ -f Package.swift ] && echo "Package.swift present" || true

.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

.gitignore

@@ -0,0 +1,54 @@
+# 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

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+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-04-22
+
+### Added
+- Initial instruments scaffold for CxLLM-INSTRUMENT-PCKG.

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

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing to CxLLM-INSTRUMENT-PCKG
+
+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).

CxLLM-INSTRUMENT-PCKG.xcodeproj/project.pbxproj

@@ -0,0 +1,167 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {
+	};
+	objectVersion = 77;
+	objects = {
+
+/* Begin PBXFileReference section */
+		20F2B1192F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG.instrdst */ = {isa = PBXFileReference; explicitFileType = com.apple.instruments.instrdst; includeInIndex = 0; path = "CxLLM-INSTRUMENT-PCKG.instrdst"; sourceTree = BUILT_PRODUCTS_DIR; };
+/* End PBXFileReference section */
+
+/* Begin PBXFileSystemSynchronizedRootGroup section */
+		20F2B11B2F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = "CxLLM-INSTRUMENT-PCKG";
+			sourceTree = "<group>";
+		};
+/* End PBXFileSystemSynchronizedRootGroup section */
+
+/* Begin PBXGroup section */
+		20F2B1122F99767600E7D2D9 = {
+			isa = PBXGroup;
+			children = (
+				20F2B11B2F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG */,
+				20F2B11A2F99767600E7D2D9 /* Products */,
+			);
+			sourceTree = "<group>";
+		};
+		20F2B11A2F99767600E7D2D9 /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				20F2B1192F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG.instrdst */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+		20F2B1182F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 20F2B11E2F99767600E7D2D9 /* Build configuration list for PBXNativeTarget "CxLLM-INSTRUMENT-PCKG" */;
+			buildPhases = (
+				20F2B1172F99767600E7D2D9 /* Sources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			fileSystemSynchronizedGroups = (
+				20F2B11B2F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG */,
+			);
+			name = "CxLLM-INSTRUMENT-PCKG";
+			packageProductDependencies = (
+			);
+			productName = "CxLLM-INSTRUMENT-PCKG";
+			productReference = 20F2B1192F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG.instrdst */;
+			productType = "com.apple.product-type.instruments-package";
+		};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+		20F2B1132F99767600E7D2D9 /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				BuildIndependentTargetsInParallel = 1;
+				LastUpgradeCheck = 2630;
+				TargetAttributes = {
+					20F2B1182F99767600E7D2D9 = {
+						CreatedOnToolsVersion = 26.3;
+					};
+				};
+			};
+			buildConfigurationList = 20F2B1162F99767600E7D2D9 /* Build configuration list for PBXProject "CxLLM-INSTRUMENT-PCKG" */;
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				en,
+				Base,
+			);
+			mainGroup = 20F2B1122F99767600E7D2D9;
+			minimizedProjectReferenceProxies = 1;
+			preferredProjectObjectVersion = 77;
+			productRefGroup = 20F2B11A2F99767600E7D2D9 /* Products */;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+				20F2B1182F99767600E7D2D9 /* CxLLM-INSTRUMENT-PCKG */,
+			);
+		};
+/* End PBXProject section */
+
+/* Begin PBXSourcesBuildPhase section */
+		20F2B1172F99767600E7D2D9 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin XCBuildConfiguration section */
+		20F2B1142F99767600E7D2D9 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				COPY_PHASE_STRIP = NO;
+			};
+			name = Debug;
+		};
+		20F2B1152F99767600E7D2D9 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				COPY_PHASE_STRIP = YES;
+			};
+			name = Release;
+		};
+		20F2B11F2F99767600E7D2D9 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CODE_SIGN_STYLE = Automatic;
+				DEVELOPMENT_TEAM = DKWVC9FQJY;
+				INSTALL_PATH = "$(LOCAL_LIBRARY_DIR)/Instruments/Packages";
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				VERSIONING_SYSTEM = "";
+			};
+			name = Debug;
+		};
+		20F2B1202F99767600E7D2D9 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CODE_SIGN_STYLE = Automatic;
+				DEVELOPMENT_TEAM = DKWVC9FQJY;
+				INSTALL_PATH = "$(LOCAL_LIBRARY_DIR)/Instruments/Packages";
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				VERSIONING_SYSTEM = "";
+			};
+			name = Release;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		20F2B1162F99767600E7D2D9 /* Build configuration list for PBXProject "CxLLM-INSTRUMENT-PCKG" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				20F2B1142F99767600E7D2D9 /* Debug */,
+				20F2B1152F99767600E7D2D9 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+		20F2B11E2F99767600E7D2D9 /* Build configuration list for PBXNativeTarget "CxLLM-INSTRUMENT-PCKG" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				20F2B11F2F99767600E7D2D9 /* Debug */,
+				20F2B1202F99767600E7D2D9 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+/* End XCConfigurationList section */
+	};
+	rootObject = 20F2B1132F99767600E7D2D9 /* Project object */;
+}

CxLLM-INSTRUMENT-PCKG.xcodeproj/project.xcworkspace/contents.xcworkspacedata

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>

CxLLM-INSTRUMENT-PCKG/CxLLM-INSTRUMENT-PCKG.instrpkg

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<package>
+	<id>cxai-studio.CxLLM-INSTRUMENT-PCKG</id>
+	<title>CxLLM-INSTRUMENT-PCKG</title>
+	<owner>
+		<name>Stephen Carter</name>
+	</owner>
+
+    <!-- Instruments Developer Help: https://help.apple.com/instruments/developer/mac/current/ -->
+
+    <!-- MARK: Schema Definitions -->
+    <!-- Define point and interval schemas needed to represent the input and output tables your package will use. -->
+    <!-- Two kinds are available: schemas with automatically generated modelers, and schemas that require custom modelers -->
+    <!--   Generated modelers: 'os-log-point-schema', 'os-signpost-interval-schema', 'ktrace-point-schema', 'ktrace-interval-schema' -->
+    <!--   Custom modeler required: 'point-schema', 'interval-schema' -->
+    <!-- To use existing schemas from other packages, declare 'import-schema' elements -->
+
+    <!-- MARK: Modeler Declarations -->
+    <!-- If there are schemas defined that require a custom modeler, each can be declared with a 'modeler' element -->
+    <!-- Modelers are based on CLIPS rules and may define 1..n output schemas, each requiring 1..n input schemas -->
+
+    <!-- MARK: Instrument Definitions -->
+    <!-- Instruments record and display data, creating concrete table requirements that instance modelers and data streams. -->
+    <!-- Any number of 'instrument' elements can be defined; each instrument should provide a cohesive graph and detail experience. -->
+
+    <!-- MARK: Embed Templates -->
+    <!-- Templates may be included and represent a collection of tools configured for a specific tracing workflow -->
+    <!-- Each 'template' element specifies the relative path to a .tracetemplate file in the project -->
+    <!-- To create a template: start with a blank document, configure with instruments desired, and choose "File -> Save as Template" -->
+</package>

LICENSE

@@ -0,0 +1,21 @@
+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.

Makefile

@@ -0,0 +1,43 @@
+# Makefile — common entry points for CxLLM-INSTRUMENT-PCKG
+SHELL := /bin/bash
+.DEFAULT_GOAL := help
+
+PROJECT := CxLLM-INSTRUMENT-PCKG
+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

README.md

@@ -0,0 +1,53 @@
+# CxLLM-INSTRUMENT-PCKG
+
+> CxLLM Instruments package
+
+Custom Instruments (.instrpkg) bundle that adds CxLLM kernel + RPC instruments to Xcode's profiling tool.
+
+[![ci](https://git.cxllm-studio.com/CxAI-LLM/CxLLM-INSTRUMENT-PCKG/actions/workflows/ci.yml/badge.svg)](https://git.cxllm-studio.com/CxAI-LLM/CxLLM-INSTRUMENT-PCKG/actions)
+[![license](https://img.shields.io/badge/license-MIT-7C3AED)](LICENSE)
+[![category](https://img.shields.io/badge/category-instruments-1F6FEB)](#)
+
+## Overview
+
+`CxLLM-INSTRUMENT-PCKG` 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 **instruments** concerns and is
+intentionally narrow so that the CxLLM monorepo can compose targets without
+pulling in unrelated dependencies.
+
+## Repository layout
+
+- `CxLLM-INSTRUMENT-PCKG/` — primary source folder (matches the Xcode group / SwiftPM root).
+- `CxLLM-INSTRUMENT-PCKG.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
+```
+
+## Versioning
+
+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.

SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy for CxLLM-INSTRUMENT-PCKG
+
+## 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.

docs/ARCHITECTURE.md

@@ -0,0 +1,24 @@
+# Architecture — CxLLM-INSTRUMENT-PCKG
+
+> CxLLM Instruments package
+
+## Goals
+
+- Provide a focused, well-tested instruments 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-INSTRUMENT-PCKG  |
+              +----------+-----------+
+                         |
+                         v
+                  CxLLM runtime / kernel
+```
+
+## Decisions
+
+- See `docs/adr/` for Architecture Decision Records.

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.