docs: ai policy

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. Mac]
+- Version: what version are you using?
+- Terminal Emulator
+- Using tmux?

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+# Summary
+
+- [] Closes issue #...
+- [] I have read the [CONTIBUTING.md](../CONTRIBUTING.md) and [AI_POLICY.md](../AI_POLICY.md) guides
+
+## How Did You Test this Change?
+
+## Images/Videos
+
+<!-- if relevant, please include any relevant images that show off how your feature is
+working -->

AI_POLICY.md

@@ -0,0 +1,43 @@
+# AI Usage Policy
+
+This project has strict rules for AI usage:
+
+- **All AI usage in any form must be disclosed.** You must state
+  the tool you used (e.g. Claude Code, Cursor, Amp) along with
+  the extent that the work was AI-assisted.
+
+- **The human-in-the-loop must fully understand all code.** If you
+  can't explain what your changes do and how they interact with the
+  greater system without the aid of AI tools, do not contribute
+  to this project.
+
+- **Issues and discussions can use AI assistance but must have a full
+  human-in-the-loop.** This means that any content generated with AI
+  must have been reviewed _and edited_ by a human before submission.
+  AI is excellent at being overly verbose and including noise that
+  distracts from the main point. Humans must do their research and
+  trim this down.
+
+- **No AI-generated media is allowed (art, images, videos, audio, etc.).**
+  Text and code are the only acceptable AI-generated content, per the
+  other rules in this policy.
+
+These rules apply only to outside contributions. Maintainers
+are exempt from these rules and may use AI tools at their discretion;
+they've proven themselves trustworthy to apply good judgment.
+
+## There Are Humans Here
+
+Please remember that this project is maintained by humans.
+
+Every discussion, issue, and pull request is read and reviewed by
+humans (and sometimes machines, too). It is a boundary point at which
+people interact with each other and the work done. It is rude and
+disrespectful to approach this boundary with low-effort, unqualified
+work, since it puts the burden of validation on the maintainer.
+
+In a perfect world, AI would produce high-quality, accurate work
+every time. But today, that reality depends on the driver of the AI.
+And today, most drivers of AI are just not good enough. So, until either
+the people get better, the AI gets better, or both, we have to have
+strict rules to protect maintainers.

CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing To `diffnav`
+
+Thank you for investing your time in contributing to our project!
+
+In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.
+
+## The Critical Rule
+
+- The most important rule: you must understand your code. If you can't explain what your changes do and how they interact with the greater system without the aid of AI tools, do not contribute to this project.
+- The second most important rule: when you submit a PR you must be willing to address comments and maintain this code. Dot not submit drive-by PRs that solve your own issue without the willingness to iterate on it. Keep these in your own fork.
+- Using AI to write code is fine. You can gain understanding by interrogating an agent with access to the codebase until you grasp all edge cases and effects of your changes. What's not fine is submitting agent-generated slop without that understanding. Be sure to read the [AI Usage Policy](AI_POLICY.md).
+
+## AI Usage
+
+The project has strict rules for AI usage. Please see the [AI Usage Policy](AI_POLICY.md). This is very important.
+
+## Quick Guide
+
+### I Have an Idea for a Feature
+
+Like bug reports, first search through both issues and discussions and try to find if your feature has already been requested. Otherwise, open a discussion in the ["Feature Requests, Ideas"](https://github.com/dlvhdr/diffnav/issues/new?template=feature_request.md) category.
+
+### I've Implemented a Feature
+
+- If there is an issue for the feature, open a pull request straight away.
+- If there is no issue, open a discussion and link to your branch.
+- If you want to live dangerously, open a pull request and hope for the best.
+
+### I Have a Question Which Is Neither a Bug Report nor a Feature Request
+
+Open a [Q&A discussion](https://github.com/dlvhdr/diffnav/discussions/categories/q-a), or join our [Discord Server](https://discord.gg/SXNXp9NctV) and ask away in the #help forum channel.
+
+## Working on the Code
+
+### Installing Required Tooling
+
+Our project uses [Devbox](https://github.com/jetpack-io/devbox) to manage its development environment.
+
+Using Devbox will get your dev environment up and running easily and make sure we're all using the same tools with the same versions.
+
+- Clone this repo
+
+```sh
+git clone git@github.com:dlvhdr/diffnav.git && cd diffnav
+```
+
+- Install `devbox`
+
+```sh
+curl -fsSL https://get.jetpack.io/devbox | bash
+```
+
+- Start the `devbox` shell and run the setup (will take awhile on first time)
+
+```sh
+devbox shell
+```
+
+_This will create a shell where all required tools are installed._
+
+- _(Optional)_ Set up `direnv` so `devbox shell` runs automatically
+  - [direnv](https://www.jetify.com/devbox/docs/ide_configuration/direnv/) is a tool that allows setting unique environment variables per directory in your filesystem.
+    - Install `direnv` with: `brew install direnv`
+    - Add the following line at the end of the `~/.bashrc` file: `eval "$(direnv hook bash)"`
+      - See [direnv's installation instructions](https://direnv.net/docs/hook.html) for other shells.
+    - Enable `direnv` by running `direnv allow`
+- _(Optional)_ Install the VSCode Extension
+  - Follow [this guide](https://www.jetify.com/devbox/docs/ide_configuration/vscode/) to set up VSCode to automatically run `devbox shell`.
+
+#### Troubleshooting
+
+- delete the `.devbox` directory at the project's root
+
+### Navigating the Codebase
+
+To navigate our codebase with confidence, familiarize yourself with:
+
+- [Bubbletea](https://github.com/charmbracelet/bubbletea) - the TUI framework we're using
+- [The Elm architecture](https://guide.elm-lang.org/architecture/)
+- [charmbracelet/glow](https://github.com/charmbracelet/glow) - for parsing and presenting Markdown
+
+### Debugging
+
+- Write to the log by using Charm's `log` package
+- Tail the log by running `task logs`
+- Run `diffnav` in debug mode with `task debug` in another terminal window / pane
+
+```go
+import "charm.land/log/v2"
+
+// more code...
+
+log.Debug("some message", "someVariable", someVariable)
+```