From ef13ef918774a36d7c70f2ffb1c95591642b4230 Mon Sep 17 00:00:00 2001
From: calesthio <celesthioailabs@gmail.com>
Date: Mon, 16 Mar 2026 11:44:54 -0700
Subject: [PATCH] docs: add contributor and security guidelines

---
 .github/ISSUE_TEMPLATE/bug_report.md      |  40 ++++++++
 .github/ISSUE_TEMPLATE/config.yml         |   5 +
 .github/ISSUE_TEMPLATE/feature_request.md |  35 +++++++
 .github/pull_request_template.md          |  45 +++++++++
 .gitignore                                |   3 +
 CONTRIBUTING.md                           | 107 ++++++++++++++++++++++
 README.md                                 |   2 +
 SECURITY.md                               |  49 ++++++++++
 8 files changed, 286 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 .github/pull_request_template.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..bcfcc25
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Report a reproducible problem in Crucix
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug clearly.
+
+## Environment
+
+- OS:
+- Install method: local / Docker / other
+- Node version:
+- LLM provider:
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+What should have happened?
+
+## Actual Behavior
+
+What happened instead?
+
+## Logs or Screenshots
+
+Paste relevant logs, screenshots, or terminal output.
+
+## Additional Context
+
+Anything else that helps narrow this down.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..b2c1cf5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: mailto:celesthioailabs@gmail.com
+    about: Report security issues privately instead of opening a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..9b08663
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,35 @@
+---
+name: Feature request
+about: Suggest a feature, source addition, or product improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+Describe the feature or source you want added.
+
+## Why This Matters
+
+What problem does this solve for Crucix users?
+
+## Scope
+
+- Bug fix:
+- New source:
+- Dashboard/UI change:
+- LLM/provider change:
+- Other:
+
+## Proposed Behavior
+
+Describe the expected behavior or output.
+
+## Maintenance Impact
+
+Note any API keys, rate limits, paid services, dependencies, or ongoing upkeep this would add.
+
+## Additional Context
+
+Links, examples, screenshots, or references.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..a84a8f9
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,45 @@
+## Summary
+
+Describe what changed.
+
+## Why
+
+Explain the problem being solved.
+
+## Scope
+
+- [ ] Focused bug fix
+- [ ] Small UX improvement
+- [ ] New source
+- [ ] Dashboard change
+- [ ] Docs/config change
+
+## Validation
+
+List the commands, checks, or manual validation you performed.
+
+## Screenshots
+
+If the dashboard or any visible output changed, add screenshots.
+
+## Config and Docs
+
+- [ ] No new environment variables
+- [ ] `.env.example` updated if needed
+- [ ] `README.md` updated if behavior changed
+
+## Source Additions
+
+If this PR adds a new source, explain:
+
+- why the source improves signal quality
+- whether it requires an API key
+- how it degrades when the key is missing
+- what changed in `apis/briefing.mjs` and `dashboard/inject.mjs`
+
+## Checklist
+
+- [ ] This PR stays within one bugfix or one feature family
+- [ ] I kept unrelated changes out of the diff
+- [ ] I considered security for any mixed-source content rendering
+- [ ] I tested the changed path locally
diff --git a/.gitignore b/.gitignore
index 25486c3..b1927a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,3 +41,6 @@ npm-debug.log*
 
 # Backup files
 *.bak
+
+# Local maintainer notes
+MAINTAINER_DECISIONS.local.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..729b7d1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,107 @@
+# Contributing to Crucix
+
+Crucix moves quickly, but review bandwidth is limited. The easiest way to get a change merged is to keep it small, well-scoped, and aligned with the project's direction.
+
+## What Contributions Are Most Helpful
+
+- Focused bug fixes with a clear reproduction and validation path
+- Documentation improvements that reduce setup friction
+- Dashboard usability improvements with a small review surface
+- New OSINT sources that add clear signal, degrade gracefully, and fit the existing architecture
+
+## Changes That Should Start With an Issue First
+
+Open an issue before writing code if your change would:
+
+- add a new external provider or paid API
+- add a new feature family or dashboard surface
+- change the project scope or roadmap
+- change licensing, distribution, or deployment model
+- introduce new dependencies
+
+## Development Baseline
+
+- Node.js 22+
+- Pure ESM
+- Keep the zero-extra-dependency approach unless there is a strong reason not to
+- Do not commit secrets, `.env` files, or generated runtime data
+
+## Adding a New Source
+
+Each source should be a standalone module in `apis/sources/` and integrate cleanly with `apis/briefing.mjs`.
+
+Minimum expectations:
+
+- export a `briefing()` function that returns structured data
+- handle upstream errors and rate limits cleanly
+- degrade gracefully when API keys are missing
+- avoid breaking the full sweep if the source fails
+- document any required environment variables in `.env.example` and `README.md`
+- explain why the source improves signal quality, not just source count
+
+If your source also affects the dashboard:
+
+- wire it through `dashboard/inject.mjs`
+- explain the user-facing impact in the PR
+- include a screenshot when the UI changes materially
+
+## Frontend and Security Expectations
+
+Frontend changes are reviewed carefully because the dashboard renders mixed-source data.
+
+- do not render untrusted content directly with `innerHTML` unless it is sanitized first
+- only allow safe external URL schemes such as `http:` and `https:`
+- escape JSON injected into inline `<script>` tags
+- prefer text rendering over HTML rendering when possible
+
+## Pull Request Scope
+
+One bugfix or one feature family per PR.
+
+Good:
+
+- fix one parser bug
+- add one source and its minimal wiring
+- improve one dashboard interaction
+
+Bad:
+
+- add a source, redesign the dashboard, and change config behavior in the same PR
+- mix bug fixes with unrelated product expansion
+- bundle license or provider changes into unrelated work
+
+Large changes may be asked to split before review.
+
+## Pull Request Checklist
+
+Before opening a PR, make sure you have:
+
+- explained the problem and why the change is needed
+- kept the diff focused
+- listed any setup or environment variable changes
+- validated the changed path locally
+- included screenshots for visible dashboard changes
+- updated docs when behavior or config changed
+
+## Review Priorities
+
+Review is primarily about:
+
+- correctness
+- regression risk
+- security of mixed-source content rendering
+- maintainability
+- fit with project direction
+
+Not every technically correct change will be merged. Scope and long-term maintenance cost matter.
+
+## Commit and PR Hygiene
+
+- Use clear commit messages
+- Avoid unrelated file churn
+- Do not include generated metadata or tool signatures in PR descriptions unless they are actually useful
+- Keep PR titles specific and concrete
+
+## Security Reports
+
+If you believe you found a security issue, do not open a public issue first. See `SECURITY.md` for reporting instructions.
diff --git a/README.md b/README.md
index 4a44b81..b522851 100644
--- a/README.md
+++ b/README.md
@@ -486,6 +486,8 @@ Found a bug? Want to add a 28th source? PRs welcome. Each source is a standalone
 
 If you find this useful, a star helps others find it too.
 
+For contribution guidelines, review expectations, and source-add rules, see `CONTRIBUTING.md`. For security reports, see `SECURITY.md`.
+
 ## Contact
 
 For partnerships, integrations, or other non-issue inquiries, you can reach me at `celesthioailabs@gmail.com`.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..9627c2f
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,49 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security issue in Crucix, please report it privately instead of opening a public GitHub issue.
+
+Email: `celesthioailabs@gmail.com`
+
+Use a subject line like:
+
+`[Crucix Security] short description`
+
+Please include:
+
+- affected component or file
+- steps to reproduce
+- impact
+- proof of concept if available
+- any suggested remediation
+
+## Response Expectations
+
+Best-effort targets:
+
+- acknowledgement within 72 hours
+- initial triage within 7 days
+- coordinated disclosure after a fix is available
+
+## Scope
+
+The highest-priority reports are:
+
+- XSS or HTML/script injection in the dashboard
+- unsafe rendering of mixed-source external content
+- authentication or secret-handling issues
+- server-side injection or path traversal
+- dependency or supply-chain issues with real exploit impact
+
+## Out of Scope
+
+The following are generally lower priority unless they create a concrete exploit path:
+
+- minor UI bugs
+- missing best-practice headers without impact
+- rate limiting or reliability issues without a security consequence
+
+## Public Disclosure
+
+Please do not disclose the issue publicly until a fix is shipped or we agree on a disclosure timeline.