docs: add AGENTS.md and update AI dev setup symlinks (#78)

Centralizes agent instructions in AGENTS.md and retargets symlink guidance in CONTRIBUTING for Claude/Gemini/Copilot. No code changes.

Author: hrntknr

AGENTS.md

@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `main.go`: CLI entry for the proxy.
+- `pkg/mcp-proxy`: Server wiring (routing, TLS, startup/shutdown).
+- `pkg/auth`: OAuth/OIDC/password providers and auth routes (`templates/`).
+- `pkg/backend`: Stdio→HTTP bridge and transparent HTTP/S backends.
+- `pkg/proxy`: Reverse proxy and header injection.
+- `pkg/repository`: Lightweight KVS persistence.
+- `pkg/utils`: Keys, randomness, logging helpers.
+- `docs/`: Docusaurus site for product docs.
+
+## Build, Test, and Development Commands
+
+- Build: `go build -o bin/mcp-auth-proxy .` — compile the binary.
+- Test: `go test ./...` — run unit tests.
+- Coverage: `go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out -o coverage.html`.
+
+## Coding Style & Naming Conventions
+
+- Language: Go 1.22+ modules (`go.mod`).
+- Formatting: `gofmt -s -w .` (CI checks formatting); `go fmt ./...` locally.
+- Packages: lower-case names; exported identifiers use PascalCase; files `*_test.go` for tests.
+- Imports: standard → third-party → local (`github.com/sigbit/mcp-auth-proxy/...`).
+
+## Testing Guidelines
+
+- Framework: Go `testing` package (`*_test.go`).
+- Scope: Test auth providers, proxy behavior, and backend adapters in `pkg/...`.
+- Naming: `TestXxx` with table-driven tests where useful.
+- Run all: `go test ./...`; target a package: `go test ./pkg/proxy -v`.
+
+## Commit & Pull Request Guidelines
+
+- Commits: Conventional Commits (feat, fix, docs, refactor, perf, test, build, ci, chore, revert). Example: `feat: add GitHub OAuth provider support`.
+- PRs: use `.github/pull_request_template.md` as the template; include a clear description, linked issues (`Fixes #123`), reproduction steps, and before/after notes. Include config snippets for new flags or env vars.
+- CI: ensure `gofmt` passes and tests are green.
+
+## Security & Configuration Tips
+
+- Set `EXTERNAL_URL` correctly; accept TLS TOS with `--tls-accept-tos` when auto-TLS is detected.
+- Avoid committing contents of `data/` (runtime-only).

CONTRIBUTING.md

@@ -2,58 +2,18 @@
 
 Thank you for your interest in contributing to MCP Auth Proxy! This document provides guidelines and information for developers.
 
-## Commit Message Guidelines
-
-This project follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps with automated versioning, changelog generation, and makes the commit history more readable.
-
-### Types
-
-- **feat**: A new feature
-- **fix**: A bug fix
-- **docs**: Documentation only changes
-- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
-- **refactor**: A code change that neither fixes a bug nor adds a feature
-- **perf**: A code change that improves performance
-- **test**: Adding missing tests or correcting existing tests
-- **build**: Changes that affect the build system or external dependencies
-- **ci**: Changes to our CI configuration files and scripts
-- **chore**: Other changes that don't modify src or test files
-- **revert**: Reverts a previous commit
-
-### Examples
-
-```
-feat: add GitHub OAuth provider support
-fix: resolve token expiration handling
-docs: update OAuth setup instructions
-refactor: simplify authentication middleware
-ci: add automated release workflow
-```
-
-### Breaking Changes
-
-Breaking changes should be indicated by a `!` after the type/scope:
-
-```
-feat!: change authentication API to support multiple providers
-```
-
-## Pull Request Template
-
-This project uses a pull request template to ensure consistency and completeness. Please follow the guidelines in [./.github/pull_request_template.md](./.github/pull_request_template.md) when creating pull requests.
-
 ## AI Development Environment Setup
 
 You can link this file to your preferred AI development environment for better integration:
 
 ```bash
 # For Claude Code
-ln -s CONTRIBUTING.md CLAUDE.md
+ln -s AGENTS.md CLAUDE.md
 
 # For Gemini
-ln -s CONTRIBUTING.md GEMINI.md
+ln -s AGENTS.md GEMINI.md
 
 # For GitHub Copilot
 mkdir -p .github
-ln -s CONTRIBUTING.md .github/copilot-instructions.md
+ln -s AGENTS.md .github/copilot-instructions.md
 ```