1 files changed, 76 insertions, 0 deletions
diff --git a/ci/README.md b/ci/README.md
new file mode 100644
index 0000000000..f1e2becff2
--- /dev/null
+++ b/ci/README.md
@@ -0,0 +1,76 @@
+# CI Infrastructure — Project Tick
+
+This directory contains CI support files for the Project Tick monorepo.
+
+## Structure
+
+```
+ci/
+├── OWNERS                    # CI code ownership (CODEOWNERS format)
+├── README.md                 # This file
+├── default.nix               # Nix CI entry point (treefmt, codeowners-validator)
+├── pinned.json               # Pinned Nixpkgs revision for reproducibility
+├── update-pinned.sh          # Update pinned.json via npins
+├── supportedBranches.js      # Branch classification for CI decisions
+├── codeowners-validator/     # Builds codeowners-validator from source
+│   ├── default.nix
+│   ├── owners-file-name.patch
+│   └── permissions.patch
+└── github-script/            # GitHub Actions JavaScript helpers
+    ├── run                   # CLI entry point for local testing
+    ├── lint-commits.js       # Commit message linter (Conventional Commits)
+    ├── prepare.js            # PR preparation & validation
+    ├── reviews.js            # GitHub review state management
+    ├── get-pr-commit-details.js  # Extract commit details from PRs
+    ├── withRateLimit.js      # GitHub API rate limit helper
+    ├── package.json          # Node.js dependencies
+    └── shell.nix             # Nix dev environment
+```
+
+## Pinned Nixpkgs
+
+CI uses a pinned Nixpkgs revision from [`pinned.json`](./pinned.json) to ensure
+reproducible builds and formatting. Run [`update-pinned.sh`](./update-pinned.sh)
+to update it.
+
+## GitHub Script
+
+JavaScript-based CI scripts using [`actions/github-script`](https://github.com/actions/github-script).
+
+### Local Testing
+
+```bash
+cd ci/github-script
+nix-shell     # or: nix develop
+gh auth login # ensure GitHub CLI is authenticated
+./run lint-commits <owner> <repo> <pr-number>
+./run prepare <owner> <repo> <pr-number>
+```
+
+## Branch Classification
+
+`ci/supportedBranches.js` classifies repository branches for CI decisions:
+
+| Prefix       | Type                     | Description                         |
+|--------------|--------------------------|-------------------------------------|
+| `master`     | development / primary    | Main development branch             |
+| `release-*`  | development / primary    | Release branches (e.g. release-1.0) |
+| `staging-*`  | development / secondary  | Pre-release staging                 |
+| `feature-*`  | wip                      | Feature branches                    |
+| `fix-*`      | wip                      | Bug fix branches                    |
+| `backport-*` | wip                      | Backport branches                   |
+
+## Commit Conventions
+
+Project Tick uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): subject
+
+feat(mnv): add new keybinding support
+fix(meshmc): resolve crash on startup
+ci(neozip): update build matrix
+docs(cmark): fix API reference
+```
+
+The commit linter (`ci/github-script/lint-commits.js`) validates this format in PRs.