[codex] add open source contribution docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report a reproducible bug in Context Drift
+title: "[Bug]: "
+labels: bug
+---
+
+## Summary
+
+Describe the bug in one or two sentences.
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+What did you expect to happen?
+
+## Actual Behavior
+
+What happened instead?
+
+## Environment
+
+- OS:
+- Node version:
+- Command:
+- Relevant branch or commit:
+
+## Additional Context
+
+Add logs, screenshots, or other details that help reproduce the issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest a focused improvement for Context Drift
+title: "[Feature]: "
+labels: enhancement
+---
+
+## Summary
+
+Describe the feature or improvement you want.
+
+## Problem Statement
+
+What issue does this solve?
+
+## Proposed Behavior
+
+What should the tool do?
+
+## Scope
+
+Keep the request focused on one problem. If there are follow-up ideas, list them separately.
+
+## Additional Context
+
+Add examples, mockups, or references if useful.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+
+Briefly describe the issue this PR solves.
+
+## Related Issue
+
+Link the issue this PR closes or references.
+
+## What Changed
+
+- 
+
+## Validation
+
+- 
+
+## Notes
+
+- Keep this PR focused on one issue.
+- If other work surfaced during implementation, open a follow-up PR instead of bundling it here.

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Typecheck
+        run: npm run typecheck

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- MIT `LICENSE` file for the project.
+- `SECURITY.md` with a private vulnerability reporting path.
+- `docs/architecture.md` and `docs/checks.md` for repository context.
+- GitHub issue and pull request templates under `.github/`.
+- A GitHub Actions CI workflow for build, test, and typecheck verification.
+- Contributor guidance for keeping pull requests focused and low-noise.
+- A pull request template in `CONTRIBUTING.md`.
+- README contribution steps for local validation and PR preparation.
+
+## [0.1.0] - 2026-06-03
+
+### Added
+
+- Initial CLI foundation for scanning supported source files.
+- Git-based changed-file detection through `check --base`.
+- Naming-style summary reporting for repository files.

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for helping improve Context Drift.
+
+Keep changes focused, reviewable, and easy to verify.
+
+## Principles
+
+- Open one issue per pull request.
+- Avoid noisy PRs that mix unrelated fixes, refactors, or formatting changes.
+- Keep the scope small enough that a reviewer can understand the change quickly.
+- Include validation steps in every PR.
+- Use the repository PR template at [`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md).
+
+## Before You Open a PR
+
+1. Create a branch for the specific issue you are solving.
+2. Make the smallest change that fully addresses that issue.
+3. Run the relevant checks:
+   - `npm run build`
+   - `npm test`
+   - `npm run typecheck`
+4. Confirm the diff contains only the files that belong in the PR.
+5. Open the PR with a clear title and a short explanation of the change.
+
+## Pull Request Template
+
+Use this template when opening a PR:
+
+```md
+## Summary
+Briefly describe the issue and the fix.
+
+## Related Issue
+Link the issue this PR closes or references.
+
+## What Changed
+- List the user-visible or behavior changes.
+- Keep this focused on the single issue the PR solves.
+
+## Validation
+- List the commands or tests you ran.
+- Mention any manual checks if they matter.
+
+## Notes
+- Call out anything a reviewer should know.
+- Mention follow-up work separately instead of bundling it here.
+```
+
+## Good PR Shape
+
+- One problem.
+- One solution.
+- One review path.
+
+If a change starts to expand, split it into a follow-up PR instead of letting the current one become noisy.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Context Drift contributors
+
+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.

README.md

@@ -1,45 +1,141 @@
-# Context Drift
+<h1 align="center">
+  <br>
+  Context Drift
+</h1>
 
-Stop AI-generated code from making your repo weird.
+<h4 align="center">A small CLI for spotting when new code starts to drift from your repository's naming conventions.</h4>
 
-Context Drift is an open-source CLI and GitHub Action that detects when new code does not match your existing codebase conventions.
+<p align="center">
+  <img src="https://img.shields.io/badge/node-20%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node 20+">
+  <img src="https://img.shields.io/badge/typescript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
+  <img src="https://img.shields.io/badge/cli-utility-111827?style=flat-square&logo=windowsterminal&logoColor=white" alt="CLI utility">
+</p>
 
-## Usage
+<p align="center">
+  Context Drift scans supported source files, summarizes their naming styles, and highlights the files that changed relative to git or an explicit file list.
+</p>
+
+<table>
+<tr>
+<td>
+
+**What it checks**
+
+- `**/*.ts`
+- `**/*.tsx`
+- `**/*.js`
+- `**/*.jsx`
+
+**What it ignores**
+
+- `node_modules`
+- `.git`
+- `.next`
+- `dist`
+- `build`
+- `coverage`
+
+</td>
+</tr>
+</table>
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+npx context-drift check --base main
+```
+
+If you already know which files changed, you can pass them directly:
 
 ```bash
-npx context-drift check
+npx context-drift check --changed src/cli.ts,src/scanner.ts
 ```
 
-Example output:
+## Output
+
+The default report is intentionally simple:
 
 ```txt
 Context Drift
 
 Files scanned: 142
 Changed files: 3
 Format: markdown
+
+Naming conventions:
+- PascalCase: 12%
+- kebab-case: 18%
+- camelCase: 41%
+- snake_case: 9%
+- lower-case: 20%
+- upper-case: 0%
 ```
 
-## Local Development
+## CLI
+
+The project exposes one command:
 
 ```bash
-npm install
-npm run build
-npm run check
+context-drift check
 ```
 
-The first milestone scans JavaScript and TypeScript source files:
+Options:
 
-- `**/*.ts`
-- `**/*.tsx`
-- `**/*.js`
-- `**/*.jsx`
+- `--base <branch>`: diff against `base...HEAD` and treat those files as changed.
+- `--changed <files>`: comma-separated, repo-relative paths to mark as changed.
+- `--format <format>`: accepts `markdown` or `json` and is reflected in the report header.
 
-It ignores common generated or vendor folders:
+Examples:
+
+```bash
+npx context-drift check --base origin/main
+npx context-drift check --format json
+npx context-drift check --changed src/index.ts,src/cli.ts
+```
+
+## Development
+
+```bash
+npm run dev
+npm test
+npm run typecheck
+```
+
+## Contributing
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
+
+Typical contribution flow:
+
+1. Create a branch for one issue.
+2. Make the smallest change that solves that issue.
+3. Run the relevant checks:
+   - `npm run build`
+   - `npm test`
+   - `npm run typecheck`
+4. Open a focused PR with a clear summary and validation notes.
+
+## How It Works
+
+1. Resolve changed files from `--changed` or `git diff --name-only <base>...HEAD`.
+2. Scan the repository for supported source files.
+3. Normalize paths and mark files that are part of the changed set.
+4. Classify file names into naming styles such as PascalCase, camelCase, kebab-case, and snake_case.
+5. Print a compact summary that is easy to read in a terminal or CI log.
+
+## Project Layout
+
+- `src/index.ts` bootstraps the CLI.
+- `src/cli.ts` defines commands and output.
+- `src/scanner.ts` finds supported files and normalizes paths.
+- `src/git.ts` reads git diff output.
+- `src/naming.ts` classifies file naming styles.
+- `tests/` contains the Vitest coverage for the scanner, git helpers, and naming logic.
+
+## Requirements
+
+- Node.js `20` or newer
+- Git for `--base` comparisons
 
-- `node_modules`
-- `.git`
-- `.next`
-- `dist`
-- `build`
-- `coverage`