docs/oss sweep (#13)

* chore(ci): align Codecov config with coverage.txt\n\n- Use go test -coverprofile=coverage.txt\n- Upload artifact and Codecov input as coverage.txt\n\nNo Jira ticket; routine CI maintenance change.

* chore(ci): use codecov/codecov-action@v5 with token/slug\n\n- Switch from v4 to v5\n- Pass token via input and set slug\n- Rely on autodiscovery for coverage.txt

* chore(ci): ensure coverage.txt is generated at repo root\n\n- Move flags before packages\n- Add -covermode=atomic and -coverpkg=./...\n- Stabilize single coverage.txt for artifact/Codecov

* docs: OSS-ready docs sweep\n\n- Align Go version to 1.24+ across docs\n- Fix CI/CD examples; add composite action + CLI variants\n- Add docs/CI.md with Codecov v5 guidance\n- Standardize branching to GitHub Flow\n- Replace gosec with govulncheck; remove aspirational links

Author: karolswdev

CONTRIBUTING.md

@@ -96,7 +96,7 @@ for retries := 0; retries < maxRetries; retries++ {
    cd ticketr
    ```
 
-2. **Install Go 1.22 or later:**
+2. **Install Go 1.24 or later:**
    Follow the instructions at https://go.dev/doc/install
 
 3. **Install dependencies:**

README.md

@@ -106,6 +106,7 @@ Format: Use `# TICKET:` headings in Markdown files.
 - Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
 - Webhooks: [docs/WEBHOOKS.md](docs/WEBHOOKS.md)
 - Development: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
+- CI & Coverage: [docs/CI.md](docs/CI.md)
 - CLI Reference: [docs/CLI.md](docs/CLI.md)
 - Examples: [examples/](examples/)
   - Rich custom fields example: [examples/tickets_with_custom_fields.md](examples/tickets_with_custom_fields.md)

docs/CI.md

@@ -0,0 +1,75 @@
+# Continuous Integration and Coverage
+
+This guide shows how to run Ticketr’s CI and report coverage with Codecov.
+
+## GitHub Actions
+
+Minimal workflow that vets, lints, tests with coverage, and uploads to Codecov:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Lint
+        uses: golangci/golangci-lint-action@v4
+        with:
+          version: latest
+          args: --timeout=5m
+
+      - name: Test
+        run: go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.txt ./...
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.txt
+
+      - name: Upload coverage reports to Codecov
+        if: success() || failure()
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: karolswdev/ticketr
+```
+
+Notes:
+- `-covermode=atomic` pairs well with `-race`.
+- `-coverpkg=./...` ensures a single `coverage.txt` at the repo root.
+- Codecov v5 autodiscovers `coverage.txt`; explicit `files:` is optional.
+
+## Local Checks
+
+Run the same steps locally:
+
+```bash
+go vet ./...
+golangci-lint run
+go test -race -covermode=atomic -coverpkg=./... -coverprofile=coverage.txt ./...
+```
+
+Open an HTML coverage report:
+
+```bash
+go tool cover -html=coverage.txt -o coverage.html
+```
+

docs/DEVELOPMENT.md

@@ -6,17 +6,15 @@ This guide provides comprehensive instructions for setting up your development e
 
 ### Required Software
 
-- **Go 1.22 or later**: [Download Go](https://go.dev/dl/)
+- **Go 1.24 or later**: [Download Go](https://go.dev/dl/)
 - **Git**: [Download Git](https://git-scm.com/downloads)
 - **Make** (optional): For simplified command execution
 - **Docker** (optional): For containerized development
 
 ### Recommended Tools
 
-- **VS Code** with Go extension
-- **GoLand** IDE
-- **golangci-lint**: For code quality checks
-- **ko**: For building container images
+- **VS Code** with Go extension or GoLand IDE
+- **golangci-lint**: Code quality checks (matches CI)
 
 ## Setting Up Your Development Environment
 
@@ -117,6 +115,7 @@ go test -timeout 30s ./...
 ```bash
 # Run tests with race detector
 go test -race ./...
+```
 
 ## Local Lint and Security Checks
 
@@ -146,15 +145,12 @@ This repository enforces a Go toolchain via `go.mod`:
 toolchain go1.24.4
 ```
 
-Most tools (including `go` itself and GitHub Actions `setup-go`) will automatically install/use this version when `go-version-file: go.mod` is configured. If you want to override locally for a single shell, you can use:
+Most tools (including `go` itself and GitHub Actions `setup-go`) automatically install/use this version when `go-version-file: go.mod` is configured. If you want to override locally for a single shell, you can use:
 
 ```bash
 GOTOOLCHAIN=go1.24.4
 ```
 
-# Note: This makes tests slower but catches concurrency issues
-```
-
 ### Benchmark Tests
 
 ```bash
@@ -206,15 +202,14 @@ func TestTicketService_ProcessTickets(t *testing.T) {
 
 ### Branch Strategy
 
-We follow a Git Flow-inspired branching model:
+We follow GitHub Flow:
 
 ```
-main           - Production-ready code
-├── develop    - Integration branch for features
-├── feat/*     - Feature branches
-├── fix/*      - Bug fix branches
-├── docs/*     - Documentation updates
-└── refactor/* - Code refactoring
+main        - Production-ready code
+feat/*      - Feature branches
+fix/*       - Bug fix branches
+docs/*      - Documentation updates
+refactor/*  - Code refactoring
 ```
 
 ### Creating a Feature Branch
@@ -280,7 +275,7 @@ git commit -m "refactor(services): Extract validation logic to separate package"
 ### Code Review Process
 
 1. **Create Pull Request**
-   - Target the `develop` branch
+   - Target the `main` branch
    - Fill out the PR template
    - Link related issues
 
@@ -323,8 +318,8 @@ golangci-lint run
 # Run go vet
 go vet ./...
 
-# Check for security issues
-gosec ./...
+# Check for known vulnerabilities
+govulncheck ./...
 ```
 
 ### Editor Configuration
@@ -484,10 +479,10 @@ Our CI pipeline runs on every push and pull request:
 1. **Lint**: Code style and quality checks
 2. **Test**: Unit and integration tests
 3. **Build**: Cross-platform binary compilation
-4. **Coverage**: Code coverage reporting
+4. **Coverage**: Code coverage reporting (Codecov)
 5. **Security**: Vulnerability scanning
 
-### Running CI Locally
+### Running CI Locally (optional)
 
 ```bash
 # Install act (GitHub Actions locally)
@@ -499,7 +494,7 @@ curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
 act push
 
 # Run specific job
-act -j test
+act -j build-test
 ```
 
 ## Release Process

docs/GETTING_STARTED.md

@@ -15,7 +15,7 @@ Welcome to Ticketr! This guide will walk you through setting up and using Ticket
 
 Before you begin, ensure you have:
 
-1. **Go 1.22+** installed (for building from source)
+1. **Go 1.24+** installed (for building from source)
 2. **JIRA Account** with API access enabled
 3. **JIRA API Token** (not your password!)
    - Generate at: https://id.atlassian.com/manage-profile/security/api-tokens
@@ -238,16 +238,40 @@ Use emojis for visual status:
 
 ### CI/CD Integration
 
-Automate ticket creation in GitHub Actions:
+Automate ticket sync in GitHub Actions.
+
+Option A — Install CLI and run:
+```yaml
+jobs:
+  ticketr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Install ticketr
+        run: go install github.com/karolswdev/ticketr/cmd/ticketr@latest
+      - name: Push tickets
+        env:
+          JIRA_URL: ${{ secrets.JIRA_URL }}
+          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
+          JIRA_API_KEY: ${{ secrets.JIRA_API_KEY }}
+          JIRA_PROJECT_KEY: PROJ
+        run: ticketr push stories/backlog.md
+```
+
+Option B — Use the composite action from this repo:
 ```yaml
 - name: Push tickets to JIRA
-  uses: karolswdev/ticketr-action@v1
+  uses: karolswdev/ticketr/.github/actions/ticketr-sync@main # Pin to a tag in production
   with:
-    file: stories/backlog.md
     jira-url: ${{ secrets.JIRA_URL }}
     jira-email: ${{ secrets.JIRA_EMAIL }}
     jira-api-key: ${{ secrets.JIRA_API_KEY }}
     jira-project-key: PROJ
+    command: push
+    file-path: stories/backlog.md
 ```
 
 ### Real-time Sync
@@ -323,11 +347,10 @@ ticketr pull --strategy=remote-wins
 
 ## Getting Help
 
-- 📚 [Full Documentation](https://github.com/karolswdev/ticketr/wiki)
 - 💬 [GitHub Discussions](https://github.com/karolswdev/ticketr/discussions)
 - 🐛 [Report Issues](https://github.com/karolswdev/ticketr/issues)
-- 📧 [Contact Support](mailto:[email protected])
+- 📚 Project docs live in the `docs/` folder of this repo
 
 ---
 
-Happy ticket management! 🎫
+Happy ticket management! 🎫