From f9b3c6acaef0501430daeb2d7eb40d74497f458d Mon Sep 17 00:00:00 2001
From: ReaperOfVeriod <reaperofveriod@gmail.com>
Date: Sun, 25 Oct 2026 03:42:56 +0100
Subject: [PATCH] chore: initialize API repository

---
 .gitea/workflows/ci.yaml | 12 ++++++++++++
 .gitignore               |  6 ++++++
 .prettierignore          |  4 ++++
 .prettierrc.json         |  6 ++++++
 AGENTS.md                | 10 ++++++++++
 CONTRIBUTING.md          |  4 ++++
 README.md                |  6 ++++++
 SECURITY.md              |  4 ++++
 docs/contract-testing.md |  4 ++++
 docs/versioning.md       |  8 ++++++++
 10 files changed, 64 insertions(+)
 create mode 100644 .gitea/workflows/ci.yaml
 create mode 100644 .gitignore
 create mode 100644 .prettierignore
 create mode 100644 .prettierrc.json
 create mode 100644 AGENTS.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 README.md
 create mode 100644 SECURITY.md
 create mode 100644 docs/contract-testing.md
 create mode 100644 docs/versioning.md

diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml
new file mode 100644
index 0000000..8b1553d
--- /dev/null
+++ b/.gitea/workflows/ci.yaml
@@ -0,0 +1,12 @@
+name: API checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: debian-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: test -f README.md && test -f AGENTS.md && test -f docs/versioning.md
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..552f2d6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,6 @@
+node_modules/
+dist/
+build/
+coverage/
+.env
+*.local
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..ee3a689
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,4 @@
+node_modules/
+dist/
+build/
+coverage/
diff --git a/.prettierrc.json b/.prettierrc.json
new file mode 100644
index 0000000..0e992e5
--- /dev/null
+++ b/.prettierrc.json
@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5cb76e1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,10 @@
+# Trixie API Agent Instructions
+
+Read this file and the parent `AGENTS.md`, `PLAN.md`, and `TODO.md` before making changes.
+
+- This repository owns shared contracts only.
+- Prefer additive changes; breaking changes require a new major API version and migration notes.
+- Every contract change requires schema validation, compatibility fixtures, contract tests, and documentation updates.
+- Never include credentials, private endpoints, or real user data.
+- Do not edit the parent `PLAN.md` without explicit user permission.
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..d2852f8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,4 @@
+# Contributing
+
+Run formatting, schema validation, compatibility checks, and contract tests before submission. Explain compatibility impact for every contract change.
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66e0902
--- /dev/null
+++ b/README.md
@@ -0,0 +1,6 @@
+# Trixie API
+
+Shared versioned HTTP and authenticated WebSocket contracts for `trixie-server` and `trixy-linux-client`.
+
+This repository contains schemas, shared enums, error codes, compatibility fixtures, contract tests, and API documentation only.
+
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..05818ac
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,4 @@
+# Security
+
+Report vulnerabilities privately through the hosting instance. Never include credentials, tokens, private URLs, or real user data in issues or fixtures.
+
diff --git a/docs/contract-testing.md b/docs/contract-testing.md
new file mode 100644
index 0000000..a1653da
--- /dev/null
+++ b/docs/contract-testing.md
@@ -0,0 +1,4 @@
+# Contract Testing
+
+Fixtures cover HTTP responses, authenticated WebSocket events, errors, permissions, version negotiation, reconnects, and server-owned state transitions. Fixtures are deterministic, synthetic, and secret-free.
+
diff --git a/docs/versioning.md b/docs/versioning.md
new file mode 100644
index 0000000..1d99f56
--- /dev/null
+++ b/docs/versioning.md
@@ -0,0 +1,8 @@
+# API Versioning
+
+- Use an explicit major API version.
+- Prefer additive fields and events.
+- Clients must tolerate unknown fields and events.
+- Breaking changes require a new major version, fixtures, migration notes, and coordinated releases.
+- Each release records minimum compatible client and server versions.
+