Add standard project documentation files

Six adds + one edit to bring the repo's project files up to the
standard expected for a research codebase that external researchers
might fork or cite.  Nothing in this PR affects code paths.

CITATION.cff
  Schema-compliant citation metadata.  Drives GitHub's "Cite this
  repository" sidebar widget and APA / BibTeX / RIS exports.

CONTRIBUTING.md
  Scope policy (in / out of scope), branch and commit conventions,
  test-suite expectations, code style, reproducibility expectations
  (seed_utils, eval.py, compute_ledger), reporting bug template
  pointers.  Codifies the workflow we've been using on PRs #21–#31.

.github/PULL_REQUEST_TEMPLATE.md
  Forces every PR to include Summary, Linked issues, Test plan,
  Reproducibility considerations, Out of scope.  Reproducibility
  section calls out research-relevant code paths explicitly.

.github/ISSUE_TEMPLATE/{bug_report,feature_request}.md + config.yml
  Two opinionated templates plus a config that disables blank issues
  and routes general questions to Discussions.  Bug template prompts
  for env / dep versions and W&B run URLs; feature template includes
  a scope check against the pre-registered analysis plan.

.editorconfig
  Whitespace and indent conventions per file type.  Standard for
  cross-editor consistency; reduces churn from contributors using
  different IDEs.

DEVELOPER_GUIDE.md
  Refresh Project Overview opening to frame this as the research
  codebase backing the 3-paper cascade rather than a generic toolkit.
  Update directory structure to include analysis/, alerts.py,
  event_flags.py, scripts/, paper/, bin/, configs/, docs/.  Add a
  Research Apparatus section after CLI architecture covering the
  analysis layer, monitoring callbacks, alerting system, Streamlit
  dashboards, pilot grid launcher, and Overleaf integration.  No
  changes to existing accurate sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

.editorconfig

@@ -0,0 +1,28 @@
+# Editor and IDE conventions for this project.
+# See https://editorconfig.org/ — most editors auto-detect.
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,markdown}]
+# Markdown is whitespace-sensitive (trailing two spaces = hard line break)
+trim_trailing_whitespace = false
+
+[{*.yml,*.yaml,*.json,*.toml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.{sh,bash}]
+indent_size = 2
+
+[*.tex]
+indent_size = 2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something doesn't work the way you expected
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+<!-- What did you expect to happen?  What actually happened? -->
+
+## Reproduction
+
+<!-- Smallest possible script / command sequence that reproduces the
+     bug.  If it only reproduces under specific data, attach a
+     minimal snapshot or paste the relevant config. -->
+
+```
+# command(s) you ran
+```
+
+## Environment
+
+- Python version:
+- Project version (or git SHA):
+- OS:
+- Key dependency versions (run `pip show pyboy stable_baselines3 sb3-contrib gymnasium torch` and paste):
+
+## Logs
+
+<!-- For training crashes, paste the relevant section of the log
+     and (if applicable) the W&B run URL. -->
+
+```
+```
+
+## Additional context
+
+<!-- Anything else worth knowing — recent changes, multi-process setup,
+     non-standard hardware, etc. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,9 @@
+# Disable blank issues — force users through a template so we get
+# actionable bug reports instead of "it doesn't work" one-liners.
+blank_issues_enabled: false
+
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/amcheste/pokemon-red-ai/discussions
+    about: For research questions, design discussion, or anything that's
+      not a clear bug or feature request, please use Discussions.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,37 @@
+---
+name: Feature request
+about: Propose a new feature or enhancement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+<!-- What problem are you trying to solve?  Be specific — "training is
+     slow" is harder to act on than "PyBoy stepping is the bottleneck
+     in profiling, accounting for 80% of wall clock". -->
+
+## Proposed solution
+
+<!-- What you'd like to see, at whatever level of detail you have. -->
+
+## Alternatives considered
+
+<!-- Other ways this problem could be solved, and why you prefer the
+     proposed solution. -->
+
+## Scope check
+
+<!-- Does this fit within the project's research scope?  See
+     CONTRIBUTING.md.  Quick checklist: -->
+
+- [ ] Doesn't change the pre-registered analysis plan
+- [ ] Doesn't change the 18 pre-registered event flags
+- [ ] Doesn't break reproducibility of completed runs
+
+If any of the above are unchecked, please explain in the proposal.
+
+## Additional context
+
+<!-- Links to related work, blog posts, papers, etc. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+<!--
+Thanks for opening a PR!  Fill in the sections below — leave any
+heading present but write "n/a" if a section doesn't apply.  See
+CONTRIBUTING.md for branch / commit / scope conventions.
+-->
+
+## Summary
+
+<!-- 1-3 bullet points describing what this PR does and why. -->
+
+-
+
+## Linked issues
+
+<!-- Link any Linear issues (AMC-NN) or GitHub issues this resolves.
+     Use "Closes #123" / "Fixes AMC-67" syntax for auto-close. -->
+
+## Test plan
+
+<!-- Concrete checklist of what you've verified. -->
+
+- [ ]
+- [ ]
+
+## Reproducibility considerations
+
+<!-- Required only for changes that touch:
+       * pokemon_red_ai/environment/        (env / reward / observation)
+       * pokemon_red_ai/training/           (callbacks, models, trainer)
+       * scripts/{train,eval,analyze}.py    (training / eval / analysis)
+     If your change can affect numerical results, document:
+       - Are existing runs in compute_ledger.md still valid? (yes/no)
+       - Does this change affect the pre-registered analysis plan? (yes/no)
+       - If yes to either: what's the migration path?
+     If your change is purely doc / tooling / test, write "n/a".
+-->
+
+n/a
+
+## Out of scope
+
+<!-- Things this PR explicitly does *not* fix or change.  Helps the
+     reviewer understand follow-up work. -->
+
+-

CITATION.cff

@@ -0,0 +1,44 @@
+# Citation File Format — used by GitHub's "Cite this repository" widget.
+# See https://citation-file-format.github.io/ for the schema.
+cff-version: 1.2.0
+title: "Pokémon Red — A Long-Horizon RL Benchmark"
+message: "If you use this software in your research, please cite the working paper below."
+type: software
+authors:
+  - given-names: Alan
+    family-names: Chester
+    email: amcheste@gmail.com
+    affiliation: CAM Labs LLC
+repository-code: "https://github.com/amcheste/pokemon-red-ai"
+url: "https://github.com/amcheste/pokemon-red-ai"
+abstract: >-
+  A controlled empirical study of observation representations
+  (pixel, symbolic, hybrid) in long-horizon, sparse-reward
+  reinforcement learning, using Pokémon Red as the benchmark
+  environment.  RecurrentPPO agents are trained against an
+  18-flag event-progress reward; results are reported with
+  rliable interquartile means and 95% stratified-bootstrap
+  confidence intervals.  Released as a 3-paper cascade
+  (EWRL 2026 → NeurIPS 2026 workshop → TMLR).
+keywords:
+  - reinforcement-learning
+  - long-horizon-rl
+  - representation-learning
+  - pokemon-red
+  - benchmark
+  - rliable
+license: MIT
+preferred-citation:
+  type: unpublished
+  authors:
+    - given-names: Alan
+      family-names: Chester
+      email: amcheste@gmail.com
+      affiliation: CAM Labs LLC
+  title: >-
+    Symbols or Pixels? A Controlled Study of Observation
+    Representations in Long-Horizon Reinforcement Learning
+  year: 2026
+  notes: >-
+    EWRL 2026 workshop submission.  Pre-print available at
+    https://github.com/amcheste/pokemon-red-ai

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing
+
+Thanks for your interest in contributing.  This is an active research
+codebase — we welcome bug reports, fixes, and small enhancements that
+fit the project's scope.  For larger changes, please open an issue
+first to discuss design.
+
+## Scope
+
+The project is the supporting code for a 3-paper research cascade
+(EWRL 2026 → NeurIPS 2026 workshop → TMLR).  Contributions that align
+with the cascade are most likely to be merged:
+
+- Bug fixes in any layer
+- Reproducibility improvements (deterministic seeding, environment hygiene)
+- Test coverage on under-tested code paths
+- Documentation accuracy fixes
+- New observation treatments, reward strategies, or callbacks that
+  don't break the existing pre-registered protocol
+- Performance improvements that don't change behaviour
+
+Out of scope without prior discussion:
+
+- Changes that alter the pre-registered analysis plan
+  ([`paper/analysis_plan.md`](paper/analysis_plan.md))
+- Changes to the 18 pre-registered event flags
+  ([`pokemon_red_ai/game/event_flags.py`](pokemon_red_ai/game/event_flags.py))
+- New reward components that retroactively affect already-completed runs
+
+## Development setup
+
+```bash
+git clone https://github.com/amcheste/pokemon-red-ai.git
+cd pokemon-red-ai
+python3 -m venv venv && source venv/bin/activate
+pip install -e .
+pip install -r requirements.txt
+```
+
+Run the test suite:
+
+```bash
+./venv/bin/python3 -m pytest                  # full suite (~17s)
+./venv/bin/python3 -m pytest tests/unit/      # unit only
+./venv/bin/python3 -m pytest -k comparison    # specific module
+```
+
+All 833 tests should pass on a clean checkout.  PRs that drop coverage
+or break tests will not be merged.
+
+## Branch and PR conventions
+
+- **Never commit to `main` or `master`** — always work on a feature
+  branch and open a pull request.
+- Branch names: `feature/<short-description>`, `fix/<short-description>`,
+  `docs/<short-description>`, `chore/<short-description>`.
+- Open the PR against `main`.  PRs are routed to `@amcheste` via
+  `CODEOWNERS`; leave the assignee field unset.
+- Keep PRs focused — one logical change per PR.  Big mixed-bag PRs
+  that combine refactors, features, and docs are hard to review and
+  often get split anyway.
+- Include a `Test plan` section in the PR body covering what you ran
+  and what you didn't.
+
+## Commit style
+
+- Imperative subject line under 72 characters
+  (`Add reward breakdowns to monitoring callback` rather than
+  `added reward breakdowns to monitoring callback`).
+- Body explains *why*, not what — the diff explains what.  Wrap the
+  body at 72 characters.
+- One logical change per commit.
+
+## Code style
+
+- Python 3.10+
+- Follow the existing module structure (see [`DEVELOPER_GUIDE.md`](DEVELOPER_GUIDE.md))
+- Type hints on every public function (`Optional[str]`, `Dict[str, Any]`, etc.)
+- Docstrings on every public class and function.  Args / Returns
+  / Raises sections where applicable.
+- Tests for every behaviour change — both the happy path and the
+  obvious failure modes
+- No emojis in code, comments, or documentation unless they're part of
+  user-facing CLI output that's intended to be visually distinctive
+
+## Reporting bugs
+
+Use the issue templates under `.github/ISSUE_TEMPLATE/`.  At minimum:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce (smallest possible example)
+- Versions: Python, the project, key dependencies (PyBoy, SB3,
+  Gymnasium, PyTorch)
+
+For training crashes, please include the relevant section of the
+training log and the W&B run URL if applicable.
+
+## Reproducibility expectations
+
+Because this is a research codebase, reproducibility is unusually
+important:
+
+- Use `scripts/seed_utils.py` for any RNG seeding in new code
+- Use `scripts/eval.py` for evaluation results (no ad-hoc eval loops
+  in notebooks or scripts)
+- Log every significant training run to
+  [`paper/compute_ledger.md`](paper/compute_ledger.md)
+- Don't commit secrets (W&B keys, Slack webhooks, ROM files) — the
+  `.gitignore` covers the obvious cases but always sanity-check
+  `git status` before pushing
+
+## License
+
+By contributing, you agree that your contributions will be licensed
+under the [MIT License](LICENSE), the same license as the rest of the
+project.