Implement In-App Help System with Contextual UX Guidance

[unclesp1d3r]

Problem Statement

HashHive currently has no in-app help system. Users navigating the web interface have no contextual guidance for key workflows — creating cracking campaigns, managing hash lists, configuring agents, or interpreting results. This creates onboarding friction and increases support burden for maintainers.

Proposed Solution

Implement a multi-tier in-app help system integrated into the web UI:

1. Contextual Tooltips / Popovers — Inline ? icons on key form fields and UI controls that surface short explanations on hover/click, without leaving the current view.
2. Guided Walkthroughs (Tours) — Step-by-step interactive tours for primary workflows:
   • Creating and running a cracking campaign
   • Importing/exporting hash lists
   • Enrolling and managing agents
   • Reviewing and exporting crack results
3. Help Sidebar / Modal — A global help panel (accessible via toolbar icon or ? keyboard shortcut) with searchable articles covering common tasks and FAQs.
4. Onboarding Wizard — First-run wizard for new users covering initial setup: agent enrollment and first campaign creation.

Implementation Notes

• Prefer a lightweight JS library for tour functionality (e.g., Shepherd.js or Intro.js) to avoid heavy bundle size increases.
• Help content should be co-located with their respective components for easier maintenance and review.
• All help copy must be versioned alongside the codebase to stay in sync with UI changes across releases.
• Help assets should be lazy-loaded to avoid any performance regression on initial page load.

Acceptance Criteria

• Contextual tooltips present on all major form fields and action buttons across core views
• At least 3 guided tours covering core workflows (campaign creation, hash management, agent enrollment)
• Global help panel accessible via toolbar button and ? keyboard shortcut
• First-run onboarding wizard shown on new installations / first login
• Help content renders correctly at all supported viewport sizes (responsive)
• No significant performance regression — help assets must be lazy-loaded
• Help content is co-located with components and tracked in version control

Related Areas

• Frontend UI components
• Campaign management workflow (campaign-management)
• Hash management workflow (hash-management)
• Agent management workflow (agent-management)

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context and a proposed solution. Improve the issue title and assign the proper labels and other metadata.

[unclesp1d3r]

@coderabbitai If there are any really good 3rd-party libraries or integrations that do this now, we should use them, rather than hand-rolling our own.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Fetch issue `#244` details
gh issue view 244 --repo EvilBit-Labs/hash_hive --json title,body,labels,assignees,milestone,state,author

echo "---LABELS---"
# Fetch all available labels
gh label list --repo EvilBit-Labs/hash_hive --json name,description,color

echo "---MILESTONES---"
gh api repos/EvilBit-Labs/hash_hive/milestones --jq '.[] | {title: .title, number: .number}'

Length of output: 3533

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

REPO="EvilBit-Labs/hash_hive"
ISSUE=244

NEW_TITLE="Implement In-App Help System with Contextual UX Guidance"

NEW_BODY='## Problem Statement

HashHive currently has no in-app help system. Users navigating the web interface have no contextual guidance for key workflows — creating cracking campaigns, managing hash lists, configuring agents, or interpreting results. This creates onboarding friction and increases support burden for maintainers.

## Proposed Solution

Implement a multi-tier in-app help system integrated into the web UI:

1. **Contextual Tooltips / Popovers** — Inline `?` icons on key form fields and UI controls that surface short explanations on hover/click, without leaving the current view.
2. **Guided Walkthroughs (Tours)** — Step-by-step interactive tours for primary workflows:
   - Creating and running a cracking campaign
   - Importing/exporting hash lists
   - Enrolling and managing agents
   - Reviewing and exporting crack results
3. **Help Sidebar / Modal** — A global help panel (accessible via toolbar icon or `?` keyboard shortcut) with searchable articles covering common tasks and FAQs.
4. **Onboarding Wizard** — First-run wizard for new users covering initial setup: agent enrollment and first campaign creation.

## Implementation Notes

- Prefer a lightweight JS library for tour functionality (e.g., [Shepherd.js](https://shepherdjs.dev/) or [Intro.js](https://introjs.com/)) to avoid heavy bundle size increases.
- Help content should be co-located with their respective components for easier maintenance and review.
- All help copy must be versioned alongside the codebase to stay in sync with UI changes across releases.
- Help assets should be lazy-loaded to avoid any performance regression on initial page load.

## Acceptance Criteria

- [ ] Contextual tooltips present on all major form fields and action buttons across core views
- [ ] At least 3 guided tours covering core workflows (campaign creation, hash management, agent enrollment)
- [ ] Global help panel accessible via toolbar button and `?` keyboard shortcut
- [ ] First-run onboarding wizard shown on new installations / first login
- [ ] Help content renders correctly at all supported viewport sizes (responsive)
- [ ] No significant performance regression — help assets must be lazy-loaded
- [ ] Help content is co-located with components and tracked in version control

## Related Areas

- Frontend UI components
- Campaign management workflow (`campaign-management`)
- Hash management workflow (`hash-management`)
- Agent management workflow (`agent-management`)'

# Edit the issue
gh issue edit "$ISSUE" \
  --repo "$REPO" \
  --title "$NEW_TITLE" \
  --body "$NEW_BODY" \
  --add-label "epic,feature,frontend,documentation" \
  --add-assignee "unclesp1d3r"

echo "Issue #$ISSUE updated."
gh issue view "$ISSUE" --repo "$REPO" --json title,labels,assignees

Length of output: 3794

---

---

@unclesp1d3r Issue #244 has been updated:

Changes applied:

Field	Before	After
Title	Create a user help guide available via the UX	Implement In-App Help System with Contextual UX Guidance
Labels	type:feature	type:feature, epic, feature, frontend, documentation
Assignee	—	unclesp1d3r
Body	One-sentence stub	Full structured spec (see below)

Body now includes:

• Problem Statement — Frames the onboarding friction and support burden
• Proposed Solution — Four-tier system: contextual tooltips, guided tours, help sidebar, onboarding wizard
• Implementation Notes — Library recommendations (Shepherd.js / Intro.js), co-location of help content, lazy-loading requirement
• Acceptance Criteria — 7 checkboxed items covering all tiers and non-functional requirements
• Related Areas — Cross-links to campaign-management, hash-management, agent-management workflows

View the updated issue: #244

[coderabbitai]

Oops, something went wrong! Please try again later. 🐰 💔