I - Fresh Start: Security-first onboarding with AI assistant for new contributors

[DonnieBLT]

Idea I — First-Time Contributor Experience & AI-Assisted Security Guide

Idea Type: Single 350-hour development effort

One line: Security-first onboarding, documentation clarity, and an AI-assisted guide to help contributors understand BLT and OWASP expectations before contributing.

Description:
Improves BLT’s first-time contributor experience by addressing onboarding, navigation, and documentation gaps that lead to insecure or low-quality contributions. The idea introduces a clear
“start here” walkthrough for new users, security-focused information architecture, and contribution clarity pages that explain what qualifies as a security contribution and why PRs may be rejected.
Includes a constrained, explain-only AI Security Guide embedded into the website that answers contributor questions in beginner-friendly language using BLT documentation, GitHub Discussions,
and OWASP public resources (e.g. OWASP Top 10, Cheat Sheet Series). The AI does not review code, analyze diffs, approve PRs, or generate exploit guidance; it is strictly scoped to explanation,
clarification, and linking to authoritative sources.

Problem Statement
Current challenges observed in BLT onboarding and contribution flow:

• No clear starting point: First-time contributors land on BLT without a clear “start here” path explaining how the platform works from a security perspective.
• Security context is implicit: Security-critical pages, tools, and apps are listed alongside general features, making it hard to tell what matters first versus what is advanced.
• Fragmented documentation: Documentation exists across README files, GitHub Discussions, and OWASP resources, but is not clearly surfaced (e.g., broken Setup.md links).
• Unclear contribution expectations: Contributors often don’t understand what qualifies as a security contribution or why PRs get rejected.
• AI slop without understanding: With increased AI usage, contributors submit code without understanding whether it introduces security risks or violates OWASP principles.
• For a security-focused OWASP project, this leads to contributor frustration, reviewer overload, and avoidable security risk.

Solution: BLT First-Time Contributor Experience & Security Guide
A UI/UX-first onboarding and learning system, supported by a constrained, explain-only AI guide, designed to educate contributors before mistakes happen.
The solution focuses on clarity, guidance, and learning, not automation or enforcement.

Key components:
1 First-time user walkthrough (“New to BLT? Start Here”) explaining BLT’s security focus, contribution flow, common beginner mistakes, and next steps

• A dedicated onboarding page that acts as the single entry point for new contributors. It explains, step-by-step:
  What BLT is and why it is security-focused
  How a secure contribution works end-to-end (issue → fix → review → learning)
  What counts as a security contribution (with concrete examples)
  Common beginner mistakes (including AI copy-paste issues)
  Where contributors should go next (correct docs, repos, beginner-friendly issues)
  This reduces confusion and prevents insecure contributions before they are submitted.

2 Security-focused navigation and page annotations to distinguish beginner paths from advanced tools and apps

• Improves how BLT is structured and perceived by new users:
  Groups security-critical sections clearly and visibly Adds short “why this matters” explanations to major areas Distinguishes beginner paths
  from advanced tools and apps This makes BLT’s security-first nature immediately obvious.
• Example: Security Contributions: Pages related to finding, fixing, and understanding security issues (Bugs, Issues,...)
  Learn & Understand: Pages that explain how security works in BLT (Documentation, “New to BLT? Start Here”, AI Security Guide,...)
  Contribute & Collaborate: Pages related to working with others (Projects, Repositories, GitHub links, Teams,...)
  Advanced / Platform Tools: Pages that are not for beginners (SimilarityScan, Time Logs, Check-In, Staking, BACON, Admin / stats tools

3 Documentation surfacing and fixes (repair broken links, define canonical entry points)

• Surfaces and organizes existing knowledge rather than creating new theory:
  Fixes broken documentation links and defines canonical entry points
  Adds clarity pages such as:
  “What counts as a security contribution?”
  “Why PRs get rejected at BLT”
  Uses plain, beginner-friendly language and anonymized real examples to explain security expectations
  This turns rejections into learning, not frustration.

4 Embedded AI Security Guide for contextual, beginner-friendly explanations grounded in BLT + OWASP content

• An embedded, context-aware AI Security Guide that acts as a smart help layer, not a general chatbot.
  What it does:
  Answers contributor questions in beginner-friendly language
  Explains OWASP concepts and BLT contribution rules
  Points users to relevant BLT docs, GitHub Discussions, and OWASP resources

• What it does NOT do:
  Review code or analyze diffs
  Approve or reject PRs
  Generate exploit guidance or security fixes

• The AI is grounded only in:
  BLT documentation and contribution guidelines
  BLT GitHub Discussions
  Well-established OWASP resources (e.g., OWASP Top 10, Cheat Sheet Series)
  All responses are source-linked and auditable.

Scope notes

• Frontend and UX heavy (React / Next.js / Tailwind)
• Light GitHub API usage (public data only)
• No vulnerability scanning, no PR automation, no model training from scratch
• AI is constrained, auditable, and source-linked

Impact:
Fewer insecure or misunderstood PRs
Better first-time contributor experience
Reduced reviewer burden
Stronger alignment with OWASP’s secure-by-design and education mission

Why this matters now
As AI-assisted coding becomes common, understanding why something is insecure is more important than ever. This idea ensures BLT remains a place where contributors learn security — not just ship code and aligns well with BLT's goals for 2026.

[mdkaifansari04]

Solid architecture and should be focused. But it should be desinged in such a way that it should not be strict with BLT, but any could use it for their starting guide. Open source community is dealing with problem from a while now, on-boardung a new contributor to their project.

Addional opinion:

• video solution / all setup video should be placed in term of course and early contributor / new to open source could take help from that.
• it will reference BLT-education in lot module for early contributor.
• gamification stuff so the contributor didn't get bored or just complete it as school homework.

could be a potential idea for gsoc.

[Nachiket-Roy]

I think L2 and I might not be necessary as standalone projects. We can keep onboarding simple and clean with well-structured documentation, which we already largely have. If something is unclear or needs improvement, that’s the beauty of an OSS project contributors are welcome to raise a PR and improve it.

[Shhazzz]

Appreciate the review and suggestions!

But just to clarify, the main idea is an AI guide with a lightweight, optional UI walkthrough for first-time visitors/users/contributors. Something similar to (click on live demo) https://introjs.com/ where users can click “New to BLT? Start Here” and see short explanations different section like - Issues, Check-In, BACON, Bounties, Staking, Domains, etc. this can help reduce initial confusion when someone lands on BLT page and sees may features at once.
The goal is not really to rewrite documentation or restrict exploration but simply to reduce the initial confusion by providing a smoother entry point. For deeper understanding, we point users to relevant docs. The tour would be skippable and accessible again later if needed.

The AI guide would act as a supporting layer, mainly to explain security concepts in simple terms, clarify jargon, and pointing users to relevant docs when needed. It won't review code or replace existing tools like CR, instead help reduce repetitive questions for maintainers and first-time contributors.
Regarding Kaif’s suggestion, I agree this shouldn’t be restricted only to BLT. The guidance structure can be designed in a configurable way so other OSS projects could reuse the same pattern.

Would love to discuss this further and refine it wherever needed based on community feedback. I hope I understood your points correctly. @mdkaifansari04 @Nachiket-Roy

[Nachiket-Roy]

Alright, we can consider adding a lightweight UI walkthrough for first-time users, but that should come after the core systems are properly in place. It probably doesn’t need to be treated as a separate standalone project.

[Nachiket-Roy]

I don’t think we can decide how other OSS projects should structure their onboarding.

[karunarapolu]

I think this project is a really good idea since BLT is confusing for a first timer, but yes I think maybe we should wait until core systems are properly in place. And yes, we can't decide about other OSS projects.

[Shhazzz]

yeah, makes sense!! so based on discussion, we could start by treating AI guide as the core work and the UI walkthrough could be added on at a later stage.
As for AI guide, we won’t hardcode specific flows, instead it'd rely on BLT docs, discussions, and public GitHub APIs (for repo metadata, discussions, etc.) so it stays aligned even if workflows evolve. Currently the idea is to keep it explain-only (can be expanded carefully based on suggestions if needed).
This will probably take a significant amount of time, so by the time it's stable BLT’s core systems should be clearer maybe... At that point, we can skip areas that are still changing and only add a UI walkthrough for stable sections. Once the AI guide is stable and integrated, we can then implement the UI part and once everything is in place it would likely require only small adjustments here and there not major rework i think.

Regarding structure, I agree we shouldn’t design this assuming reuse across other OSS projects so definitely the primary goal remains BLT. However, if designed cleanly, parts of the AI guide’s structure could be made configurable (via data/config files). That way, BLT keeps a constrained version tailored to its needs, and if ever useful, a more general version could optionally be open-sourced for reuse by simply changing links/content sources. But that would simply be a by-product of good design, not the main objective. If it feels unnecessary, we can drop that idea entirely. This is just an idea if we are considering anything for other projects.
Let me know if this better addresses the concerns or if ya'll suggest we refine the direction further. @karunarapolu @Nachiket-Roy @mdkaifansari04 @DonnieBLT

[Shhazzz]

this could be the potential timeline..

Phase 1: Understanding & Design (Weeks 1–2 | ~40h)

Study BLT docs, pages, discussions
Identify common first-time confusion points
Decide what the AI can and cannot answer
Define guardrails (explain-only, no exploits)

Phase 2: AI Guide Core (Weeks 3–7 | ~160–180h)

Building the AI interface (chat/help panel)
Connecting it to: BLT documentation, GitHub discussions, GitHub public APIs (read-only)
Teaching it to: Explain BLT features in simple words, Simplify security jargon, Summarize long docs
Redirect users to the right place (docs, Sorting Hat, discussions)
Strong safety rules (no exploit guidance, no code review)

Phase 3: Integration Across BLT Pages (Weeks 8–9 | ~50–60h)

Improve response clarity based on feedback
Improve UX triggers

Phase 4: UI Walkthrough (Weeks 10–11 | ~40–50h)

Intro.js-style walkthrough
Only stable sections
Skippable, optional
Small explanations, no heavy logic
Output: smoother first-time experience, low maintenance

Phase 5: Testing, Polish, Docs (Weeks 12 | ~30–40h)

Edge cases
Accessibility checks
Final documentation
Handover notes

[Nachiket-Roy]

or combine W and I.