Feat/separate reference and walkthrough

[kOaDT]

Description

Splits the per-challenge documentation into two distinct roles:

• content/vulnerabilities/*.md — in-app reference doc rendered at /vulnerabilities/<slug> after the player finds the flag. Focuses on the concept and the fix.
• docs/src/data/blog/*.md — walkthrough on the Astro docs site. Focuses on step-by-step exploitation with payloads and screenshots.

Before this PR the two were ~70% redundant. Now each has a clear lane and a cross-link from the in-app reference page to the matching walkthrough.

What changes

1. In-app vulnerability page (app/vulnerabilities/[slug]/page.tsx)

• Hero shows the humanized vulnerability name (e.g. "SQL Injection") instead of the raw flag value.
• Category surtitle added.
• Callout under the hero linking to the walkthrough on the docs site when flag.walkthroughSlug is set.
• DOCS_BASE_URL extracted to lib/config.ts so the dashboard and vulnerability pages share one source of truth.

2. /flags page (app/flags/page.tsx, app/flags/FlagsClient.tsx)

• Flag values are now masked behind a "Locked — solve to reveal" pill until the player has actually found that flag.
• Found flags display the value in plain text with a small "Found" badge.
• Spoiler warning replaced with a neutral info banner explaining the masking and pointing to the flag checker.
• Search no longer matches flag values for unfound challenges (no leak via filter).

3. Reference doc rewrite (32 files in content/vulnerabilities/)

• Each file now follows the same structure: Overview / Why This Is Dangerous / Vulnerable Code / Secure Implementation / References.
• Removed from every file: step-by-step exploitation, attack payloads, flag values (OSS{...}), screenshot references, "How to Retrieve the Flag" sections.
• Kept: vulnerable code snippets from the codebase, root-cause explanation, fix examples, external references (OWASP, CWE, PortSwigger, CVE).
• Net result: −1744 lines across the markdowns. Less surface area to drift, no spoilers in the in-app doc.

4. Contribution guides aligned

• CONTRIBUTING.md, AGENTS.md, and .github/PULL_REQUEST_TEMPLATE.md updated to make the role split explicit and to mention walkthroughSlug for new challenges.

Type of change

• Bug fix
• New feature (e-commerce site improvement)
• New vulnerability / flag
• Walkthrough / writeup
• Documentation update
• Other: refactor of content/ to remove exploit details and flag values from in-app docs

Testing done

• npx tsc --noEmit clean
• npx eslint clean on all modified .ts/.tsx files
• npx prettier --check clean across the diff
• Manual smoke test:
  • /flags with no flags found → all cards show "Locked" pill, info banner reads correctly.
  • /flags after submitting a valid flag via the flag checker → that card flips to plain-text value + green "Found" badge.
  • /vulnerabilities/sql-injection → hero shows "SQL Injection" + Injection surtitle, callout points to https://koadt.github.io/oss-oopssec-store/posts/sql-injection-writeup, body has no flag value and no exploit steps.
  • Player dashboard "DOCS" and "WALKTHROUGH" links still work (shared DOCS_BASE_URL).
• grep -l 'OSS{' content/vulnerabilities/*.md → no matches (no flag values left in any reference doc).

Checklist

• Documentation updated (if applicable)

If adding a new vulnerability

• Flag added in prisma/seed.ts with format OSS{...}
• Three progressive hints added in prisma/seed.ts
• Vulnerable code path is exploitable and demonstrable
• Markdown documentation added under content/vulnerabilities/
• Regression tests added (unit, API, and/or E2E)
• No real-world secrets introduced

[github-actions]

Thank you @kOaDT for contributing once again!

📊 PR overview

Files changed	Additions	Deletions	Size
42	+1459	-3203	XL

📝 Before review

To help maintainers review your changes efficiently, please ensure that:

• The PR description clearly explains what was changed and why
• The PR checklist has been filled out
• All existing tests continue to pass
• New tests have been added for any new functionality

📖 Please review our Contributing Guidelines and Code of Conduct.

✅ Continuous Integration

Two CI workflows will run automatically on this PR:

• Code Quality — linting and formatting checks
• Exploitation Tests — ensures vulnerabilities and flags work as expected

You can follow their progress in the Checks tab.

🤝 A note on collaboration

We value respectful and constructive interactions. Whether you are a contributor or a reviewer, please be patient, kind, and open to feedback.

---

A maintainer will review your changes as soon as possible. If you have any questions, feel free to ask in this thread.

kOaDT