docs: comprehensive community health and contributor guide overhaul

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,6 +9,14 @@ body:
       value: |
         Please search existing issues first. Include the smallest reproducible example you can.
 
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Pre-flight checks
+      options:
+        - label: I have checked the Troubleshooting section in the README
+          required: true
+
   - type: textarea
     id: description
     attributes:
@@ -39,14 +47,49 @@ body:
     id: version
     attributes:
       label: Graphify version
-      placeholder: "0.9.64"
+      placeholder: "e.g. 0.9.68"
 
-  - type: input
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - WSL
+    validations:
+      required: true
+
+  - type: dropdown
+    id: python
+    attributes:
+      label: Python Version
+      options:
+        - 3.10
+        - 3.11
+        - 3.12
+        - 3.13
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install_method
+    attributes:
+      label: Installation Method
+      options:
+        - uv tool install (recommended)
+        - pipx
+        - pip
+        - built from source (git clone)
+    validations:
+      required: true
+
+  - type: textarea
     id: environment
     attributes:
-      label: Environment
-      description: Include operating system, Python version, and installation method.
-      placeholder: "macOS 15, Python 3.12, uv tool install"
+      label: Additional Environment Details
+      description: List any provider environment variables set (e.g., OPENAI_API_KEY) and whether a clean checkout reproduced the issue.
 
   - type: textarea
     id: additional

.github/ISSUE_TEMPLATE/config.yml

@@ -7,5 +7,5 @@ contact_links:
     url: https://github.com/Graphify-Labs/graphify/blob/v8/README.md
     about: Check the README and docs before opening an issue.
   - name: 🤝 Contributing guide
-    url: https://github.com/Graphify-Labs/graphify/blob/v8/README.md#development-setup
+    url: https://github.com/Graphify-Labs/graphify/blob/v8/CONTRIBUTING.md
     about: Read the development and contribution guidelines before opening a pull request.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -47,6 +47,25 @@ body:
     validations:
       required: true
 
+  - type: dropdown
+    id: pr
+    attributes:
+      label: Are you willing to submit a PR?
+      options:
+        - Yes, I can work on this
+        - Yes, but I will need guidance
+        - No, I just wanted to request it
+    validations:
+      required: true
+
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility / behavior impact
+      description: Does this affect node/edge IDs, cache semantics, graph.json schema, generated skills, MCP output, or incremental updates?
+    validations:
+      required: true
+
   - type: textarea
     id: context
     attributes:

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,6 @@
 
 <!-- Describe the problem and the change. Link the relevant issue when one exists. -->
 
-
 ## Type of change
 
 - [ ] Bug fix
@@ -12,18 +11,29 @@
 - [ ] Refactor
 - [ ] Security fix
 
+## Verification & Invariants
+
+<!-- What invariant does this code protect? How do you prove your change doesn't break it? What generated or persisted state could your change invalidate? -->
+
+- [ ] **Read** the [CONTRIBUTING.md](../CONTRIBUTING.md) guide.
+- [ ] **Reproduced** the issue and identified the invariant.
+- [ ] Made the **smallest fix** necessary.
+- [ ] Added a **regression test** (if bug fix) or isolated boundary test.
+- [ ] Kept the PR description **synchronized** with the final implementation.
+- [ ] Documented any **limitations / unsupported cases** explicitly.
+
 ## How was this tested?
 
-<!-- Include the commands you ran and any platform-specific checks. -->
+<!-- List the commands you actually ran. Mention environment isolation if touching provider paths. -->
 
 ```text
 
 ```
 
 ## Graphify-specific checklist
 
-- [ ] I added or updated tests for behavior changes.
-- [ ] I updated documentation or confirmed that no documentation is needed.
-- [ ] I updated generated skill artifacts when changing their source fragments.
-- [ ] I considered compatibility across supported Python versions.
-- [ ] I confirmed that no API keys, generated graph data, or local-only files are included.
+- [ ] I updated generated skill artifacts (`uv run python -m tools.skillgen --bless`) when changing their source fragments.
+- [ ] I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables).
+- [ ] I reviewed changes for security implications (no unsafe interpolation into shell/Python).
+- [ ] I confirmed no API keys or local-only graph data are included.
+- [ ] (If applicable) I disclosed AI authorship in my commit messages.

AGENTS.md

@@ -3,6 +3,6 @@
 This project has a graphify knowledge graph at graphify-out/.
 
 Rules:
-- Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
+- When working on Graphify itself, use the repository's existing Graphify guidance. For codebase questions, prefer scoped graph queries where available; use the report for broad orientation. Do not use the graph as evidence when the task concerns the graph's correctness itself.
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

ARCHITECTURE.md

@@ -8,7 +8,7 @@ graphify is a Claude Code skill backed by a Python library. The skill orchestrat
 detect()  →  extract()  →  build()  →  cluster()  →  analyze helpers  →  report.generate()  →  export.to_*()
 ```
 
-Each stage lives in its own module and they communicate through plain Python dicts and NetworkX graphs - no shared state, no side effects outside `graphify-out/`. Most stages are a single function; `analyze.py` and `export.py` are sets of sibling functions rather than one entry point.
+Each stage lives in its own module and they communicate through plain Python dicts and NetworkX graphs. While designed to minimize shared state, some stages (like extractors) rely on ambient module-level state around the active scan root. Most stages are a single function; `analyze.py` and `export.py` are sets of sibling functions rather than one entry point.
 
 ## Module responsibilities
 
@@ -87,7 +87,7 @@ All external input passes through `graphify/security.py` before use:
 - URLs → `validate_url()` (http/https only) + `_NoFileRedirectHandler` (blocks file:// redirects)
 - Fetched content → `safe_fetch()` / `safe_fetch_text()` (size cap, timeout)
 - Graph file paths → `validate_graph_path()` (must resolve inside `graphify-out/`)
-- Node labels → `sanitize_label()` (strips control chars, caps 256 chars, HTML-escapes)
+- Node labels → `sanitize_label()` (strips control chars, caps 256 chars)
 
 See `SECURITY.md` for the full threat model.
 
@@ -99,4 +99,4 @@ One test file per module under `tests/`. Run with:
 pytest tests/ -q
 ```
 
-All tests are pure unit tests - no network calls, no file system side effects outside `tmp_path`.
+The test suite is designed to avoid network access and uncontrolled filesystem effects; most tests are isolated with temporary directories and environment fixtures.

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, including the GitHub repository, Discord server, and any other channels managed by Graphify Labs. It also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers by directly messaging a Community Leader on the [Graphify Discord server](https://discord.gg/XDnKVpzdXB) or by emailing the maintainer directly if known.
+
+All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).