chore: prep repo for public release (#56)

- ignore internal redesign artifacts (redisign/, frontend-redesign.md, qa-frontend-agent.md)
- annotate test-only FERNET_KEY in CI workflow
- add hardware sizing table to self-hosting guide
- add SECURITY.md (private vulnerability reporting via GitHub advisories)
- add issue templates (bug, feature) + config redirecting security and setup questions
- README: MIT/status badges, alpha status section, BYOK cost note, link to SECURITY.md

Author: mariuspruvot

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Something isn't working
+title: ''
+labels: bug
+assignees: ''
+---
+
+## What happened
+
+<!-- A clear description of the bug. What did you expect, what did you observe? -->
+
+## Reproduction
+
+1.
+2.
+3.
+
+## Environment
+
+- helPRs version / commit:
+- Deployment: <!-- docker-compose / Coolify / other -->
+- Host OS:
+- Browser (if frontend issue):
+
+## Logs
+
+<!--
+Relevant excerpts. For API issues:
+  docker compose logs api | tail -100
+
+For a specific runner container:
+  docker logs <container-id>
+
+Please scrub tokens, webhook secrets, and the Fernet key before pasting.
+-->
+
+```
+paste here
+```
+
+## Anything else
+
+<!-- Workarounds you tried, hypotheses, screenshots. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/mariuspruvot/helprs/security/advisories/new
+    about: Please report security issues privately, not as a public issue. See SECURITY.md.
+  - name: Self-hosting question
+    url: https://github.com/mariuspruvot/helprs/blob/main/docs/self-hosting.md
+    about: Most setup questions are answered in the self-hosting guide.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose an enhancement or a new skill
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+<!-- What problem are you trying to solve, or what is missing today? -->
+
+## Proposed solution
+
+<!-- What you'd like helPRs to do. If this is a new skill, link to or paste the skill prompt sketch. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about. Why are they worse? -->
+
+## Additional context
+
+<!-- Use case, screenshots, links to similar tools. -->

.github/workflows/ci.yml

@@ -45,6 +45,8 @@ jobs:
       - run: uv sync --frozen
       - run: uv run pytest --cov=helprs --cov-report=term-missing --cov-fail-under=70
         env:
+          # Test-only values. The ephemeral CI database is destroyed after each run
+          # and nothing it encrypts ever leaves the job. Do not reuse anywhere else.
           DATABASE_URL: postgresql+asyncpg://helprs:helprs@localhost:5432/helprs_test
           SECRET_KEY: ci-test-secret-key
           FERNET_KEY: "-fB7lL74GHGbXnRClRQTaBP9_flqSUHFC9_c2n3Tvbo="

.gitignore

@@ -53,3 +53,8 @@ apps/api/alembic/versions/*.pyc
 _bmad/
 _bmad-output/
 .claude/
+
+# Internal redesign artifacts & dev-only scratchpads (kept locally, not in public repo)
+redisign/
+docs/frontend-redesign.md
+scripts/qa-frontend-agent.md

README.md

@@ -1,12 +1,18 @@
 # helPRs
 
 [![CI](https://github.com/mariuspruvot/helprs/actions/workflows/ci.yml/badge.svg)](https://github.com/mariuspruvot/helprs/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
 
 **Pluggable AI skill runner for pull requests.**
 
 helPRs spins up ephemeral Docker containers running [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to execute skills against your PRs -- comprehension quizzes, code reviews, security audits -- and streams results back in real time.
 
-BYOK (Bring Your Own Key): you provide your Claude credentials once. The backend never calls the Claude API -- containers use your credentials natively.
+BYOK (Bring Your Own Key): you provide your Claude credentials once. The backend never calls the Claude API -- containers use your credentials natively. Costs are billed to your Claude subscription (or Anthropic API account if you use an API key instead).
+
+## Status
+
+helPRs is **alpha**. The architecture is stable, the core flows work end-to-end, but the API and skill spec may still break between releases. Self-hosting is supported and documented -- see the [self-hosting guide](docs/self-hosting.md) for hardware requirements and step-by-step setup.
 
 ---
 
@@ -108,6 +114,7 @@ For the full picture, see:
 | [Creating Skills](docs/creating-skills.md) | Skill authors | Build custom skills |
 | [Skill Specification](skills/SKILL_SPEC.md) | Skill authors | Formal spec for skill definitions |
 | [Contributing](CONTRIBUTING.md) | Contributors | Dev setup, code style, PR process |
+| [Security policy](SECURITY.md) | Everyone | Reporting vulnerabilities |
 | [ADR-001](docs/adr-001-claude-code-container-pivot.md) | Everyone | Why ephemeral containers |
 
 ---

SECURITY.md

@@ -0,0 +1,55 @@
+# Security Policy
+
+## Supported versions
+
+helPRs is in early development. Only the `main` branch receives security fixes. There is no LTS line.
+
+## Reporting a vulnerability
+
+**Please do not file public GitHub issues for security problems.**
+
+Use GitHub's private vulnerability reporting:
+
+1. Go to [the Security tab of the repository](https://github.com/mariuspruvot/helprs/security)
+2. Click **Report a vulnerability**
+3. Fill in the form with as much detail as you can (reproduction, impact, suggested fix)
+
+If you cannot use GitHub for any reason, email **marius.pruvot@outlook.fr** with the subject line `helPRs security:`.
+
+### What to include
+
+- A description of the issue and the version / commit it affects
+- Steps to reproduce (proof-of-concept is ideal)
+- Your assessment of impact (data disclosure, RCE, auth bypass, etc.)
+- Any suggested mitigation
+
+### What to expect
+
+- Acknowledgement within 72 hours
+- A first assessment within 7 days
+- Coordinated disclosure: a fix will be published before public details, and credit will be given unless you ask otherwise
+
+## Scope
+
+In scope:
+
+- The API (`apps/api/`), the web app (`apps/web/`), and the runner image (`infra/docker/claude-runner/`)
+- The default `docker-compose` and Coolify deployment recipes
+- Container orchestration (privilege escalation, sandbox escape, credential leaks across sessions)
+
+Out of scope:
+
+- Vulnerabilities in upstream dependencies that have not been disclosed upstream (please report to the upstream first)
+- Issues that require an attacker to already have admin / database access
+- Social engineering of operators or users
+- Anything depending on a misconfigured deployment that the documentation explicitly warns against
+
+## Operator responsibilities
+
+helPRs is self-hosted. As an operator you are responsible for:
+
+- Keeping the host OS, Docker, and the helPRs image up to date
+- Protecting the `.env` file, the Postgres volume, and the `FERNET_KEY` (loss of the key means stored Claude credentials cannot be decrypted)
+- Restricting access to the `/admin` panel (set a strong `ADMIN_PASSWORD`)
+- Terminating TLS at a reverse proxy (helPRs does not serve HTTPS directly)
+- Treating the Docker socket mounted into the API container as a privileged surface -- only run helPRs on hosts where that is acceptable

docs/self-hosting.md

@@ -11,6 +11,20 @@ Deploy helPRs from zero to a running instance. By the end you'll have helPRs con
 - A **Claude account** -- you'll generate an OAuth token with `claude setup-token` (or use an Anthropic API key)
 - A server with a public URL if you want GitHub webhooks (or use a tunnel like ngrok for local dev)
 
+### Hardware
+
+helPRs itself is lightweight (API + web + Postgres). The real footprint comes from the ephemeral `claude-runner` containers it spawns per session -- each one runs Node + Claude Code CLI, clones the target repo, and holds it in memory for the duration of the skill (typically 5-15 min).
+
+| Profile | vCPU | RAM | Disk | Concurrency |
+|---------|------|-----|------|-------------|
+| **Minimum** (try it out, 1 user, 1 session at a time) | 2 | 2 GB | 10 GB | 1 |
+| **Recommended** (small team, a few concurrent sessions) | 2-4 | 4 GB | 20 GB | 3-5 |
+| **Comfortable** (larger team, many parallel PRs) | 4-8 | 8 GB+ | 40 GB+ | 10+ |
+
+Each running `claude-runner` container peaks around 300-600 MB RSS and one core. Plan ~1 GB of RAM headroom per concurrent session you expect, on top of the base ~1 GB used by the API + Postgres + web. Disk usage grows with the size of the repos cloned at runtime (shallow clones, so it's small; cleaned up on container exit).
+
+Runners are killed after `CONTAINER_TTL_SECONDS` (default 15 min). Lower it if your host is tight on RAM.
+
 ---
 
 ## Step 1: Create a GitHub App