Build a trustworthy open source foundation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report a reproducible problem with Nitpick.
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please remove credentials, private logs, and proprietary source code before submitting.
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      placeholder: "0.1.0 or e71b3b7"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.13"
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Include the smallest sanitized configuration or fixture that demonstrates the issue.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/FlyLikeAPenguin/nitpick/security/advisories/new
+    about: Report security issues privately; do not open a public issue.
+  - name: Roadmap and design discussions
+    url: https://github.com/FlyLikeAPenguin/nitpick/discussions
+    about: Discuss ideas and broader design questions with the community.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest an improvement or new provider.
+title: "feature: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What workflow is currently difficult, slow, or unsafe?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed outcome
+      description: Describe the behavior that would make the workflow better.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What changed?
+
+<!-- Describe the change in user-facing terms. -->
+
+## Why?
+
+<!-- Link the issue or explain the problem this solves. -->
+
+## Validation
+
+- [ ] `pytest`
+- [ ] `ruff check .`
+- [ ] Documentation updated where behavior changed
+- [ ] No secrets, production logs, or private source code included
+
+## Risk and operations
+
+<!-- Note any security, privacy, cost, migration, or deployment implications. -->

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install development dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest
+      - name: Run lint checks
+        run: ruff check .

.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 data/
 logs/
 .claude/
+*.egg-info/

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to Nitpick are documented here.
+
+## [Unreleased]
+
+- Add safe-by-default automatic-fix controls.
+- Add tests, CI, contributor guidance, and security reporting guidance.
+- Improve the README with setup, safety, limitations, and development documentation.
+
+## [0.1.0] - 2026-07-18
+
+- Initial public release of the Datadog-to-Claude incident investigation pipeline.
+- Add local dashboard, SQLite deduplication, provider adapters, RCA sinks, issue tracking, notifications, and optional fix PRs.

CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+Nitpick is a small open-source project, and contributors are expected to make participation safe and welcoming.
+
+Examples of expected behavior:
+
+- Be respectful and constructive.
+- Assume good intent while discussing technical trade-offs.
+- Focus feedback on the code, documentation, or proposal—not the person.
+- Respect privacy and never post credentials, private logs, or private source code.
+
+Harassment, discrimination, threats, deliberate disruption, and sharing someone else's private information are not acceptable.
+
+Report unacceptable behavior privately through the repository maintainer's GitHub profile. Security vulnerabilities should follow [SECURITY.md](SECURITY.md) instead.

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Nitpick
+
+Thanks for helping make incident response less repetitive. Small documentation, test, and provider improvements are welcome.
+
+## Before you start
+
+- Search existing issues before opening a new one.
+- For a larger change, open an issue first so the design and scope are clear.
+- Never include credentials, production log payloads, or private source code in an issue or pull request.
+
+## Local development
+
+Nitpick supports Python 3.12 and newer.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The unit tests do not call Datadog, Claude, GitHub, Linear, Notion, or Slack. Keep external calls behind provider boundaries and use deterministic fixtures or mocks in tests.
+
+## Pull requests
+
+Please keep pull requests focused and include:
+
+- the problem and user impact
+- a short explanation of the implementation
+- tests added or updated
+- documentation updates for changed behavior
+- any security, privacy, or cost implications
+
+Generated fixes must remain reviewable pull requests. Do not add behavior that writes to a live checkout or bypasses the existing safety controls.
+
+## Good first contributions
+
+- Add provider contract tests.
+- Improve the dashboard with accessible labels and keyboard support.
+- Add sanitized log fixtures for additional error formats.
+- Improve setup documentation for Linux and macOS scheduling.

README.md

@@ -1,6 +1,37 @@
 # Nitpick
 
-Automated error monitoring and investigation powered by Claude. Fetches errors from your log provider, investigates each with Claude CLI, documents findings, files issues, and optionally opens fix PRs — all on autopilot.
+[![CI](https://github.com/FlyLikeAPenguin/nitpick/actions/workflows/ci.yml/badge.svg)](https://github.com/FlyLikeAPenguin/nitpick/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
+
+Datadog errors → Claude root-cause analysis → GitHub issues and reviewable fix PRs.
+
+Nitpick turns recurring production errors into deduplicated, actionable investigations. It runs locally, keeps costs visible, and never changes a live checkout during investigation.
+
+> Nitpick is alpha software. Review every generated issue and PR before merging. Automatic fixes are disabled by default.
+
+## Why Nitpick
+
+Incident response often starts with the same manual loop: search logs, find the relevant code, write an RCA, file a ticket, and decide whether a fix is safe. Nitpick automates that loop while keeping the evidence, budget, and proposed change visible to the team.
+
+- **Less duplicate work** — fingerprints group recurring errors before they consume investigation budget.
+- **Actionable output** — each investigation can produce an RCA, issue, notification, and optional fix PR.
+- **Local-first** — the dashboard and Markdown RCA sink run locally; provider credentials stay in environment variables.
+- **Reviewable automation** — fixes happen in isolated git worktrees and are delivered as pull requests, never deployed directly.
+
+## Safety model
+
+Nitpick investigates errors with read-only access to configured code paths. Automatic fixes are **off by default**. To enable them, open the dashboard and turn on **Settings → Auto-fix & PR** for the relevant scope. A fix is still limited by a separate Claude budget, an isolated worktree, and a 250-line diff ceiling.
+
+Before using Nitpick with production logs, review the data flow: matching log entries and configured source-code paths are supplied to Claude CLI, while provider APIs receive only the records needed to create the configured RCA, issue, or notification.
+
+## Project status
+
+Nitpick is an actively developed alpha project. The core pipeline, local dashboard, Datadog source, GitHub/Linear trackers, Markdown/Notion sinks, and console/Slack notifiers are implemented. See [issues](https://github.com/FlyLikeAPenguin/nitpick/issues) for current work and limitations.
+
+![Nitpick workflow preview](docs/social-preview.svg)
+
+See the [roadmap](docs/ROADMAP.md) for planned work and the [GitHub issues](https://github.com/FlyLikeAPenguin/nitpick/issues) for implementation-level tasks.
 
 ## How it works
 
@@ -48,12 +79,13 @@ With the defaults, you need only **Datadog + Claude CLI + `gh`** to get full val
 ## Quickstart
 
 ```bash
-git clone <this-repo> && cd nitpick
+git clone https://github.com/FlyLikeAPenguin/nitpick.git && cd nitpick
 python -m venv .venv && source .venv/bin/activate
 pip install -e .
 
 cp .env.example .env
-# Edit .env — fill in your Datadog keys at minimum
+# Edit .env — fill in your Datadog keys at minimum.
+# Start with NITPICK_DRY_RUN=true while validating the setup.
 ```
 
 Edit `config.yml` to add your services:
@@ -88,6 +120,9 @@ NITPICK_DRY_RUN=true python -m src.main run
 
 # Start dashboard
 python -m src.main serve
+
+# Preview the dashboard without Datadog or Claude credentials
+python -m src.main demo
 ```
 
 ## Configuration
@@ -171,7 +206,26 @@ Available at `http://localhost:8111` when running `python -m src.main serve`.
 - **Costs** — Daily cost chart for the last 30 days.
 - **Logs** — Live tail of the pipeline log.
 - **Services** — Add/remove monitored services (edits `config.yml`).
-- **Settings** — Toggle investigations, fixes, and notifications globally or per-service.
+- **Settings** — Toggle investigations, auto-fix PRs, and notifications globally or per-service. Auto-fix PRs start disabled.
+
+## Known limitations
+
+- Datadog is currently the only error-source provider.
+- Claude CLI must be installed and authenticated separately.
+- The dashboard is intentionally bound to `127.0.0.1`; it is not an authenticated multi-user web service.
+- Generated fixes are proposals. Your normal review, CI, and deployment controls still apply.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, issue expectations, and pull-request checklist. Please use [SECURITY.md](SECURITY.md) for vulnerability reports rather than opening a public issue.
 
 ## Scheduling
 
@@ -211,6 +265,7 @@ Create a timer unit for the pipeline and a service unit for the dashboard.
 ├── .env                        # Credentials (not committed)
 ├── src/
 │   ├── main.py                 # CLI + pipeline orchestrator
+│   ├── demo.py                 # Credential-free dashboard demo data
 │   ├── config.py               # Env + YAML config loader
 │   ├── models.py               # Dataclasses
 │   ├── fingerprint.py          # Error normalisation + hashing
@@ -229,6 +284,8 @@ Create a timer unit for the pipeline and a service unit for the dashboard.
 │       └── notifiers/slack.py  # Slack webhook notifier
 ├── static/
 │   └── index.html              # Single-page dashboard UI
+├── tests/                      # Fast unit and integration-boundary tests
+├── .github/                    # CI, issue forms, and PR guidance
 ├── data/
 │   └── error_cache.db          # SQLite database (created on first run)
 └── logs/

SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a security vulnerability. Use [GitHub's private vulnerability reporting](https://github.com/FlyLikeAPenguin/nitpick/security/advisories/new) when available, or contact the maintainer through the GitHub profile.
+
+Include:
+
+- the affected version or commit
+- a description of the issue and its impact
+- reproducible steps or a minimal proof of concept
+- any suggested mitigation
+
+Please redact API keys, tokens, production log contents, and private source code. We will acknowledge reports as soon as practical and coordinate disclosure after a fix or mitigation is available.
+
+## Scope notes
+
+Nitpick handles error logs and can provide configured code paths to Claude CLI. Treat those inputs as sensitive, review provider permissions, and run the dashboard only on trusted local interfaces. The dashboard is bound to `127.0.0.1` by default but is not an authentication boundary.

SUPPORT.md

@@ -0,0 +1,8 @@
+# Getting help
+
+- Check the [README](README.md) and [known limitations](README.md#known-limitations) first.
+- Search [existing issues](https://github.com/FlyLikeAPenguin/nitpick/issues) before opening a new one.
+- Use the bug report form for reproducible defects.
+- Use a feature request or discussion for design questions and ideas.
+
+Never include credentials, private logs, or proprietary source code in public support requests.

config.yml

@@ -26,3 +26,6 @@ repos:
 ignore_patterns:
   - "DeprecationWarning"
   - "health_check"
+
+# Automatic fix branches and PRs are disabled by default.
+# Enable them deliberately from the dashboard after reviewing the safety model.

docs/ROADMAP.md

@@ -0,0 +1,24 @@
+# Roadmap
+
+The roadmap is intentionally short and outcome-focused. Priorities may change as users try Nitpick and report what blocks adoption.
+
+## Now
+
+- Make the safe, reviewable workflow easy to install and understand.
+- Improve test coverage around provider contracts, cache migrations, and error normalization.
+- Document privacy, permissions, cost controls, and operational limitations.
+
+## Next
+
+- Add a fixture-backed demo mode that works without Datadog or Claude credentials.
+- Add more error-source providers behind the existing provider interface.
+- Improve dashboard accessibility and run history details.
+- Add release automation and compatibility checks for supported Python versions.
+
+## Later
+
+- Support richer incident timelines and related-error grouping.
+- Add configurable approval gates before issue creation or fix-PR creation.
+- Evaluate hosted or team-oriented deployment only after the local workflow is stable.
+
+Have a use case that should influence the order? [Open an issue](https://github.com/FlyLikeAPenguin/nitpick/issues/new/choose) with the problem and the desired outcome.