If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/helpyio/helpy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live helpyio/helpy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/helpyio/helpy.

What it runs against: a local clone of helpyio/helpy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in helpyio/helpy | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1188 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of helpyio/helpy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/helpyio/helpy.git
#   cd helpy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of helpyio/helpy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "helpyio/helpy(\\.git)?\\b" \\
  && ok "origin remote is helpyio/helpy" \\
  || miss "origin remote is not helpyio/helpy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "app/assets/javascripts/application.js" \\
  && ok "app/assets/javascripts/application.js" \\
  || miss "missing critical file: app/assets/javascripts/application.js"
test -f ".travis.yml" \\
  && ok ".travis.yml" \\
  || miss "missing critical file: .travis.yml"
test -f "Procfile" \\
  && ok "Procfile" \\
  || miss "missing critical file: Procfile"
test -f "app.json" \\
  && ok "app.json" \\
  || miss "missing critical file: app.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1188 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1158d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/helpyio/helpy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Helpy is an open-source Ruby on Rails helpdesk platform that integrates multichannel email ticketing, a searchable knowledgebase, and community support forums into a single unified system. It handles inbound email via Sendgrid/Mailgun/Mandrill, serves as a public-facing helpcenter with SEO-optimized articles, and provides agents with a web UI to manage support requests across all channels. Classic Rails monolith: app/ contains controllers, models, views, and assets (app/assets has images, SCSS in app/assets/stylesheets implied by 112k SCSS lines). Themes are handled separately for customization. Email integration is built into the core models. The Dockerfile and Procfile indicate production deployment is containerized and Heroku-ready.

Support teams and product companies who need to run their own self-hosted or cloud-deployed helpdesk instead of paying for SaaS solutions like Zendesk. Developers who want to customize or white-label a support platform without vendor lock-in, and contribute to an MIT-licensed open-source project.

Helpy is production-ready and actively maintained. It has 676k lines of Ruby code, CI/CD via Travis CI (.travis.yml present), code quality monitoring via CodeClimate, and documented deployment paths (HEROKU.md, Dockerfile, app.json for Heroku). The presence of CHANGELOG.md, UPDATING.md, and SECURITY.md indicates mature release management practices.

Single-maintainer risk exists (see SECURITY.md and Patreon sponsorship appeal), and the last visible commit recency is not shown in provided data, making staleness uncertain. The large monolithic Rails codebase (676k Ruby LOC) creates high maintenance burden and potential for deep architectural debt. Dependency management relies on Gemfile/Gemfile.lock without visible lock file age, and the Pro version suggests a split between open and commercial codebases that could diverge.

The repository is actively maintained with Docker support, Heroku deployment improvements (app.json, Heroku-specific docs), and compliance features (GDPR anonymization mentioned in README). Recent work includes linting setup (.eslintrc, .scss-lint.yml, .rubocop.yml, .hound.yml) suggesting code quality initiatives. No specific PR/milestone data visible, but the presence of CONTRIBUTING.md indicates active community engagement is desired.

git clone https://github.com/helpyio/helpy.git && cd helpy && bundle install && rails db:create && rails db:migrate && rails s -p 3000

Daily commands: rails server or rails s (port 3000 default). For production: use Procfile with Puma/web dyno, or docker build . && docker run. Background jobs are implied (no Sidekiq visible, likely ActiveJob with Delayed Job or similar).

• Gemfile — Declares all Ruby dependencies including Rails, email integration, and authentication gems that form the foundation of the helpdesk system.
• app/assets/javascripts/application.js — Main JavaScript manifest that loads all frontend assets and initializes the core application behavior across pages.
• .travis.yml — Defines the CI/CD pipeline and build requirements; understanding this clarifies how tests are run and code quality is enforced.
• Procfile — Specifies the process types (web, worker, etc.) that run the application; critical for understanding deployment and background job architecture.
• app.json — Heroku app manifest defining environment variables and addon dependencies; essential for understanding deployment configuration.
• CONTRIBUTING.md — Contribution guidelines and development setup instructions that every contributor must follow to maintain code quality standards.
• README.md — Project overview, feature list, and licensing information that establishes the scope and open-core business model of Helpy.

Add a new helpdesk ticket status

1. Define the new status as a constant in the Ticket model (app/models/ticket.rb (implied))
2. Create a database migration to add the status to tickets table (db/migrate/* (create new migration file))
3. Add the status to the admin status filter dropdown in the tickets view (app/views/admin/tickets/* (implied))
4. Update API serializer to include the new status in JSON responses (app/serializers/* (implied))

Integrate a new email service provider

1. Add the email provider gem to Gemfile and run bundle install (Gemfile)
2. Create a mailer configuration module in config/initializers (config/initializers/* (create new file, e.g., email_provider.rb))
3. Add provider credentials to environment variables and app.json (app.json)
4. Create an incoming email webhook handler in the Rails routes and controller (config/routes.rb (implied))

Add a new dashboard widget for agents

1. Create a new Vue or jQuery component in the admin JavaScript assets (app/assets/javascripts/admin.js (or new component file))
2. Add SCSS styling for the widget (app/assets/stylesheets/* (implied))
3. Create or update the admin dashboard view to include the widget (app/views/admin/* (implied))
4. Create a Rails API endpoint to serve the widget data (app/controllers/api/* (implied))

Customize the public-facing support widget

1. Modify the widget JavaScript file for v2 (latest implementation) (app/assets/javascripts/widget.v2.js)
2. Update widget styling assets (app/assets/images/widgets/* and app/assets/stylesheets/*)
3. Update widget initialization parameters in the main application (app/assets/javascripts/app.js (implied))
4. Document widget configuration options in README (README.md)

• Ruby on Rails — Provides rapid development of full-stack MVC application with built-in ORM, routing, and asset pipeline; well-suited for SaaS/helpdesk platforms.
• Email Integration (gems like actionmailer) — Essential for ticket lifecycle: receiving support emails, notifying agents, and sending responses to customers; core to helpdesk workflow.
• JavaScript (jQuery/Vue) for widgets — Enables embedded, lightweight widgets (v1 and v2) that can be integrated into customer websites without heavy dependencies.
• Docker & Heroku — Provides containerized deployment and zero-config cloud hosting, lowering barrier for self-hosted and managed instances.
• PostgreSQL (implied by Rails setup) — Robust relational database for complex ticket hierarchies, user relationships, and search indexing of knowledgebase articles.

• Open-core licensing (MIT base + premium features)

  • Why: Balance between community adoption and sustainable business model; allows redistribution while creating monetization via sponsorship.
  • Consequence: Contributors and users must understand which features are open vs. premium; potential complexity in feature parity testing.

• Monolithic Rails application over microservices

  • Why: Simpler operational model, faster development iteration, easier to deploy and maintain for small-to-medium support teams.
  • Consequence: Limited horizontal scaling for email processing or background jobs; would require refactoring into services as load increases.

• Embedded widgets (v1 & v2) bundled with app

  • Why: Simplifies integration and keeps UI centralized; users don't need separate CDN or deployment.
  • Consequence: Widget updates require app deployment; widget version compatibility must be managed carefully.

• Multiple linting & quality tools (.rubocop, .eslint, .hound, CodeClimate)

  • Why: Enforces code consistency and catches issues early in CI/CD pipeline; critical for open-source quality.
  • Consequence: Developer friction from tool configuration overhead; competing rulesets can create false positives.

• Real-time chat (uses ticketing model, not live messaging)
• AI-powered ticket routing or NLP auto-categorization (not mentioned in core features)
• Multi-tenant SaaS platform as a hosted service (designed for self-hosting and open-source deployment)
• Mobile-native apps (web/widget-only, responsive design assumed)

Email webhook security requires proper signing from Sendgrid/Mailgun/Mandrill (verify X-Sendgrid-Signature or equivalent). Database must be PostgreSQL (Rails default SQLite won't scale). Heroku deployment requires DATABASE_URL, SECRET_KEY_BASE, and SMTP credentials in environment. Asset pipeline requires rails assets:precompile in production. Themes may override core views in non-obvious places causing merge conflicts. Background job processor (Delayed Job or similar) must be running or tickets won't send. Multi-language support requires config/locales/*.yml files to be complete.

• Email webhook ingest (Sendgrid/Mailgun/Mandrill) — Helpy's core differentiator is turning inbound email into tickets; understanding webhook signatures, parsing headers, and creating ticket records from email is essential to contributing to the ticketing system
• Rails asset pipeline and theming — 112k SCSS and 114k JavaScript lines are managed via Sprockets; understanding how assets are bundled, precompiled, and overridden per theme is critical for UI changes
• ActionMailer and outbound SMTP — Agents respond to tickets via email; Helpy must construct and send HTML emails with attachments, requiring knowledge of ActionMailer configuration and SMTP credential rotation
• Internationalization (i18n) in Rails — README states 19 languages supported; the i18n gem manages locale files and translations, essential for adding new languages or fixing incomplete translations
• Background job processing (Delayed Job / ActiveJob) — Email sending and large knowledgebase indexing must be async; understanding how to enqueue and process background jobs prevents blocking request cycles
• Full-text search (PostgreSQL tsvector or Elasticsearch) — Knowledgebase and community forums require 'full text searchable' functionality; understanding how search indexes are built and queried is needed for feature additions
• GDPR data deletion and anonymization — README mentions 'GDPR Compliant'; implementing right-to-be-forgotten requests requires cascading deletes and PII scrubbing without breaking referential integrity or audit trails

• osTicket/osTicket — Established PHP-based open-source helpdesk; direct competitor solving the same self-hosted ticketing problem with different tech stack
• discourse/discourse — Ruby on Rails forum/community platform; Helpy borrows community features and shares Rails patterns, useful for understanding how public discussions are built
• chatwoot/chatwoot — Modern open-source customer communication platform written in Rails; similar architecture for multi-channel support, knowledgebase, and agent UI
• mailman-ng/mailman — Email handling and mailing list management in Python; shares the challenge of reliable email ingest/outbound, useful patterns for webhook processing
• helpyio/helpy-docker — Official Docker deployment companion repo for Helpy; if it exists, contains compose files and production setup guidance

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI/CD workflow to replace Travis CI (.travis.yml deprecation)

The repo uses .travis.yml for CI which is now deprecated. GitHub Actions is the modern standard for GitHub-hosted projects. This would modernize the build pipeline, improve integration with GitHub's ecosystem, and provide better visibility into test results directly in PRs. This is critical since .travis.yml exists but Travis CI has sunset free tier support.

• [ ] Create .github/workflows/test.yml with Rails test matrix (Ruby versions, databases)
• [ ] Add linting checks for .rubocop.yml, .eslintrc, and .scss-lint.yml configurations already present in repo
• [ ] Add CodeClimate coverage reporting step to replace Travis integration
• [ ] Remove .travis.yml once workflow is verified
• [ ] Test against Gemfile to ensure Rails dependencies run correctly

Add comprehensive test coverage for app/assets image optimization and accessibility

The repo contains 42+ icon files (app/assets/images/icons/001_*.png) and critical assets like favicon.ico, logos (helpy-logo.svg, helpy-logo.png), but there's no test coverage verifying these assets exist, are properly referenced, or meet accessibility standards. This prevents asset breakage and ensures brand consistency across deployments.

• [ ] Create spec/assets_spec.rb to verify all referenced images in app/assets/images exist
• [ ] Add tests that validate favicon.ico is properly linked in app layouts
• [ ] Add SVG alt-text validation tests for helpy-logo.svg and other decorative assets
• [ ] Verify all 42 icon files are used or document unused assets for cleanup
• [ ] Add test to ensure background images in cheatsheet-bg.png and collage3.png load correctly

Create Docker build validation and security scanning workflow

The repo has a Dockerfile and .dockerignore but no CI validation ensuring the Docker image builds successfully or scanning for vulnerabilities. This is critical for users deploying via Docker (especially since HEROKU.md suggests container deployment). Adding automated Docker security checks prevents supply chain attacks.

• [ ] Add .github/workflows/docker-build.yml that builds the Dockerfile on every push
• [ ] Integrate Trivy or similar tool to scan resulting image for CVEs in dependencies
• [ ] Add step to verify Procfile and app.json compatibility with Dockerfile CMD/ENTRYPOINT
• [ ] Test that docker build respects .dockerignore to verify image size optimization
• [ ] Document Docker image build process in CONTRIBUTING.md with security best practices

• Add missing test coverage for app/models/ticket.rb email ingest logic—no spec file visible in top 60, but email handling is core functionality that should be fully tested
• Improve documentation for custom theme creation in CONTRIBUTING.md or add a docs/THEMING.md file—README mentions 'easy to customize' but no guidance on app/themes/ structure visible
• Add missing locale translations for key features—README mentions 19 languages supported, but if config/locales/*.yml files are incomplete, adding translations for common UI strings (e.g., ticket status labels) is high-value and low-risk

Helpy has a moderate security posture with several notable concerns. The most critical issues are the use of outdated Ruby 2.5 (EOL) and the incomplete/suspicious Dockerfile configuration. The dependency on an

• High · Outdated Ruby Version in Docker — Dockerfile, line 1. The Dockerfile uses Ruby 2.5, which is significantly outdated and no longer receives security updates. Ruby 2.5 reached end-of-life in March 2020 and contains numerous known vulnerabilities. Fix: Upgrade to Ruby 3.2 or later. Ruby 2.5 is no longer maintained and does not receive security patches.
• High · Incomplete Dockerfile Command — Dockerfile, lines 30-32. The final RUN command in the Dockerfile appears truncated (ends with 'HE'). This suggests either a copy-paste error or incomplete configuration that could indicate malformed Docker builds and unpredictable behavior. Fix: Complete and review the sed command. The line appears to be cut off: '&& sed -i '128i\gem "helpy_slack"...' $HE' - verify the full command and $HELPY_HOME variable usage.
• High · Dependency on External Git Repository Without Version Pinning — Dockerfile, line 31. The Dockerfile dynamically adds the helpy_slack gem from a GitHub repository using the 'master' branch without version pinning. This creates a supply chain risk where changes to the master branch could introduce vulnerabilities or breaking changes. Fix: Pin to a specific commit hash or release tag instead of 'master' branch. Example: 'git: "https://github.com/helpyio/helpy_slack.git", ref: "v1.2.3"' or use a specific commit SHA.
• Medium · Missing Security Headers Configuration — Configuration files not visible in provided structure. No evidence of security headers (CSP, HSTS, X-Frame-Options, etc.) configuration visible in the provided configuration files. This increases XSS and clickjacking risks. Fix: Implement security headers in config/initializers/security_headers.rb or equivalent. Use gems like 'secure_headers' to enforce CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc.
• Medium · Potential Slack Integration Security Risk — Dockerfile, line 4. The Dockerfile unconditionally enables Slack integration via environment variable (HELPY_SLACK_INTEGRATION_ENABLED=true). If this gem or integration contains vulnerabilities, they would be enabled by default in production deployments. Fix: Default to disabled state (HELPY_SLACK_INTEGRATION_ENABLED=false) and require explicit opt-in. Perform security audit of the helpy_slack gem before enabling in production.
• Medium · Non-root User Privilege Separation Issue — Dockerfile, lines 9-23. While the Dockerfile creates a non-root user (helpyuser), there's no explicit verification that all operations execute as this user. The USER directive appears at the end but some RUN commands execute before it. Fix: Move 'USER $HELPY_USER' earlier in the Dockerfile, before any COPY operations that don't require root. Ensure all runtime operations execute as non-root.
• Low · Potential XXE/XML Injection Risk — Dockerfile, line 11. The application uses ImageMagick (installed in Dockerfile) which has a history of XXE vulnerabilities and other attack vectors when processing untrusted image files. No apparent input validation configuration visible. Fix: Validate and sanitize all image uploads. Configure ImageMagick security policies to restrict dangerous operations. Use gems like 'ruby-vips' as a safer alternative if appropriate for use cases.
• Low · Missing SECURITY.md Details — SECURITY.md. The SECURITY.md file provides email and Slack contact for vulnerability reporting, but lacks detail on response timelines, severity levels, or whether advisories are published. Fix: Expand SECURITY.md with clear vulnerability disclosure policy, expected response times, versioning scheme, and process for publishing security advisories.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.