AOSSIE-Org · shubham5080 · Aug 21, 2026 · Aug 17, 2026 · Aug 18, 2026
diff --git a/QUICK_START_GUIDE.txt b/QUICK_START_GUIDE.txt
@@ -1,52 +1,65 @@
-GITCORD BOT - QUICK START GUIDE
-================================
-
-1. LINK YOUR GITHUB ACCOUNT (Required First Step)
----------------------------------------------------
-Type in Discord: /link
-• Bot will DM you a verification code
-• Comment that code on any GitHub issue/PR
-• Return to Discord and type: /verify-link
-
-2. AVAILABLE COMMANDS
--------------------
-/link               - Start GitHub identity linking
-/verify-link        - Complete identity verification  
-/unlink             - Remove your GitHub link
-/status             - Check your linked GitHub account
-/metrics            - View your contribution stats
-/request-issue      - Request an issue assignment (needs mentor approval)
-/assign-issue       - Directly assign yourself to an issue (mentors only)
-/sync               - Manually sync data (mentors only)
-/issue-requests     - View pending issue requests (mentors only)
-
-3. HOW TO REQUEST AN ISSUE
---------------------------
-1. Find an issue on GitHub you want to work on
-2. Copy the issue URL
-3. In Discord type: /request-issue <paste-url>
-4. A mentor will review and approve your request
-5. Once approved, the issue is assigned to you on GitHub
-
-4. FOR MENTORS
---------------
-• /assign-issue <url> - Instantly assign issue to yourself or others
-• /sync - Refresh all data and apply pending changes
-• /issue-requests - View all pending requests from contributors
-
-5. HOW SCORING WORKS
---------------------
-• PR merged = +10 points (base)
-• Difficulty labels adjust score (easy/medium/hard)
-• Quality bonuses: PR review (+2), helpful comment (+1)
-• Quality penalties: Reverted PR (-5), failed CI merge (-3)
-• Top contributors get Discord roles automatically
-
-6. TIPS
+GITCORD — QUICK START GUIDE
+===========================
+
+Gitcord links Discord and GitHub for verified contributors, then helps with
+profiles, contribution summaries, PR lookups, and scheduler notifications.
+
+Works in the AOSSIE and Stability Nexus Discord servers (separate bot stacks).
+
+
+1. LINK YOUR GITHUB ACCOUNT (required first)
+--------------------------------------------
+In Discord:
+
+  /link github_username:<your-github-login>
+
+• Bot replies (ephemeral) with a short verification code and a Verify button
+• Paste that code into your GitHub profile bio OR a public gist
+• Click Verify in Discord, or run: /verify-link github_username:<same-login>
+
+Tips:
+• Code is short-lived — if it expires, run /link again
+• You can remove the code from your bio/gist after you are verified
+• Need to switch accounts? /unlink, then /link again
+
+
+2. CONTRIBUTOR COMMANDS
+-----------------------
+/link                 Link Discord → GitHub (get verification code)
+/verify-link          Complete verification after placing the code
+/profile              Your (or another member’s) Gitcord profile
+/who-is               Look up a GitHub username → Discord + link freshness
+/summary              Contribution metrics (7d / 30d); optional member
+/open-prs             List currently open PRs for a contributor
+/pr                   Recent PRs by closed / merged / open (count, skip)
+/connect-social       Attach X or LinkedIn username/URL to your profile
+/disconnect-social    Remove X or LinkedIn from your profile
+/unlink               Remove your GitHub link
+
+
+3. MENTOR COMMAND
+-----------------
+/sync                 Manually sync GitHub events and send notifications
+                      (requires a mentor role from discord.command_permissions)
+
+
+4. WHAT HAPPENS AFTER YOU VERIFY
+--------------------------------
+• Scheduler cycles ingest GitHub activity for configured repos
+• Notifications go to verified Discord users only (DMs / mapped channels)
+• /profile and /summary use your verified GitHub identity
+• Org settings may live in the org’s .github/gitcord.yaml (remote config)
+
+
+5. TIPS
 -------
-• Must be verified (/link + /verify-link) to use most commands
-• Use /metrics to track your progress
-• Request issues early - they're assigned on first-come basis
-• Stay active to maintain contributor roles
+• Most commands need a verified link — start with /link
+• Use /profile to confirm you are verified and see socials/roles
+• Use /who-is when you know a GitHub login but not the Discord account
+• Use /pr or /open-prs for PR status without leaving Discord
+• Mentors: prefer dry-run / observer modes for bulk GitHub writes
+
 
-Need help? Type /status to check your verification status.
+Need help?
+• Docs: README.md, docs/IDENTITY_VERIFICATION.md, INSTALLATION.md
+• Discord: #gitcord (AOSSIE) — ask maintainers or open a GitHub issue
diff --git a/README.md b/README.md
@@ -84,8 +84,8 @@ Gitcord is a local, offline‑first automation engine that reads GitHub activity
 4. [Brand kit](brand/Brand.md) - Logo, colors, typography, icons
 5. [Maintainers](MAINTAINERS.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Best Practices](BestPracticesChecklist.md)
 6. [AOSSIE Discord — Gitcord thread](https://discord.com/channels/1022871757289422898/1465995983791063140)
-4. [Technical Documentation](TECHNICAL_DOCUMENTATION.md) - Architecture and design
-5. [Docker Guide](docs/DOCKER.md) - Docker setup and mentor-friendly deployment
+7. [Technical Documentation](TECHNICAL_DOCUMENTATION.md) - Architecture and design
+8. [Docker Guide](docs/DOCKER.md) - Docker setup and mentor-friendly deployment
 
 ---
 
@@ -277,6 +277,8 @@ Wait 30 seconds for commands to sync.
 
 ## 🤖 Discord Bot Commands
 
+Contributor-facing cheat sheet: [`QUICK_START_GUIDE.txt`](QUICK_START_GUIDE.txt).
+
 ### Identity Linking
 
 - `/link` - Link your Discord account to GitHub (creates verification code)