From 120c49d24d6663da2a04f324438bbd3137f84575 Mon Sep 17 00:00:00 2001
From: Ravi Kishan <ravikishan63392@gmail.com>
Date: Fri, 29 May 2026 17:15:29 +0530
Subject: [PATCH 1/2] Enchancing the content in beginners projects

---
 improvements.md                               | 367 +++++++++++
 .../projects/Beginners/asciiartgenerator.mdx  | 295 ++++++---
 .../projects/Beginners/automatedfilemover.mdx | 477 +++++++-------
 .../projects/Beginners/basic-calendar-app.mdx | 602 +++++++++---------
 .../projects/Beginners/basic-text-editor.mdx  | 510 +++++++++------
 .../projects/Beginners/basicalarmclock.mdx    | 296 ++++++---
 .../docs/projects/Beginners/basicchatbot.mdx  | 507 ++++++++-------
 .../projects/Beginners/basicmusicplayer.mdx   | 308 ++++++---
 .../projects/Beginners/basicwebcrawler.mdx    | 317 ++++++---
 .../projects/Beginners/basicwebscrapper.mdx   | 463 +++++++-------
 .../projects/Beginners/basicwebserver.mdx     | 307 +++++++--
 .../projects/Beginners/binarytodecimal.mdx    | 456 +++++++------
 .../docs/projects/Beginners/blackjack.mdx     | 396 +++++++-----
 .../docs/projects/Beginners/calculatorgui.mdx | 355 +++++++----
 .../projects/Beginners/currencyconverter.mdx  | 332 +++++++---
 .../currencyexchnageratecalculator.mdx        | 295 +++++++--
 .../docs/projects/Beginners/dicerolling.mdx   | 188 +++++-
 .../docs/projects/Beginners/emailsender.mdx   | 426 +++++++------
 .../projects/Beginners/fibonaccisequence.mdx  | 384 ++++++-----
 .../docs/projects/Beginners/fileexplorer.mdx  | 379 +++++++----
 .../projects/Beginners/guessthenumber.mdx     | 232 +++++--
 .../docs/projects/Beginners/hangman.mdx       | 442 ++++++++-----
 .../docs/projects/Beginners/helloworld.mdx    | 180 +++++-
 .../Beginners/json-data-validator.mdx         | 597 ++++++++---------
 .../Beginners/morsecodetranslator.mdx         | 430 ++++++-------
 .../Beginners/movie-recommendation-system.mdx | 516 +++++++--------
 .../Beginners/numberguessingwithai.mdx        | 250 ++++++--
 src/content/docs/projects/Beginners/paint.mdx | 283 +++++---
 .../Beginners/passwordstrengthchecker.mdx     | 394 +++++++-----
 .../docs/projects/Beginners/personaldiary.mdx | 367 +++++++----
 .../docs/projects/Beginners/quizapp.mdx       | 459 ++++++-------
 .../Beginners/randompasswordgenerator.mdx     | 330 ++++++----
 .../projects/Beginners/rockpaperscissors.mdx  | 265 +++++---
 .../docs/projects/Beginners/rssfeedreader.mdx | 300 ++++++---
 .../projects/Beginners/simple-blog-system.mdx | 504 ++++++++-------
 .../projects/Beginners/simplecalculator.mdx   | 236 +++++--
 .../projects/Beginners/simplereminderapp.mdx  | 351 ++++++----
 .../projects/Beginners/simplestopwatch.mdx    | 432 +++++++------
 .../docs/projects/Beginners/tempconv.mdx      | 296 +++++++--
 .../Beginners/textbasedadventuregame.mdx      | 378 +++++++----
 src/content/docs/projects/Beginners/todo.mdx  | 378 +++++++----
 .../docs/projects/Beginners/todolist.mdx      | 534 ++++++++--------
 .../docs/projects/Beginners/urlshorter.mdx    | 359 +++++++----
 .../Beginners/webpagecontentdownloader.mdx    | 393 ++++++------
 .../Beginners/webpagescrapernotifications.mdx | 355 +++++++----
 .../docs/projects/Beginners/wordcounter.mdx   | 349 ++++++----
 46 files changed, 10760 insertions(+), 6510 deletions(-)
 create mode 100644 improvements.md

diff --git a/improvements.md b/improvements.md
new file mode 100644
index 00000000..f4cecbfd
--- /dev/null
+++ b/improvements.md
@@ -0,0 +1,367 @@
+# PythonCentralHub — Improvements, Bugs & Roadmap
+
+> Comprehensive audit of the PythonCentralHub site (Astro Starlight, https://pythoncentralhub.live).
+> Findings grouped by category. Each item lists **file:line where applicable**, **what's wrong**, and **suggested fix**.
+
+---
+
+## 1. Bugs & Errors
+
+### 1.1 Print button destroys DOM and forces reload
+- **File:** `src/components/Footer.astro:142-146`
+- **Issue:** `document.body.innerHTML = printContent.innerHTML; window.print(); document.body.innerHTML = mainContent;` then calls `window.location.reload()`. This wipes event listeners, loses form state, and the reload is harsh.
+- **Fix:** Use a CSS `@media print` stylesheet that hides non-content elements, then call `window.print()` natively. No DOM mutation, no reload.
+
+### 1.2 Share button has no fallback
+- **File:** `src/components/Footer.astro:111-129`
+- **Issue:** `navigator.share` is not supported in desktop Firefox/older browsers. Current path shows "Not supported!" with no alternative.
+- **Fix:** Fall back to `navigator.clipboard.writeText(location.href)` and show a toast "Link copied".
+
+### 1.3 Environment variables interpolated without fallback
+- **File:** `astro.config.mjs:140, 222, 264-265, 287-288`
+- **Issue:** `import.meta.env.VITE_GOOGLE_ANALYTICS`, `VITE_GOOGLE_ADSENSE`, `VITE_MONETAG` are dropped into script `src` and meta `content` with no guard. If env var is missing, the URL becomes `...?id=undefined` and ad/analytics requests 404 silently.
+- **Fix:** Conditionally include those tags only when the env var is truthy. Example:
+  ```js
+  ...(import.meta.env.VITE_GOOGLE_ANALYTICS ? [{ tag: "script", attrs: {...} }] : [])
+  ```
+
+### 1.4 DataCamp iframe message listener missing null guards
+- **File:** `src/components/DataCampExercise.astro:212-222, 252-254`
+- **Issue:** `event.data.type` and `event.data.id` accessed without checking `event.data` is an object. Fullscreen handler queries `originalFrame` then accesses `.sandbox` / `.srcdoc` without a null check.
+- **Fix:** Guard with `if (!event.data || typeof event.data !== 'object') return;` and `if (!originalFrame) return;`.
+
+### 1.5 Mermaid plugin swallows errors
+- **File:** `lib/mermaid/remake.ts:58-99`
+- **Issue:** `renderDiagram()` calls inside `Promise.all` are not wrapped in try/catch. A single bad diagram silently fails — no fallback SVG, no console warning to the user.
+- **Fix:** Wrap each render in try/catch; on failure emit an inline `<pre>` with the original mermaid source plus an error comment.
+
+### 1.6 Weak ID generation in forms
+- **File:** `src/components/Contact.astro:97-99`, `src/components/Feedback.astro:177-179`
+- **Issue:** `Date.now().toString(36) + Math.random().toString(36).substr(2)` — `substr` is deprecated; not collision-safe under high concurrency.
+- **Fix:** Use `crypto.randomUUID()` (supported in all modern browsers).
+
+### 1.7 Toast helper uses `innerHTML`
+- **File:** `public/scripts/toast.js`
+- **Issue:** Title/description passed into `innerHTML`. If toast ever surfaces user-controlled text (form errors, comment input), this is an XSS vector.
+- **Fix:** Use `textContent` for strings; allow markup only via a separate `html: true` opt-in.
+
+### 1.8 Self-referential package dependency
+- **File:** `package.json:21`
+- **Issue:** `"pythoncentralhub": "file:"` references the package itself. Confuses `npm install` on fresh clones.
+- **Fix:** Remove the line unless this is intentional for a monorepo layout (not currently the case).
+
+### 1.9 `astro check` not in build chain everywhere
+- **File:** `package.json:8`
+- **Issue:** Build runs `astro check && astro build` locally, but no CI enforces it.
+- **Fix:** Add a GitHub Action that runs `npm run build` on PR.
+
+### 1.10 Service worker is empty
+- **File:** `public/sw.js`
+- **Issue:** PWA manifest links a service worker but the file is empty — no offline support, no cache strategy.
+- **Fix:** Either implement a real `workbox-window` strategy (cache-first for fonts/assets, stale-while-revalidate for HTML) or remove the SW + manifest reference.
+
+---
+
+## 2. Security
+
+### 2.1 Firebase config hardcoded client-side
+- **File:** `src/components/Contact.astro:82-88`, `src/components/Feedback.astro:161-167`
+- **Issue:** Firebase config is public by design, but exposing apiKey + projectId in source means the security boundary is **entirely** in Firestore Security Rules. If rules are loose, anyone can read/write.
+- **Fix:**
+  1. Audit Firestore Security Rules — restrict writes to authenticated users or to a specific collection with rate-limited fields.
+  2. Add App Check (reCAPTCHA v3 or Play Integrity) to block non-browser traffic.
+  3. Move shared init into `src/lib/firebase.ts` so config lives in one place.
+
+### 2.2 No CSP / no SRI on third-party scripts
+- **File:** `astro.config.mjs:124-128, 262-320`
+- **Issue:** FontAwesome CSS, GTM, AdSense, DataCamp, Mermaid all loaded from external CDNs without `integrity=` hashes or a Content Security Policy.
+- **Fix:**
+  1. Add CSP via deploy headers (Vercel/Netlify `_headers` file or middleware): `script-src 'self' https://www.googletagmanager.com https://pagead2.googlesyndication.com https://cdn.datacamp.com https://cdn.jsdelivr.net;` etc.
+  2. Generate SRI hashes for static third-party assets and add `integrity` + `crossorigin="anonymous"`.
+
+### 2.3 Forms post directly to Firestore — no rate limit, no captcha
+- **File:** `src/components/Contact.astro`, `src/components/Feedback.astro`
+- **Issue:** Spam bots can write to Firestore at will.
+- **Fix:** Add reCAPTCHA v3 to both forms, validate token on a Cloud Function before write. Or front the writes with a server route.
+
+### 2.4 `<form>` has no `action` and relies entirely on JS
+- **File:** `src/components/Contact.astro:14`, `src/components/Feedback.astro:9`
+- **Issue:** If JS fails to load, form silently does nothing.
+- **Fix:** Either add a server endpoint that handles the POST (graceful degradation) or `e.preventDefault()` + clearly indicate JS requirement.
+
+### 2.5 External link `target="_blank"` without `rel`
+- **File:** `src/components/YoutuberCard.astro:99-101`
+- **Issue:** Reverse-tabnabbing risk.
+- **Fix:** Add `rel="noopener noreferrer"`.
+
+---
+
+## 3. Performance
+
+### 3.1 Astro 3.2.3 is two majors behind
+- **File:** `package.json:19`
+- **Issue:** Astro 5 ships View Transitions, Content Layer API, faster builds, smaller runtime. Starlight 0.12 is also old (current 0.30+).
+- **Fix:** Plan a migration: bump Astro → 4 → 5 incrementally, then Starlight. Many breaking changes — schedule a dedicated branch.
+
+### 3.2 Five render-blocking custom font CSS files
+- **File:** `astro.config.mjs:101-107`
+- **Issue:** Poppins, Atkinson, Source, Fira, plus global — all blocking. No `font-display: swap`, no preload.
+- **Fix:**
+  1. Add `font-display: swap;` to every `@font-face` in those CSS files.
+  2. Preload only the single primary weight: `<link rel="preload" as="font" type="font/woff2" crossorigin href="...">`.
+  3. Consider self-hosting via Fontsource or dropping a font family.
+
+### 3.3 FontAwesome `all.min.css` loaded globally
+- **File:** `astro.config.mjs:124-128`
+- **Issue:** Full FontAwesome (~100KB CSS + huge font files) loaded on every page; site only uses a handful of icons.
+- **Fix:** Replace with inline SVGs from a single icon set (Lucide / Heroicons), or import only the icons used.
+
+### 3.4 DataCamp JS + CSS loaded on every page
+- **File:** `astro.config.mjs:312-320`
+- **Issue:** `dcl-react.js.gz` and `dcl-react.css` are pulled into the global `<head>` even on pages without exercises.
+- **Fix:** Move those tags into the `DataCampExercise.astro` component itself (Astro automatically hoists them) or dynamically inject the script when the component mounts via `IntersectionObserver`.
+
+### 3.5 Mermaid loaded everywhere with `startOnLoad: true`
+- **File:** `public/scripts/mermaid.js`
+- **Issue:** Mermaid library is downloaded and initialized on pages with zero diagrams.
+- **Fix:** In a `<BaseHead>` or layout, check if the page contains `.mermaid` blocks (build-time flag in frontmatter, or set a global) and only inject the script then.
+
+### 3.6 Pyodide is heavy and downloaded on first click
+- **File:** `public/scripts/python-playground.js`
+- **Issue:** Pyodide is ~10MB compressed. First-click latency is several seconds with no progress feedback.
+- **Fix:**
+  1. Use `requestIdleCallback` to start the Pyodide download in the background after page load.
+  2. Show a progress bar in the playground modal while loading.
+  3. Cache via service worker (see 1.10).
+
+### 3.7 Images lack `loading="lazy"` and responsive sizing
+- **File:** `src/components/YoutuberCard.astro:84-93`, content MDX images
+- **Issue:** Eagerly loaded; no `srcset`.
+- **Fix:** Add `loading="lazy"` and `decoding="async"`. For author images, use Astro's `<Image>` component to auto-generate responsive variants.
+
+### 3.8 Google Adsense + GTM not deferred behind consent
+- **File:** `astro.config.mjs:263-290`
+- **Issue:** Marked `async`, but they still contend with critical resource fetching.
+- **Fix:** Inject after `DOMContentLoaded` or use Partytown to push them to a web worker.
+
+---
+
+## 4. UI / UX
+
+### 4.1 Form feedback is `alert()`
+- **File:** `src/components/Contact.astro:122-124`, `src/components/Feedback.astro`
+- **Issue:** Browser `alert()` is jarring, blocks the page, looks unprofessional.
+- **Fix:** Use the existing `window.toast.show(...)` helper for success/error. Add a loading spinner on the submit button while the request is in flight.
+
+### 4.2 No visible focus styles on icon buttons
+- **File:** `src/components/Footer.astro:106-152`
+- **Issue:** Share/print buttons only have `:hover`. Keyboard users can't tell which is focused.
+- **Fix:** Add `:focus-visible { outline: 2px solid var(--sl-color-accent-high); outline-offset: 2px; }`.
+
+### 4.3 Required field indicators missing
+- **File:** `src/components/Feedback.astro:45-82`, `src/components/Contact.astro`
+- **Issue:** `required` attribute set, but no visual marker (no asterisk) and no `aria-required`.
+- **Fix:** Add `<span class="text-red-500">*</span>` next to required field labels and `aria-required="true"`.
+
+### 4.4 Placeholder text is generic Flowbite boilerplate
+- **File:** `src/components/Contact.astro:26`
+- **Issue:** `name@flowbite.com` and similar placeholders look unfinished.
+- **Fix:** Replace with project-relevant examples: `you@example.com`, `Your full name`, etc.
+
+### 4.5 Radio buttons in Feedback hidden with no focus state
+- **File:** `src/components/Feedback.astro:11-43`
+- **Issue:** Radios are `display: none`; emoji labels are clickable but keyboard users can't see focus.
+- **Fix:** Use `position: absolute; opacity: 0;` instead of `display: none` so they remain focusable, then style `input:focus-visible + label` with a ring.
+
+### 4.6 404 page is a dead end
+- **File:** `src/content/docs/404.mdx`
+- **Issue:** No search, no popular-pages list, no navigation suggestions.
+- **Fix:** Add: a search bar (Starlight `<Search />` if extractable), links to Guides / Projects / Tutorials index, an "edit on GitHub" link in case the page should exist.
+
+### 4.7 No "Copied!" feedback on code blocks
+- **File:** Site-wide
+- **Issue:** Starlight's copy button exists but the success state may be subtle.
+- **Fix:** Verify checkmark/toast appears for ≥1.5s; otherwise add custom feedback.
+
+---
+
+## 5. Accessibility
+
+### 5.1 Alt text contains image URLs
+- **File:** `src/components/YoutuberCard.astro:85-92`
+- **Issue:** `alt="${coverImg}-${name}"` — screen readers literally read the URL.
+- **Fix:** `alt="${name} channel cover image"` and `alt="${name} profile picture"`.
+
+### 5.2 No skip-to-content link
+- **File:** Site layout
+- **Issue:** Keyboard users tab through nav on every page load.
+- **Fix:** Add `<a href="#main" class="sr-only focus:not-sr-only">Skip to content</a>` at the top of the layout.
+
+### 5.3 Hardcoded text colors break dark mode
+- **File:** `src/components/YoutuberCard.astro:56, 63-73`
+- **Issue:** `color: #222` on a card that sits on the page background — in dark mode the card is light and the contrast inverts unpredictably.
+- **Fix:** Use Starlight CSS variables: `var(--sl-color-text)`, `var(--sl-color-bg-nav)`.
+
+### 5.4 Form errors lack `aria-live` regions
+- **File:** `src/components/Contact.astro`, `src/components/Feedback.astro`
+- **Issue:** Validation messages won't be announced to screen readers.
+- **Fix:** Add `<div role="alert" aria-live="polite" id="form-error">` and write messages there.
+
+### 5.5 Mermaid diagrams have no text alternative
+- **File:** `lib/mermaid/render-diagram.ts`
+- **Issue:** Rendered SVG has no `<title>` or `aria-label`.
+- **Fix:** Inject the original mermaid source as a `<title>` or `aria-label` on the SVG root for screen reader users.
+
+---
+
+## 6. SEO
+
+### 6.1 Single OG image for all 300+ pages
+- **File:** `astro.config.mjs:112-115`
+- **Issue:** `/og.png?v=1` is shared across every page — social shares look identical.
+- **Fix:** Generate per-page OG images at build time using Satori / `@vercel/og` based on page title + category.
+
+### 6.2 No structured data (JSON-LD)
+- **File:** Site-wide
+- **Issue:** No `Article`, `Course`, `BreadcrumbList`, `HowTo` schemas.
+- **Fix:** Add a Starlight component override that emits JSON-LD per page based on frontmatter (`type: tutorial | project | guide`).
+
+### 6.3 No RSS feed
+- **File:** None
+- **Issue:** Hundreds of pages, no syndication.
+- **Fix:** Add `@astrojs/rss` and emit at `/rss.xml` — include tutorials and project pages.
+
+### 6.4 Sitemap lacks `lastmod` / `priority`
+- **File:** `astro.config.mjs:326`
+- **Issue:** Default sitemap plugin emits flat priorities.
+- **Fix:** Configure sitemap with `serialize` to set `lastmod` from frontmatter `updated`, higher priority for index/guides.
+
+### 6.5 No canonical verification
+- **File:** Starlight default
+- **Issue:** Starlight should emit canonicals but worth verifying after any custom head changes.
+- **Fix:** Curl a few pages, confirm `<link rel="canonical">` is present and correct.
+
+### 6.6 No `lastUpdated` shown on content
+- **File:** Frontmatter / Starlight config
+- **Issue:** Readers can't tell if a tutorial is current.
+- **Fix:** Enable Starlight's `lastUpdated: true` config and set `git` strategy.
+
+---
+
+## 7. Tooling / DX
+
+### 7.1 No lint / format / test scripts
+- **File:** `package.json:5-10`
+- **Fix:** Add:
+  ```json
+  "lint": "eslint . --ext .ts,.astro,.tsx",
+  "format": "prettier --write .",
+  "typecheck": "astro check",
+  "test": "vitest"
+  ```
+- Add `eslint-plugin-astro`, `prettier-plugin-astro`, base configs.
+
+### 7.2 No CI workflow
+- **File:** `.github/workflows/` (missing)
+- **Fix:** Add `.github/workflows/ci.yml` running `npm ci && npm run typecheck && npm run build` on PR.
+
+### 7.3 No Dependabot / Renovate
+- **File:** `.github/dependabot.yml` (missing)
+- **Fix:** Add Dependabot config for npm weekly updates.
+
+### 7.4 No pre-commit hooks
+- **File:** None
+- **Fix:** Add Husky + lint-staged for Prettier-on-commit.
+
+### 7.5 Root-level Python helper scripts
+- **Files:** `fix_code_blocks.py`, `fix_python_filenames.py`, `scaffold_exercises.py`
+- **Fix:** Move to `scripts/` and add a one-line entry to README documenting each.
+
+### 7.6 README out of date
+- **File:** `README.md`
+- **Fix:** Update with: current stack (Astro Starlight), local dev steps (`npm i && npm run dev`), folder structure, deployment notes, contribution guide pointer.
+
+### 7.7 Missing `CONTRIBUTING.md`
+- **Fix:** Document how to add a project guide (folder + frontmatter conventions), tutorial, fix a typo.
+
+### 7.8 Loose version constraints
+- **File:** `package.json`
+- **Issue:** `^` allows minor bumps; combined with stale lockfile this means surprising regressions.
+- **Fix:** Lock the file in CI (`npm ci`), pin majors of riskier deps (Starlight especially).
+
+---
+
+## 8. Content Hygiene
+
+### 8.1 No automated broken-link checking
+- **Fix:** Add `linkinator` or `lychee` in CI to crawl built site.
+
+### 8.2 No alt-text audit
+- **Fix:** Add a build-time check (custom remark plugin) that fails if any MDX image lacks alt text.
+
+### 8.3 No frontmatter validation
+- **File:** `src/content/config.ts`
+- **Fix:** Tighten Zod schema — require `description` (140–160 chars), `category`, `difficulty` for project pages.
+
+### 8.4 Code blocks without language tags
+- **Fix:** Build-time check (or `fix_code_blocks.py` extended) flagging untagged ``` blocks.
+
+---
+
+## 9. Missing Features / Roadmap
+
+Things the site does **not** have today that would meaningfully improve it. Roughly ordered by impact.
+
+### High impact
+- [ ] **Full-text search** beyond Starlight's local index — Algolia DocSearch or Pagefind, with analytics on queries.
+- [ ] **Comments / discussion** — Giscus (GitHub Discussions) under each tutorial.
+- [ ] **Edit on GitHub** link per page — pull from `src/content/docs/...` relative path.
+- [ ] **Last updated date** displayed on every doc.
+- [ ] **Prev / next** navigation at the bottom of each page in a section.
+- [ ] **Related content** — manually curated or tag-based recommendations at page end.
+- [ ] **Breadcrumbs** above the page title.
+- [ ] **Table of contents** with active-section highlight (Starlight supports it, verify enabled on all pages).
+- [ ] **Per-page OG images** generated at build time.
+- [ ] **RSS feed** for new content.
+
+### Medium impact
+- [ ] **Newsletter signup** (Buttondown, ConvertKit, or self-hosted via Resend + Firestore).
+- [ ] **Code playground on every Python tutorial** — embed the existing Pyodide playground inline below code blocks (opt-in via frontmatter `runnable: true`).
+- [ ] **Difficulty & duration badges** on project cards (driven by frontmatter).
+- [ ] **Tag-based browsing** (`/tags/machine-learning`, etc.).
+- [ ] **Series / learning path** grouping — order tutorials into curricula.
+- [ ] **Bookmark / favorites** (localStorage; no auth needed).
+- [ ] **Progress tracking** — mark tutorial as completed (localStorage to start).
+- [ ] **Light/dark code block theme switcher** synced with site theme.
+- [ ] **Print stylesheet** (replaces 1.1 fix and serves as a real feature).
+
+### Low impact / future
+- [ ] **User accounts** (only if multi-device progress sync becomes a clear need).
+- [ ] **Achievements / gamification.**
+- [ ] **Discussion forum** beyond per-page comments.
+- [ ] **Translations (i18n)** — Starlight supports multi-language; needs translator volunteers.
+- [ ] **Interactive notebooks** (JupyterLite alternative to Pyodide for richer projects).
+- [ ] **Course completion certificates.**
+- [ ] **Mobile app** (PWA improvements first — install prompt, offline reading of completed tutorials).
+- [ ] **Quiz / knowledge check** at the end of each tutorial.
+
+### Infra & operations
+- [ ] **Lighthouse CI** on PRs.
+- [ ] **Bundle analyzer** in CI to flag JS regressions.
+- [ ] **Web Vitals reporting** wired to analytics.
+- [ ] **Error tracking** (Sentry) on the client.
+- [ ] **Status page / uptime monitoring** for the site and Firebase backend.
+- [ ] **Backup strategy** for Firestore feedback/contact submissions.
+
+---
+
+## 10. Suggested Sequence
+
+1. **Critical security & correctness (week 1)** — items 1.3, 1.4, 2.3, 2.5, plus audit Firestore Security Rules.
+2. **Performance quick wins (week 1–2)** — items 3.2, 3.3, 3.4, 3.5, 3.7.
+3. **Tooling (week 2)** — items 7.1, 7.2, 7.3, 7.4 so future changes are safer.
+4. **Accessibility pass (week 2–3)** — section 5 in full.
+5. **UX polish (week 3)** — section 4 in full, plus copy/print fixes (1.1, 1.2).
+6. **Astro / Starlight upgrade (week 3–4)** — item 3.1 on its own branch.
+7. **SEO uplift (week 4)** — section 6.
+8. **Roadmap features** — pick from section 9 based on user feedback.
diff --git a/src/content/docs/projects/Beginners/asciiartgenerator.mdx b/src/content/docs/projects/Beginners/asciiartgenerator.mdx
index d43b3066..d1ea16a8 100644
--- a/src/content/docs/projects/Beginners/asciiartgenerator.mdx
+++ b/src/content/docs/projects/Beginners/asciiartgenerator.mdx
@@ -1,6 +1,6 @@
 ---
 title: ASCII Art Generator
-description: A Python program that converts text into ASCII art using different fonts and colors. Users can customize the style and color of their ASCII art and save it to a file.
+description: Turn any text into colorful ASCII art with Python using pyfiglet and termcolor. Learn external libraries, font systems, terminal colors, file I/O, and how to convert real images into ASCII too.
 sidebar: 
     order: 14
 hero:
@@ -13,36 +13,38 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-ASCII Art Generator is a fun Python program that converts text into ASCII art using various fonts and colors. The program uses the `pyfiglet` library to generate ASCII text art and `termcolor` to add colors. Users can choose from multiple font styles, customize colors, and save their ASCII art to a file. This is a great project for beginners to learn about external libraries and file handling in Python.
+ASCII art is the ancient practice of drawing pictures with text characters. It started in the typewriter era, exploded in the BBS days, and is still a charming way to dress up CLI tools, terminal banners, and Git commit messages. In this project you will build a Python ASCII Art Generator that turns any text into stylized character art with dozens of fonts, applies terminal colors, and saves the result to a file. Then we will go further — converting real images into ASCII using pixel brightness mapping.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- pyfiglet module
-- termcolor module
-- colorama module
+You will learn:
+- How to install and use external libraries (`pyfiglet`, `termcolor`, `colorama`).
+- How fonts work in `pyfiglet` and where to discover the 500+ available ones.
+- How terminal colors are rendered with ANSI escape codes.
+- How to save styled output to a plain-text file without color codes leaking in.
+- How to turn a JPEG into ASCII using pixel-brightness mapping.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download). You must have the required modules installed on your computer. If you don't have these modules installed, you can install them by using the following commands in your terminal.
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- A terminal that supports ANSI color codes (Windows Terminal, iTerm2, GNOME Terminal — anything modern).
 
-```cmd title="command" showLineNumbers{1} {1-3}
-C:\Users\Your Name>pip install pyfiglet
-C:\Users\Your Name>pip install termcolor
-C:\Users\Your Name>pip install colorama
+## Install Dependencies
+```cmd title="install"
+pip install pyfiglet termcolor colorama
 ```
+- **`pyfiglet`** — Python port of the classic FIGlet program; provides the fonts.
+- **`termcolor`** — convenience wrapper for ANSI color codes.
+- **`colorama`** — makes ANSI codes work on legacy Windows terminals. (Optional on modern systems, but harmless.)
 
 ## Getting Started
-#### Create a Project
+
+### Create the project
 1. Create a folder named `ascii-art-generator`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `asciiartgenerator.py`.
-4. Copy the given code and paste it in your `asciiartgenerator.py` file.
+2. Inside it, create `asciiartgenerator.py`.
 
-## Write the Code
-1. Copy and paste the following code in your `asciiartgenerator.py` file.
+### Write the code
 <FileCode file="projects/beginners/asciiartgenerator.py" lang="python" title="ASCII Art Generator" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `ascii-art-generator`.
+
+### Run it
 ```cmd title="command" showLineNumbers{1} {1-20}
 C:\Users\Your Name\ascii-art-generator> python asciiartgenerator.py
 ASCII Art Generator
@@ -64,78 +66,197 @@ y
 Enter the name of the file: 
 hello.txt
 File saved successfully!
-Do you want to clear the screen? (y/n)
-n
-Thank you for using ASCII Art Generator!
 ```
 
-## Explanation
-1. Import the required modules.
-```python title="asciiartgenerator.py" showLineNumbers{1} {1-5}
-import pyfiglet # pip install pyfiglet
-import termcolor # pip install termcolor
+## Step-by-Step Explanation
+
+### 1. Imports
+```python title="asciiartgenerator.py"
+import pyfiglet
+import termcolor
 import colorama
 import os
+colorama.init()             # Windows ANSI shim — harmless elsewhere
+```
+`colorama.init()` swaps `sys.stdout` for a translating wrapper that turns ANSI codes into Windows console API calls on older Windows. On modern terminals it is a no-op.
+
+### 2. Collect text, color, font
+```python title="asciiartgenerator.py"
+text = input("Text: ")
+color = input("Color: ")
+font = input("Font (e.g. big, slant, banner): ")
+```
+`termcolor` accepts: `grey`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`.
+
+### 3. Generate the art
+```python title="asciiartgenerator.py"
+ascii_art = pyfiglet.figlet_format(text, font=font)
+print(termcolor.colored(ascii_art, color=color))
+```
+- `figlet_format(text, font=...)` returns a multi-line ASCII string.
+- `termcolor.colored(...)` wraps it in ANSI codes for the requested color.
+
+### 4. Save it
+```python title="asciiartgenerator.py"
+if input("Save? (y/n) ").lower() == "y":
+    filename = input("Filename: ")
+    with open(filename, "w", encoding="utf-8") as f:
+        f.write(ascii_art)              # NOTE: plain art, no color codes
+    print("Saved.")
+```
+Saving the **uncolored** version is intentional — ANSI escape codes look like garbage when opened in a text editor. If you really want the colors persisted, save with the escape codes included; viewing in `cat` will preserve them.
+
+### 5. Optional: clear the screen
+```python title="asciiartgenerator.py"
+if input("Clear screen? (y/n) ").lower() == "y":
+    os.system("cls" if os.name == "nt" else "clear")
+```
+`os.name == "nt"` is True on Windows; otherwise we assume a Unix-like terminal.
+
+## Discovering Fonts
+
+`pyfiglet` ships with around 500 fonts. List them all:
+
+```python title="list_fonts.py"
+import pyfiglet
+for f in pyfiglet.FigletFont.getFonts():
+    print(f)
+```
+Or preview one:
+```python title="preview.py"
+print(pyfiglet.figlet_format("Hello", font="slant"))
 ```
+Memorable fonts to try: `slant`, `big`, `banner`, `block`, `bubble`, `digital`, `doom`, `epic`, `isometric1`, `larry3d`, `lean`, `nancyj`, `ogre`, `roman`, `script`, `shadow`, `small`, `standard`, `starwars`, `stop`.
+
+## Input Validation
+
+The naive script crashes on a misspelled font. Wrap it:
+```python title="safe_font.py"
+available = set(pyfiglet.FigletFont.getFonts())
+while True:
+    font = input("Font: ").strip()
+    if font in available:
+        break
+    print(f"Unknown font '{font}'. Try one of: slant, big, banner, …")
+```
+Same for color:
+```python title="safe_color.py"
+VALID_COLORS = {"grey","red","green","yellow","blue","magenta","cyan","white"}
+while True:
+    color = input("Color: ").strip().lower()
+    if color in VALID_COLORS:
+        break
+    print(f"Pick one of: {', '.join(VALID_COLORS)}")
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `pyfiglet.FontNotFound` | Misspelled font name | Validate against `getFonts()` |
+| `KeyError: 'orange'` | termcolor only knows eight colors | Use one of the supported names |
+| Garbled colors on Windows | Old Windows terminal | `colorama.init()` once at startup |
+| Saved file has weird `` characters | Saved the colored string | Save the plain `ascii_art`, not `colored_ascii` |
+| Wide output wraps awkwardly | Terminal narrower than the font width | Use a narrower font (`small`, `mini`) or widen the terminal |
+
+## Variations to Try
+
+### 1. Rainbow text
+Cycle through colors line by line:
+```python title="rainbow.py"
+COLORS = ["red","yellow","green","cyan","blue","magenta"]
+for i, line in enumerate(ascii_art.splitlines()):
+    print(termcolor.colored(line, COLORS[i % len(COLORS)]))
+```
+
+### 2. Random font each run
+```python title="random_font.py"
+import random
+font = random.choice(pyfiglet.FigletFont.getFonts())
+```
+
+### 3. CLI flags with argparse
+```python title="cli.py"
+python asciiartgenerator.py "Hello" --font slant --color red --out hello.txt
+```
+Use Python's `argparse` library instead of `input()`.
+
+### 4. Convert a real image to ASCII
+A real image becomes ASCII by mapping pixel brightness to characters from dark to light:
+```python title="image_to_ascii.py"
+from PIL import Image
+
+CHARS = "@%#*+=-:. "        # dark → light
+
+def image_to_ascii(path, width=80):
+    img = Image.open(path).convert("L")           # grayscale
+    aspect = img.height / img.width
+    height = int(width * aspect * 0.55)           # chars are taller than wide
+    img = img.resize((width, height))
+    out = []
+    for y in range(height):
+        row = "".join(CHARS[int(img.getpixel((x, y)) / 255 * (len(CHARS) - 1))]
+                      for x in range(width))
+        out.append(row)
+    return "\n".join(out)
+
+print(image_to_ascii("photo.jpg"))
+```
+- `convert("L")` turns the image to 8-bit grayscale (0–255).
+- We scale brightness into the index range of `CHARS`.
+- The 0.55 factor compensates for terminal characters being roughly twice as tall as wide.
+
+### 5. Animated text
+```python title="animate.py"
+import time, os
+words = ["Hello", "World", "Python"]
+for w in words:
+    os.system("cls" if os.name == "nt" else "clear")
+    print(pyfiglet.figlet_format(w, font="big"))
+    time.sleep(0.8)
+```
+
+### 6. Banner in your shell prompt
+Print a small ASCII banner from your `.bashrc` / PowerShell profile every time a new shell starts.
+
+### 7. Web service
+Wrap with Flask (see [Basic Web Server](./basicwebserver)) so visitors POST text and get ASCII back.
+
+### 8. GUI version
+Tkinter with an entry field, a dropdown of fonts, a color picker, and a multi-line text widget showing the result.
+
+## How ANSI Colors Work
+
+Behind the scenes, "red text" is a short escape sequence:
+```
+\x1b[31mHello\x1b[0m
+```
+- `\x1b` is the ESC character.
+- `[31m` says *"foreground = red"*.
+- `[0m` resets to default at the end.
+
+Terminals interpret these codes and color the text; text files just show the raw characters. That is why we save the **plain** ASCII art to disk — to keep it portable.
+
+## Real-World Applications
+- **CLI tool banners** — projects like Docker, npm, and Git all print stylized ASCII at startup.
+- **README art** — a one-line `pyfiglet` call generates great GitHub headers.
+- **CTF / hacking flair** — security tools love a good banner.
+- **Image-to-ASCII previews** for terminals that cannot render images.
+- **Email signatures** in plain-text-only environments.
 
-2. Create the main function that handles ASCII art generation.
-```python title="asciiartgenerator.py" showLineNumbers{1} {1-10}
-def asciiartgenerator():
-    print("ASCII Art Generator")
-    print("Enter the text to convert to ASCII Art: ")
-    text = input()
-    print("Enter the color of the text: ")
-    color = input()
-```
-
-3. Display available font styles for the user to choose from.
-```python title="asciiartgenerator.py" showLineNumbers{1} {1-50}
-print('''
-3-d	
-3x5	
-5lineoblique
-acrobatic
-alligator
-# ... more font options
-''')
-```
-
-4. Generate ASCII art with the selected font and color.
-```python title="asciiartgenerator.py" showLineNumbers{1} {1-5}
-font = input()
-asciiart = pyfiglet.figlet_format(text, font=font)
-colored_asciiart = termcolor.colored(asciiart, color=color)
-print(colored_asciiart)
-```
-
-5. Optional file saving functionality.
-```python title="asciiartgenerator.py" showLineNumbers{1} {1-10}
-print("Do you want to save the ASCII Art? (y/n)")
-save = input()
-if save == 'y':
-    print("Enter the name of the file: ")
-    filename = input()
-    with open(filename, 'w') as f:
-        f.write(colored_asciiart)
-    print("File saved successfully!")
-```
-
-## Features
-- Convert text to ASCII art using various fonts
-- Add colors to your ASCII art
-- Choose from 50+ different font styles
-- Save ASCII art to a file
-- User-friendly command-line interface
-- Option to clear screen after generation
+## Educational Value
+- **External library usage** — installing, importing, reading docs.
+- **Terminal output** — escape codes, cross-platform differences.
+- **File I/O** — saving text safely.
+- **Image processing** — converting pixel data to character art.
+- **User experience** — validation, prompts, friendly error messages.
 
 ## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Creating a web version using Flask
-- Adding more color options and effects
-- Implementing font preview functionality
-- Adding support for multi-line text input
-- Creating preset font and color combinations
+- Add **multi-line input** support (until the user enters an empty line).
+- Build the **image-to-ASCII** variation above into a separate command.
+- Wrap in a **CLI with argparse** for power users.
+- Combine with **Tkinter** to make a desktop banner-generator.
+- Publish on **PyPI** as a `python asciibanner` command.
 
 ## Conclusion
-In this project, we learned how to create an ASCII Art Generator using Python. We used external libraries like `pyfiglet` for text-to-ASCII conversion and `termcolor` for adding colors. This project demonstrates file handling, user input processing, and working with external libraries. To find more projects like this, you can visit Python Central Hub.
+You used three external libraries, generated styled text, saved it safely, and learned how terminals render color along the way. The same techniques (pixel-to-char mapping, escape sequences, font tables) underlie far more impressive demos — but every one of them starts with `figlet_format("Hello", font="big")`. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/asciiartgenerator.py). Find more visual projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/automatedfilemover.mdx b/src/content/docs/projects/Beginners/automatedfilemover.mdx
index a076bd66..d6d03ff3 100644
--- a/src/content/docs/projects/Beginners/automatedfilemover.mdx
+++ b/src/content/docs/projects/Beginners/automatedfilemover.mdx
@@ -1,6 +1,6 @@
 ---
 title: Automated File Mover
-description: A Python script that automatically organizes files by moving them from a source directory to a destination directory based on file types and extensions.
+description: Build a Python script that auto-sorts files into folders by extension. Learn pathlib, conflict handling, watchdog for real-time monitoring, dry-run mode, and a path to a full file-organizer service.
 sidebar: 
     order: 26
 hero:
@@ -13,289 +13,272 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Automated File Mover is a Python script that helps organize files by automatically moving them from a source directory to a destination directory based on their file extensions. The script targets specific file types (text, PDF, and image files) and provides feedback on each file moved. This project demonstrates file system operations, directory manipulation, and automated organization tasks. It's an excellent tool for maintaining clean directories and automating repetitive file management tasks.
+The Downloads folder is the universal Python beginner's enemy. Hundreds of mixed files — receipts, screenshots, installers, random PDFs — piled in one place. In this project you build a script that scans a source directory and routes each file to a typed destination folder (`Documents/`, `Images/`, `Videos/`, `Archives/`, `Code/`). Then we make it robust: conflict resolution for duplicate names, logging, dry-run mode, recursive scanning, real-time watching with `watchdog`, and a scheduled run via cron / Task Scheduler.
+
+You will leave with:
+- Clean use of **`pathlib`** instead of string concatenation.
+- A reusable file-type registry.
+- Patterns for safely renaming on conflict.
+- Dry-run mode — the difference between a careful script and a destructive one.
+- A real-time watcher for `Downloads/`.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Read/write permissions for target directories
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with file paths.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-**Note:** This project uses only built-in Python modules (`os` and `shutil`), so no additional installations are required.
+### Create the project
+1. Create folder `file-organizer`.
+2. Inside, create `automatedfilemover.py`.
+3. Create `source/` and `destination/` subfolders. Drop a few test files into `source/`.
 
-### Directory Setup
-Before running the script, create the following directory structure:
-```
-project-folder/
-├── automatedfilemover.py
-├── source/          (create this folder and add test files)
-└── destination/     (create this folder - files will be moved here)
-```
+### Write the code
+<FileCode file="projects/beginners/automatedfilemover.py" lang="python" title="File Mover" />
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `automated-file-mover`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `automatedfilemover.py`.
-4. Create two subfolders: `source` and `destination`.
-5. Add some test files to the `source` folder (e.g., test.txt, image.png, document.pdf).
-6. Copy the given code and paste it in your `automatedfilemover.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `automatedfilemover.py` file.
-<FileCode file="projects/beginners/automatedfilemover.py" lang="python" title="Automated File Mover" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `automated-file-mover`.
-```cmd title="command" showLineNumbers{1} {1-10}
-C:\Users\Your Name\automated-file-mover> python automatedfilemover.py
-Moved document.txt to C:\Users\Your Name\automated-file-mover\destination\document.txt
-Moved report.pdf to C:\Users\Your Name\automated-file-mover\destination\report.pdf
-Moved photo.png to C:\Users\Your Name\automated-file-mover\destination\photo.png
-Moved image.jpg to C:\Users\Your Name\automated-file-mover\destination\image.jpg
+### Run it
+```cmd title="command"
+C:\Users\Your Name\file-organizer> python automatedfilemover.py
+Moved document.txt → destination/document.txt
+Moved photo.png → destination/photo.png
+Moved report.pdf → destination/report.pdf
 Move Complete
-
-# All files with supported extensions are moved from source/ to destination/
 ```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Code Breakdown
-1. **Import required modules for file operations.**
-```python title="automatedfilemover.py" showLineNumbers{1} {1-2}
-import os
+### 1. Imports — switch to `pathlib`
+```python title="automatedfilemover.py"
 import shutil
+from pathlib import Path
 ```
-
-2. **Set up source and destination directory paths.**
-```python title="automatedfilemover.py" showLineNumbers{1} {1-2}
-source = os.getcwd() + "/source/"
-destination = os.getcwd() + "/destination/"
+The original used `os` + string concatenation (`source + file`). `pathlib`:
+- Is OS-agnostic (`/` works everywhere).
+- Returns `Path` objects with useful methods (`.suffix`, `.stem`, `.exists()`).
+- Catches errors at object construction, not at use.
+
+### 2. The simple version
+```python title="automatedfilemover.py"
+SOURCE = Path("source")
+DEST = Path("destination")
+WANTED_EXTENSIONS = {".txt", ".pdf", ".png", ".jpg", ".jpeg"}
+
+DEST.mkdir(exist_ok=True)
+for file in SOURCE.iterdir():
+    if file.is_file() and file.suffix.lower() in WANTED_EXTENSIONS:
+        target = DEST / file.name
+        shutil.move(str(file), str(target))
+        print(f"Moved {file.name} → {target}")
+print("Move complete.")
 ```
-
-3. **Get list of files in the source directory.**
-```python title="automatedfilemover.py" showLineNumbers{1} {1}
-files = os.listdir(source)
+- `file.suffix` includes the leading dot (`.pdf`), and `.lower()` normalizes case.
+- `DEST / file.name` joins paths properly.
+- `mkdir(exist_ok=True)` does not error if the folder already exists.
+
+## Sort Into Typed Sub-folders
+
+The naïve version dumps everything into one destination. The interesting version routes by file type:
+
+```python title="categories.py"
+CATEGORIES = {
+    "Documents": {".pdf", ".txt", ".doc", ".docx", ".odt", ".rtf"},
+    "Spreadsheets": {".xls", ".xlsx", ".csv", ".ods"},
+    "Images":    {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"},
+    "Videos":    {".mp4", ".mov", ".avi", ".mkv", ".webm"},
+    "Audio":     {".mp3", ".wav", ".ogg", ".flac", ".m4a"},
+    "Archives":  {".zip", ".rar", ".7z", ".tar", ".gz"},
+    "Code":      {".py", ".js", ".ts", ".html", ".css", ".java", ".cpp"},
+    "Installers":{".exe", ".msi", ".dmg", ".deb", ".rpm", ".pkg"},
+}
+
+def category_for(suffix: str) -> str:
+    for cat, exts in CATEGORIES.items():
+        if suffix in exts:
+            return cat
+    return "Other"
+
+for file in SOURCE.iterdir():
+    if not file.is_file(): continue
+    cat = category_for(file.suffix.lower())
+    target_dir = DEST / cat
+    target_dir.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(file), str(target_dir / file.name))
 ```
-
-4. **Define target file types for organization.**
-```python title="automatedfilemover.py" showLineNumbers{1} {1}
-file_types = ["txt", "pdf", "png", "jpg", "jpeg"]
+Now `report.pdf` lands in `destination/Documents/`, `photo.png` in `destination/Images/`, etc.
+
+## Conflict Resolution
+
+What if `destination/Images/photo.png` already exists? The naïve `shutil.move` overwrites it silently — a quiet way to lose files.
+
+```python title="conflict.py"
+def unique_path(target: Path) -> Path:
+    if not target.exists(): return target
+    stem, suffix, parent = target.stem, target.suffix, target.parent
+    counter = 1
+    while True:
+        candidate = parent / f"{stem}_{counter}{suffix}"
+        if not candidate.exists():
+            return candidate
+        counter += 1
 ```
-
-5. **Move files based on their extensions.**
-```python title="automatedfilemover.py" showLineNumbers{1} {1-6}
-for file in files:
-    for file_type in file_types:
-        if file.endswith(file_type):
-            shutil.move(source + file, destination + file)
-            print("Moved " + file + " to " + destination + file)
+Now `photo.png` collides → next save becomes `photo_1.png`, then `photo_2.png`, and so on. No data lost.
+
+## Dry-Run Mode
+
+Always preview before destructive changes:
+```python title="dryrun.py"
+DRY_RUN = True              # toggle this
+
+for file in SOURCE.iterdir():
+    if not file.is_file(): continue
+    target = DEST / category_for(file.suffix.lower()) / file.name
+    if DRY_RUN:
+        print(f"[dry-run] Would move {file.name} → {target}")
+    else:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(file), str(unique_path(target)))
 ```
+Run once with `DRY_RUN = True`, review the plan, then run again with it `False`. This single discipline prevents almost every accidental-data-loss disaster.
+
+## Logging
 
-## Features
-- **Automatic File Detection:** Scans source directory for target file types
-- **Selective Moving:** Only moves files with specified extensions
-- **Progress Feedback:** Reports each file moved with full path
-- **Multiple File Types:** Supports text, PDF, and image files
-- **Simple Configuration:** Easy to modify file types and directories
-- **Error Prevention:** Uses built-in file operations for reliability
-- **Completion Notification:** Confirms when all operations are finished
-
-## Supported File Types
-The script currently handles these file extensions:
-- **Text Files:** .txt
-- **PDF Documents:** .pdf
-- **Image Files:** .png, .jpg, .jpeg
-
-### Adding More File Types
-To support additional file types, simply modify the `file_types` list:
-```python title="automatedfilemover.py" showLineNumbers{1}
-file_types = ["txt", "pdf", "png", "jpg", "jpeg", "docx", "xlsx", "mp3", "mp4"]
+Print is fine for ad-hoc runs. For a scheduled service, write a log file:
+```python title="logging.py"
+import logging
+logging.basicConfig(
+    filename="file_mover.log",
+    level=logging.INFO,
+    format="%(asctime)s  %(message)s",
+)
+logging.info("Moved %s → %s", file.name, target)
 ```
+Each run appends timestamped lines you can review later.
 
-## How It Works
+## Real-Time Watcher
 
-### Directory Structure
+For continuous organization, use **`watchdog`**:
+```bash title="install"
+pip install watchdog
 ```
-Before Running:
-source/
-├── document.txt
-├── report.pdf
-├── photo.png
-├── data.csv      (not moved - not in file_types)
-└── script.py     (not moved - not in file_types)
-
-destination/
-└── (empty)
-
-After Running:
-source/
-├── data.csv      (remains - not in file_types)
-└── script.py     (remains - not in file_types)
-
-destination/
-├── document.txt  (moved)
-├── report.pdf    (moved)
-└── photo.png     (moved)
+```python title="watch.py"
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+import time
+
+class Mover(FileSystemEventHandler):
+    def on_created(self, event):
+        if event.is_directory: return
+        time.sleep(1)                       # wait for write to finish
+        organize_one(Path(event.src_path))
+
+obs = Observer()
+obs.schedule(Mover(), str(SOURCE), recursive=False)
+obs.start()
+try:
+    while True: time.sleep(60)
+except KeyboardInterrupt:
+    obs.stop()
+obs.join()
 ```
+Now every file dropped into `source/` is sorted instantly. Run this as a background service and your Downloads folder organizes itself.
 
-### Process Flow
-1. **Scan Source:** Get list of all files in source directory
-2. **Filter by Type:** Check each file against target extensions
-3. **Move Files:** Transfer matching files to destination
-4. **Report Progress:** Print status for each moved file
-5. **Complete:** Notify when all operations are finished
-
-## Use Cases
-- **Download Organization:** Automatically sort downloaded files
-- **Photo Management:** Organize images by moving to specific folders
-- **Document Sorting:** Separate documents by type or project
-- **Cleanup Tasks:** Remove clutter from working directories
-- **Backup Operations:** Move files to backup locations
-- **Project Organization:** Sort project files into appropriate folders
+## Common Mistakes
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface for directory selection
-- Implementing subdirectory organization by file type
-- Adding file size filtering and duplicate detection
-- Creating scheduled automation with task scheduling
-- Adding undo functionality to reverse moves
-- Implementing regex patterns for complex file matching
-- Adding logging and error handling for failed operations
-- Creating configuration files for custom rules
-- Adding network drive support for remote file management
-- Implementing file compression before moving
-
-## Enhanced Version Ideas
-```python title="automatedfilemover.py" showLineNumbers{1}
-import logging
-from datetime import datetime
-from pathlib import Path
+| Problem | Cause | Fix |
+|---|---|---|
+| Files overwritten silently | `shutil.move` to an existing path | Use `unique_path()` |
+| `PermissionError` | File still being downloaded/used | Try a second time after a delay |
+| Hidden files moved | Glob included `.DS_Store`, `desktop.ini` | Skip `file.name.startswith(".")` |
+| `shutil` across drives slow | Move = copy + delete on cross-drive | Acceptable; use `shutil.move` for portability |
+| Recursive infinite loop | `dest` is inside `source` | Validate that one is not a subpath of the other |
+| Source folder not exists | Typo in path | `assert SOURCE.is_dir(), f"missing {SOURCE}"` early |
 
-class AdvancedFileMover:
-    def __init__(self, source_dir, destination_dir):
-        self.source = Path(source_dir)
-        self.destination = Path(destination_dir)
-        self.setup_logging()
-    
-    def setup_logging(self):
-        logging.basicConfig(
-            filename='file_moves.log',
-            level=logging.INFO,
-            format='%(asctime)s - %(message)s'
-        )
-    
-    def organize_by_type(self):
-        # Create subdirectories for each file type
-        file_type_map = {
-            'txt': 'Documents/Text',
-            'pdf': 'Documents/PDF',
-            'png': 'Images/PNG',
-            'jpg': 'Images/JPEG'
-        }
-        
-        for file_type, subfolder in file_type_map.items():
-            target_dir = self.destination / subfolder
-            target_dir.mkdir(parents=True, exist_ok=True)
-    
-    def move_with_conflict_resolution(self, source_file, target_file):
-        if target_file.exists():
-            # Handle file name conflicts
-            counter = 1
-            while target_file.exists():
-                name = target_file.stem
-                extension = target_file.suffix
-                target_file = target_file.parent / f"{name}_{counter}{extension}"
-                counter += 1
-        
-        shutil.move(str(source_file), str(target_file))
-        logging.info(f"Moved {source_file} to {target_file}")
-```
+## Variations to Try
 
-## Configuration Options
+### 1. By date
+Sort into `Year/Month/Day` folders using `datetime.fromtimestamp(file.stat().st_mtime)`.
 
-### Custom Directory Paths
-```python title="automatedfilemover.py" showLineNumbers{1}
-# Modify these paths as needed
-source = "/path/to/your/source/directory/"
-destination = "/path/to/your/destination/directory/"
+### 2. By size
+Bucket into `Small/`, `Medium/`, `Large/` (e.g., < 1 MB, < 100 MB, ≥ 100 MB).
 
-# Or use command line arguments
-import sys
-if len(sys.argv) > 2:
-    source = sys.argv[1]
-    destination = sys.argv[2]
-```
+### 3. By name regex
+Receipts (`receipt_*.pdf`), screenshots (`Screenshot_*.png`), invoices — handled by pattern, not extension.
+
+### 4. Recursive scan
+`SOURCE.rglob("*")` to handle nested directories.
+
+### 5. Undo log
+Append every move as `(source, destination)` to `moves.log`. An `undo.py` script reads the log and reverses them.
+
+### 6. Config file
+Move `CATEGORIES` into `config.yaml` so the user can adjust without editing Python.
+
+### 7. GUI
+Tkinter window with source/destination pickers, a "Preview" button (dry-run), and "Move" button.
+
+### 8. Cloud sync
+Move source = local Downloads, destination = synced cloud folder.
+
+### 9. Duplicate detection
+Hash files with `hashlib.md5(file.read_bytes())`. If the hash already exists in destination, delete the duplicate instead of moving it.
 
-### File Type Categories
-```python title="automatedfilemover.py" showLineNumbers{1}
-# Organize by categories
-document_types = ["txt", "pdf", "doc", "docx"]
-image_types = ["png", "jpg", "jpeg", "gif", "bmp"]
-video_types = ["mp4", "avi", "mov", "mkv"]
-audio_types = ["mp3", "wav", "flac", "aac"]
+### 10. Cron / Task Scheduler
+Run every 15 minutes:
+```bash title="cron"
+*/15 * * * * /usr/bin/python /path/to/automatedfilemover.py
 ```
+Or on Windows: Task Scheduler → Create Basic Task → Daily / 15-min interval.
 
-## Error Handling Improvements
-```python title="automatedfilemover.py" showLineNumbers{1}
-import os
-import shutil
-import logging
+### 11. Trash, not delete
+For "Other" category files, move to a `Trash/` folder with a 30-day cleanup rule rather than deleting.
+
+### 12. AI sort
+For unclear files, OCR / read the content (PDFs with `pypdf`) and route by detected topic.
+
+## Architecture Path
 
-def safe_file_move():
-    try:
-        for file in files:
-            source_path = os.path.join(source, file)
-            destination_path = os.path.join(destination, file)
-            
-            # Check if source file exists
-            if not os.path.exists(source_path):
-                print(f"Warning: {file} not found in source")
-                continue
-            
-            # Check if destination already exists
-            if os.path.exists(destination_path):
-                print(f"Warning: {file} already exists in destination")
-                continue
-            
-            # Perform the move
-            shutil.move(source_path, destination_path)
-            print(f"Successfully moved {file}")
-            
-    except PermissionError:
-        print("Error: Permission denied. Check file permissions.")
-    except Exception as e:
-        print(f"Unexpected error: {e}")
+```
+Script run on demand (you are here)
+   ↓
+Logging + dry-run
+   ↓
+watchdog real-time daemon
+   ↓
+systemd service / Windows service
+   ↓
+GUI front-end on top
+   ↓
+Cross-device sync rules
 ```
 
-## Automation Ideas
-- **Schedule Regular Runs:** Use cron (Linux/Mac) or Task Scheduler (Windows)
-- **Watch Directory Changes:** Use `watchdog` library for real-time monitoring
-- **Email Notifications:** Send reports when file moves are completed
-- **Integration:** Combine with other scripts for complete workflow automation
+## Common Use Cases
+- **Personal cleanup** — Downloads, Desktop.
+- **Photo import** — phone-dumped pictures sorted into year/month.
+- **Server intake** — incoming uploads routed by user / type.
+- **Build artifacts** — sort by extension into `dist/`, `coverage/`, `logs/`.
+- **Mail sorting** — combined with `imaplib`, sort attachments into folders.
 
 ## Security Considerations
-- **Path Validation:** Ensure source and destination paths are safe
-- **Permission Checks:** Verify read/write access before operations
-- **Backup Creation:** Create backups before moving important files
-- **Logging:** Maintain records of all file operations
+- **Path safety** — refuse moves where target escapes `DEST` (`target.resolve().is_relative_to(DEST.resolve())`).
+- **Symbolic links** — by default `iterdir()` follows them; check `file.is_symlink()` if that worries you.
+- **Permissions** — wrap `shutil.move` in `try/except OSError` and log failures.
+- **Concurrent execution** — two instances racing on the same folder corrupts state; use a lock file.
 
 ## Educational Value
-This project teaches:
-- **File System Operations:** Working with directories and files
-- **Path Manipulation:** Understanding file paths and navigation
-- **Iteration and Conditionals:** Processing lists and making decisions
-- **String Operations:** Working with file extensions and names
-- **Error Prevention:** Safe file handling practices
-
-## Real-World Applications
-- **System Administration:** Automated file organization on servers
-- **Personal Productivity:** Organizing downloads and documents
-- **Data Processing:** Sorting data files for analysis workflows
-- **Content Management:** Organizing media files and assets
-- **Backup Systems:** Automated file archiving and organization
+- **`pathlib`** — the modern way to do file paths.
+- **`shutil`** — file copy/move/delete, cross-platform.
+- **Defensive programming** — dry-run, conflict resolution, logging.
+- **Real-time programming** — event-driven watchers.
+- **Service operation** — cron, systemd, Windows Task Scheduler.
+
+## Next Steps
+- Refactor with **`pathlib`**.
+- Add **typed sub-folders** by category.
+- Add **conflict resolution** with `unique_path`.
+- Add **`DRY_RUN` mode** and use it before every real move.
+- Schedule with **cron / Task Scheduler**.
+- Switch to a **`watchdog`** daemon for real-time organization.
 
 ## Conclusion
-In this project, we learned how to create an Automated File Mover using Python's built-in file system modules. We explored directory operations, file manipulation, and automation techniques. This script demonstrates practical applications of programming in everyday file management tasks and provides a foundation for more complex automation projects. The ability to programmatically organize files is valuable for both personal productivity and professional system administration. To find more projects like this, you can visit Python Central Hub.
+You wrote a real productivity tool — the script can run from your `Downloads/` folder and stop entropy in its tracks. The patterns (path objects, conflict resolution, dry-run, logging) reappear in every batch-processing script you will ever write. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/automatedfilemover.py). Find more automation projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basic-calendar-app.mdx b/src/content/docs/projects/Beginners/basic-calendar-app.mdx
index 85823c6d..14ff28ee 100644
--- a/src/content/docs/projects/Beginners/basic-calendar-app.mdx
+++ b/src/content/docs/projects/Beginners/basic-calendar-app.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Calendar App
-description: A comprehensive command-line calendar application with event management, scheduling, categories, and export features built with Python
+description: Build a Python calendar app with event scheduling, categories, monthly view, recurring events, reminders, ICS export, and a Tkinter GUI. Learn datetime, the calendar module, and how production scheduling apps work.
 sidebar:
   order: 49
 hero:
@@ -13,331 +13,323 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A calendar app is one of the most useful pieces of software ever built, and surprisingly approachable in Python. In this project you create a command-line calendar with event creation, categories, monthly views, search, statistics, and JSON persistence. Then we layer on the features that turn a toy into a tool: recurring events, desktop reminders, ICS export (the universal calendar format), and a Tkinter GUI with a real grid view.
 
-A comprehensive command-line calendar application that provides complete event management functionality including scheduling, categorization, search, and export capabilities. This project demonstrates advanced data structures, date/time handling, and file persistence techniques.
-
-## 🎯 Project Overview
-
-This project creates a full-featured calendar application with:
-- Event creation and management system
-- Calendar view with visual event indicators
-- Category-based organization
-- Search and filtering capabilities
-- Statistics and analytics
-- Data export functionality
-- Persistent storage using JSON
-
-## ✨ Features
-
-### Event Management
-- **Create Events**: Add events with title, date, time, description, and category
-- **Edit Events**: Update existing event details
-- **Delete Events**: Remove events with confirmation
-- **Event Categories**: Organize events by custom categories
-
-### Calendar Views
-- **Monthly Calendar**: Visual calendar with event indicators
-- **Daily View**: Detailed view of events for specific dates
-- **Today's Events**: Quick view of current day's schedule
-- **Upcoming Events**: Configurable future event preview
-
-### Organization & Search
-- **Category System**: Built-in and custom categories for organization
-- **Event Search**: Search by title, description, or category
-- **Date Filtering**: View events by specific date ranges
-- **Sorting**: Automatic chronological sorting of events
-
-### Analytics & Export
-- **Statistics Dashboard**: Event counts, category distribution, and trends
-- **Data Export**: Export events to text files with date filtering
-- **Monthly Distribution**: Track event patterns over time
-- **Category Analytics**: Monitor category usage
-
-## 🛠️ Technical Implementation
-
-### Class Structure
-```python title="basiccalendarapp.py" showLineNumbers{1}
-class Event:
-    def __init__(self, event_id, title, date, time="", description="", category="General"):
-        # Event data model with validation
-        # Automatic ID generation and timestamps
-    
-    def get_datetime(self):
-        # Convert string date/time to datetime object
-    
-    def is_upcoming(self, days=7):
-        # Check if event is within specified timeframe
-
-class BasicCalendarApp:
-    def __init__(self, data_file="calendar_data.json"):
-        # Initialize calendar with data persistence
-        # Load existing events and categories
-    
-    def add_event(self, title, date_str, time_str, description, category):
-        # Create and store new event with validation
-    
-    def get_calendar_view(self, year, month):
-        # Generate ASCII calendar with event indicators
-```
-
-### Key Components
-
-#### Data Models
-- **Event Class**: Represents calendar events with metadata
-- **Unique IDs**: Automatic generation of event identifiers (EVT001, EVT002, etc.)
-- **Datetime Handling**: Robust date and time parsing and validation
-- **Category Management**: Dynamic category creation and assignment
-
-#### Calendar Display
-- **ASCII Calendar**: Visual month view using Python's calendar module
-- **Event Indicators**: Asterisk markers for days with events
-- **Formatted Output**: Clean, readable event listings
-- **Date Navigation**: Easy month/year navigation
-
-#### Data Persistence
-- **JSON Storage**: Automatic saving and loading of all data
-- **Error Handling**: Graceful handling of file operations
-- **Data Validation**: Ensure data integrity on load/save
-- **Backup Safety**: Protection against data corruption
-
-## 🚀 How to Run
-
-1. **Install Python**: Ensure Python 3.6+ is installed (uses built-in modules)
-2. **Run the Calendar**:
-   ```bash
-   python basiccalendarapp.py
-   ```
-
-3. **Getting Started**:
-   - Add your first event
-   - Explore the monthly calendar view
-   - Try different categories and search features
-   - View statistics and export data
-
-## 💡 Usage Examples
-
-### Creating Events
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Create calendar app instance
-calendar_app = BasicCalendarApp()
-
-# Add a simple event
-event = calendar_app.add_event(
-    title="Team Meeting",
-    date_str="2024-01-15",
-    time_str="14:30",
-    description="Weekly team sync",
-    category="Work"
-)
-
-print(f"Event created with ID: {event.id}")
-```
-
-### Viewing Calendar
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Get monthly calendar view
-calendar_view = calendar_app.get_calendar_view(2024, 1)
-print(calendar_view)
+You will learn:
+- Python's `datetime` and `calendar` modules.
+- How to build an ASCII monthly calendar with event indicators.
+- The data model used by every calendar app (RFC 5545 / iCalendar).
+- How recurring events work (RRULE).
+- How to export to `.ics` so events sync to Google Calendar / Apple Calendar.
 
-# Get events for specific date
-date_events = calendar_app.get_events_for_date("2024-01-15")
-for event in date_events:
-    print(f"• {event}")
-```
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with classes, dictionaries, and `datetime` basics.
+- Familiarity with [Personal Diary](./personaldiary) for the same JSON-persistence shape.
 
-### Search and Filter
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Search events
-results = calendar_app.search_events("meeting")
+## Getting Started
 
-# Get events by category
-work_events = calendar_app.get_events_by_category("Work")
+### Create the project
+1. Create folder `calendar-app`.
+2. Inside, create `basiccalendarapp.py`.
 
-# Get upcoming events
-upcoming = calendar_app.get_upcoming_events(7)  # Next 7 days
-```
+### Write the code
+<FileCode file="projects/beginners/basiccalendarapp.py" lang="python" title="Calendar App" />
 
-### Analytics
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Get comprehensive statistics
-stats = calendar_app.get_event_statistics()
-print(f"Total events: {stats['total_events']}")
-print(f"Categories: {stats['categories']}")
+### Run it
+```bash title="run"
+python basiccalendarapp.py
 ```
 
-## 🎨 Interactive Menu System
-
-### Main Menu Options
-1. **Add Event** - Create new calendar events
-2. **View Today's Events** - See current day's schedule
-3. **View Upcoming Events** - Preview future events
-4. **View Monthly Calendar** - ASCII calendar with event indicators
-5. **View Events by Date** - Specific date event listing
-6. **Search Events** - Find events by keywords
-7. **View Events by Category** - Filter by event categories
-8. **Edit Event** - Modify existing event details
-9. **Delete Event** - Remove events with confirmation
-10. **View Statistics** - Analytics dashboard
-11. **Export Events** - Save events to text files
-12. **Manage Categories** - Add custom categories
-
-### User Experience Features
-- **Input Validation**: Robust date and time format checking
-- **Smart Defaults**: Sensible default values for optional fields
-- **Confirmation Prompts**: Safety checks for destructive operations
-- **Error Handling**: Graceful error recovery and user feedback
-
-## 📅 Calendar Features
-
-### Monthly Calendar View
 ```
-January 2024
+1. Add event
+2. Today's events
+3. Upcoming events
+4. Monthly view
+5. Events on date
+6. Search
+7. Edit / delete
+8. Statistics
+9. Export
+10. Quit
+> 4
+       January 2026
 Mo Tu We Th Fr Sa Su
- 1  2  3  4  5  6  7 
- 8  9 10 11 12 13 14 
-15*16 17 18*19 20 21 
-22 23 24 25 26 27 28 
-29 30 31 
+          1  2  3  4
+ 5  6  7  8* 9 10 11
+12 13 14*15 16 17 18
+19 20 21 22 23 24 25
+26 27 28 29 30 31
 
-* = Has events
+* = has events
 ```
 
-### Event Display Format
+## Step-by-Step Explanation
+
+### 1. The `Event` data class
+```python title="basiccalendarapp.py"
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, date, timedelta
+
+@dataclass
+class Event:
+    id: str
+    title: str
+    date: str               # YYYY-MM-DD
+    time: str = ""          # HH:MM
+    description: str = ""
+    category: str = "General"
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def dt(self) -> datetime:
+        if self.time:
+            return datetime.strptime(f"{self.date} {self.time}", "%Y-%m-%d %H:%M")
+        return datetime.strptime(self.date, "%Y-%m-%d")
+
+    def is_upcoming(self, within_days: int = 7) -> bool:
+        return date.today() <= self.dt().date() <= date.today() + timedelta(days=within_days)
+
+    def to_dict(self): return asdict(self)
+    @classmethod
+    def from_dict(cls, d): return cls(**d)
 ```
-=== Today's Events ===
+Storing date and time as **ISO strings** is deliberate — JSON has no native datetime, and ISO format sorts correctly lexicographically.
+
+### 2. The `Calendar` class
+```python title="basiccalendarapp.py"
+import json
+from pathlib import Path
+
+class Calendar:
+    def __init__(self, filename="calendar_data.json"):
+        self.path = Path(filename)
+        self.events: list[Event] = []
+        self.next_id = 1
+        self.load()
+
+    def load(self):
+        if self.path.exists() and self.path.stat().st_size:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            self.events = [Event.from_dict(d) for d in data["events"]]
+            self.next_id = data.get("next_id", len(self.events) + 1)
+
+    def save(self):
+        self.path.write_text(json.dumps({
+            "events": [e.to_dict() for e in self.events],
+            "next_id": self.next_id,
+        }, indent=2), encoding="utf-8")
+
+    def add(self, title, date_str, time_str="", description="", category="General"):
+        eid = f"EVT{self.next_id:03d}"
+        self.events.append(Event(eid, title, date_str, time_str, description, category))
+        self.next_id += 1
+        self.save()
+        return eid
+```
+`EVT001`, `EVT002`, `...` IDs are human-readable and survive sorting.
+
+### 3. Date input with validation
+```python title="basiccalendarapp.py"
+def get_date(prompt: str) -> str:
+    while True:
+        raw = input(prompt + " (YYYY-MM-DD): ").strip()
+        try:
+            datetime.strptime(raw, "%Y-%m-%d")
+            return raw
+        except ValueError:
+            print("Bad format. Example: 2026-01-15")
+```
+`strptime` *validates while it parses* — fail-early.
+
+### 4. Monthly view with event indicators
+```python title="basiccalendarapp.py"
+import calendar as cal
+
+def month_view(self, year: int, month: int) -> str:
+    has_event = {e.date for e in self.events
+                 if e.dt().year == year and e.dt().month == month}
+    text_cal = cal.month(year, month)
+    lines = text_cal.splitlines()
+    out = [lines[0], lines[1]]
+    for line in lines[2:]:
+        new = []
+        for piece in line.split():
+            d = f"{year:04d}-{month:02d}-{int(piece):02d}"
+            new.append(f"{piece}*" if d in has_event else piece.rjust(2))
+        out.append("  ".join(new))
+    return "\n".join(out)
+```
+`calendar.month()` does the heavy formatting; we just sprinkle `*` next to days with events.
+
+### 5. Today / upcoming / search
+```python title="basiccalendarapp.py"
+def today(self):
+    today_str = date.today().isoformat()
+    return [e for e in self.events if e.date == today_str]
+
+def upcoming(self, days=7):
+    return sorted([e for e in self.events if e.is_upcoming(days)],
+                  key=lambda e: e.dt())
+
+def search(self, query: str):
+    q = query.lower()
+    return [e for e in self.events
+            if q in e.title.lower() or q in e.description.lower()]
+```
+
+## Recurring Events
 
-2024-01-15 (Monday)
--------------------------
-  [EVT001] Team Meeting at 14:30 (Work)
-      Weekly team sync
-  [EVT002] Dentist Appointment at 16:00 (Health)
+A real calendar must handle "every Monday at 10:00" or "the 15th of every month." Store recurrence as an extra field:
+```python title="recurring.py"
+@dataclass
+class Event:
+    # … existing fields …
+    recurrence: str = ""        # "daily", "weekly", "monthly", "yearly", ""
+
+def expand(event: Event, until: date) -> list[Event]:
+    out = [event]
+    start = event.dt().date()
+    if event.recurrence == "daily":
+        step = timedelta(days=1)
+    elif event.recurrence == "weekly":
+        step = timedelta(weeks=1)
+    elif event.recurrence == "monthly":
+        # naive month-step — use python-dateutil for correctness
+        step = timedelta(days=30)
+    else:
+        return out
+    d = start + step
+    while d <= until:
+        out.append(replace(event, date=d.isoformat()))
+        d += step
+    return out
+```
+For production correctness, use the **`dateutil.rrule`** library (RFC 5545 compliant) — it handles "second Tuesday of the month" and exceptions cleanly.
+
+## ICS Export (Google / Apple Calendar Compatible)
+
+```python title="ics.py"
+def to_ics(events: list[Event]) -> str:
+    lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//PCH//Calendar//EN"]
+    for e in events:
+        dt = e.dt()
+        end = dt + timedelta(hours=1)
+        lines += [
+            "BEGIN:VEVENT",
+            f"UID:{e.id}@pythoncentralhub",
+            f"DTSTAMP:{datetime.utcnow().strftime('%Y%m%dT%H%M%SZ')}",
+            f"DTSTART:{dt.strftime('%Y%m%dT%H%M%S')}",
+            f"DTEND:{end.strftime('%Y%m%dT%H%M%S')}",
+            f"SUMMARY:{e.title}",
+            f"DESCRIPTION:{e.description}",
+            f"CATEGORIES:{e.category}",
+            "END:VEVENT",
+        ]
+    lines.append("END:VCALENDAR")
+    return "\r\n".join(lines)
+```
+Save as `calendar.ics`. Drop into Google Calendar's import dialog or Apple Calendar — every event appears. **`pip install icalendar`** for a production-grade library.
+
+## Desktop Reminders
+
+Combine with [Simple Reminder App](./simplereminderapp). On startup, schedule one timer per upcoming event:
+```python title="remind.py"
+import threading
+from plyer import notification
+
+def schedule(event):
+    delay = (event.dt() - datetime.now()).total_seconds()
+    if delay <= 0: return
+    def fire():
+        notification.notify(title=event.title,
+                            message=event.description or "Event now.",
+                            timeout=10)
+    threading.Timer(delay, fire).start()
 ```
 
-### Category Organization
-- **Built-in Categories**: General, Work, Personal, Health, Education
-- **Custom Categories**: User-defined categories for specific needs
-- **Category Statistics**: Track usage and distribution
-- **Category Filtering**: View events by specific categories
+## Common Mistakes
 
-## 🔧 Advanced Features
+| Problem | Cause | Fix |
+|---|---|---|
+| `ValueError: time data '...' does not match format` | Mixed date formats | Validate with `strptime` on entry |
+| Events on Feb 30 accepted | No real-date validation | `strptime` rejects them — use it |
+| Timezone confusion | Naive datetimes | Use `datetime.now(timezone.utc)` consistently |
+| Recurring events past year 9999 | No upper bound | Cap with a `RRULE UNTIL` or hard limit |
+| Two events same minute reorder randomly | Sort key is date only | Sort by full `dt()` |
+| `next_id` collisions on restart | Did not save | Persist counter alongside events |
 
-### Date Validation
-```python title="basiccalendarapp.py" showLineNumbers{1}
-def get_date_input(prompt):
-    # Validate YYYY-MM-DD format
-    # Provide user-friendly error messages
-    # Allow empty input for optional fields
-```
+## Variations to Try
 
-### Event Updates
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Update any event field selectively
-calendar_app.update_event(
-    event_id="EVT001",
-    title="Updated Meeting Title",
-    date_str="2024-01-16",
-    # Other fields remain unchanged
-)
-```
+### 1. Tkinter GUI
+A real month grid built from `ttk.Treeview` (or hand-drawn with a `Canvas`). Click a day to see events; double-click to add.
 
-### Export Functionality
-```python title="basiccalendarapp.py" showLineNumbers{1}
-# Export all events
-calendar_app.export_events("all_events.txt")
-
-# Export with date range
-calendar_app.export_events(
-    "january_events.txt",
-    start_date="2024-01-01",
-    end_date="2024-01-31"
-)
-```
+### 2. iCal sync
+Periodically download a friend's `.ics` URL and merge in their events.
 
-## 📊 Data Structure
-
-### Event Format
-```json
-{
-  "id": "EVT001",
-  "title": "Team Meeting",
-  "date": "2024-01-15",
-  "time": "14:30",
-  "description": "Weekly team sync",
-  "category": "Work",
-  "created_at": "2024-01-01T10:00:00.000000"
-}
-```
+### 3. Google Calendar API
+Authenticate with OAuth and push events into the user's real Google Calendar.
 
-### Statistics Output
-```python title="basiccalendarapp.py" showLineNumbers{1}
-{
-  'total_events': 25,
-  'today_events': 3,
-  'upcoming_events': 8,
-  'categories': {
-    'Work': 12,
-    'Personal': 8,
-    'Health': 3,
-    'Education': 2
-  },
-  'monthly_distribution': {
-    '2024-01': 15,
-    '2024-02': 10
-  },
-  'total_categories': 4
-}
-```
+### 4. Conflict detection
+Refuse (or warn) when adding an event that overlaps an existing one.
+
+### 5. Reminders with snooze
+Snoozeable desktop notifications. See [Simple Reminder App](./simplereminderapp).
+
+### 6. Timezones
+Store events as UTC; display in user's local timezone via `zoneinfo` (built into 3.9+).
+
+### 7. Web frontend
+Flask app + a calendar widget. See [Basic Web Server](./basicwebserver).
+
+### 8. Multi-user with auth
+SQLite + user accounts. Each user sees only their events.
+
+### 9. Statistics dashboard
+Plot events per category, per month, per weekday with `matplotlib`.
+
+### 10. Natural-language input
+`pip install dateparser` so "tomorrow at 3pm — dentist" parses cleanly.
+
+### 11. Color categories
+Each category gets a color. ANSI in terminal, hex in GUI/web.
+
+### 12. iOS / Android sync
+Generate ICS, host on a small Flask server, subscribe to its URL from the phone's calendar app.
+
+## Why Real Calendars Are Hard
+
+Once you go past toy versions:
+- **Daylight saving** — events move an hour, sometimes split.
+- **Cross-timezone scheduling** — "9 AM PT" means three different wall times across the year.
+- **Rule exceptions** — "every Monday except holidays."
+- **Mutable past events** — moving an instance of a recurring event without breaking others.
+- **Conflict resolution** for events synced from multiple sources.
+- **Notifications** that must fire even when the device is asleep.
+
+Every major calendar app (Google, Apple, Outlook) has hundreds of engineers working on these — but the foundation is exactly the data model you just built.
+
+## Real-World Applications
+- **Personal scheduling** — your own habit tracker.
+- **Internal team calendars** for small companies.
+- **Booking systems** for one-person businesses (consultants, tutors).
+- **Project planning** — milestones, sprints, releases.
+- **Event-driven automation** — schedule scripts to run at specific times.
+
+## Educational Value
+- **`datetime` mastery** — parsing, formatting, arithmetic.
+- **`calendar`** — the standard library's underused gem.
+- **Dataclass + JSON persistence** — reusable for any small CRUD app.
+- **Recurrence rules (RRULE)** — the same model every calendar uses.
+- **Standards (iCalendar / RFC 5545)** — interoperability with real-world tools.
+
+## Next Steps
+- Add **recurring events** with `dateutil.rrule`.
+- Implement **ICS export** above and try it in Google Calendar.
+- Combine with [Simple Reminder App](./simplereminderapp) for desktop reminders.
+- Wrap with a **Tkinter GUI** that shows a real grid.
+- Move to **SQLite** for thousands of events.
+- Layer **OAuth + Google Calendar API** for two-way sync.
 
-## 🛡️ Error Handling
-
-- **Date Validation**: Comprehensive date and time format checking
-- **File Operations**: Graceful handling of JSON file errors
-- **User Input**: Input validation with helpful error messages
-- **Data Integrity**: Protection against data corruption
-
-## 📚 Learning Objectives
-
-- **Date/Time Handling**: Working with Python's datetime module
-- **Data Persistence**: JSON file operations and data management
-- **User Interface Design**: Command-line interface best practices
-- **Input Validation**: Robust user input handling
-- **Data Organization**: Categorization and search algorithms
-
-## 🎯 Potential Enhancements
-
-1. **GUI Interface**: Tkinter or PyQt graphical interface
-2. **Recurring Events**: Support for repeating events
-3. **Reminders**: Email or desktop notification system
-4. **Shared Calendars**: Multi-user calendar sharing
-5. **Import/Export**: ICS file format support
-6. **Web Interface**: Flask web application
-7. **Database Storage**: SQLite or PostgreSQL integration
-8. **Mobile App**: Cross-platform mobile application
-
-## 📈 Usage Patterns
-
-### Typical Workflow
-1. **Setup**: Create categories for your lifestyle
-2. **Planning**: Add upcoming events and appointments
-3. **Daily Use**: Check today's events and add new ones
-4. **Review**: Use monthly view to see patterns
-5. **Analysis**: Review statistics to understand scheduling trends
-
-### Best Practices
-- Use descriptive event titles
-- Leverage categories for better organization
-- Include time for important appointments
-- Add descriptions for complex events
-- Regular exports for backup
-
-## 🏆 Project Completion
-
-This Basic Calendar App demonstrates:
-- ✅ Complete event lifecycle management (CRUD operations)
-- ✅ Visual calendar presentation
-- ✅ Data persistence and integrity
-- ✅ Search and filtering capabilities
-- ✅ Analytics and statistics
-- ✅ Export and backup functionality
-
-Perfect for beginners learning data management and intermediate developers exploring calendar application development!
+## Conclusion
+You built a complete calendar with events, categories, search, monthly view, statistics, and export. The data model is the same one every commercial calendar uses; the difference between this and Google Calendar is mostly *scale* and *integration*. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basiccalendarapp.py). Find more productivity projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basic-text-editor.mdx b/src/content/docs/projects/Beginners/basic-text-editor.mdx
index 40ed2011..600c2c4d 100644
--- a/src/content/docs/projects/Beginners/basic-text-editor.mdx
+++ b/src/content/docs/projects/Beginners/basic-text-editor.mdx
@@ -1,216 +1,352 @@
 ---
-title: "Basic Text Editor"
-description: "A comprehensive text editor built with Tkinter featuring file operations, text editing, find/replace, and customization options."
+title: Basic Text Editor
+description: Build a fully featured text editor in Python with Tkinter. File operations, undo/redo, find/replace, font customization, keyboard shortcuts, status bar, and a path to syntax highlighting and tabs.
 sidebar:
   order: 45
+hero:
+  actions:
+    - text: View on GitHub
+      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basictexteditor.py
+      icon: github
+      variant: primary
 ---
+import FileCode from '../../../../components/FileCode.astro'
 
-# Basic Text Editor
+## Abstract
+A text editor is the most concentrated GUI project a Python developer can build. You touch every part of Tkinter — menus, toolbars, the `Text` widget, dialog windows, keyboard shortcuts, clipboard integration, status bars, and asking-to-save logic. In this tutorial you will build a working editor with new/open/save/save-as, undo/redo, find, font selection, and word-wrap toggle. Then we will discuss the natural next steps — syntax highlighting, tabs, and find-and-replace.
 
-A comprehensive text editor application built with Python's Tkinter library, providing essential text editing features with a user-friendly graphical interface.
+You will learn:
+- How to lay out a real application with `pack` + frames.
+- How a Tkinter menubar, toolbar, and status bar fit together.
+- How to wire keyboard shortcuts to commands.
+- How to track unsaved changes and prompt the user before discarding them.
+- How to use the `Text` widget's built-in undo/redo.
 
-## 🎯 Project Overview
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with Python; Linux: `sudo apt install python3-tk`).
+- Comfort with classes — this project deserves OO from the start.
 
-This project creates a fully functional text editor with modern features including:
-- Complete file operations (new, open, save, save as)
-- Text editing with undo/redo functionality
-- Find and search capabilities
-- Font customization
-- Word wrap toggle
-- Status bar with cursor position
-- Keyboard shortcuts
-- Toolbar for quick access
+## Getting Started
 
-## ✨ Features
+### Create the project
+1. Create folder `basic-text-editor`.
+2. Inside, create `basictexteditor.py`.
 
-### File Operations
-- **New File**: Create a new document
-- **Open File**: Load existing text files
-- **Save/Save As**: Save documents with change tracking
-- **Auto-save prompts**: Prevents data loss
-
-### Text Editing
-- **Cut, Copy, Paste**: Standard clipboard operations
-- **Undo/Redo**: Multiple levels of undo support
-- **Select All**: Quick text selection
-- **Find Text**: Search functionality with highlighting
-
-### User Interface
-- **Menu Bar**: Organized menu system
-- **Toolbar**: Quick access buttons
-- **Status Bar**: Shows cursor position
-- **Scrollbars**: Handle large documents
-- **Keyboard Shortcuts**: Efficient navigation
+### Run it
+```bash title="run"
+python basictexteditor.py
+```
+A window appears with **File**, **Edit**, **Format** menus, a toolbar, the editing area, and a status bar at the bottom.
 
-### Customization
-- **Font Selection**: Choose font family and size
-- **Word Wrap**: Toggle text wrapping
-- **Multiple File Types**: Support for .txt, .py, and all files
+## Class Skeleton
 
-## 🛠️ Technical Implementation
+```python title="basictexteditor.py"
+import tkinter as tk
+from tkinter import filedialog, messagebox, font, ttk
 
-### Class Structure
-```python title="basictexteditor.py" showLineNumbers{1}
 class BasicTextEditor:
     def __init__(self):
-        # Initialize GUI components
-        # Set up event bindings
-        # Configure layout
-    
-    def create_menu(self):
-        # Create menu bar with File, Edit, Format menus
-        # Bind keyboard shortcuts
-    
-    def create_toolbar(self):
-        # Create toolbar with quick access buttons
-    
-    def create_text_area(self):
-        # Create main text widget with scrollbars
-    
-    def create_status_bar(self):
-        # Create status bar for cursor position
+        self.root = tk.Tk()
+        self.root.title("Untitled — Basic Text Editor")
+        self.root.geometry("900x600")
+        self.current_file = None
+        self.modified = False
+
+        self._build_menu()
+        self._build_toolbar()
+        self._build_text_area()
+        self._build_status_bar()
+        self._bind_shortcuts()
+
+    def run(self):
+        self.root.protocol("WM_DELETE_WINDOW", self.on_close)
+        self.root.mainloop()
+```
+Each `_build_*` helper does one thing. The constructor is now a high-level recipe.
+
+## Step-by-Step Explanation
+
+### 1. The text area
+```python title="basictexteditor.py"
+def _build_text_area(self):
+    frame = tk.Frame(self.root)
+    frame.pack(fill="both", expand=True)
+    self.text = tk.Text(frame, undo=True, wrap="word", font=("Consolas", 11))
+    vsb = ttk.Scrollbar(frame, orient="vertical", command=self.text.yview)
+    self.text.configure(yscrollcommand=vsb.set)
+    vsb.pack(side="right", fill="y")
+    self.text.pack(side="left", fill="both", expand=True)
+    self.text.bind("<<Modified>>", self._on_modified)
+```
+- `undo=True` enables built-in undo/redo.
+- `wrap="word"` wraps at word boundaries (toggleable later).
+- `<<Modified>>` fires the first time the text content changes after `edit_modified(False)` — we use it to track unsaved changes.
+
+### 2. The menubar
+```python title="basictexteditor.py"
+def _build_menu(self):
+    menubar = tk.Menu(self.root)
+    self.root.config(menu=menubar)
+
+    file_menu = tk.Menu(menubar, tearoff=0)
+    file_menu.add_command(label="New",       command=self.new_file,       accelerator="Ctrl+N")
+    file_menu.add_command(label="Open...",   command=self.open_file,      accelerator="Ctrl+O")
+    file_menu.add_command(label="Save",      command=self.save_file,      accelerator="Ctrl+S")
+    file_menu.add_command(label="Save As...",command=self.save_file_as,   accelerator="Ctrl+Shift+S")
+    file_menu.add_separator()
+    file_menu.add_command(label="Exit",      command=self.on_close)
+    menubar.add_cascade(label="File", menu=file_menu)
+
+    edit_menu = tk.Menu(menubar, tearoff=0)
+    edit_menu.add_command(label="Undo", command=self.text.edit_undo, accelerator="Ctrl+Z")
+    edit_menu.add_command(label="Redo", command=self.text.edit_redo, accelerator="Ctrl+Y")
+    edit_menu.add_separator()
+    edit_menu.add_command(label="Cut",   command=lambda: self.text.event_generate("<<Cut>>"))
+    edit_menu.add_command(label="Copy",  command=lambda: self.text.event_generate("<<Copy>>"))
+    edit_menu.add_command(label="Paste", command=lambda: self.text.event_generate("<<Paste>>"))
+    edit_menu.add_command(label="Select All", command=self._select_all)
+    edit_menu.add_command(label="Find...", command=self.show_find, accelerator="Ctrl+F")
+    menubar.add_cascade(label="Edit", menu=edit_menu)
+
+    format_menu = tk.Menu(menubar, tearoff=0)
+    format_menu.add_command(label="Font...",   command=self.show_font_dialog)
+    self.wrap_var = tk.BooleanVar(value=True)
+    format_menu.add_checkbutton(label="Word Wrap", variable=self.wrap_var,
+                                command=self._toggle_wrap)
+    menubar.add_cascade(label="Format", menu=format_menu)
+```
+- `accelerator="Ctrl+N"` only **shows** the shortcut next to the menu label. You bind it separately (see `_bind_shortcuts`).
+- `tearoff=0` disables the legacy Tk feature of dragging menus into floating windows.
+
+### 3. File operations
+```python title="basictexteditor.py"
+def new_file(self):
+    if not self._confirm_discard(): return
+    self.text.delete("1.0", "end")
+    self.current_file = None
+    self.modified = False
+    self.text.edit_modified(False)
+    self._set_title()
+
+def open_file(self):
+    if not self._confirm_discard(): return
+    path = filedialog.askopenfilename(filetypes=[("Text", "*.txt"),
+                                                  ("Python", "*.py"),
+                                                  ("All files", "*.*")])
+    if not path: return
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = f.read()
+    except Exception as e:
+        messagebox.showerror("Open failed", str(e))
+        return
+    self.text.delete("1.0", "end")
+    self.text.insert("1.0", data)
+    self.current_file = path
+    self.modified = False
+    self.text.edit_modified(False)
+    self._set_title()
+
+def save_file(self):
+    if self.current_file is None:
+        return self.save_file_as()
+    try:
+        with open(self.current_file, "w", encoding="utf-8") as f:
+            f.write(self.text.get("1.0", "end-1c"))
+        self.modified = False
+        self.text.edit_modified(False)
+        self._set_title()
+    except Exception as e:
+        messagebox.showerror("Save failed", str(e))
+
+def save_file_as(self):
+    path = filedialog.asksaveasfilename(defaultextension=".txt",
+        filetypes=[("Text", "*.txt"), ("Python", "*.py"), ("All", "*.*")])
+    if path:
+        self.current_file = path
+        self.save_file()
+```
+- `"end-1c"` strips the trailing newline Tkinter implicitly appends.
+- `_confirm_discard` asks the user if there are unsaved changes before discarding them — covered next.
+
+### 4. Tracking unsaved changes
+```python title="basictexteditor.py"
+def _on_modified(self, _event):
+    if self.text.edit_modified():
+        self.modified = True
+        self._set_title()
+
+def _confirm_discard(self) -> bool:
+    if not self.modified:
+        return True
+    ans = messagebox.askyesnocancel("Unsaved changes",
+        "You have unsaved changes. Save now?")
+    if ans is None: return False
+    if ans:
+        self.save_file()
+        return not self.modified
+    return True
+
+def _set_title(self):
+    name = self.current_file or "Untitled"
+    mark = "*" if self.modified else ""
+    self.root.title(f"{mark}{name} — Basic Text Editor")
+```
+- `askyesnocancel` returns `True` / `False` / `None` — three outcomes, three behaviors.
+- The window title shows `*` for unsaved files — the universal convention.
+
+### 5. Keyboard shortcuts
+```python title="basictexteditor.py"
+def _bind_shortcuts(self):
+    self.root.bind_all("<Control-n>",      lambda e: self.new_file())
+    self.root.bind_all("<Control-o>",      lambda e: self.open_file())
+    self.root.bind_all("<Control-s>",      lambda e: self.save_file())
+    self.root.bind_all("<Control-Shift-S>", lambda e: self.save_file_as())
+    self.root.bind_all("<Control-f>",      lambda e: self.show_find())
+    self.root.bind_all("<Control-a>",      lambda e: self._select_all())
+```
+`bind_all` ensures the shortcut works no matter which widget has focus.
+
+### 6. Find dialog
+```python title="basictexteditor.py"
+def show_find(self):
+    win = tk.Toplevel(self.root)
+    win.title("Find")
+    tk.Label(win, text="Find:").pack(side="left")
+    entry = tk.Entry(win)
+    entry.pack(side="left", padx=4)
+    def do_find():
+        self.text.tag_remove("found", "1.0", "end")
+        target = entry.get()
+        if not target: return
+        start = "1.0"
+        while True:
+            idx = self.text.search(target, start, stopindex="end", nocase=True)
+            if not idx: break
+            end = f"{idx}+{len(target)}c"
+            self.text.tag_add("found", idx, end)
+            start = end
+        self.text.tag_config("found", background="yellow")
+    tk.Button(win, text="Find", command=do_find).pack(side="left")
+```
+A real Toplevel mini-window with an Entry and a Button — the same pattern works for find-and-replace.
+
+### 7. Font customization
+```python title="basictexteditor.py"
+def show_font_dialog(self):
+    win = tk.Toplevel(self.root); win.title("Font")
+    families = sorted(font.families())
+    fam = tk.StringVar(value="Consolas")
+    size = tk.IntVar(value=11)
+    ttk.Combobox(win, textvariable=fam, values=families).pack()
+    tk.Spinbox(win, from_=8, to=72, textvariable=size).pack()
+    tk.Button(win, text="Apply",
+              command=lambda: self.text.config(font=(fam.get(), size.get()))).pack()
 ```
 
-### Key Components
+### 8. Status bar
+```python title="basictexteditor.py"
+def _build_status_bar(self):
+    self.status = tk.Label(self.root, text="Line 1, Col 0", anchor="w", relief="sunken")
+    self.status.pack(side="bottom", fill="x")
+    self.text.bind("<KeyRelease>", self._update_status)
+    self.text.bind("<ButtonRelease>", self._update_status)
+
+def _update_status(self, _e=None):
+    line, col = self.text.index("insert").split(".")
+    self.status.config(text=f"Line {line}, Col {col}")
+```
 
-#### File Management
-- **File I/O**: Handle text file reading/writing with proper encoding
-- **Change Tracking**: Monitor document modifications
-- **Save Prompts**: Prevent accidental data loss
+### 9. Closing the window
+```python title="basictexteditor.py"
+def on_close(self):
+    if self._confirm_discard():
+        self.root.destroy()
+```
+Protocol hook ensures the X button also asks about unsaved changes.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Extra newline on save | Used `get("1.0", "end")` | Use `get("1.0", "end-1c")` |
+| Ctrl+S does nothing | Bound on `self.text`, not `self.root` | Use `bind_all` |
+| `*` never disappears | Forgot `edit_modified(False)` after save | Reset after every save |
+| Save dialog skips on Save vs Save As | Mixed semantics | `save_file` calls `save_file_as` when `current_file is None` |
+| `UnicodeDecodeError` opening files | Default encoding | Use `encoding="utf-8"`, catch and report |
+
+## Variations to Try
+
+### 1. Find and Replace
+Add a second `Entry` and a "Replace" button that calls `text.replace(start, end, new)` for each match.
+
+### 2. Syntax highlighting
+Use **Pygments** to color Python/JS/etc:
+```python title="highlight.py"
+from pygments import lex
+from pygments.lexers import get_lexer_for_filename
+for tok, val in lex(code, get_lexer_for_filename(path)):
+    self.text.insert("end", val, str(tok))
+self.text.tag_config("Token.Keyword", foreground="blue")
+```
 
-#### Text Operations
-- **Clipboard Integration**: Use system clipboard for cut/copy/paste
-- **Search Functionality**: Implement text finding with highlighting
-- **Undo System**: Utilize Tkinter's built-in undo/redo
+### 3. Multiple tabs
+Use `ttk.Notebook`. Each tab owns its own `Text` widget and file state.
 
-#### User Interface
-- **Layout Management**: Use frames and packing for responsive design
-- **Event Handling**: Bind keyboard and mouse events
-- **Dialog Windows**: Create custom dialogs for find and font selection
+### 4. Line numbers
+A side panel that mirrors the main `Text` and shows numbers. Real implementations use a canvas with re-renders on scroll/edit.
 
-## 🚀 How to Run
+### 5. Recent files
+Keep the last N opened paths in a JSON config; show as the bottom of the File menu.
 
-1. **Install Python**: Ensure Python 3.6+ is installed (Tkinter included)
+### 6. Themes (dark/light)
+Store palettes in a dict; apply by iterating all widgets and reconfiguring `bg`/`fg`.
 
-2. **Run the Editor**:
-   ```bash
-   python basictexteditor.py
-   ```
+### 7. Print support
+Use `os.startfile(path, "print")` on Windows or `lpr` via `subprocess` on Linux/macOS.
 
-3. **Using the Editor**:
-   - **New**: Ctrl+N or File → New
-   - **Open**: Ctrl+O or File → Open
-   - **Save**: Ctrl+S or File → Save
-   - **Find**: Ctrl+F or Edit → Find
-   - **Font**: Format → Font
+### 8. Autosave
+Every 30 seconds, write to `current_file + ".autosave"`. Offer to restore on next open if it exists and is newer.
 
-## 💡 Usage Examples
+### 9. Markdown preview
+Pair with a `tkhtmlview` widget that renders Markdown to HTML side-by-side.
 
-### Basic File Operations
-```python title="basictexteditor.py" showLineNumbers{1}
-# Create new editor instance
-editor = BasicTextEditor()
+### 10. Drag and drop
+`tkinterdnd2` lets users drop files onto the window to open them.
 
-# Start the application
-editor.run()
-```
+## Architecture Notes
 
-### Keyboard Shortcuts
-- `Ctrl+N`: New file
-- `Ctrl+O`: Open file
-- `Ctrl+S`: Save file
-- `Ctrl+Z`: Undo
-- `Ctrl+Y`: Redo
-- `Ctrl+X`: Cut
-- `Ctrl+C`: Copy
-- `Ctrl+V`: Paste
-- `Ctrl+A`: Select all
-- `Ctrl+F`: Find text
-
-### Menu Navigation
-- **File Menu**: New, Open, Save, Save As, Exit
-- **Edit Menu**: Undo, Redo, Cut, Copy, Paste, Select All, Find
-- **Format Menu**: Font selection, Word wrap toggle
-
-## 🎨 Advanced Features
-
-### Find Dialog
-- Search for text within the document
-- Highlight found text
-- Case-sensitive searching
-- Navigate through search results
-
-### Font Customization
-- Choose from system fonts
-- Adjust font size
-- Real-time preview
-- Apply changes instantly
-
-### Status Information
-- Current line and column position
-- Real-time cursor tracking
-- Document modification indicator
-
-## 🔧 Customization Options
-
-### Extending Functionality
-```python title="basictexteditor.py" showLineNumbers{1}
-# Add syntax highlighting
-def add_syntax_highlighting(self):
-    # Implement keyword highlighting
-    pass
-
-# Add line numbers
-def add_line_numbers(self):
-    # Create line number widget
-    pass
-
-# Add find and replace
-def find_replace(self):
-    # Implement replace functionality
-    pass
-```
+A class-based editor avoids `global` pitfalls and isolates state per window. Add a `Tab` class once you implement notebook tabs — each tab carries its own `Text`, `current_file`, and `modified` flag.
+
+Keep three responsibilities separate:
+- **Storage** — load/save files, encoding handling.
+- **UI** — menus, toolbar, status bar, key bindings.
+- **Document** — text content, modified flag, undo stack (Tkinter's `Text` already handles this).
+
+When these blur, every new feature breaks two old ones.
+
+## Real-World Applications
+- Internal tooling — log viewers, config editors.
+- Educational tools — student note-takers.
+- Specialized editors — Markdown, YAML, Python-only editors.
+- Onboarding for "real" editors — VS Code, Sublime use the same primitives, just way more of them.
+
+## Educational Value
+- Tkinter widget composition at scale (menus, toolbars, dialogs, status bars).
+- Event-driven flow tracking (`<<Modified>>`).
+- Unsaved-changes UX — three-button askyesnocancel.
+- Cross-cutting concerns — keyboard shortcuts as a layer over commands.
+- Class-based GUI architecture.
+
+## Next Steps
+- Implement **find-and-replace**.
+- Add **syntax highlighting** with Pygments.
+- Add **multiple tabs** with `ttk.Notebook`.
+- Add **line numbers** in a side panel.
+- Add **recent files** list.
+- Compare with [Basic File Explorer](./fileexplorer) — the smaller cousin of this project.
 
-### Configuration
-- Default font settings
-- Window size and position
-- File type associations
-- Custom keyboard shortcuts
-
-## 🛡️ Error Handling
-
-- **File Access**: Handle permission errors and file not found
-- **Encoding**: Support UTF-8 encoding for international characters
-- **Memory**: Efficient handling of large files
-- **User Input**: Validate font sizes and file paths
-
-## 📚 Learning Objectives
-
-- **GUI Development**: Learn Tkinter widget system
-- **Event-Driven Programming**: Handle user interactions
-- **File Operations**: Implement robust file I/O
-- **Menu Systems**: Create professional menu interfaces
-- **Text Processing**: Work with text widgets and operations
-
-## 🎯 Potential Enhancements
-
-1. **Syntax Highlighting**: Add code highlighting for programming languages
-2. **Multiple Tabs**: Support multiple documents simultaneously
-3. **Plugin System**: Allow custom extensions
-4. **Themes**: Add dark/light theme support
-5. **Auto-completion**: Implement text suggestions
-6. **Print Support**: Add document printing functionality
-7. **Recent Files**: Track recently opened files
-8. **Find and Replace**: Extend search with replace functionality
-
-## 🏆 Project Completion
-
-This Basic Text Editor project demonstrates:
-- ✅ Complete GUI application development
-- ✅ File management implementation
-- ✅ Text editing functionality
-- ✅ User interface design
-- ✅ Event handling and shortcuts
-- ✅ Professional application structure
-
-Perfect for beginners learning GUI programming and intermediate developers exploring desktop application development with Python!
+## Conclusion
+You built a real text editor: menus, toolbar, status bar, undo/redo, find, fonts, word wrap, and unsaved-changes handling. The class-based architecture means every future feature has a clear home. From here, every step toward "real" editor functionality is incremental — and every step you skip is one a commercial editor like VS Code already did for you. Find more GUI projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basicalarmclock.mdx b/src/content/docs/projects/Beginners/basicalarmclock.mdx
index 172be224..b92e80ac 100644
--- a/src/content/docs/projects/Beginners/basicalarmclock.mdx
+++ b/src/content/docs/projects/Beginners/basicalarmclock.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Alarm Clock
-description: Create a time-based alarm system with audio alerts using Python datetime and sound modules
+description: Build a Python alarm clock that triggers a sound at a chosen time. Learn the datetime and time modules, polling loops, input validation, sound playback, and how to evolve a single-alarm script into a full scheduler.
 sidebar:
   order: 43
 hero:
@@ -14,104 +14,250 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a functional alarm clock application that lets users set a specific time and receive an audio alert when that time arrives. This project demonstrates working with time modules, user input validation, and system audio playbook.
+An alarm clock teaches a deceptively rich set of concepts in a small amount of code: parsing user input that represents a time, comparing the current time against a target, looping until that target is reached, and triggering an external effect (sound) once it is. In this project you will build a command-line alarm clock that lets the user enter a 24-hour-format time and waits until exactly that moment to play an alert.
+
+Along the way you will learn:
+- How Python represents time with the `datetime` and `time` modules.
+- The polling pattern: "do something until a condition is true."
+- How to play sounds across platforms.
+- How to validate human-friendly input.
+- How a one-shot alarm grows into a scheduler with snooze, multiple alarms, and persistence.
 
 ## Prerequisites
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of datetime module
-- Familiarity with loops and conditional statements
+- Python 3.6 or above.
+- A text editor or IDE.
+- A working speaker. (Headphones if a 3 AM alarm test would disturb anyone.)
+- Familiarity with running scripts from the terminal.
+
+## Concepts You Will Use
+
+| Concept | Purpose |
+|---|---|
+| **`datetime`** | Get the current date and time, format it as text, parse text back into a time object. |
+| **`time.sleep(seconds)`** | Pause execution. Used so we do not check the clock millions of times per second. |
+| **`winsound` / `playsound` / `pygame.mixer`** | Make noise when the alarm fires. Choice depends on your OS. |
+| **String formatting (`strftime`)** | Turn a `datetime` object into a string like `"14:30:00"`. |
+| **Polling loop** | A `while True` loop that wakes periodically and checks whether the alarm time has arrived. |
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `basicAlarmClock`.
-2. Create a new file and name it `basicalarmclock.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `basicalarmclock.py` file.
+### Create the project
+1. Create a folder named `basic-alarm-clock`.
+2. Inside it, create `basicalarmclock.py`.
+3. (Optional) drop a custom `alarm.wav` file in the folder to use as the alert sound.
 
 ### Write the code
-1. Add the following code to your `basicalarmclock.py` file.
 <FileCode file="projects/beginners/basicalarmclock.py" lang="python" title="Basic Alarm Clock" />
-2. Save the file.
-3. Open the terminal and navigate to the project folder.
-4. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\basicAlarmClock> python basicalarmclock.py
-Enter the time of alarm to be set: HH.MM.SS AM/PM
-Enter the time: 02:30:00 PM
-Alarm is set for 02:30:00 PM
+
+### Run it
+```cmd title="command"
+C:\Users\username\Documents\basic-alarm-clock> python basicalarmclock.py
+Enter the time of alarm to be set (HH:MM:SS, 24-hour): 14:30:00
+Alarm is set for 14:30:00
 Waiting for alarm time...
 *Alarm sound plays*
 Wake Up! Wake Up!
 ```
 
-## Explanation
+> 💡 To test without waiting hours, set the alarm one minute into the future.
 
-1. The `import datetime` statement imports the datetime module for working with dates and times.
-2. The `import time` statement imports the time module for adding delays and sleep functionality.
-3. The `import winsound` statement imports the Windows sound module for playing audio alerts.
-4. The `def alarm(Timing):` function defines the main alarm functionality that takes the alarm time as a parameter.
-5. The `while True:` loop continuously checks the current time against the alarm time.
-6. The `datetime.datetime.now().strftime("%H:%M:%S")` gets the current time in HH:MM:SS format.
-7. The `if Now == Timing:` condition checks if the current time matches the alarm time.
-8. The `winsound.PlaySound()` function plays the alarm sound when the time matches.
-9. The `input()` function prompts the user to enter the desired alarm time.
-10. The program uses 24-hour time format for setting alarms.
+## Step-by-Step Explanation
 
-## Next Steps
+### 1. Import what you need
+```python title="basicalarmclock.py"
+import datetime
+import time
+import winsound        # Windows only — see "Cross-platform sound" below
+```
+- `datetime` gives you `datetime.datetime.now()`, which returns the current local date and time.
+- `time` gives you `time.sleep(seconds)` for pausing.
+- `winsound` plays a `.wav` file with one call. **It only works on Windows.** macOS and Linux need a different approach.
 
-Congratulations! You have successfully created a Basic Alarm Clock in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add multiple alarm support
-- Implement snooze functionality  
-- Create GUI interface with Tkinter
-- Add custom sound file selection
-- Include alarm name/description feature
-- Add recurring alarm options (daily, weekly)
-- Implement alarm history and logs
-- Add volume control for alarms
-- Create different alarm tones
+### 2. Ask for the alarm time
+```python title="basicalarmclock.py"
+alarm_time = input("Enter the time of alarm (HH:MM:SS, 24-hour): ")
+print(f"Alarm is set for {alarm_time}")
+```
+Using **24-hour format** (`14:30:00` instead of `2:30:00 PM`) is the simplest choice: it avoids ambiguity, and `strftime("%H:%M:%S")` produces the same format directly.
 
-## Conclusion
+### 3. Poll the clock
+```python title="basicalarmclock.py"
+while True:
+    now = datetime.datetime.now().strftime("%H:%M:%S")
+    if now == alarm_time:
+        print("Wake Up! Wake Up!")
+        winsound.PlaySound("alarm.wav", winsound.SND_ASYNC)
+        break
+    time.sleep(1)
+```
+- `datetime.datetime.now()` returns a full date+time object.
+- `.strftime("%H:%M:%S")` formats it as `HH:MM:SS` (zero-padded).
+- The comparison is a **string equality check** — both sides are strings in the same format.
+- `winsound.SND_ASYNC` plays the sound in the background so the next `print` is not delayed.
+- `time.sleep(1)` is the key to making this loop efficient. Without it, Python would check the clock millions of times per second and pin a CPU core.
 
-In this project, you learned how to create a Basic Alarm Clock in Python. You also learned how to work with time modules, user input validation, and system audio playback. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicalarmclock.py)
+### 4. Why we sleep for one second
 
-## Features
+If the alarm is set for `14:30:00`, we have exactly **one** second during which the time string equals `"14:30:00"`. Sleeping for more than a second could cause us to skip past it entirely. One second is the right balance.
 
-- **12-Hour Time Format**: Accepts AM/PM time input
-- **Real-Time Monitoring**: Continuously checks current time
-- **Audio Alerts**: Plays sound when alarm triggers
-- **Automatic Termination**: Stops after alarm time passes
-- **Simple Interface**: Command-line based interaction
+## Cross-Platform Sound
 
-## Next Steps
+`winsound` only exists on Windows. For a program that works everywhere, use **`playsound`** (any OS) or **`pygame.mixer`**:
+
+```bash title="install"
+pip install playsound==1.2.2
+```
+
+```python title="cross_platform.py"
+from playsound import playsound
+playsound("alarm.wav")
+```
+
+Or with Pygame:
+```python title="pygame_sound.py"
+from pygame import mixer
+mixer.init()
+mixer.music.load("alarm.wav")
+mixer.music.play()
+```
+
+If you have no `.wav` file handy, beep the terminal:
+```python title="beep.py"
+print("\a")          # ASCII bell — terminal may flash or beep
+```
+
+## Robust Input
+
+The basic version accepts any string. A malformed value like `"14:30"` (missing seconds) silently fails — the loop just never matches. Validate up front:
 
-### Enhancements
-- Add multiple alarm support
-- Implement snooze functionality
-- Create GUI interface with Tkinter
-- Add custom sound file selection
-- Include alarm name/description feature
-- Add recurring alarm options (daily, weekly)
-- Implement alarm history and logs
-
-### Learning Extensions
-- Study threading for non-blocking alarms
-- Explore cross-platform audio libraries
-- Learn about system notifications
-- Practice with configuration files for settings
-- Understand process scheduling and background tasks
+```python title="validate.py"
+from datetime import datetime
+
+while True:
+    raw = input("Enter alarm time (HH:MM:SS): ")
+    try:
+        alarm_dt = datetime.strptime(raw, "%H:%M:%S")
+        break
+    except ValueError:
+        print("Bad format. Use HH:MM:SS, for example 07:30:00.")
+```
+`strptime` parses the string into a real `datetime` object **and** raises `ValueError` if the format is wrong. Once you have a `datetime`, you can compare numerically instead of by string.
+
+## Better: Compute the Delay and Sleep Once
+
+The polling pattern is fine for short waits. For long waits, it is cleaner to compute exactly how many seconds away the alarm is and sleep that long:
+
+```python title="single_sleep.py"
+from datetime import datetime, timedelta
+
+target = datetime.strptime(input("Time HH:MM:SS: "), "%H:%M:%S").time()
+now = datetime.now()
+alarm_dt = now.replace(hour=target.hour, minute=target.minute,
+                       second=target.second, microsecond=0)
+if alarm_dt <= now:
+    alarm_dt += timedelta(days=1)    # next day if the time already passed
+seconds = (alarm_dt - now).total_seconds()
+print(f"Sleeping for {seconds:.0f} seconds...")
+time.sleep(seconds)
+print("Wake Up!")
+```
+This:
+- Handles **next-day** alarms automatically (e.g., set 06:00 at midnight).
+- Sleeps a single, precise interval instead of waking every second.
+- Uses one clear `datetime` object rather than two strings to compare.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Alarm never triggers | Mismatched format (`"2:30:00"` vs `"02:30:00"`) | Use `strptime` validation; require zero-padding |
+| 100 % CPU spike | Forgot `time.sleep(1)` | Always sleep inside polling loops |
+| `ModuleNotFoundError: No module named 'winsound'` on Mac/Linux | `winsound` is Windows-only | Use `playsound` or `pygame.mixer` |
+| Sound plays once then silence | `SND_ASYNC` returns immediately — script then exits | Loop the sound or `time.sleep` after triggering |
+| Alarm fires twice the same second | Loop did not `break` after match | Add `break` after firing |
+
+## Variations to Try
+
+### 1. Snooze
+After the alarm fires, ask the user:
+```python title="snooze.py"
+choice = input("Snooze 5 minutes? (y/n): ")
+if choice.lower() == "y":
+    time.sleep(5 * 60)
+    fire_alarm()
+```
+
+### 2. Multiple alarms
+Keep a list of alarm times. Sort, then sleep until the soonest:
+```python title="multi.py"
+alarms = sorted({"06:30:00", "07:00:00", "07:15:00"})
+for a in alarms:
+    wait_until(a)
+    fire_alarm()
+    print(f"Alarm at {a} fired.")
+```
+
+### 3. Custom alarm message
+Let the user attach a label: *"Take medicine — 14:30"* — show it on trigger.
+
+### 4. Persistent alarms
+Save alarms to a JSON file so they survive restarts.
+```python title="persist.py"
+import json
+alarms = json.loads(Path("alarms.json").read_text())
+```
+
+### 5. GUI version
+Build a Tkinter window with time-entry fields, a list of pending alarms, and a snooze button. See [Simple Reminder App](./simplereminderapp) for a similar pattern.
+
+### 6. Recurring alarms
+Use the [`schedule`](https://schedule.readthedocs.io/) library:
+```python title="recur.py"
+import schedule
+schedule.every().day.at("07:00").do(fire_alarm)
+while True:
+    schedule.run_pending()
+    time.sleep(30)
+```
+
+### 7. System notification
+On Windows use `plyer`; on macOS use `osascript`. Combine with sound for a full desktop alert.
+
+## Real-World Applications
+
+- Personal wake-up alarm or pomodoro timer.
+- Reminder for medication, meetings, calls.
+- Trigger automation scripts at a specific time (lights, backups, downloads).
+- Build the timing core of a meditation or workout app.
+- Server-side cron alternative for tasks that need a specific local time.
+
+## Features Implemented
+
+- **24-hour time format** input.
+- **Real-time monitoring** with a polling loop.
+- **Audio alert** via `winsound`.
+- **Automatic termination** once the alarm fires.
+- **Simple, distraction-free CLI**.
 
 ## Educational Value
 
 This project teaches:
-- **Time Manipulation**: Working with datetime objects and formatting
-- **Input Validation**: Parsing and validating time formats
-- **System Integration**: Using OS-specific sound capabilities
-- **Loop Control**: Implementing monitoring loops with break conditions
-- **String Processing**: Extracting and converting time components
-- **Real-Time Programming**: Creating responsive time-based applications
-
-Perfect for understanding how time-based applications work and practicing system-level programming concepts.
+- **Working with time** — `datetime`, `strftime`, `strptime`, `timedelta`.
+- **Loop control** — polling with `time.sleep`.
+- **OS-specific code** — recognizing when a module only works on one platform.
+- **Input validation** — converting and validating user input early.
+- **Trade-offs** — polling versus single-sleep, simple versus precise.
+
+## Next Steps
+
+- Replace `winsound` with a cross-platform library so it runs on Mac/Linux.
+- Add a Tkinter GUI with multiple slots, on/off switches, and snooze.
+- Schedule daily recurring alarms with the `schedule` library.
+- Combine with a TTS library (`pyttsx3`) to have the alarm read out a message.
+- Persist alarms across restarts in a JSON or SQLite file.
+- Wrap as a Windows Service or macOS LaunchAgent so it runs at boot.
+
+## Conclusion
+
+You built a working alarm clock and saw two ways to wait for a target time — polling and single-sleep — each with its own trade-offs. The same patterns (polling loop, time formatting, input validation) appear in scheduled-task tools, monitoring scripts, and game timers. Source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicalarmclock.py). Explore more beginner projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basicchatbot.mdx b/src/content/docs/projects/Beginners/basicchatbot.mdx
index 0645e6fa..dc6a7798 100644
--- a/src/content/docs/projects/Beginners/basicchatbot.mdx
+++ b/src/content/docs/projects/Beginners/basicchatbot.mdx
@@ -1,6 +1,6 @@
 ---
-title: Basic Chatbot
-description: A basic chatbot that can answer some basic questions. You have some predefined commands that you can ask the chatbot and it will answer you accordingly. 
+title: Basic Chatbot (Jarvis-style)
+description: Build a voice-activated Python assistant with speech recognition, text-to-speech, web search, music control, and a path to LLM-powered intelligence. Learn pyttsx3, speech_recognition, intent dispatch, and ethical assistant design.
 sidebar: 
     order: 10
 hero:
@@ -13,282 +13,323 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-This is a basic chatbot that can answer some basic questions. You have some predefined commands that you can ask the chatbot and it will answer you accordingly. In this chatbot, you can ask the chatbot to open youtube, google, stackoverflow, play music, tell you the time, open code, and send an email to someone. This is inspire by Jarvis Project From CodeWithHarry.
+A "Jarvis"-style voice assistant is one of the most rewarding beginner-to-intermediate Python projects. In ~100 lines you wire together a microphone, speech-to-text, a command dispatcher, web automation, and a text-to-speech engine — and end up with something that genuinely *responds* when you speak. In this tutorial you build that classic assistant (open YouTube, search Wikipedia, tell the time, send mail), then refactor the if/elif chain into a clean intent registry, add fuzzy matching, and finish with a sketch of an LLM-powered upgrade using the OpenAI / Anthropic / local-LLM APIs.
+
+You will learn:
+- How `speech_recognition` captures and transcribes microphone input.
+- How `pyttsx3` produces speech offline.
+- The intent-dispatch pattern (vs. growing `if`/`elif` chains).
+- How to integrate Wikipedia, `webbrowser`, and SMTP cleanly.
+- How to design assistants safely (mic privacy, command validation).
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- pyttsx3 module
-- speech_recognition module
-- wikipedia module
-- webbrowser module
-
-## Before you Start
-Before starting making this project, you must have python installed on your computer. If you don’t have python installed you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don’t have any code editor or IDE installed you can download Visual Studio Code from [here](https://code.visualstudio.com/download). You must have the request module and BeautifulSoup module installed on your computer. If you don’t have these modules installed you can install them by using the following commands in your terminal. 
-
-```cmd title="command" showLineNumbers{1} {1-10}
-C:\Users\Your Name>pip install pyttsx3
-C:\Users\Your Name>pip install speechRecognition
-C:\Users\Your Name>pip install wikipedia
-C:\Users\Your Name>pip install webbrowser
-C:\Users\Your Name>pip install pyaudio
-C:\Users\Your Name>pip install smtplib
-C:\Users\Your Name>pip install setuptools
+- Python 3.6 or above.
+- Microphone and speakers.
+- A code editor or IDE.
+- Internet connection (for Google's speech recognition and Wikipedia).
+
+## Install Dependencies
+```cmd title="install"
+pip install pyttsx3 SpeechRecognition wikipedia pyaudio
 ```
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `basicchatbot`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `basicchatbot.py`.
-4. Copy the code given code and paste it in your `basicchatbot.py` file.
-
-## Write the code
-1. Copy and paste the following code in your `basicchatbot.py` file.
-<FileCode file="projects/beginners/basicchatbot.py" lang="python" title="Basic Chat Bot" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `basicchatbot`.
-```cmd title="command" showLineNumbers{1} {1-30}
-C:\Users\Your Name\basicchatbot> python basicchatbot.py
-Listening...
-Recognizing...
-User said: Silicon Valley Wikipedia
+If `pyaudio` fails on Windows:
+```cmd title="windows"
+pip install pipwin
+pipwin install pyaudio
+```
 
-Silicon Valley is a region in Northern California that is a global center for high technology and innovation. Located in the southern part of the San Francisco Bay Area, it corresponds roughly to the geographical area of the Santa Clara Valley.
-Listening...
-Recognizing...
-User said: open YouTube
+On macOS:
+```bash title="macos"
+brew install portaudio
+pip install pyaudio
+```
 
-Listening...
-Recognizing...
-User said: open Google
+On Linux:
+```bash title="linux"
+sudo apt install portaudio19-dev python3-pyaudio
+pip install pyaudio
+```
 
-Listening...
-Recognizing...
-User said: open stack overflow
+## Getting Started
 
-Listening...
-Recognizing...
-Say that again please...
-Listening...
-Recognizing...
-User said: tell me the time
+### Create the project
+1. Create folder `basicchatbot`.
+2. Inside, create `basicchatbot.py`.
 
+### Write the code
+<FileCode file="projects/beginners/basicchatbot.py" lang="python" title="Basic Chatbot" />
+
+### Run it
+```cmd title="command"
+C:\Users\Your Name\basicchatbot> python basicchatbot.py
+Good Evening!
+I am Jarvis Sir. Please tell me how may I help you
 Listening...
 Recognizing...
-User said: open code
+User said: open YouTube
 ```
 
-## Explanation
-1. Import the required modules.
-```python title="basicchatbot.py" showLineNumbers{1} {1-10}
-import pyttsx3 #pip install pyttsx3
-import speech_recognition as sr #pip install speechRecognition
-import datetime
-import wikipedia #pip install wikipedia
-import webbrowser
-import os
-import smtplib
-```
+## Step-by-Step Explanation
 
-2. Initialize the pyttsx3 module.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-engine = pyttsx3.init('sapi5')
-voices = engine.getProperty('voices')
-engine.setProperty('voice', voices[0].id)
-```
+### 1. Initialize TTS
+```python title="basicchatbot.py"
+import pyttsx3
+engine = pyttsx3.init("sapi5" if os.name == "nt" else None)
+voices = engine.getProperty("voices")
+engine.setProperty("voice", voices[0].id)
 
-3. Define a function `speak()` that will take `audio` as an argument and will speak the `audio` that is passed to it.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-def speak(audio):
-    engine.say(audio)
+def speak(text: str):
+    print(f"Jarvis: {text}")
+    engine.say(text)
     engine.runAndWait()
 ```
+- `sapi5` is the Windows speech API; on macOS use `nsss`, on Linux `espeak`.
+- `voices[0]` is usually male; `voices[1]` female on Windows.
+- `runAndWait()` blocks until speech finishes — important because the assistant is otherwise a fire-and-forget design.
 
-4. Define a function `wishMe()` that will wish you according to the time.
-```python title="basicchatbot.py" showLineNumbers{1} {1-20}
-def wishMe():
-    hour = int(datetime.datetime.now().hour)
-    if hour>=0 and hour<12:
-        speak("Good Morning!")
-
-    elif hour>=12 and hour<18:
-        speak("Good Afternoon!")   
-
-    else:
-        speak("Good Evening!")  
-
-    speak("I am Jarvis Sir. Please tell me how may I help you")       
+### 2. Wish based on time of day
+```python title="basicchatbot.py"
+import datetime
+def wish_me():
+    hour = datetime.datetime.now().hour
+    if   hour < 12:  speak("Good Morning!")
+    elif hour < 18:  speak("Good Afternoon!")
+    else:            speak("Good Evening!")
+    speak("I am Jarvis. How may I help you?")
 ```
 
-5. Define a function `takeCommand()` that will take microphone input from the user and returns string output.
-```python title="basicchatbot.py" showLineNumbers{1} {1-30}
-def takeCommand():
-    #It takes microphone input from the user and returns string output
-
+### 3. Capture and recognize speech
+```python title="basicchatbot.py"
+import speech_recognition as sr
+def take_command() -> str:
     r = sr.Recognizer()
     with sr.Microphone() as source:
         print("Listening...")
+        r.adjust_for_ambient_noise(source, duration=0.5)
         r.pause_threshold = 1
-        audio = r.listen(source)
-
+        try:
+            audio = r.listen(source, timeout=5, phrase_time_limit=8)
+        except sr.WaitTimeoutError:
+            return ""
     try:
-        print("Recognizing...")    
-        query = r.recognize_google(audio, language='en-in')
-        print(f"User said: {query}\n")
-
-    except Exception as e:
-        # print(e)    
-        print("Say that again please...")  
-        return "None"
-    return query
+        print("Recognizing...")
+        query = r.recognize_google(audio, language="en-in")
+        print(f"User said: {query}")
+        return query.lower()
+    except sr.UnknownValueError:
+        speak("Sorry, I did not catch that.")
+        return ""
+    except sr.RequestError as e:
+        speak("Speech service unavailable.")
+        return ""
 ```
-
-6. Define a function `sendEmail()` that will send an email to the person you want to send an email to.
-```python title="basicchatbot.py" showLineNumbers{1} {1-14}
-def sendEmail(to, content):
-    server = smtplib.SMTP('smtp.gmail.com', 587)
-    server.ehlo()
-    server.starttls()
-    server.login('youremail@gmail.com', 'your-password') # Enter your email and password at
-    server.sendmail('youremail@gmail.com', to, content) # Enter your email at youremail@gmail
-    server.close()
+Important upgrades over the naïve version:
+- **`adjust_for_ambient_noise`** calibrates for background hum.
+- **`timeout` and `phrase_time_limit`** prevent the call from hanging forever.
+- **Specific exception handling** distinguishes "could not hear you" from "Google is offline."
+
+### 4. The if/elif command chain (start here)
+```python title="basicchatbot.py"
+import webbrowser, wikipedia, os
+while True:
+    query = take_command()
+    if not query: continue
+
+    if "wikipedia" in query:
+        speak("Searching Wikipedia.")
+        topic = query.replace("wikipedia", "").strip()
+        try:
+            summary = wikipedia.summary(topic, sentences=2)
+            speak(summary)
+        except wikipedia.exceptions.PageError:
+            speak("I could not find that topic.")
+    elif "open youtube" in query:
+        webbrowser.open("https://youtube.com")
+    elif "open google" in query:
+        webbrowser.open("https://google.com")
+    elif "the time" in query:
+        speak(datetime.datetime.now().strftime("It is %H %M."))
+    elif "quit" in query or "exit" in query:
+        speak("Goodbye."); break
 ```
-
-7. Define the main function `main()` that will call all the functions.
-```python title="basicchatbot.py" showLineNumbers{1} {1-4}
-if __name__ == "__main__":
-    wishMe()
-    while True:
+This works — but the chain becomes unmanageable past ten commands. The next section fixes that.
+
+## Refactor: Intent Registry
+
+Replace the if/elif chain with a list of *(matcher, handler)* pairs:
+```python title="intents.py"
+INTENTS = []
+
+def intent(*keywords):
+    def deco(fn):
+        INTENTS.append((keywords, fn))
+        return fn
+    return deco
+
+@intent("wikipedia")
+def do_wiki(query):
+    topic = query.replace("wikipedia", "").strip()
+    speak(wikipedia.summary(topic, sentences=2))
+
+@intent("open youtube", "play youtube")
+def do_youtube(query):
+    webbrowser.open("https://youtube.com")
+
+@intent("the time", "what time")
+def do_time(query):
+    speak(datetime.datetime.now().strftime("It is %H %M."))
+
+def dispatch(query):
+    for kws, fn in INTENTS:
+        if any(k in query for k in kws):
+            return fn(query)
+    speak("I don't know how to do that yet.")
 ```
+Adding a new command is now one decorator, no menu re-shuffling. Each handler is independently testable.
 
-8. Call the `takeCommand()` function and store the returned value in the variable `query`.
-```python title="basicchatbot.py" showLineNumbers{1} {1-10}
-if __name__ == "__main__":
-    wishMe()
-    while True:
-    # if 1:
-        query = takeCommand().lower()
-```
+## Fuzzy Matching
 
-9. Check if the word `wikipedia` is in the `query` variable. If it is in the `query` variable then call the `speak()` function and speak the following lines.
-```python title="basicchatbot.py" showLineNumbers{1} {1-10}
-if 'wikipedia' in query:
-    speak('Searching Wikipedia...')
-    query = query.replace("wikipedia", "")
-    results = wikipedia.summary(query, sentences=2)
-    speak("According to Wikipedia")
-    print(results)
-    speak(results)
+Exact substring matching breaks on typos ("youtuve" instead of "youtube"). Use **`difflib`**:
+```python title="fuzzy.py"
+from difflib import get_close_matches
+def best_intent(query):
+    all_words = [k for kws, _ in INTENTS for k in kws]
+    return get_close_matches(query, all_words, n=1, cutoff=0.6)
 ```
 
-10. Check if the word `open youtube` is in the `query` variable. If it is in the `query` variable then call the `webbrowser.open()` function and open youtube.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-elif 'open youtube' in query:
-    webbrowser.open("youtube.com")
+For real-world intent matching, consider **`rapidfuzz`** (faster) or train a small classifier with scikit-learn over labeled examples.
+
+## Sending Email Safely
+
+The original tutorial included an email handler with hardcoded credentials. Replace with environment variables and an App Password:
+```python title="email.py"
+import smtplib, os
+from email.mime.text import MIMEText
+
+def send_email(to_addr: str, body: str):
+    sender = os.environ["GMAIL_USER"]
+    password = os.environ["GMAIL_APP_PASSWORD"]
+    msg = MIMEText(body)
+    msg["Subject"] = "From Jarvis"
+    msg["From"] = sender
+    msg["To"] = to_addr
+    with smtplib.SMTP("smtp.gmail.com", 587) as s:
+        s.starttls()
+        s.login(sender, password)
+        s.send_message(msg)
 ```
-
-11. Check if the word `open google` is in the `query` variable. If it is in the `query` variable then call the `webbrowser.open()` function and open google.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-elif 'open google' in query:
-    webbrowser.open("google.com")
+See [Basic Email Sender](./emailsender) for the full breakdown.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `OSError: No Default Input Device` | No mic, or system muted | Check OS sound settings |
+| `pyaudio` install fails | Missing PortAudio | Use OS-specific install steps above |
+| Recognizer hangs | No `timeout` set | Pass `timeout=5` to `r.listen()` |
+| TTS sounds robotic | Default voice | Try `voices[1]` or install a better engine |
+| Mic always hears its own output | TTS and STT both running | Use headphones, or pause listening during `runAndWait` |
+| 400 Bad Request from Google | No internet | Catch `sr.RequestError`, offer fallback |
+| Same word matches two intents | Overlapping keywords | Order intents most-specific first |
+
+## Privacy & Ethics
+
+Voice assistants raise real concerns:
+- **The mic is always live during `listen()`** — pause when not in use.
+- **Audio is sent to Google's servers** by default. Use an **offline** recognizer (`Vosk`, `Whisper`) for privacy-sensitive deployments.
+- **Never log raw audio or transcripts** without explicit user consent.
+- **Hardcoded passwords in source** are a constant temptation in tutorials — use env vars or `keyring`.
+
+If you ship the assistant to friends/family:
+- Display a clear "listening" indicator.
+- Provide a one-key mute.
+- Document what data leaves the device.
+
+## Variations to Try
+
+### 1. Wake word
+Only respond after hearing "hey jarvis". Libraries: **`pvporcupine`** (best, free for personal), **`snowboy`** (deprecated but widely used).
+
+### 2. Offline speech recognition
+Replace `recognize_google` with `Vosk` (small, ~50 MB models) or `OpenAI whisper` running locally. No internet, no third-party logging.
+
+### 3. LLM-powered fallback
+When no built-in intent matches, send the query to an LLM:
+```python title="llm.py"
+from anthropic import Anthropic
+client = Anthropic()
+def llm_answer(query):
+    r = client.messages.create(
+        model="claude-haiku-4-5-20251001",
+        max_tokens=500,
+        messages=[{"role": "user", "content": query}])
+    return r.content[0].text
 ```
+Now your assistant can chat about anything — but it costs per-call and needs an API key.
 
-12. Check if the word `open stackoverflow` is in the `query` variable. If it is in the `query` variable then call the `webbrowser.open()` function and open stackoverflow.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-elif 'open stackoverflow' in query:
-    webbrowser.open("stackoverflow.com")   
-```
+### 4. Smart-home control
+Integrate with **Home Assistant** or **Hue** APIs: "turn off the lights".
 
-13. Check if the word `play music` is in the `query` variable. If it is in the `query` variable then call the `os.listdir()` function and list all the files in the music directory. Then call the `os.startfile()` function and play the first song in the music directory.
-```python title="basicchatbot.py" showLineNumbers{1} {1-6}
-elif 'play music' in query:
-    music_dir = 'Your Music Directory' # Enter your music directory here like C:\\Users\\Ravi\\Music
-    songs = os.listdir(music_dir)
-    print(songs)    
-    os.startfile(os.path.join(music_dir, songs[0]))
-```
+### 5. Music player
+Replace `os.startfile` with [Basic Music Player](./basicmusicplayer) — actual play/pause/next controls.
 
-14. Check if the word `the time` is in the `query` variable. If it is in the `query` variable then call the `datetime.datetime.now()` function and get the current time. Then call the `speak()` function and speak the current time.
-```python title="basicchatbot.py" showLineNumbers{1} {1-4}
-elif 'the time' in query:
-    strTime = datetime.datetime.now().strftime("%H:%M:%S")    
-    speak(f"Sir, the time is {strTime}")
-```
+### 6. Calendar / weather / news
+Pull from APIs: Google Calendar, OpenWeatherMap, NewsAPI.
 
-15. Check if the word `open code` is in the `query` variable. If it is in the `query` variable then call the `os.startfile()` function and open the code.
-```python title="basicchatbot.py" showLineNumbers{1} {1-3}
-elif 'open code' in query:
-    codePath = "C:\\Users\\Ravi\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe"
-    os.startfile(codePath)
-```
+### 7. Cross-platform launcher
+`platform.system()` to pick the right `subprocess` command for opening VS Code on Windows/macOS/Linux.
 
-16. Check if the word `email to ravi` is in the `query` variable. If it is in the `query` variable then call the `speak()` function and speak the following lines. Then call the `takeCommand()` function and store the returned value in the variable `content`. Then call the `sendEmail()` function and send the email to the person you want to send the email to.
-```python title="basicchatbot.py" showLineNumbers{1} {1-14}
-elif 'email to ravi' in query:
-    try:
-        speak("What should I say?")
-        content = takeCommand()
-        to = "ravi@gmail.com"
-        sendEmail(to, content)
-        speak("Email has been sent!")
-    except Exception as e:
-        print(e)
-        speak("Sorry. I am not able to send this email")
-```
+### 8. Conversation memory
+Keep a short rolling history so "open it" works after "find me Python docs".
 
-## Usage
-1. Open the terminal in your code editor or IDE and navigate to the folder `basicchatbot`.
-```cmd title="command" showLineNumbers{1} {1-2}
-C:\Users\Your Name\basicchatbot> python basicchatbot.py
-```
-2. Run the `basicchatbot.py` file.
-```cmd title="command" showLineNumbers{1} {1-2}
-C:\Users\Your Name\basicchatbot> python basicchatbot.py
-```
-3. Now you can ask the chatbot to open youtube, google, stackoverflow, play music, tell you the time, open code, and send an email to someone.
+### 9. Multi-language
+`recognize_google` accepts `language="hi-IN"` (Hindi), `"fr-FR"`, etc. Pair with a TTS voice that matches.
 
-## Output
-```cmd title="command" showLineNumbers{1} {1-30}
-C:\Users\Your Name\basicchatbot> python basicchatbot.py
-Listening...
-Recognizing...
-User said: Silicon Valley Wikipedia
+### 10. Web GUI
+Run the assistant in a Flask app with a "press to talk" button. Streams the response back as text and synthesized audio.
 
-Silicon Valley is a region in Northern California that is a global center for high technology and innovation. Located in the southern part of the San Francisco Bay Area, it corresponds roughly to the geographical area of the Santa Clara Valley.
-Listening...
-Recognizing...
-User said: open YouTube
-
-Listening...
-Recognizing...
-User said: open Google
-
-Listening...
-Recognizing...
-User said: open stack overflow
-
-Listening...
-Recognizing...
-Say that again please...
-Listening...
-Recognizing...
-User said: tell me the time
+## Architecture for the Real Version
 
-Listening...
-Recognizing...
-User said: open code
 ```
+microphone
+   ↓
+[Wake-word detector]  ← optional
+   ↓
+[Speech-to-text]  (Vosk / Whisper / Google)
+   ↓
+[Intent classifier]  ← if/elif → registry → ML model
+   ↓
+[Handler]  ← Wikipedia / webbrowser / smarthome / LLM fallback
+   ↓
+[Text-to-speech]  (pyttsx3 / ElevenLabs / Azure)
+   ↓
+speaker
+```
+Each stage is swappable. Start with the simplest version of each, then upgrade where it matters.
+
+## Real-World Applications
+- **Personal automation** — launch apps, run scripts.
+- **Accessibility** — voice control for users with limited mobility.
+- **Smart home** — Alexa/Google Home clones using your own voice.
+- **Customer-service bots** — but rate-limit and validate inputs aggressively.
+- **Hands-free workflows** — cooking, garage, workshop.
+
+## Educational Value
+- **Microphone I/O** — capturing audio in Python.
+- **External APIs** — Wikipedia, Google STT.
+- **Pattern matching** — keyword vs. fuzzy vs. classifier.
+- **Intent-dispatch** — design pattern used by every voice assistant.
+- **Cross-platform concerns** — TTS engines differ per OS.
+- **Privacy mindset** — every audio capture is a trust boundary.
 
 ## Next Steps
-Congratulations 🎉 you have successfully created a basic chatbot that can answer some basic questions. You have some predefined commands that you can ask the chatbot and it will answer you accordingly. Now you can ask the chatbot to open youtube, google, stackoverflow, play music, tell you the time, open code, and send an email to someone. You can also add more commands to the chatbot.
-
-Here are some ideas:
-1. You can add more commands to the chatbot.
-2. You can add more features to the chatbot.
-3. Add more voices to the chatbot.
-4. You can use more intelligent algorithms to make the chatbot more intelligent.
-5. Use open-source libraries to make the chatbot more intelligent.
+- Refactor to the **intent-registry** pattern.
+- Move secrets to **environment variables**.
+- Add **wake-word detection** so the mic is not always processing.
+- Switch to **offline STT** (Vosk / Whisper) for privacy.
+- Wire an **LLM fallback** for the long tail of queries.
+- Cross-link with [Basic Email Sender](./emailsender) and [Basic Music Player](./basicmusicplayer).
 
 ## Conclusion
-Now you have a good understanding of how to create a basic chatbot that can answer some basic questions. You have some predefined commands that you can ask the chatbot and it will answer you accordingly. In this chatbot, you can ask the chatbot to open youtube, google, stackoverflow, play music, tell you the time, open code, and send an email to someone. This is inspire by Jarvis Project From CodeWithHarry. You can also add more commands to the chatbot. You can add more features to the chatbot. Add more voices to the chatbot. You can use more intelligent algorithms to make the chatbot more intelligent. Use open-source libraries to make the chatbot more intelligent.
\ No newline at end of file
+You built a working voice assistant — mic in, action out, voice back — with off-the-shelf libraries. The same architecture (STT → intent → handler → TTS) underlies every commercial assistant from Alexa to Siri. The difference is the *quality* of each stage, not the shape of the pipeline. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicchatbot.py). Find more automation projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basicmusicplayer.mdx b/src/content/docs/projects/Beginners/basicmusicplayer.mdx
index 490a8580..2be260ff 100644
--- a/src/content/docs/projects/Beginners/basicmusicplayer.mdx
+++ b/src/content/docs/projects/Beginners/basicmusicplayer.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Music Player
-description: Build a GUI music player with playlist management, playback controls, and directory loading using Tkinter and Pygame
+description: Build a GUI music player in Python with Tkinter and Pygame. Learn event-driven programming, playlist management, audio playback, file dialogs, and how to grow a 100-line script into a polished desktop app.
 sidebar:
   order: 45
 hero:
@@ -14,94 +14,256 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Create a fully functional music player application with a graphical user interface that supports playlist management, playback controls (play, pause, stop, resume), directory loading, and visual feedback. This project combines GUI development with audio processing capabilities.
+A working desktop music player is one of the best mid-beginner projects because it combines four things at once: a **graphical user interface** (windows, buttons, lists), **file-system browsing** (loading a folder), **audio playback** (actually producing sound), and **event-driven programming** (the program reacts to button clicks instead of running top-to-bottom). The result feels like a real application from the moment it launches.
+
+In this tutorial you will build a music player that:
+- Opens a window with playback controls (play, pause, stop, resume).
+- Lets the user pick a folder, then lists every audio file inside it.
+- Plays the selected song through your speakers.
+- Shows which song is currently playing and the player's status.
+
+By the end you will be comfortable with Tkinter widgets, `pygame.mixer`, the `os` module for folder listings, and the event loop model that all GUI frameworks share.
 
 ## Prerequisites
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of Tkinter for GUI development
-- Familiarity with file system operations
-- Understanding of event-driven programming
+- Python 3.6 or above.
+- A text editor or IDE.
+- A few `.mp3` (or `.wav`) files in a folder somewhere on your disk.
+- Comfort running a Python script from the terminal.
+- Familiarity with functions and conditionals (see [Simple Calculator](./simplecalculator) if you need a refresher).
 
-## Getting Started
+## What Each Library Does
+
+| Library | Why we use it |
+|---|---|
+| **Tkinter** | Standard-library GUI framework. Provides windows, buttons, labels, listboxes. |
+| **`tkinter.filedialog`** | A pre-made directory-picker dialog. |
+| **`pygame.mixer`** | A sound system that loads and plays audio files. We use Pygame *only* for the mixer, not for graphics. |
+| **`os`** | Lists files in a folder, builds file paths in a cross-platform way. |
 
-### Create a new project
-1. Create a new project folder and name it `basicMusicPlayer`.
-2. Create a new file and name it `basicmusicplayer.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `basicmusicplayer.py` file.
+Tkinter ships with Python. Pygame does not — install it with pip:
 
-### Install required dependencies
-1. Install pygame for audio handling:
-```bash
+```bash title="install"
 pip install pygame
 ```
 
+## Concept: The Event Loop
+
+Up to this point your programs ran top-to-bottom: read input, compute, print, exit. A GUI program is different. It enters a **loop** managed by Tkinter (`root.mainloop()`) that does three things forever:
+
+1. Wait for an event (mouse click, keypress, window resize).
+2. Run the function you registered for that event.
+3. Repaint the window.
+
+You never write the loop yourself. You just register **callbacks** — functions that Tkinter will call when something happens. `Button(command=play_song)` is registering `play_song` as the callback for "this button was clicked."
+
+## Getting Started
+
+### Create the project
+1. Create a folder named `basic-music-player`.
+2. Inside it, create `basicmusicplayer.py`.
+3. Have a separate folder ready with a handful of music files.
+
 ### Write the code
-1. Add the following code to your `basicmusicplayer.py` file.
 <FileCode file="projects/beginners/basicmusicplayer.py" lang="python" title="Basic Music Player" />
-2. Save the file.
-3. Prepare some music files in a folder.
-4. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\basicMusicPlayer> python basicmusicplayer.py
-[Music Player GUI Opens]
-- Click "Load" to browse and select music folder
-- Select songs from the playlist
-- Use Play, Pause, Stop, Resume buttons
-- Current song and status displayed at top
+
+### Run it
+```bash title="run"
+python basicmusicplayer.py
+```
+A window appears with **Load**, **Play**, **Pause**, **Stop**, **Resume** buttons and an empty playlist. Click **Load**, pick your music folder, then double-click a song and press **Play**.
+
+## Step-by-Step Explanation
+
+### 1. Initialize the audio mixer
+```python title="basicmusicplayer.py"
+import pygame.mixer as mixer
+mixer.init()
+```
+`mixer.init()` sets up the audio output device. Until you call it, none of the mixer functions work. Calling it more than once is harmless on most systems.
+
+### 2. Create the main window
+```python title="basicmusicplayer.py"
+from tkinter import *
+root = Tk()
+root.title("Basic Music Player")
+root.geometry("500x350")
+```
+- `Tk()` creates the top-level window.
+- `title` sets the title-bar text.
+- `geometry("WIDTHxHEIGHT")` sets the size in pixels.
+
+### 3. Organize widgets into frames
+```python title="basicmusicplayer.py"
+song_frame = LabelFrame(root, text="Now Playing")
+button_frame = LabelFrame(root, text="Controls")
+listbox_frame = LabelFrame(root, text="Playlist")
+```
+A `LabelFrame` is a box with a title. Grouping related widgets makes the layout obvious to both the user and the developer.
+
+### 4. Define playback callbacks
+```python title="basicmusicplayer.py"
+def play_song():
+    song_name = playlist.get(ACTIVE)
+    mixer.music.load(song_name)
+    mixer.music.play()
+    status_label.config(text="Playing")
+
+def pause_song():
+    mixer.music.pause()
+    status_label.config(text="Paused")
+
+def stop_song():
+    mixer.music.stop()
+    status_label.config(text="Stopped")
+
+def resume_song():
+    mixer.music.unpause()
+    status_label.config(text="Playing")
 ```
+- `playlist.get(ACTIVE)` returns the currently highlighted entry in the listbox.
+- `mixer.music.load(path)` reads the file (no sound yet).
+- `mixer.music.play()` actually starts playback.
+- `status_label.config(text=...)` updates the label in real time.
+
+### 5. Load a directory
+```python title="basicmusicplayer.py"
+from tkinter import filedialog
+import os
+
+def load():
+    directory = filedialog.askdirectory()
+    os.chdir(directory)
+    songs = os.listdir(directory)
+    for song in songs:
+        if song.lower().endswith((".mp3", ".wav")):
+            playlist.insert(END, song)
+```
+- `filedialog.askdirectory()` opens the OS file dialog. The function returns the chosen path (or an empty string if the user cancels).
+- `os.chdir(directory)` makes that folder the working directory so `mixer.music.load(song)` finds the file with just its name.
+- `os.listdir(directory)` returns every file/folder name as a list.
+- The `if song.lower().endswith(...)` filter ignores non-audio files like `cover.jpg` or `desktop.ini`.
+
+### 6. Build the playlist widget
+```python title="basicmusicplayer.py"
+playlist = Listbox(listbox_frame, bg="black", fg="white", width=60, height=10)
+playlist.pack()
+```
+A `Listbox` is the scrollable list on the left of the window. Items are added with `playlist.insert(END, "song_name.mp3")`.
+
+### 7. Hand control to Tkinter
+```python title="basicmusicplayer.py"
+root.mainloop()
+```
+This call **never returns** until the user closes the window. While it runs, Tkinter listens for clicks and dispatches them to your callbacks.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `pygame.error: mixer not initialized` | Forgot `mixer.init()` | Call it once near the top |
+| Window appears but no sound | Wrong working directory or unsupported format | `os.chdir(directory)` first; stick to MP3/WAV/OGG |
+| Listbox is empty after Load | All files filtered out by the extension check | Print `os.listdir(directory)` to see what is there |
+| Window freezes when clicking Play | Long-running code blocking the event loop | Audio playback is non-blocking; if you add other long work, run it on a thread |
+| `_tkinter.TclError: invalid command name` | Used a widget after `root.destroy()` | Do not touch widgets after the window closes |
+
+## Variations to Try
+
+### 1. Volume slider
+```python title="volume.py"
+def set_volume(value):
+    mixer.music.set_volume(float(value) / 100)
+
+Scale(root, from_=0, to=100, orient=HORIZONTAL, command=set_volume).pack()
+```
+`Scale` is Tkinter's slider; its `command` is called with the new value as a string each time the user drags.
+
+### 2. Display the current track in the title bar
+```python title="title.py"
+def play_song():
+    song = playlist.get(ACTIVE)
+    mixer.music.load(song); mixer.music.play()
+    root.title(f"Now playing — {song}")
+```
+
+### 3. Next / Previous buttons
+```python title="nav.py"
+def next_song():
+    current = playlist.curselection()
+    if not current: return
+    new_index = (current[0] + 1) % playlist.size()
+    playlist.selection_clear(0, END)
+    playlist.selection_set(new_index)
+    playlist.activate(new_index)
+    play_song()
+```
+
+### 4. Shuffle and repeat
+- **Shuffle:** keep a shuffled copy of the indices using `random.sample`.
+- **Repeat one:** when the song ends, replay it. Detect end with `pygame.mixer.music.get_busy()` polled by `root.after(1000, check)`.
+
+### 5. Show the duration of each song
+Use the `mutagen` library (`pip install mutagen`) to read MP3 tags:
+```python title="duration.py"
+from mutagen.mp3 import MP3
+mp3 = MP3(filename)
+duration_seconds = int(mp3.info.length)
+```
+
+### 6. Drag-and-drop loading
+Use `tkinterDnD2` to drop files directly onto the playlist.
+
+### 7. Save and load playlists
+Write the current list of songs to a `.txt` or `.json` file and load it on start.
+
+## Architecture Notes
+
+This script keeps everything at module level for simplicity. For a serious version, wrap state in a class:
+
+```python title="oop.py"
+class MusicPlayer:
+    def __init__(self, root):
+        mixer.init()
+        self.root = root
+        self.build_ui()
+
+    def build_ui(self):
+        # create frames, buttons, listbox here
+        ...
+
+    def play(self):
+        ...
+```
+Why bother? Because a class gives you:
+- **`self.current_song`** — clean state without globals.
+- **Testability** — instantiate and inspect without launching a window.
+- **Reusability** — embed the player as a widget inside a larger app.
+
+## Real-World Applications
+
+- Personal media players for offline music collections.
+- Kiosk or installation apps that loop background music.
+- Audio-book players with bookmark support.
+- White-noise and meditation apps.
+- The audio layer of a game (Pygame's mixer is exactly the same API).
+
+## Educational Value
 
-1. **Install Required Dependencies**
-   ```bash
-   pip install pygame
-   # tkinter comes built-in with Python
-   ```
-
-2. **Prepare Music Files**
-   - Create a folder with music files (MP3, WAV, etc.)
-   - Ensure files are in supported audio formats
-
-3. **Run the Music Player**
-   ```bash
-   python basicmusicplayer.py
-   ```
-
-4. **Load Music Directory**
-   - Click "Load Directory" button
-   - Select folder containing your music files
-   ```
-
-## Explanation
-
-1. The `import pygame.mixer as mixer` statement imports the Pygame mixer module for audio playback.
-2. The `mixer.init()` function initializes the audio system for playing music files.
-3. The `from tkinter import *` imports all Tkinter components for creating the GUI.
-4. The `from tkinter import filedialog` imports the file dialog for browsing directories.
-5. The `song_frame = LabelFrame()` creates a labeled frame to display the current song.
-6. The `button_frame = LabelFrame()` creates a frame for organizing control buttons.
-7. The `listbox_frame = LabelFrame()` creates a frame for the playlist display.
-8. The `def play_song()` function handles music playback and status updates.
-9. The `def pause_song()` function pauses the current song and updates status.
-10. The `def load()` function opens a directory browser to load music files.
-11. The `playlist = Listbox()` creates a scrollable list for managing songs.
-12. The control buttons (Play, Pause, Stop, Resume) provide music player functionality.
+This project teaches:
+- **GUI fundamentals** — widgets, frames, packing, the event loop.
+- **Event-driven thinking** — code runs in response to actions, not top-to-bottom.
+- **Working with the file system** — directories, listings, extensions.
+- **Multimedia I/O** — using a binding (Pygame) to access the OS audio device.
+- **Separation of UI and logic** — even in 100 lines, callbacks isolate concerns.
 
 ## Next Steps
 
-Congratulations! You have successfully created a Basic Music Player in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add volume control slider
-- Implement shuffle and repeat modes
-- Add song information display (duration, artist, album)
-- Create playlist saving and loading functionality
-- Add keyboard shortcuts for controls
-- Implement music visualization
-- Add support for more audio formats
-- Create custom themes and skins
-- Add favorite songs functionality
+- Replace the basic Tkinter look with **`ttk`** widgets for native styling.
+- Add **`pygame.mixer.music.set_endevent`** to auto-advance to the next track.
+- Display **album art** by extracting it from MP3 tags with `mutagen`.
+- Stream audio over the network with `pygame.mixer` + a remote URL.
+- Port the same project to **PyQt** or **CustomTkinter** for a modern look.
 
 ## Conclusion
 
-In this project, you learned how to create a Basic Music Player in Python using Tkinter and Pygame. You also learned about GUI development, audio processing, and event-driven programming. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicmusicplayer.py)
+You built a real desktop application with a window, controls, a playlist, and working sound — in roughly a hundred lines of Python. The same patterns (event loop, callbacks, widget composition) power every other Tkinter project on Python Central Hub. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicmusicplayer.py). Try one of the variations above and ship your own customized version.
diff --git a/src/content/docs/projects/Beginners/basicwebcrawler.mdx b/src/content/docs/projects/Beginners/basicwebcrawler.mdx
index 24ef90f4..601b8876 100644
--- a/src/content/docs/projects/Beginners/basicwebcrawler.mdx
+++ b/src/content/docs/projects/Beginners/basicwebcrawler.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Web Crawler
-description: Build a web crawler that systematically browses and extracts data from websites
+description: Build a polite, breadth-first web crawler in Python that fetches pages, extracts links, scrapes structured data, and saves results to CSV. Learn requests, BeautifulSoup, URL handling, and crawling ethics.
 sidebar:
   order: 57
 hero:
@@ -14,141 +14,266 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Create a web crawler that automatically navigates through websites, extracts content, and saves structured data. This project demonstrates advanced web scraping, URL management, and systematic data collection techniques.
+A web crawler is a program that visits web pages, reads them, follows the links it finds, and repeats. Search engines crawl the web at massive scale; you can build a tiny version in under a hundred lines of Python. In this project you will build a polite, breadth-first crawler that starts at a URL, stays within the same domain, extracts structured data from each page (title, meta description, headings), and saves the results to a CSV file.
 
-## Prerequisites
+The goals are real:
+- Understand how HTTP, HTML parsing, and link discovery fit together.
+- Use Python's `requests` library to fetch pages.
+- Use **BeautifulSoup** to parse HTML.
+- Manage a **frontier** (the queue of URLs to visit) and a **visited set** (so we never visit the same page twice).
+- Crawl **politely** — with delays, domain restrictions, and respect for `robots.txt`.
 
-- Solid understanding of Python syntax
-- Knowledge of web scraping with BeautifulSoup
-- Familiarity with HTTP requests and web protocols
-- Understanding of data structures (queues, sets)
-- Basic knowledge of CSV file operations
+## Crawling 101
 
-## Getting Started
+The simplest crawler is just three loops:
+1. Take the next URL from the frontier.
+2. Fetch and parse it.
+3. Add every link you find back to the frontier (if you have not seen it).
+
+What separates a useful crawler from a server-crashing pest:
+- **Limit the rate** of requests so you do not hammer the site.
+- **Stay on-domain** unless you explicitly want to crawl the wider web.
+- **Respect `robots.txt`** — the file at `/robots.txt` tells crawlers which paths are off-limits.
+- **Identify yourself** with a clear `User-Agent` header that includes contact info.
+- **Bound your work** — set a max page count so you do not crawl forever.
+
+## Prerequisites
 
+- Python 3.6 or above.
+- A text editor or IDE.
+- Internet connection.
+- Basic understanding of HTML structure (tags, attributes).
+- Familiarity with functions and classes.
 
+## Install Dependencies
+```bash title="install"
+pip install requests beautifulsoup4
+```
 
-1. **Install Required Dependencies**
-   ```bash
-   pip install requests beautifulsoup4
-   ```
+## Getting Started
 
-2. **Run the Web Crawler**
-   ```bash
-   python basicwebcrawler.py
-   ```
+### Create the project
+1. Create a folder named `basic-web-crawler`.
+2. Inside it, create `basicwebcrawler.py`.
 
-3. **Configure Crawling**
-   - Enter the starting URL
-   - Set maximum pages to crawl
-   - Choose whether to save results to CSV
+### Write the code
+<FileCode file="projects/beginners/basicwebcrawler.py" lang="python" title="Basic Web Crawler" />
 
+### Run it
+```bash title="run"
+python basicwebcrawler.py
+```
+The crawler prompts for a start URL, max page count, and whether to save a CSV. Sample run:
+```
+Start URL: https://example.com
+Max pages: 5
+Save CSV? (y/n): y
+[1/5] Fetched https://example.com (200) — 3 new links
+[2/5] Fetched https://example.com/about (200) — 1 new link
+...
+Saved 5 rows to crawl_results.csv
+```
 
+## Step-by-Step Explanation
 
-## Code Explanation
+### 1. Imports and class skeleton
+```python title="basicwebcrawler.py"
+from collections import deque
+from urllib.parse import urljoin, urlparse
+import csv
+import time
+import requests
+from bs4 import BeautifulSoup
 
-### Crawler Architecture
-```python title="basicwebcrawler.py" showLineNumbers{1}
 class WebCrawler:
     def __init__(self, start_url, max_pages=10, delay=1):
+        self.start_url = start_url
+        self.max_pages = max_pages
+        self.delay = delay
         self.visited_urls = set()
         self.to_visit = deque([start_url])
         self.crawled_data = []
 ```
+- `deque` (double-ended queue) gives O(1) `popleft()` and `append()`, which is exactly what a FIFO frontier needs.
+- `visited_urls` is a **set** so duplicate detection is O(1).
+- `crawled_data` accumulates one dict per page for CSV export.
 
-Uses queue-based architecture to systematically process URLs while avoiding duplicates.
-
-### URL Validation and Management
-```python title="basicwebcrawler.py" showLineNumbers{1}
+### 2. URL validation
+```python title="basicwebcrawler.py"
 def is_valid_url(self, url):
     parsed = urlparse(url)
     return bool(parsed.netloc) and bool(parsed.scheme)
+```
+A valid URL has both a **scheme** (`http`, `https`) and a **netloc** (`example.com`). Without either, it cannot be fetched.
 
+### 3. Extract links
+```python title="basicwebcrawler.py"
 def extract_links(self, html, base_url):
-    soup = BeautifulSoup(html, 'html.parser')
-    for link in soup.find_all('a', href=True):
-        full_url = urljoin(base_url, href)
+    soup = BeautifulSoup(html, "html.parser")
+    links = []
+    for a in soup.find_all("a", href=True):
+        absolute = urljoin(base_url, a["href"])
+        if self.is_valid_url(absolute):
+            links.append(absolute)
+    return links
 ```
+`urljoin(base, href)` turns relative links like `/about` into absolute URLs like `https://example.com/about`. Always do this — relative paths are useless to `requests.get`.
 
-Implements robust URL handling with validation and proper absolute URL construction.
-
-### Data Extraction Pipeline
-```python title="basicwebcrawler.py" showLineNumbers{1}
+### 4. Extract page data
+```python title="basicwebcrawler.py"
 def extract_page_data(self, html, url):
-    soup = BeautifulSoup(html, 'html.parser')
-    
-    title = soup.find('title').get_text().strip()
-    meta_desc = soup.find('meta', attrs={'name': 'description'})
-    headings = [h.get_text().strip() for h in soup.find_all(['h1', 'h2', 'h3'])]
+    soup = BeautifulSoup(html, "html.parser")
+    title = soup.title.get_text(strip=True) if soup.title else ""
+    meta = soup.find("meta", attrs={"name": "description"})
+    description = meta["content"] if meta and meta.get("content") else ""
+    headings = [h.get_text(strip=True) for h in soup.find_all(["h1", "h2", "h3"])]
+    return {
+        "url": url,
+        "title": title,
+        "description": description,
+        "headings": " | ".join(headings)[:500],
+    }
 ```
+This grabs the bits most analysts care about: title, meta description, headings.
 
-Extracts structured data including titles, descriptions, headings, and content previews.
-
-### Respectful Crawling
-```python title="basicwebcrawler.py" showLineNumbers{1}
+### 5. The main loop
+```python title="basicwebcrawler.py"
 def crawl(self):
-    # Be respectful - add delay
-    time.sleep(self.delay)
-    
-    # Only crawl within the same domain
-    if urlparse(link).netloc == urlparse(self.start_url).netloc:
-        self.to_visit.append(link)
+    while self.to_visit and len(self.visited_urls) < self.max_pages:
+        url = self.to_visit.popleft()
+        if url in self.visited_urls:
+            continue
+        try:
+            response = requests.get(url, timeout=10, headers={
+                "User-Agent": "BasicCrawler/1.0 (+contact@example.com)"
+            })
+            response.raise_for_status()
+        except requests.RequestException as e:
+            print(f"Failed {url}: {e}")
+            continue
+
+        self.visited_urls.add(url)
+        self.crawled_data.append(self.extract_page_data(response.text, url))
+
+        for link in self.extract_links(response.text, url):
+            if urlparse(link).netloc == urlparse(self.start_url).netloc:
+                if link not in self.visited_urls:
+                    self.to_visit.append(link)
+
+        time.sleep(self.delay)
 ```
-
-Implements ethical crawling practices with delays and domain restrictions.
-
-### Data Export
-```python title="basicwebcrawler.py" showLineNumbers{1}
+Key points:
+- **Timeout** keeps a hanging server from freezing the crawl.
+- **`raise_for_status()`** turns 4xx/5xx responses into exceptions.
+- **Domain check** keeps us from accidentally crawling Wikipedia from `example.com`.
+- **`time.sleep(self.delay)`** is the polite delay between requests.
+
+### 6. CSV export
+```python title="basicwebcrawler.py"
 def save_to_csv(self, filename="crawl_results.csv"):
-    with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
-        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+    if not self.crawled_data:
+        return
+    fieldnames = self.crawled_data[0].keys()
+    with open(filename, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
         writer.writeheader()
-        writer.writerow(data_copy)
+        writer.writerows(self.crawled_data)
 ```
+`csv.DictWriter` matches dictionary keys to columns automatically.
 
-Exports crawled data to structured CSV format for analysis and reporting.
+## Respecting `robots.txt`
 
-## Features
+Politeness is not optional. Use Python's built-in `urllib.robotparser`:
 
-- **Systematic Crawling**: Queue-based URL processing with duplicate detection
-- **Data Extraction**: Captures titles, descriptions, headings, and content
-- **Domain Restriction**: Stays within the starting domain for focused crawling
-- **Rate Limiting**: Respectful delays between requests
-- **Error Handling**: Robust handling of network errors and invalid URLs
-- **CSV Export**: Structured data export for further analysis
-- **Progress Tracking**: Real-time crawling progress and statistics
-- **Configurable Limits**: Set maximum pages and crawling parameters
+```python title="robots.py"
+from urllib.robotparser import RobotFileParser
 
-## Next Steps
+rp = RobotFileParser()
+rp.set_url("https://example.com/robots.txt")
+rp.read()
+
+if rp.can_fetch("BasicCrawler/1.0", url):
+    response = requests.get(url, ...)
+else:
+    print(f"Skipping {url} — disallowed by robots.txt")
+```
+Most public sites set their crawler rules in `/robots.txt`. Ignoring those rules is rude and can get your IP banned.
+
+## Common Mistakes
 
-### Enhancements
-- Add support for robots.txt compliance
-- Implement depth-first vs breadth-first crawling options
-- Create advanced filtering based on content type
-- Add database storage for large-scale crawling
-- Implement parallel/concurrent crawling
-- Create web interface for crawler management
-- Add image and file download capabilities
-- Implement crawling analytics and reporting
-
-### Learning Extensions
-- Study advanced web scraping techniques and anti-bot measures
-- Explore distributed crawling systems
-- Learn about search engine indexing principles
-- Practice with database integration for large datasets
-- Understand legal and ethical considerations in web crawling
-- Explore machine learning for content classification
+| Problem | Cause | Fix |
+|---|---|---|
+| Crawler runs forever | No max-pages limit | Always cap `len(visited_urls) < max_pages` |
+| 403 Forbidden everywhere | Default `requests` User-Agent | Set a descriptive `User-Agent` header |
+| Same page visited many times | Trailing slash or query string differences | Normalize URLs before adding to the visited set |
+| Memory grows unbounded | Storing every page's HTML | Store only the extracted fields |
+| `RecursionError` | Recursive crawl instead of iterative | Use the `deque`-based loop above |
+| Server returns 429 | Hitting too fast | Increase the delay or back off on 429 |
+
+## Variations to Try
+
+### 1. Depth-first vs. breadth-first
+Swap `popleft()` for `pop()` and the queue becomes a stack — depth-first crawling. Useful for very narrow, deep sites.
+
+### 2. Concurrent crawling
+Use `concurrent.futures.ThreadPoolExecutor` to fetch several URLs in parallel — but **rate-limit per domain**. Anything else is impolite.
+
+### 3. Sitemap-aware crawling
+Fetch `/sitemap.xml` first to seed the frontier with URLs the site *wants* indexed.
+
+### 4. Async crawler
+Rewrite with `aiohttp` + `asyncio` for higher throughput at the same politeness budget.
+
+### 5. Download files
+Extend the crawler to grab `.pdf`, `.jpg`, etc. Save under a folder named after the domain.
+
+### 6. Headless browser
+Some sites render content with JavaScript and serve empty HTML to `requests`. Use **Playwright** or **Selenium** to render the page first.
+
+### 7. Persistent state
+Save `visited_urls` and `to_visit` to a JSON file every minute so you can resume after a crash.
+
+### 8. Incremental indexing
+After each fetch, push the page text into a SQLite full-text index. You now have a personal Google.
+
+## Crawling Ethics & Legality
+
+Crawling is powerful and risky. Before you point your crawler at a real site:
+- Read its **Terms of Service**. Many sites explicitly forbid automated access.
+- Honor **`robots.txt`**.
+- Avoid crawling content behind login forms unless you have permission.
+- Set a polite **delay** — at least 1 second between requests by default.
+- Identify your crawler with a real `User-Agent` and contact URL.
+- Stop immediately if the site asks you to.
+
+Hammering a small site can cost the owner real money in bandwidth bills. Treat every fetch like a tiny favor someone is doing you.
+
+## Real-World Applications
+
+- **Search engines** — Google's crawler is the most famous example.
+- **Price-tracking bots** — comparing items across e-commerce sites (with permission).
+- **SEO audits** — building a sitemap, finding broken internal links.
+- **News aggregators** — collecting recent headlines for analysis.
+- **Academic research** — gathering corpora for NLP training (where licenses allow).
 
 ## Educational Value
 
 This project teaches:
-- **Web Crawling Architecture**: Designing systematic data collection systems
-- **Queue Management**: Using data structures for efficient URL processing
-- **HTTP Programming**: Advanced request handling and error management
-- **Data Extraction**: Parsing and structuring web content systematically
-- **File Operations**: Writing structured data to various file formats
-- **Ethical Programming**: Implementing respectful web interaction practices
-- **URL Management**: Handling relative/absolute URLs and link resolution
-- **System Design**: Building scalable and maintainable data collection tools
-
-Perfect for understanding large-scale data collection, web technologies, and building tools for automated information gathering.
+- **HTTP** — requests, status codes, headers.
+- **HTML parsing** with BeautifulSoup.
+- **URL manipulation** with `urllib.parse`.
+- **Data structures** — queues for the frontier, sets for the visited list.
+- **OOP** — wrapping state and behavior in a class.
+- **Ethics** — politeness is engineering, not a nice-to-have.
+
+## Next Steps
+
+- Combine with [RSS Feed Reader](./rssfeedreader) to crawl articles automatically.
+- Add **content classification** with a small ML model (`scikit-learn`).
+- Build a **search interface** with Flask (see [Basic Web Server](./basicwebserver)).
+- Deploy as a **scheduled job** — re-crawl every day, diff the results, alert on changes.
+- Move to a real crawler framework like **Scrapy** when your needs outgrow a single script.
+
+## Conclusion
+
+You wrote a real, working web crawler — not a toy. It fetches pages politely, parses them, follows links, stays on-domain, and exports structured results. The patterns scale: a thousand-line Scrapy spider is still doing the same three things in a loop. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicwebcrawler.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basicwebscrapper.mdx b/src/content/docs/projects/Beginners/basicwebscrapper.mdx
index 6c7b21a8..1beb91cc 100644
--- a/src/content/docs/projects/Beginners/basicwebscrapper.mdx
+++ b/src/content/docs/projects/Beginners/basicwebscrapper.mdx
@@ -1,6 +1,6 @@
 ---
-title: Basic Web Scrapper
-description: This is a basic web scrapper that scrapes the data from the website and stores it in a csv file. This is a beginner level project. We are going to use the BeautifulSoup library for this project and requests library to get the data from the website.
+title: Basic Web Scraper
+description: Build a Python scraper that extracts product data from a real e-commerce page and saves to CSV. Learn BeautifulSoup, requests, robust CSV writing, polite scraping, pagination, and a Scrapy preview.
 sidebar: 
     order: 5
 hero:
@@ -13,247 +13,280 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-This is a basic web scrapper that scrapes the data from the website and stores it in a csv file. This is a beginner level project. We are going to use the BeautifulSoup library for this project and requests library to get the data from the website. In this application, we are going to scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/phones/touch and store the data in a csv file. We are going to scrape the data of the product name, price, and description of the product.
+Web scraping is one of the most marketable Python skills you can pick up — every business eventually needs to extract data from a page that has no API. In this project you build a real scraper against [webscraper.io's test site](https://webscraper.io/test-sites/e-commerce/allinone/phones/touch), pulling name, price, description, review count, rating, and image URL for each phone, then writing the results to a CSV. We start with the bare-bones version, then fix half a dozen real bugs (CSV quoting, encoding, missing fields), add pagination, retries, polite rate-limiting, and finish with a preview of when to graduate from BeautifulSoup to Scrapy.
 
+You will learn:
+- The standard `requests` + `BeautifulSoup` pipeline.
+- How to find the right CSS selectors using browser DevTools.
+- Why naïve string concatenation is wrong for CSV — and how to use the `csv` module.
+- How to handle missing fields gracefully.
+- Polite-scraping practices: User-Agent, delays, robots.txt.
+- When to switch to a real scraping framework.
 
 ## Prerequisites
-- Python 3.6 or above
-- BeautifulSoup library
-- requests library
-- Text editor or IDE
-
-## Before we start
-Before we start, we need to install the BeautifulSoup library and requests library. To install the BeautifulSoup library, we need to run the following command in the terminal.
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\username>pip install beautifulsoup4
-```
+- Python 3.6 or above.
+- A code editor or IDE.
+- Internet connection.
+- Familiarity with basic HTML structure (tags, attributes, classes).
 
-To install the requests library, we need to run the following command in the terminal.
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\username>pip install requests
+## Install Dependencies
+```cmd title="install"
+pip install requests beautifulsoup4
 ```
 
 ## Getting Started
-### Creating a project
-1. Create a folder named `basicwebscrapper` and open it in the text editor or IDE.
-2. Create a file named `basicwebscrapper.py` in the `basicwebscrapper` folder.
-3. Open the `basicwebscrapper.py` file in the text editor or IDE.
-4. Copy the code below and paste it into the `basicwebscrapper.py` file.
+
+### Create the project
+1. Create folder `basicwebscrapper`.
+2. Inside, create `basicwebscrapper.py`.
 
 ### Write the code
-1. Copy and paste the following code into the `basicwebscrapper.py` file.
-<FileCode file="projects/beginners/basicwebscrapper.py" lang="python" title="Basic Web Scrapper" />
-2. Save the file.
-3. Open the terminal in the `basicwebscrapper` folder.
-4. Run the following command in the terminal.
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\username\basicwebscrapper>python basicwebscrapper.py
-Name: Nokia 123 
-Price: $24.99 
-Description: 7 day battery
-Reviews: 11 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: LG Optimus
-Price: $57.99
-Description: 3.2" screen
-Reviews: 11 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Samsung Galaxy
-Price: $93.99
-Description: 5 mpx. Android 5.0
-Reviews: 3 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Nokia X
-Price: $109.99
-Description: Andoid, Jolla dualboot
-Reviews: 4 reviews
-Rating: 4
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Sony Xperia
-Price: $118.99
-Description: GPS, waterproof
-Reviews: 6 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Ubuntu Edge
-Price: $499.99
-Description: Sapphire glass
-Reviews: 2 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Iphone
-Price: $899.99
-Description: White
-Reviews: 10 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Iphone
-Price: $899.99
-Description: Silver
-Reviews: 8 reviews
-Rating: 2
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Iphone
-Price: $899.99
-Description: Black
-Reviews: 1 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
+<FileCode file="projects/beginners/basicwebscrapper.py" lang="python" title="Basic Web Scraper" />
+
+### Run it
+```cmd title="command"
+C:\Users\username\basicwebscrapper> python basicwebscrapper.py
+Name: Nokia 123       Price: $24.99    Rating: 3
+Name: LG Optimus      Price: $57.99    Rating: 3
+…
+Saved 9 rows to phones.csv
 ```
 
-## Explanation
-1. First, we import the `requests` library and the `BeautifulSoup` library.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1-2}
+## Step-by-Step Explanation
+
+### 1. Fetch and parse
+```python title="basicwebscrapper.py"
 import requests
 from bs4 import BeautifulSoup
+
+URL = "https://webscraper.io/test-sites/e-commerce/allinone/phones/touch"
+response = requests.get(URL, timeout=15, headers={
+    "User-Agent": "PCH-Scraper/1.0 (+contact@example.com)"
+})
+response.raise_for_status()
+soup = BeautifulSoup(response.text, "html.parser")
 ```
-2. Then, we assign the URL to the variable `url`.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1}
-url = "https://webscraper.io/test-sites/e-commerce/allinone/phones/touch"
+- `User-Agent` identifies you to the server. The default `python-requests/2.x` is blocked by many real sites.
+- `raise_for_status()` raises on 4xx/5xx so we do not silently scrape error pages.
+- `"html.parser"` is built in. For tolerant parsing of broken markup, install `lxml` and use `"lxml"`.
+
+### 2. Find the right selectors
+Open DevTools (F12) → Inspect → click a product → identify the wrapper:
+```html
+<div class="card thumbnail">
+  <div class="card-body">
+    <h4 class="pull-right price">$24.99</h4>
+    <a class="title" title="Nokia 123">Nokia 123</a>
+    <p class="description">7 day battery</p>
+  </div>
+  <div class="ratings">
+    <p class="pull-right">11 reviews</p>
+    <p data-rating="3">★★★☆☆</p>
+  </div>
+  <img src="/images/test-sites/.../cart2.png"/>
+</div>
 ```
-3. Next, we request the URL and assign it to the variable `response`. Then, we parse the HTML using the `html.parser` and assign it to the variable `soup`.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1-2}
-response = requests.get(url)
-soup = BeautifulSoup(response.text, "html.parser")
+We will find all `div.card-body`, then within each look up the inner elements.
+
+### 3. Extract per product
+```python title="basicwebscrapper.py"
+phones = soup.select("div.thumbnail")        # one wrapper per phone
+
+rows = []
+for phone in phones:
+    rows.append({
+        "name":        phone.select_one("a.title")["title"].strip(),
+        "price":       phone.select_one("h4.price").get_text(strip=True),
+        "description": phone.select_one("p.description").get_text(strip=True),
+        "reviews":     phone.select_one("p.pull-right").get_text(strip=True),
+        "rating":      int(phone.select_one("p[data-rating]")["data-rating"]),
+        "image":       phone.select_one("img")["src"],
+    })
 ```
-4. After that, we find all the phones and assign it to the variable `phones`.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1}
-phones = soup.find_all("div", class_="card-body")
+- `select_one(css)` returns the first match (or `None`); `select(css)` returns a list.
+- `["title"]` reads an HTML attribute; `.get_text(strip=True)` reads text content.
+- We pull the rating *value* from the `data-rating` attribute, not the visible stars — far more reliable.
+
+### 4. Save as proper CSV
+The naïve version did this:
+```python title="naive_csv.py"
+open_file.write(f'{name}, {price}, {description}, ...\n')   # ❌
 ```
-5. Then, we create a CSV file named `phones.csv` and open it in append mode. Then, we write the headers to the CSV file.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1-3}
-open_file = open("phones.csv", "a")
-headers = "Name, Price, Description, Reviews, Rating, Image\n"
-open_file.write(headers)
+This breaks the moment a description contains a comma (`"5 mpx, Android 5.0"`). Always use the `csv` module:
+```python title="proper_csv.py"
+import csv
+with open("phones.csv", "w", newline="", encoding="utf-8") as f:
+    writer = csv.DictWriter(f, fieldnames=rows[0].keys())
+    writer.writeheader()
+    writer.writerows(rows)
 ```
-6. Next, we loop through the phones and find the name, price, description, reviews, rating, and image of the phone. Then, we write the data to the CSV file.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1-2}
-name = phone.find("a", class_="title")
-price = phone.find("h4", class_="price")
+The `csv` module quotes any field containing commas, quotes, or newlines, producing real RFC-4180-compliant output that loads cleanly into Excel/Pandas.
+
+## Defensive Selectors
+
+What happens when a product has no rating? `select_one("p[data-rating]")` returns `None`, and `None["data-rating"]` raises `TypeError`. Guard every extraction:
+```python title="safe.py"
+def text_of(parent, selector, default=""):
+    node = parent.select_one(selector)
+    return node.get_text(strip=True) if node else default
+
+def attr_of(parent, selector, attr, default=""):
+    node = parent.select_one(selector)
+    return node[attr] if node and node.has_attr(attr) else default
+
+row = {
+    "name":  attr_of(phone, "a.title", "title"),
+    "price": text_of(phone, "h4.price"),
+    "rating": int(attr_of(phone, "p[data-rating]", "data-rating", 0)),
+}
 ```
+The scraper now runs to completion even when some products miss a field.
 
-and so on...
+## Pagination
 
-after that, we write the data to the CSV file.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1-2}
-open_file.write(f'{name.text}, {price.text}, {description.text}, {reviews.text}, {rating["data-rating"]}, {image}\n')
+Most e-commerce sites paginate results. Find the "next" link and loop:
+```python title="paginate.py"
+def crawl_all(start_url):
+    url = start_url
+    while url:
+        soup = fetch(url)
+        yield from extract_products(soup)
+        next_link = soup.select_one("a.next, li.next > a")
+        url = urljoin(url, next_link["href"]) if next_link else None
+        time.sleep(1)               # polite delay
 ```
-7. Finally, we close the CSV file.
-```python title="basicwebscrapper.py" showLineNumbers{1} {1}
-open_file.close()
+A generator (`yield from`) streams results one at a time so you can stop early or process incrementally.
+
+## Polite Scraping
+
+Hammering a server gets your IP banned. Three rules:
+
+1. **Sleep between requests.** `time.sleep(1)` between pages is friendly.
+2. **Honor `robots.txt`.**
+   ```python title="robots.py"
+   from urllib.robotparser import RobotFileParser
+   rp = RobotFileParser()
+   rp.set_url("https://example.com/robots.txt"); rp.read()
+   if not rp.can_fetch("PCH-Scraper/1.0", URL):
+       sys.exit("robots.txt forbids this URL.")
+   ```
+3. **Identify yourself.** `User-Agent: PCH-Scraper/1.0 (+contact@example.com)` lets a sysadmin reach you instead of just banning.
+
+For more on this, see [Basic Web Crawler](./basicwebcrawler).
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `AttributeError: 'NoneType'` on `.get_text` | Selector did not match anything | Guard with `if node` or helper |
+| CSV row splits across columns in Excel | Manual string formatting | Use `csv.writer` / `DictWriter` |
+| Same data on every page | Forgot to refetch when paginating | Update the URL each iteration |
+| 403 Forbidden | Missing User-Agent | Set a real header |
+| Encoding garbage in CSV | Wrong encoding when opening | `encoding="utf-8"` (or `"utf-8-sig"` for Excel BOM) |
+| Selectors break next week | Site changed its HTML | Treat selectors as data; centralize them |
+| Loaded blank `<div id="root">` | JavaScript-rendered SPA | Use **Playwright** instead of `requests` |
+
+## Variations to Try
+
+### 1. Scrape laptops or tablets
+```python title="other.py"
+for cat in ["phones/touch", "computers/laptops", "computers/tablets"]:
+    crawl(f"https://webscraper.io/test-sites/e-commerce/allinone/{cat}")
 ```
 
-## Usage
-1. Open the terminal in the `basicwebscrapper` folder.
-2. Run the following command in the terminal.
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\username\basicwebscrapper>python basicwebscrapper.py
+### 2. Save as JSON
+```python title="json_out.py"
+import json
+json.dump(rows, open("phones.json", "w", encoding="utf-8"), indent=2)
 ```
-3. The data will be scraped from the website and stored in the `phones.csv` file.
-4. The data will be printed in the terminal.
-5. The data will be stored in the `phones.csv` file.
-```csv title="phones.csv" showLineNumbers{1} {1-9}
-Name, Price, Description, Reviews, Rating, Image
-Nokia 123, $24.99, 7 day battery, 11 reviews, 3, /images/test-sites/e-commerce/items/cart2.png
-LG Optimus, $57.99, 3.2" screen, 11 reviews, 3, /images/test-sites/e-commerce/items/cart2.png
-Samsung Galaxy, $93.99, 5 mpx. Android 5.0, 3 reviews, 3, /images/test-sites/e-commerce/items/cart2.png
-Nokia X, $109.99, Andoid, Jolla dualboot, 4 reviews, 4, /images/test-sites/e-commerce/items/cart2.png
-Sony Xperia, $118.99, GPS, waterproof, 6 reviews, 1, /images/test-sites/e-commerce/items/cart2.png
-Ubuntu Edge, $499.99, Sapphire glass, 2 reviews, 1, /images/test-sites/e-commerce/items/cart2.png
-Iphone, $899.99, White, 10 reviews, 1, /images/test-sites/e-commerce/items/cart2.png
-Iphone, $899.99, Silver, 8 reviews, 2, /images/test-sites/e-commerce/items/cart2.png
-Iphone, $899.99, Black, 1 reviews, 1, /images/test-sites/e-commerce/items/cart2.png
+
+### 3. Save to SQLite
+```python title="sqlite.py"
+import sqlite3
+db = sqlite3.connect("phones.db")
+db.execute("""CREATE TABLE IF NOT EXISTS phones(
+    name TEXT, price TEXT, description TEXT, reviews TEXT, rating INTEGER, image TEXT)""")
+db.executemany("INSERT INTO phones VALUES(?,?,?,?,?,?)",
+               [(r["name"], r["price"], r["description"], r["reviews"], r["rating"], r["image"]) for r in rows])
+db.commit()
 ```
-6. The data will be printed in the terminal.
-```cmd title="command" showLineNumbers{1} {2-60}
-C:\Users\username\basicwebscrapper>python basicwebscrapper.py
-Name: Nokia 123
-Price: $24.99
-Description: 7 day battery
-Reviews: 11 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: LG Optimus
-Price: $57.99
-Description: 3.2" screen
-Reviews: 11 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Samsung Galaxy
-Price: $93.99
-Description: 5 mpx. Android 5.0
-Reviews: 3 reviews
-Rating: 3
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Nokia X
-Price: $109.99
-Description: Andoid, Jolla dualboot
-Reviews: 4 reviews
-Rating: 4
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Sony Xperia
-Price: $118.99
-Description: GPS, waterproof
-Reviews: 6 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Ubuntu Edge
-Price: $499.99
-Description: Sapphire glass
-Reviews: 2 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Iphone
-Price: $899.99
-Description: White
-Reviews: 10 reviews
-Rating: 1
-Image: /images/test-sites/e-commerce/items/cart2.png
-
-Name: Iphone
-Price: $899.99
-Description: Silver
-Reviews: 8 reviews
-Rating: 2
-Image: /images/test-sites/e-commerce/items/cart2.png
+
+### 4. Concurrent fetching
+Use `concurrent.futures.ThreadPoolExecutor` (with a 1-second per-domain throttle).
+
+### 5. Price-change tracker
+Run daily, compare to yesterday's CSV, alert on drops. See [Web Page Scraper with Notifications](./webpagescrapernotifications) for the alerting half.
+
+### 6. GUI / Web UI
+- Tkinter form to enter URL → display table.
+- Flask app to expose `GET /scrape?url=...`.
+
+### 7. Headless browser
+If the site renders client-side, `requests` returns empty HTML. Switch to **Playwright**:
+```python title="playwright.py"
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    page = p.chromium.launch().new_page()
+    page.goto(url)
+    html = page.content()
 ```
 
+### 8. Scrapy framework
+For multi-spider projects, **Scrapy** gives you pipelines, item loaders, throttling, retries, and exports out of the box. Worth learning when you cross 5+ scrapers in one repo.
+
+### 9. Cron job
+On Linux: `crontab -e` → `0 6 * * * /usr/bin/python /path/to/scraper.py`.
+On Windows: Task Scheduler.
+
+### 10. Slack/Discord alerts on new products
+Diff yesterday's run vs today's; push new SKUs to a webhook.
+
+## When to Graduate to Scrapy
+
+A few signs you have outgrown a single script:
+- More than ~5 spiders.
+- You re-implement retry logic and rate limiting in each script.
+- You want resumable crawls.
+- You want item-pipeline hooks (clean → validate → save).
+
+Scrapy gives you all of that for free, plus a dedicated CLI (`scrapy crawl phones -o phones.json`).
+
+## Legal & Ethical Reminder
+
+Scraping is legal in many jurisdictions when:
+- The data is publicly accessible.
+- You do not violate the site's Terms of Service.
+- You respect `robots.txt` and rate limits.
+- You do not republish copyrighted content.
+
+It is **not** legal to scrape:
+- Behind logins without permission.
+- Personal data covered by GDPR / CCPA without lawful basis.
+- Content explicitly forbidden by the site's ToS.
+
+When in doubt, ask the site owner. Many will give you an API or a data dump.
+
+## Real-World Applications
+- **Competitive pricing intelligence**.
+- **Job board aggregation** (most platforms forbid this — check first).
+- **News aggregation** (RSS is usually a better path — see [RSS Feed Reader](./rssfeedreader)).
+- **Academic research datasets**.
+- **Inventory monitoring** — restock alerts, drop-shipping pipelines.
+
+## Educational Value
+- **HTTP fundamentals**, headers, status codes.
+- **HTML/CSS selectors** translated into BeautifulSoup queries.
+- **Defensive coding** — every selector can return `None`.
+- **CSV/JSON/SQLite trade-offs** as output formats.
+- **Politeness** — User-Agent, delays, robots.txt.
+
 ## Next Steps
-Congratulations 🎉 you have successfully created a basic web scrapper that scrapes the data from the website and stores it in a csv file. 
-
-Here are some ideas to get you started:
-1. Scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/computers/laptops and store the data in a csv file.
-2. Scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/computers/tablets and store the data in a csv file.
-3. Add a feature to scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/phones/touch and store the data in a json file.
-4. Add a feature to scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/phones/touch and store the data in a database.
-5. Create a GUI for the application.
-6. Create a web application for the application.
-7. Add a cron_job to scrape the data from the website https://webscraper.io/test-sites/e-commerce/allinone/phones/touch and store the data in a csv file every 24 hours.
-:::note
-cron_job is a task scheduler in Unix-like systems that schedules tasks to run periodically at fixed times, dates, or intervals.
-:::
-
-## Resources
-- [BeautifulSoup Documentation](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)
-- [Requests Documentation](https://docs.python-requests.org/en/master/)
-- [Cron Job](https://en.wikipedia.org/wiki/Cron)
+- Add **pagination** to crawl every page.
+- Add **`csv.DictWriter`** instead of manual writing.
+- Set a real **User-Agent** and respect **`robots.txt`**.
+- Save to **SQLite** so each run inserts incrementally.
+- Schedule with **cron / Task Scheduler**.
+- Cross-link with [Basic Web Crawler](./basicwebcrawler) and [Web Page Scraper with Notifications](./webpagescrapernotifications).
 
 ## Conclusion
-In this tutorial, we learned how to create a basic web scrapper that scrapes the data from the website and stores it in a csv file. This is a beginner level project. We used the BeautifulSoup library for this project and requests library to get the data from the website. In this application, we scraped the data from the website https://webscraper.io/test-sites/e-commerce/allinone/phones/touch and stored the data in a csv file. For more information, visit the resources listed above. For more projects like this, visit Python Central Hub.
\ No newline at end of file
+You built a real scraper against a real e-commerce page, fixed the half-dozen subtle bugs that bite every first scraper, and have a road map to a polite, scheduled, alerting data pipeline. Scraping is one of the best applied-Python skills — every commercial scraper in the world is a few hundred lines on top of `requests` + BeautifulSoup. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicwebscrapper.py). Explore more on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/basicwebserver.mdx b/src/content/docs/projects/Beginners/basicwebserver.mdx
index ffd3284a..a4862415 100644
--- a/src/content/docs/projects/Beginners/basicwebserver.mdx
+++ b/src/content/docs/projects/Beginners/basicwebserver.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Web Server (Flask)
-description: Create a simple web server using Flask framework with routes and dynamic content
+description: Build your first web server in Python using the Flask framework. Learn HTTP basics, routing, dynamic content, query parameters, templates, and how a "Hello World" route becomes a real web application.
 sidebar:
   order: 56
 hero:
@@ -14,99 +14,280 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a basic web server using the Flask framework to serve web pages, handle HTTP requests, and create dynamic web applications. This project introduces web development fundamentals and server-side programming.
+A web server is a program that listens for HTTP requests and responds with content — HTML pages, JSON data, images, anything a browser or API client asks for. In this project you will build a minimal web server with **Flask**, Python's most popular micro-framework. The starting point is a single route that returns "Hello, World!" and the finish line is a multi-page application with dynamic URLs, query strings, JSON endpoints, and HTML templates.
+
+You will learn:
+- What a web server actually does and how HTTP works at a conceptual level.
+- How Flask maps URLs to Python functions (routing).
+- How to read data from the URL (path variables and query strings).
+- How to return HTML, JSON, and template-rendered responses.
+- How to run a server in development mode and what to do before deploying it.
+
+## What Is a Web Server?
+
+When you type `https://example.com/about` into your browser, this happens:
+1. Your browser **opens a TCP connection** to the server at `example.com` on port 443 (HTTPS) or 80 (HTTP).
+2. It sends a textual **HTTP request** like `GET /about HTTP/1.1`.
+3. The server reads the request, decides what to do, and sends an **HTTP response** consisting of a **status code** (200, 404, 500, …), some **headers**, and a **body** (HTML, JSON, etc.).
+4. The browser parses the body and renders it.
+
+A web framework like Flask hides the TCP/HTTP plumbing so you write *only* the part where you decide what to send back.
 
 ## Prerequisites
 
-- Basic understanding of Python syntax
-- Knowledge of web concepts (HTTP, URLs, requests)
-- Familiarity with command-line operations
-- Understanding of client-server architecture
-- Basic knowledge of HTML (helpful but not required)
+- Python 3.6 or above.
+- A text editor or IDE.
+- Familiarity with the command line.
+- Basic understanding of how to open a URL in a browser. (You do not need to know HTML yet.)
 
-## Getting Started
+## Install Flask
 
+Flask is **not** in the standard library; you install it with `pip`:
 
+```bash title="install"
+pip install flask
+```
 
-1. **Install Flask**
-   ```bash
-   pip install flask
-   ```
+Verify it installed:
+```bash title="verify"
+python -c "import flask; print(flask.__version__)"
+```
+You should see something like `3.0.0`.
 
-2. **Run the Web Server**
-   ```bash title="command" showLineNumbers{1}
-   python basicwebserver.py
-   ```
+> 💡 Best practice: create a virtual environment first so each project gets its own copies of dependencies. On Windows: `python -m venv venv && venv\Scripts\activate`. On macOS/Linux: `python -m venv venv && source venv/bin/activate`.
+
+## Getting Started
+
+### Create the project
+1. Create a folder named `basic-web-server`.
+2. Inside it, create `basicwebserver.py`.
+3. Open the folder in your editor.
 
-3. **Access the Server**
-   - Open your browser and go to `http://localhost:5000`
-   - You should see "Hello, World!" displayed
+### Write the code
+<FileCode file="projects/beginners/basicwebserver.py" lang="python" title="Basic Web Server" />
 
+### Run it
+```bash title="run"
+python basicwebserver.py
+```
+You will see output similar to:
+```
+ * Serving Flask app 'basicwebserver'
+ * Debug mode: on
+ * Running on http://127.0.0.1:5000
+Press CTRL+C to quit
+```
+Open `http://127.0.0.1:5000` (or `http://localhost:5000`) in your browser. You should see **Hello, World!**.
 
+Stop the server with **Ctrl+C** when you are done.
 
-## Code Explanation
+## Step-by-Step Explanation
 
-### Flask Application Setup
-```python title="basicwebserver.py" showLineNumbers{1}
+### 1. Import Flask and create the app
+```python title="basicwebserver.py"
 from flask import Flask
 app = Flask(__name__)
 ```
+- `Flask` is the framework's main class.
+- `__name__` tells Flask where to look for templates and static files relative to the current module.
+- `app` is the **application object**. Routes, configuration, and extensions all attach to it.
 
-Creates a Flask application instance that will handle web requests and responses.
-
-### Route Definition
-```python title="basicwebserver.py" showLineNumbers{1}
+### 2. Define a route
+```python title="basicwebserver.py"
 @app.route("/")
 def index():
     return "Hello, World!"
 ```
+- `@app.route("/")` is a **decorator** — it tells Flask "when a request arrives for `/`, call the function below this line."
+- `index` is just a Python function name. Flask does not care what you call it, only that it is unique.
+- The return value becomes the response body. Returning a string sends back HTML with status 200.
 
-Defines a route that responds to requests at the root URL ("/") with a simple text response.
-
-### Server Execution
-```python title="basicwebserver.py" showLineNumbers{1}
+### 3. Start the development server
+```python title="basicwebserver.py"
 if __name__ == "__main__":
     app.run(debug=True)
 ```
+- The `if __name__ == "__main__":` guard ensures the server only starts when you run *this file directly* — not when another module imports it.
+- `debug=True` turns on Flask's debugger and auto-reloader, so saving a code change restarts the server automatically. **Never** leave debug on in production — it exposes a remote code execution surface.
 
-Starts the development server with debug mode enabled for automatic reloading and error reporting.
+## Adding More Routes
 
-## Features
+A real site needs more than one page. Routes can be plain strings, dynamic patterns, or restricted to specific HTTP methods.
 
-- **HTTP Server**: Serves web content over HTTP protocol
-- **Route Handling**: Maps URLs to Python functions
-- **Development Mode**: Debug mode for easy development
-- **Automatic Reloading**: Server restarts when code changes
-- **Error Reporting**: Detailed error messages for debugging
+```python title="more_routes.py"
+@app.route("/about")
+def about():
+    return "<h1>About Page</h1><p>This is a basic Flask server.</p>"
 
-## Next Steps
+@app.route("/api/health")
+def health():
+    return {"status": "ok"}, 200       # dict → JSON automatically
+
+@app.route("/user/<username>")
+def user_profile(username):
+    return f"<h1>Profile of {username}</h1>"
+
+@app.route("/post/<int:post_id>")
+def show_post(post_id):
+    return f"Showing post #{post_id} (type: {type(post_id).__name__})"
+```
+- `<username>` is a **path variable** — anything in that position is captured and passed to the function.
+- `<int:post_id>` adds a **converter** that rejects non-integer values with a 404 automatically.
+- Returning a dictionary makes Flask serialize it to JSON with `Content-Type: application/json`.
+
+## Reading Query Strings
+
+A URL like `/search?q=python&page=2` carries query parameters. Use `request.args`:
 
-### Enhancements
-- Add multiple routes and pages
-- Implement HTML templates with Jinja2
-- Add CSS styling and static files
-- Create forms and handle POST requests
-- Implement user sessions and authentication
-- Add database integration
-- Create REST API endpoints
-- Deploy to production server
-
-### Learning Extensions
-- Study HTTP protocol and status codes
-- Learn HTML, CSS, and JavaScript
-- Explore Flask extensions and blueprints
-- Practice with database integration (SQLAlchemy)
-- Understand web security concepts
-- Learn about deployment and hosting
+```python title="query.py"
+from flask import request
+
+@app.route("/search")
+def search():
+    q = request.args.get("q", "")
+    page = int(request.args.get("page", "1"))
+    return f"Searching for '{q}' on page {page}"
+```
+`request.args.get(key, default)` returns the value if present, otherwise the default. This avoids `KeyError` when the user omits a parameter.
+
+## HTML Templates with Jinja2
+
+Embedding HTML in Python strings gets ugly fast. Use templates instead.
+
+1. Create a `templates/` folder next to `basicwebserver.py`.
+2. Inside it, create `index.html`:
+   ```html title="templates/index.html"
+   <!doctype html>
+   <html>
+     <head><title>{{ title }}</title></head>
+     <body>
+       <h1>Hello, {{ name }}!</h1>
+       <ul>
+         {% for item in items %}
+           <li>{{ item }}</li>
+         {% endfor %}
+       </ul>
+     </body>
+   </html>
+   ```
+3. Render it from Python:
+   ```python title="render.py"
+   from flask import render_template
+
+   @app.route("/greet/<name>")
+   def greet(name):
+       return render_template(
+           "index.html",
+           title="Greeting",
+           name=name,
+           items=["Apples", "Bananas", "Cherries"],
+       )
+   ```
+The `{{ ... }}` is variable substitution, `{% ... %}` is control flow. Jinja2 (Flask's template engine) auto-escapes variables to prevent XSS — never undo that without a very good reason.
+
+## Handling POST Requests
+
+To accept form submissions, declare the methods explicitly:
+
+```python title="form.py"
+from flask import request, redirect, url_for
+
+@app.route("/login", methods=["GET", "POST"])
+def login():
+    if request.method == "POST":
+        username = request.form.get("username")
+        return redirect(url_for("user_profile", username=username))
+    return '''
+      <form method="post">
+        <input name="username" required>
+        <button type="submit">Log in</button>
+      </form>
+    '''
+```
+- `request.form` reads `application/x-www-form-urlencoded` bodies (standard HTML forms).
+- `request.get_json()` reads JSON bodies (typical for API clients).
+- `redirect(url_for("name"))` sends the browser to another route by **function name**, not URL — safer when URLs change.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `ModuleNotFoundError: No module named 'flask'` | Flask not installed in the active interpreter | `pip install flask` inside the right virtualenv |
+| Server "not responding" | You stopped it, or the port is already in use | Check the terminal; use `app.run(port=5001)` to switch ports |
+| Changes do not show up | Browser cached, or debug mode off | Hard refresh (Ctrl+Shift+R) or set `debug=True` |
+| 404 on `/about` | Route defined but server not restarted in non-debug mode | Restart the script, or use `debug=True` |
+| Static files (CSS, images) not loading | They must live under `static/` and be referenced with `url_for('static', filename='style.css')` | Move them and use `url_for` |
+
+## Security Notes
+
+Once your server actually runs, the security checklist begins:
+
+- **Never run `debug=True` in production.** It exposes a Python shell to anyone who can reach the server.
+- **Validate every piece of input** — path variables, query strings, form bodies, headers.
+- **Use HTTPS** in production. Front Flask with Nginx or a managed platform that terminates TLS.
+- **Set a real `SECRET_KEY`** before using sessions or CSRF: `app.config["SECRET_KEY"] = os.environ["FLASK_SECRET"]`.
+- **Do not trust the client.** A path that opens a file based on user input is one of the easiest ways to write a directory-traversal bug.
+
+## Real-World Applications
+
+- **JSON APIs** for mobile apps, single-page apps, IoT devices.
+- **Internal dashboards** for monitoring or admin tools.
+- **Form back-ends** for static sites that need a contact endpoint.
+- **Webhook receivers** for GitHub, Stripe, Slack, etc.
+- **Prototyping** machine-learning models behind an HTTP endpoint.
+
+## Beyond `app.run` — Production Servers
+
+The built-in development server is single-threaded and not designed for real traffic. For production use a **WSGI server**:
+
+```bash title="prod"
+pip install gunicorn
+gunicorn basicwebserver:app --workers 4 --bind 0.0.0.0:8000
+```
+Or run inside a Docker container behind Nginx. PaaS options like Render, Railway, Fly.io, or PythonAnywhere abstract the details if you just want to deploy.
+
+## Variations to Try
+
+### 1. JSON API for a to-do list
+```python title="todo_api.py"
+todos = []
+
+@app.route("/todos", methods=["GET", "POST"])
+def todos_route():
+    if request.method == "POST":
+        todos.append(request.get_json())
+        return {"ok": True}, 201
+    return {"items": todos}
+```
+
+### 2. Static HTML + CSS site
+Put files in `static/`, point a route at `index.html`, style with CSS.
+
+### 3. Connect to a database
+Use **SQLAlchemy** (`pip install flask-sqlalchemy`) to persist data instead of an in-memory list.
+
+### 4. Add login
+Use **Flask-Login** for sessions and **Werkzeug** for password hashing.
+
+### 5. Render Markdown
+Pair Flask with a Markdown library to render `.md` files as HTML pages — basis for a simple blog.
 
 ## Educational Value
 
 This project teaches:
-- **Web Development Fundamentals**: Understanding client-server architecture
-- **Flask Framework**: Introduction to Python web frameworks
-- **HTTP Protocol**: Working with web requests and responses
-- **Route Mapping**: Connecting URLs to application logic
-- **Server Development**: Creating applications that serve web content
-- **Debug Workflow**: Using development tools for web applications
-
-Perfect for beginning web development and understanding how web servers work.
+- **HTTP fundamentals** — verbs, status codes, request/response.
+- **Routing** — URLs as a public API to your code.
+- **Templating** — separating presentation from logic.
+- **Server lifecycle** — start, listen, serve, shut down.
+- **The dev/prod distinction** — debug servers vs. WSGI servers.
+
+## Next Steps
+- Add a `/about` and `/contact` page to practice multi-route apps.
+- Convert your routes into a **REST API** that stores data in a SQLite database.
+- Read about **Flask Blueprints** for organizing larger applications.
+- Compare Flask with **FastAPI** — modern, typed, async-friendly alternative.
+- Deploy your server to a free host (Render, Fly.io, PythonAnywhere).
+
+## Conclusion
+
+In about ten lines you built a real web server, and in another twenty you turned it into a multi-route application with templates and JSON endpoints. Every full-stack Python developer started here. Flask's strength is exactly this — it gets out of the way and lets you focus on what your endpoints actually do. Find the full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/basicwebserver.py) and explore more web-development projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/binarytodecimal.mdx b/src/content/docs/projects/Beginners/binarytodecimal.mdx
index 9623abca..c0961b12 100644
--- a/src/content/docs/projects/Beginners/binarytodecimal.mdx
+++ b/src/content/docs/projects/Beginners/binarytodecimal.mdx
@@ -1,6 +1,6 @@
 ---
 title: Binary to Decimal Converter
-description: A Python application that converts numbers between binary and decimal formats, demonstrating number system conversions and user interface design.
+description: Convert between binary, decimal, octal, and hexadecimal in Python. Learn how int(s, base) works, bitwise operations, two's complement for negative numbers, IEEE 754 floats, and an arbitrary-base implementation.
 sidebar: 
     order: 46
 hero:
@@ -13,263 +13,261 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Binary to Decimal Converter is a Python application that performs bidirectional conversion between binary and decimal number systems. The program provides a menu-driven interface allowing users to convert binary numbers to decimal or decimal numbers to binary. This project demonstrates fundamental concepts of number systems, base conversions, user input handling, and menu-based program design. It's an excellent project for understanding how computers represent numbers internally.
+Converting numbers between bases is the bridge between how *we* count (base 10) and how *computers* count (base 2). In this project you build a Python converter that goes both ways between binary and decimal, then extend it to handle octal, hexadecimal, arbitrary bases (2–36), negative numbers via two's complement, and a peek at how floating-point numbers are stored in IEEE 754. Along the way you implement both the "use the built-in" version and the "from scratch" algorithm so you understand what `int(s, 2)` and `bin()` actually do.
+
+You will learn:
+- The mechanics of positional number systems.
+- Python's `int(string, base)` and `bin()` / `oct()` / `hex()`.
+- How to convert any base in pure Python.
+- Two's complement for representing negative integers.
+- IEEE 754 single-precision float layout.
+- Input validation and friendly error reporting.
+
+## Why Bases Matter
+- **Base 2 (binary)** — the physical layer of every digital computer (transistors are on/off).
+- **Base 8 (octal)** — Unix file permissions (`chmod 755`).
+- **Base 10 (decimal)** — humans.
+- **Base 16 (hex)** — RGB colors (`#ff8000`), memory addresses, MAC addresses, byte dumps.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Basic understanding of number systems
-
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
-
-Note: This project uses only built-in Python features, so no additional installations are required.
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with `input()`, `if/elif/else`, and basic loops.
 
 ## Getting Started
-#### Create a Project
-1. Create a folder named `binary-decimal-converter`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `binary_to_decimal.py`.
-4. Copy the given code and paste it in your `binary_to_decimal.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `binary_to_decimal.py` file.
-<FileCode file="projects/beginners/binary_to_decimal.py" lang="python" title="Binary to Decimal Converter" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `binary-decimal-converter`.
-```cmd title="command" showLineNumbers{1} {1-25}
-C:\Users\Your Name\binary-decimal-converter> python binary_to_decimal.py
-Binary to Decimal Conveter
-Choose one of the following options:
-1. Convert a binary number to a decimal number
-2. Convert a decimal number to a binary number
-3. Exit
-Enter your option: 1
-Enter a binary number: 1101
-The decimal value of 1101 is 13
 
-C:\Users\Your Name\binary-decimal-converter> python binary_to_decimal.py
-Binary to Decimal Conveter
-Choose one of the following options:
-1. Convert a binary number to a decimal number
-2. Convert a decimal number to a binary number
-3. Exit
-Enter your option: 2
-Enter a decimal number: 13
-The binary value of 13 is 0b1101
+### Create the project
+1. Create folder `binary-decimal-converter`.
+2. Inside, create `binary_to_decimal.py`.
+
+### Write the code
+<FileCode file="projects/beginners/binary_to_decimal.py" lang="python" title="Binary to Decimal" />
 
+### Run it
+```cmd title="command"
 C:\Users\Your Name\binary-decimal-converter> python binary_to_decimal.py
-Binary to Decimal Conveter
-Choose one of the following options:
-1. Convert a binary number to a decimal number
-2. Convert a decimal number to a binary number
+Binary ↔ Decimal Converter
+1. Binary → Decimal
+2. Decimal → Binary
 3. Exit
-Enter your option: 3
+Choice: 1
+Binary: 1101
+1101₂ = 13₁₀
 ```
 
-## Explanation
-
-### Understanding Number Systems
-- **Binary (Base 2):** Uses only digits 0 and 1
-- **Decimal (Base 10):** Uses digits 0-9 (our standard counting system)
-- **Conversion:** Process of changing from one base to another
-
-### Code Breakdown
-1. **Display the program title and menu options.**
-```python title="binary_to_decimal.py" showLineNumbers{1} {1-6}
-print("Binary to Decimal Conveter")
-print("Choose one of the following options:")
-print("1. Convert a binary number to a decimal number")
-print("2. Convert a decimal number to a binary number")
-print("3. Exit")
-```
+## Step-by-Step Explanation
 
-2. **Get user's choice.**
-```python title="binary_to_decimal.py" showLineNumbers{1} {1}
-option = int(input("Enter your option: "))
-```
+### 1. Using built-ins (the right answer for production)
+```python title="builtins.py"
+# Binary string → decimal int
+decimal = int("1101", 2)        # 13
 
-3. **Handle binary to decimal conversion.**
-```python title="binary_to_decimal.py" showLineNumbers{1} {1-4}
-if option == 1:
-    binary = input("Enter a binary number: ")
-    decimal = int(binary, 2)
-    print("The decimal value of", binary, "is", decimal)
-```
+# Decimal int → binary string (with '0b' prefix)
+binary = bin(13)                # '0b1101'
 
-4. **Handle decimal to binary conversion.**
-```python title="binary_to_decimal.py" showLineNumbers{1} {1-4}
-elif option == 2:
-    decimal = int(input("Enter a decimal number: "))
-    binary = bin(decimal)
-    print("The binary value of", decimal, "is", binary)
-```
+# Strip the prefix if you want just the digits
+binary_clean = bin(13)[2:]      # '1101'
 
-5. **Handle exit option.**
-```python title="binary_to_decimal.py" showLineNumbers{1} {1-2}
-elif option == 3:
-    exit()
+# Also available:
+hexadecimal = hex(13)           # '0xd'
+octal       = oct(13)           # '0o15'
+```
+`int(s, base)` accepts any base from 2 to 36. Above 10, digits use letters `a..z` (case-insensitive).
+
+### 2. Menu with validation
+```python title="menu.py"
+def main():
+    while True:
+        print("\n1. Binary → Decimal  2. Decimal → Binary  3. Exit")
+        choice = input("> ").strip()
+        if choice == "1":
+            raw = input("Binary: ").strip()
+            if not all(c in "01" for c in raw) or not raw:
+                print("Use only 0s and 1s."); continue
+            print(f"{raw}₂ = {int(raw, 2)}₁₀")
+        elif choice == "2":
+            raw = input("Decimal: ").strip()
+            try:
+                n = int(raw)
+            except ValueError:
+                print("Not an integer."); continue
+            print(f"{n}₁₀ = {bin(n)[2:]}₂")
+        elif choice == "3":
+            break
+        else:
+            print("Invalid choice.")
 ```
+Two validation guards — character set for binary, `int()` for decimal — and friendly error messages.
 
-## Conversion Methods
+## Doing It By Hand
 
-### Binary to Decimal
-Python's `int()` function with base parameter:
-```python title="binary_to_decimal.py" showLineNumbers{1}
-decimal = int(binary_string, 2)
+### Binary → Decimal
+```python title="bin2dec.py"
+def bin_to_dec(s: str) -> int:
+    total = 0
+    for digit in s:
+        total = total * 2 + int(digit)        # Horner's method
+    return total
+```
+**Trace** for `"1101"`:
+```
+start    total = 0
+'1'      total = 0*2 + 1 = 1
+'1'      total = 1*2 + 1 = 3
+'0'      total = 3*2 + 0 = 6
+'1'      total = 6*2 + 1 = 13
 ```
+That single multiply-and-add idiom is **Horner's method** and works for any base (replace `2` with `base`).
+
+### Decimal → Binary
+```python title="dec2bin.py"
+def dec_to_bin(n: int) -> str:
+    if n == 0: return "0"
+    if n < 0:  return "-" + dec_to_bin(-n)
+    out = []
+    while n:
+        out.append(str(n & 1))                # last bit
+        n >>= 1                               # shift right
+    return "".join(reversed(out))
+```
+- `n & 1` extracts the least-significant bit (0 or 1).
+- `n >>= 1` shifts right, dropping that bit.
+- Building backwards then reversing avoids inefficient string prepend.
+
+## Arbitrary-Base Conversions
+
+```python title="any_base.py"
+DIGITS = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+def to_base(n: int, base: int) -> str:
+    if not 2 <= base <= 36:
+        raise ValueError("base must be 2..36")
+    if n == 0: return "0"
+    sign = "-" if n < 0 else ""
+    n = abs(n)
+    out = []
+    while n:
+        out.append(DIGITS[n % base])
+        n //= base
+    return sign + "".join(reversed(out))
+
+def from_base(s: str, base: int) -> int:
+    s = s.lower().strip()
+    sign = 1
+    if s.startswith("-"): sign, s = -1, s[1:]
+    n = 0
+    for ch in s:
+        digit = DIGITS.index(ch)
+        if digit >= base:
+            raise ValueError(f"'{ch}' is not valid in base {base}")
+    return sign * sum(DIGITS.index(c) * (base ** i)
+                      for i, c in enumerate(reversed(s)))
+```
+Now `to_base(255, 16)` → `"ff"`, `from_base("ff", 16)` → `255`. The exact same algorithm handles base-3, base-7, base-32, base-36.
 
-**Manual calculation for 1101:**
-- 1×2³ + 1×2² + 0×2¹ + 1×2⁰
-- 1×8 + 1×4 + 0×2 + 1×1
-- 8 + 4 + 0 + 1 = 13
+## Negative Numbers and Two's Complement
 
-### Decimal to Binary
-Python's `bin()` function:
-```python title="binary_to_decimal.py" showLineNumbers{1}
-binary = bin(decimal_number)
-```
+Computers represent signed integers as **two's complement**. For an 8-bit number:
+- Positive 5 → `0000 0101`.
+- Negative 5 → invert bits, add 1 → `1111 1011`.
 
-**Manual calculation for 13:**
-- 13 ÷ 2 = 6 remainder 1
-- 6 ÷ 2 = 3 remainder 0
-- 3 ÷ 2 = 1 remainder 1
-- 1 ÷ 2 = 0 remainder 1
-- Reading remainders from bottom to top: 1101
-
-## Features
-- **Bidirectional Conversion:** Binary ↔ Decimal
-- **Menu-Driven Interface:** Easy-to-use option selection
-- **Built-in Functions:** Uses Python's efficient conversion methods
-- **Simple Input/Output:** Clear prompts and results
-- **Exit Option:** Clean program termination
-- **Error Handling:** Basic input validation
-
-## Number System Examples
-
-### Binary to Decimal Examples
-| Binary | Calculation | Decimal |
-|--------|-------------|---------|
-| 1010 | 1×8 + 0×4 + 1×2 + 0×1 | 10 |
-| 1111 | 1×8 + 1×4 + 1×2 + 1×1 | 15 |
-| 10000 | 1×16 + 0×8 + 0×4 + 0×2 + 0×1 | 16 |
-
-### Decimal to Binary Examples
-| Decimal | Binary | Explanation |
-|---------|--------|-------------|
-| 5 | 101 | 4 + 1 |
-| 8 | 1000 | 8 |
-| 255 | 11111111 | 128+64+32+16+8+4+2+1 |
-
-## Applications in Computer Science
-- **Computer Architecture:** How computers store numbers
-- **Digital Logic:** Foundation of digital circuits
-- **Programming:** Understanding data representation
-- **Networking:** IP addresses and subnetting
-- **Cryptography:** Binary operations in encryption
+```python title="twos.py"
+def to_twos_complement(n: int, bits: int = 8) -> str:
+    if n < 0:
+        n = (1 << bits) + n               # wrap into range
+    return format(n, f"0{bits}b")
 
-## Next Steps
-You can enhance this project by:
-- Adding input validation for binary numbers
-- Supporting other number systems (octal, hexadecimal)
-- Creating a GUI version using Tkinter
-- Adding batch conversion from files
-- Implementing custom conversion algorithms
-- Adding floating-point number support
-- Creating visualization of conversion process
-- Adding history of conversions
-- Implementing error handling for invalid inputs
-- Adding unit tests for validation
-
-## Enhanced Version Ideas
-```python title="binary_to_decimal.py" showLineNumbers{1}
-def enhanced_converter():
-    # Features to add:
-    # - Support for octal and hexadecimal
-    # - Input validation
-    # - Conversion history
-    # - Batch processing
-    # - Custom base conversions
-    pass
-
-def validate_binary(binary_str):
-    # Check if string contains only 0s and 1s
-    return all(digit in '01' for digit in binary_str)
-
-def manual_binary_to_decimal(binary_str):
-    # Implement manual conversion algorithm
-    decimal = 0
-    for i, digit in enumerate(reversed(binary_str)):
-        decimal += int(digit) * (2 ** i)
-    return decimal
-```
+def from_twos_complement(s: str) -> int:
+    bits = len(s)
+    n = int(s, 2)
+    return n - (1 << bits) if s[0] == "1" else n
 
-## Manual Conversion Algorithms
-
-### Binary to Decimal (Manual)
-```python title="binary_to_decimal.py" showLineNumbers{1}
-def binary_to_decimal_manual(binary):
-    decimal = 0
-    power = 0
-    for digit in reversed(binary):
-        decimal += int(digit) * (2 ** power)
-        power += 1
-    return decimal
+print(to_twos_complement(-5, 8))    # 11111011
+print(from_twos_complement("11111011"))  # -5
 ```
-
-### Decimal to Binary (Manual)
-```python title="binary_to_decimal.py" showLineNumbers{1}
-def decimal_to_binary_manual(decimal):
-    if decimal == 0:
-        return "0"
-    binary = ""
-    while decimal > 0:
-        binary = str(decimal % 2) + binary
-        decimal = decimal // 2
-    return binary
+This is exactly how a C `int8_t` works.
+
+## IEEE 754 Float Layout
+
+Python's `struct` module lets you peek at how 32-bit floats are stored:
+```python title="ieee754.py"
+import struct
+bits = struct.pack(">f", 3.14)        # big-endian float
+binary = "".join(f"{b:08b}" for b in bits)
+print(binary)
+# 01000000010010001111010111000011
+# sign: 0, exponent: 10000000 (=128 → bias-adjusted 1),
+# mantissa: 10010001111010111000011
 ```
+This is the layout every desktop CPU uses. It explains why `0.1 + 0.2 != 0.3` in every language with IEEE 754 floats.
 
-## Educational Value
-This project teaches:
-- **Number Systems:** Understanding different bases
-- **Built-in Functions:** Using int() and bin()
-- **Menu Design:** Creating user-friendly interfaces
-- **Conditional Logic:** Handling different user choices
-- **Input/Output:** Processing user input and displaying results
-
-## Common Use Cases
-- **Educational Tool:** Teaching number system conversions
-- **Programming Practice:** Understanding data representation
-- **Computer Science Fundamentals:** Base conversion concepts
-- **Digital Electronics:** Understanding binary representation
-- **Quick Calculations:** Converting between systems
-
-## Error Handling Improvements
-```python title="binary_to_decimal.py" showLineNumbers{1}
-def safe_binary_to_decimal():
-    try:
-        binary = input("Enter a binary number: ")
-        if not all(digit in '01' for digit in binary):
-            print("Error: Please enter only 0s and 1s")
-            return
-        decimal = int(binary, 2)
-        print(f"The decimal value of {binary} is {decimal}")
-    except ValueError:
-        print("Error: Invalid binary number")
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `ValueError: invalid literal for int()` | Non-binary characters in input | Validate with `all(c in "01" for c in s)` |
+| `bin(13)` returns `'0b1101'` not `'1101'` | The `0b` prefix is informative | Slice `[2:]` |
+| Manual `int(digit) * 2**i` is O(n²) string-wise | Bad algorithm | Use Horner: `total = total * base + d` |
+| Negative numbers print as `-0b101` | Built-in `bin()` includes the sign | Either accept it, or build your own |
+| Leading zeros lost | Numbers do not preserve format | Pad: `format(n, "08b")` |
+| `int(s, 0)` infers wrong base | `0` means "guess from prefix" — `0b`, `0o`, `0x` | Pass an explicit base |
+
+## Variations to Try
+
+### 1. Add octal and hex
+Extend the menu with `Hex → Decimal`, `Decimal → Octal`, etc.
+
+### 2. Conversion history
+Print each conversion plus a timestamp; export to CSV.
+
+### 3. Batch mode
+Read a list of numbers from a file; emit a converted column.
+
+### 4. CLI flags
+```bash title="cli"
+python convert.py 255 --from 10 --to 16    # → ff
+python convert.py ff  --from 16 --to 2     # → 11111111
 ```
 
-## Performance Considerations
-- **Built-in Functions:** Very efficient for conversion
-- **String Operations:** Minimal overhead for typical inputs
-- **Memory Usage:** Constant space complexity
-- **Large Numbers:** Python handles arbitrary precision
+### 5. GUI version
+Tkinter with two big text boxes and base dropdowns. Type in either box; the other updates live.
+
+### 6. Bitwise visualizer
+For each step of the decimal→binary algorithm, show the running value, the bit being extracted, and the resulting binary so far. Great for classrooms.
+
+### 7. Fractional binary
+Extend to fractions: `0.625` ↔ `0.101`. Loop `value *= 2`; integer part is the next bit.
+
+### 8. Two's-complement signed converter
+Use the function above; ask the user how many bits.
+
+### 9. Color picker
+Parse `#ff8000` → `(255, 128, 0)` in RGB.
+
+### 10. Web tool
+A Flask form (see [Basic Web Server](./basicwebserver)) that converts on submit.
 
 ## Real-World Applications
-- **Computer Programming:** Understanding data types
-- **Digital Systems:** Binary logic and circuits
-- **Network Administration:** IP address calculations
-- **Embedded Systems:** Low-level programming
-- **Data Analysis:** Binary data processing
+- **Networking** — IPv4 `192.168.1.1` to its 32-bit binary representation, subnet calculations.
+- **Color manipulation** — `#rrggbb` ↔ tuples of decimal.
+- **Unix permissions** — `chmod 755` is octal `rwxr-xr-x`.
+- **Reverse engineering** — interpreting hex dumps and memory addresses.
+- **Cryptography** — XOR, bit rotations, hex-encoded keys.
+- **Embedded programming** — register values are hex; bit fields matter.
+
+## Educational Value
+- **Positional number systems** — the most fundamental abstraction in computing.
+- **`int(s, base)`** — one of Python's most underused built-ins.
+- **Horner's method** — fewer multiplications than `digit * base ** i`.
+- **Bitwise operators** — `&`, `|`, `^`, `<<`, `>>`.
+- **Two's complement** — the actual representation of signed integers.
+
+## Next Steps
+- Extend to **octal and hex**.
+- Implement **`to_base` / `from_base`** for arbitrary bases.
+- Add **two's complement** handling.
+- Build a **GUI** with live conversion as the user types.
+- Read about **IEEE 754** to understand why `0.1 + 0.2 != 0.3`.
 
 ## Conclusion
-In this project, we learned how to create a Binary to Decimal Converter using Python's built-in conversion functions. We explored fundamental concepts of number systems, menu-driven programming, and user interface design. This project provides essential knowledge for understanding how computers represent and process numerical data. The conversion between binary and decimal systems is fundamental to computer science and digital technology. To find more projects like this, you can visit Python Central Hub.
+You built a converter both ways using built-ins, then implemented the math by hand so the `int(s, 2)` and `bin(n)` calls stopped looking like magic. The same algorithms power every hex dump, color picker, and networking calculator you have ever used. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/binary_to_decimal.py). Find more algorithm projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/blackjack.mdx b/src/content/docs/projects/Beginners/blackjack.mdx
index 63d368ce..d2cb4ae0 100644
--- a/src/content/docs/projects/Beginners/blackjack.mdx
+++ b/src/content/docs/projects/Beginners/blackjack.mdx
@@ -1,6 +1,6 @@
 ---
 title: Text-based Blackjack Game
-description: Create a complete blackjack game with cards, betting, and classic casino rules
+description: Build a complete Blackjack game in Python with OOP. Cards, decks, hands, betting, ace handling, dealer AI, and a path to double-down, split, statistics, and basic strategy.
 sidebar:
   order: 54
 hero:
@@ -14,40 +14,48 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a fully functional text-based blackjack game that implements classic casino rules, card dealing, betting systems, and game logic. This project demonstrates object-oriented programming, game state management, and complex conditional logic.
+Blackjack is the perfect "first serious OOP project." You model real objects — cards, decks, hands, chips — and watch class composition do its job. You also implement rules with edge cases (the ace counts as 1 *or* 11), simulate a deterministic dealer AI, and run a betting loop. In this tutorial you build the complete game, refactor where the original could be cleaner, and add features (double-down, split, statistics) that show how a good class design absorbs new requirements without panic.
 
-## Prerequisites
+You will leave understanding:
+- How to model cards, decks, and hands as Python classes.
+- The "aces count as 1 or 11" rule, encoded cleanly.
+- The standard dealer rule ("hit on 16, stand on 17").
+- How to keep player chips and bets in one place.
+- How to extend the game: double-down, split, insurance, basic strategy hints.
+
+## The Rules (Quick)
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax
-- Knowledge of object-oriented programming (classes, objects)
-- Familiarity with game logic and conditional statements
-- Understanding of loops and user input handling
+- Goal: beat the dealer without exceeding 21 ("bust").
+- Cards 2–10 are worth their face value, J/Q/K count as 10, A counts as 1 *or* 11.
+- Player and dealer each get two cards. One of the dealer's is face down.
+- Player choices: **hit** (take another card), **stand** (stop).
+- Dealer must **hit** until reaching 17 or higher.
+- 21 on the first two cards is a **blackjack** (typically pays 3:2).
+- Ties = **push** (bet returned).
+
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with classes and methods. (See [Personal Diary](./personaldiary) for an OOP refresher.)
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `blackjackGame`.
-2. Create a new file and name it `blackjack.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `blackjack.py` file.
+### Create the project
+1. Create folder `blackjack-game`.
+2. Inside, create `blackjack.py`.
 
 ### Write the code
-1. Add the following code to your `blackjack.py` file.
-<FileCode file="projects/beginners/blackjack.py" lang="python" title="Text-based Blackjack Game" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\blackjackGame> python blackjack.py
+<FileCode file="projects/beginners/blackjack.py" lang="python" title="Blackjack" />
+
+### Run it
+```cmd title="command"
+C:\Users\username\Documents\blackjack-game> python blackjack.py
 Welcome to BlackJack! Get as close to 21 as you can without going over!
     Dealer hits until she reaches 17. Aces count as 1 or 11.
 
 How many chips would you like to play with? 100
-Betting
--------
 Current chips: 100
-How much chips would you like to bet? 20
+How much would you like to bet? 20
 
 Dealer Hand:
 <card hidden>
@@ -56,176 +64,250 @@ Four of Hearts
 Player Hand:
 Jack of Spades
 Seven of Hearts
-Total:  17
+Total: 17
 
-Would you like to Hit or Stand? Enter 'h' or 's' s
+Would you like to Hit or Stand? Enter 'h' or 's': s
 Dealer Wins!
 Player chips total only 80
-Would you like to play again? y/n y
+Would you like to play again? y/n
 ```
 
-2. **Run the Blackjack Game**
-   ```bash
-   python blackjack.py
-   ```
-
-```
-
-## Explanation
-
-1. The `import random` statement imports the random module for card shuffling and dealing.
-2. The `class Card:` defines individual playing cards with suit and rank attributes.
-3. The `class Deck:` creates a full 52-card deck with shuffling functionality.
-4. The `class Hand:` manages collections of cards and calculates hand values.
-5. The `class Chips:` handles the betting system and chip management.
-6. The ace handling logic automatically adjusts ace values from 11 to 1 when needed.
-7. The `hit_or_stand()` function handles player decisions during gameplay.
-8. The dealer follows standard casino rules (hits until 17 or higher).
-9. The game loop allows for multiple rounds of play.
-10. Win/loss conditions check for busts, blackjacks, and hand comparisons.
-11. The betting system tracks wins and losses with chip adjustments.
-12. Input validation ensures proper user responses throughout the game.
-
-## Next Steps
+## Step-by-Step Explanation
 
-Congratulations! You have successfully created a Text-based Blackjack Game in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add GUI interface with card graphics
-- Implement double down and split functionality
-- Add insurance betting option
-- Create multiplayer support for multiple players
-- Add statistics tracking (wins, losses, streaks)
-- Implement different difficulty levels
-- Add sound effects and animations
-- Create tournament mode with multiple rounds
-- Add card counting practice features
+### 1. The `Card` class
+```python title="blackjack.py"
+SUITS = ("Hearts", "Diamonds", "Spades", "Clubs")
+RANKS = ("Two","Three","Four","Five","Six","Seven","Eight","Nine","Ten",
+         "Jack","Queen","King","Ace")
+VALUES = {**{r: i for i, r in enumerate(RANKS[:9], start=2)},
+          "Jack": 10, "Queen": 10, "King": 10, "Ace": 11}
 
-## Conclusion
-
-In this project, you learned how to create a Text-based Blackjack Game in Python using object-oriented programming. You also learned about game logic, state management, and implementing classic card game rules. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/blackjack.py)
-
-## Code Explanation
-
-### Card and Deck Classes
-```python title="blackjack.py" showLineNumbers{1}
 class Card:
-    def __init__(self, suit, rank):
+    def __init__(self, suit: str, rank: str):
         self.suit = suit
         self.rank = rank
-    
-    def value(self):
-        if self.rank in ['Jack', 'Queen', 'King']:
-            return 10
-        elif self.rank == 'Ace':
-            return 11
-        else:
-            return int(self.rank)
+    def __str__(self):
+        return f"{self.rank} of {self.suit}"
 ```
+Putting `VALUES` outside the class avoids recomputing it for every card.
+
+### 2. The `Deck` class
+```python title="blackjack.py"
+import random
+class Deck:
+    def __init__(self):
+        self.cards = [Card(s, r) for s in SUITS for r in RANKS]
+        random.shuffle(self.cards)
+    def deal(self) -> Card:
+        return self.cards.pop()
+```
+A list comprehension builds all 52 cards in one line. `pop()` removes from the end — O(1).
 
-Implements card representation with proper value calculation for different card types.
-
-### Hand Management with Ace Handling
-```python title="blackjack.py" showLineNumbers{1}
+### 3. The `Hand` class with ace adjustment
+```python title="blackjack.py"
 class Hand:
+    def __init__(self):
+        self.cards: list[Card] = []
+        self.value = 0
+        self.aces = 0
+    def add(self, card: Card):
+        self.cards.append(card)
+        self.value += VALUES[card.rank]
+        if card.rank == "Ace":
+            self.aces += 1
+        self.adjust_for_ace()
     def adjust_for_ace(self):
         while self.value > 21 and self.aces:
-            self.value -= 10
+            self.value -= 10            # demote one Ace from 11 → 1
             self.aces -= 1
 ```
+The ace rule is **only** awkward because it depends on the rest of the hand. The trick is to **count aces** and demote them one at a time when needed.
 
-Automatically adjusts ace values from 11 to 1 when hand total exceeds 21, implementing classic blackjack ace rules.
-
-### Betting System
-```python title="blackjack.py" showLineNumbers{1}
+### 4. The `Chips` class
+```python title="blackjack.py"
 class Chips:
-    def __init__(self, total=100):
+    def __init__(self, total: int = 100):
         self.total = total
         self.bet = 0
-    
-    def win_bet(self):
-        self.total += self.bet
-    
-    def lose_bet(self):
-        self.total -= self.bet
+    def win(self):  self.total += self.bet
+    def lose(self): self.total -= self.bet
 ```
+A tiny class with one job. The single-line methods are intentional — "what happens on a win" is one source of truth.
+
+### 5. Player turn — hit or stand
+```python title="blackjack.py"
+def hit(deck, hand):
+    hand.add(deck.deal())
+
+def hit_or_stand(deck, hand, playing_ref):
+    while True:
+        choice = input("Hit (h) or Stand (s)? ").lower()
+        if choice == "h":
+            hit(deck, hand)
+            return
+        if choice == "s":
+            playing_ref[0] = False
+            return
+        print("Enter h or s.")
+```
+`playing_ref` is a one-element list used as a "ref cell" — Python passes integers by value, so we wrap a mutable container to let `hit_or_stand` flip the flag for the outer loop.
 
-Manages player's chip count with betting mechanics for wins and losses.
+### 6. Dealer logic
+```python title="blackjack.py"
+while dealer_hand.value < 17:
+    dealer_hand.add(deck.deal())
+```
+Standard rule, two lines.
+
+### 7. Decide outcomes
+```python title="blackjack.py"
+if player_hand.value > 21:
+    print("Player busts.")
+    chips.lose()
+elif dealer_hand.value > 21 or player_hand.value > dealer_hand.value:
+    print("Player wins.")
+    chips.win()
+elif dealer_hand.value > player_hand.value:
+    print("Dealer wins.")
+    chips.lose()
+else:
+    print("Push.")
+```
+The order matters — check **player bust first** so the dealer does not "win" automatically by also busting.
+
+## Polished Output
+
+A small helper that hides the dealer's hole card during play:
+```python title="show.py"
+def show_some(player, dealer):
+    print("\nDealer's Hand:")
+    print("<hidden>")
+    print(dealer.cards[1])
+    print("\nPlayer's Hand:")
+    for c in player.cards: print(c)
+    print(f"Total: {player.value}")
+
+def show_all(player, dealer):
+    print("\nDealer's Hand:")
+    for c in dealer.cards: print(c)
+    print(f"Total: {dealer.value}")
+    print("\nPlayer's Hand:")
+    for c in player.cards: print(c)
+    print(f"Total: {player.value}")
+```
 
-### Game Logic Flow
-```python title="blackjack.py" showLineNumbers{1}
-def hit_or_stand(deck, hand):
-    choice = input("Would you like to Hit or Stand? Enter 'h' or 's': ").lower()
-    if choice == 'h':
-        hit(deck, hand)
-    elif choice == 's':
-        playing = False
+## Betting Validation
+
+```python title="bet.py"
+def take_bet(chips: Chips):
+    while True:
+        try:
+            chips.bet = int(input(f"Bet (1-{chips.total}): "))
+        except ValueError:
+            print("Enter a whole number.")
+            continue
+        if 1 <= chips.bet <= chips.total:
+            return
+        print("Out of range.")
 ```
 
-Handles player decisions and game state transitions with input validation.
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Ace always counts as 11 | No demotion logic | `adjust_for_ace` after every `add` |
+| Dealer bust and player bust → player wins | Wrong condition order | Check player bust first |
+| Same card dealt twice | Forgot to shuffle, or rebuilt deck wrong | Use one `Deck` instance per round, or reshuffle when low |
+| Bet bigger than chip total accepted | No upper-bound check | Validate against `chips.total` |
+| `IndexError: pop from empty list` | Did not reshuffle | Add `if len(self.cards) < 10: reshuffle()` |
+| Score breaks at 22 with two aces | Adjusted only once | `while`, not `if`, in `adjust_for_ace` |
+
+## Variations to Try
+
+### 1. Multiple decks
+Casinos use 4–8 decks shuffled together:
+```python title="multi_deck.py"
+class Deck:
+    def __init__(self, num_decks=4):
+        self.cards = [Card(s, r) for _ in range(num_decks)
+                                 for s in SUITS for r in RANKS]
+        random.shuffle(self.cards)
+```
 
-### Dealer AI
-```python title="blackjack.py" showLineNumbers{1}
-if player_hand.value <= 21:
-    while dealer_hand.value < 17:
-        hit(deck, dealer_hand)
+### 2. Blackjack pays 3:2
+A natural 21 on the first two cards pays 1.5× the bet:
+```python title="natural.py"
+if len(player_hand.cards) == 2 and player_hand.value == 21:
+    chips.total += int(chips.bet * 1.5)
+    return "natural"
 ```
 
-Implements standard casino dealer rules (hit until 17 or higher).
+### 3. Double Down
+After the deal, the player may double the bet, take exactly one more card, and end the turn.
 
-### Win/Loss Conditions
-```python title="blackjack.py" showLineNumbers{1}
-if dealer_hand.value > 21:
-    dealer_busts(player_hand, dealer_hand, player_chips)
-elif dealer_hand.value > player_hand.value:
-    dealer_wins(player_hand, dealer_hand, player_chips)
-elif dealer_hand.value < player_hand.value:
-    player_wins(player_hand, dealer_hand, player_chips)
-else:
-    push(player_hand, dealer_hand)
+### 4. Split
+With a pair, split into two hands, each played independently with a separate bet.
+
+### 5. Insurance
+When the dealer's up-card is an Ace, the player can buy insurance (half the bet) that pays 2:1 if the dealer has blackjack.
+
+### 6. Basic-strategy hints
+Hard-code the standard chart. After each hand, show what basic strategy would have done.
+
+### 7. Statistics
+Track hands played, wins, losses, ties, biggest hand, longest streak. Save to a JSON file between sessions.
+
+### 8. Card counting trainer
+Show the running count after each hand. Quiz the player at the end of each shoe.
+
+### 9. ASCII card art
+Render each card as 5-line ASCII art:
+```
+┌─────────┐
+│7        │
+│         │
+│    ♥    │
+│         │
+│        7│
+└─────────┘
 ```
 
-Evaluates all possible game outcomes with proper chip adjustments.
+### 10. GUI version
+Tkinter or PyGame with real card images. See [Basic Music Player](./basicmusicplayer) for the Tkinter pattern.
 
-## Features
+### 11. Multiplayer (one dealer, multiple players)
+Each player has their own `Hand` and `Chips`. Iterate through them before the dealer's turn.
 
-- **Complete Card System**: Full 52-card deck with proper shuffling
-- **Realistic Blackjack Rules**: Standard casino rules including ace handling
-- **Betting System**: Chip management with wins/losses tracking
-- **Dealer AI**: Automated dealer following standard rules (hit until 17)
-- **Game State Management**: Proper handling of busts, wins, and pushes
-- **Input Validation**: Robust user input handling and error checking
-- **Replay Functionality**: Option to play multiple hands
-- **Visual Card Display**: Clear representation of hands and card values
+### 12. Web version
+Flask backend + a React frontend. The server stores the deck and hands; the client renders.
 
-## Next Steps
+## Architecture Notes
+
+The original code worked but mixed game logic with I/O. A cleaner separation:
+- **`Card`, `Deck`, `Hand`, `Chips`** — pure game state, no `input`/`print`.
+- **`Game`** — orchestrates a round: deals, asks for choices, decides winner.
+- **`UI`** — talks to the user. Could be CLI, GUI, or web.
 
-### Enhancements
-- Add GUI interface with card graphics
-- Implement double down and split functionality
-- Add insurance betting option
-- Create multiplayer support for multiple players
-- Add statistics tracking (wins, losses, streaks)
-- Implement progressive betting strategies
-- Add sound effects and animations
-- Create tournament mode with multiple rounds
-
-### Learning Extensions
-- Study probability and card counting concepts
-- Explore advanced blackjack strategies and optimal play
-- Learn about casino mathematics and house edge
-- Practice with database integration for player statistics
-- Understand random number generation and fairness
-- Explore AI techniques for optimal play strategies
+That separation is what lets you swap CLI for GUI without rewriting rules.
+
+## Real-World Connections
+- Probability and combinatorics teaching.
+- Reinforcement learning — Blackjack is a classic toy problem in Sutton & Barto's *Reinforcement Learning*.
+- Card-counting math (Kelly criterion, edge calculation).
+- Game-design fundamentals — state, choices, randomness, reward.
 
 ## Educational Value
+- **OOP composition** — Card → Deck → Hand.
+- **Edge-case modeling** — Aces, blackjacks, busts, pushes.
+- **State machines** — round phases (deal, player turn, dealer turn, settle).
+- **Game-theory thinking** — when basic strategy beats intuition.
+
+## Next Steps
+- Implement **double-down** and **split** — the natural feature jumps from beginner Blackjack to "real" Blackjack.
+- Add a **basic-strategy hint** that prints what the optimal move would be.
+- Track **session statistics** and persist them.
+- Try a tiny **reinforcement-learning agent** that learns to play.
+- Compare with [Hangman](./hangman) and [Rock Paper Scissors](./rockpaperscissors) for different game-state patterns.
 
-This project teaches:
-- **Object-Oriented Programming**: Creating and managing multiple interacting classes
-- **Game Logic Design**: Implementing complex rules and state management
-- **Random Number Generation**: Working with shuffling and fair card distribution
-- **Conditional Logic**: Handling multiple game outcomes and decision trees
-- **User Interface Design**: Creating intuitive text-based interactions
-- **State Management**: Tracking game progress and player status
-- **Input Validation**: Ensuring robust user input handling
-- **Mathematical Modeling**: Implementing probability-based game mechanics
-
-Perfect for understanding game development, object-oriented design, and complex program flow control in Python.
+## Conclusion
+You built a complete card game, modeled the rules of Blackjack including the Ace dance, simulated a deterministic dealer, and ran a betting loop. The same class composition (`Card → Deck → Hand → Game`) underlies poker, solitaire, Hearts, and dozens of other card games. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/blackjack.py). Find more games on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/calculatorgui.mdx b/src/content/docs/projects/Beginners/calculatorgui.mdx
index 4b449db1..a3ef0abc 100644
--- a/src/content/docs/projects/Beginners/calculatorgui.mdx
+++ b/src/content/docs/projects/Beginners/calculatorgui.mdx
@@ -1,6 +1,6 @@
 ---
 title: Calculator GUI
-description: Build a graphical calculator application with standard arithmetic operations using Tkinter
+description: Build a graphical calculator in Python with Tkinter. Learn grid layout, button callbacks, expression evaluation, why eval() is dangerous, AST-based safe evaluation, keyboard support, and themes.
 sidebar:
   order: 46
 hero:
@@ -14,181 +14,264 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Create a fully functional calculator with a graphical user interface that supports basic arithmetic operations, decimal numbers, error handling, and clear functionality. This project demonstrates GUI design, event handling, and mathematical expression evaluation.
+A graphical calculator is the perfect "first real Tkinter app" — every button is a callback, every press updates one shared variable, and the result lights up immediately. In this project you will build a working calculator with a number pad, four operators, clear/equals buttons, and error handling. Then we will replace the dangerous `eval()` evaluator with a safe AST-based one, add keyboard input, expression history, and a scientific mode.
 
-## Prerequisites
+You will learn:
+- The Tkinter grid layout in earnest.
+- The lambda + default-argument trick for binding buttons in a loop.
+- Why `eval()` is dangerous and how to evaluate math expressions safely.
+- How to capture keyboard input alongside button clicks.
+- How to keep a running history and let the user reuse prior results.
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of Tkinter for GUI development
-- Familiarity with arithmetic operations
-- Understanding of event-driven programming
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with Python on Windows/macOS; Linux: `sudo apt install python3-tk`).
+- Familiarity with functions, events, and basic Tkinter widgets.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `calculatorGUI`.
-2. Create a new file and name it `calculatorgui.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `calculatorgui.py` file.
+### Create the project
+1. Create folder `calculatorGUI`.
+2. Inside, create `calculatorgui.py`.
 
 ### Write the code
-1. Add the following code to your `calculatorgui.py` file.
 <FileCode file="projects/beginners/calculatorgui.py" lang="python" title="Calculator GUI" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\calculatorGUI> python calculatorgui.py
-[Calculator GUI Opens]
-- Click number buttons to input values
-- Click operation buttons (+, -, *, /) for calculations
-- Click "=" to get the result
-- Click "Clear" to reset the calculator
-Example: 5 + 3 = 8
-```
 
+### Run it
+```cmd title="command"
+C:\Users\Your Name\calculatorGUI> python calculatorgui.py
+# Window opens with:
+#   - Display at the top
+#   - Number pad (0-9)
+#   - Operator buttons (+, -, *, /)
+#   - = and Clear buttons
 ```
 
-## Explanation
-
-1. The `from tkinter import *` statement imports all Tkinter components for creating the GUI.
-2. The `solution = ""` creates a global variable to store the current mathematical expression.
-3. The `equation = StringVar()` creates a Tkinter string variable for the display.
-4. The `def press(num):` function handles button presses and updates the expression.
-5. The `def equalpress():` function evaluates the mathematical expression using eval().
-6. The `def clear():` function resets the calculator by clearing the expression.
-7. The `gui = Tk()` creates the main window for the calculator.
-8. The `expression_field = Entry()` creates the display field for showing expressions and results.
-9. The number buttons (0-9) are created with lambda functions to pass their values.
-10. The operation buttons (+, -, *, /) handle arithmetic operations.
-11. The grid layout system organizes buttons in a calculator-style arrangement.
-12. Error handling displays "error" when invalid expressions are entered.
-
-## Next Steps
-
-Congratulations! You have successfully created a Calculator GUI in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add advanced mathematical functions (sin, cos, tan, log, sqrt)
-- Implement memory functions (M+, M-, MR, MC)
-- Add keyboard input support
-- Create a history feature to track calculations
-- Implement bracket support for complex expressions
-- Add a scientific calculator mode
-- Create different themes and color schemes
-- Add sound effects for button presses
-- Implement percentage calculations
-
-## Conclusion
+## Step-by-Step Explanation
 
-In this project, you learned how to create a Calculator GUI in Python using Tkinter. You also learned about GUI design, event handling, and mathematical expression evaluation. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/calculatorgui.py)
-
-
-
-## Code Explanation
+### 1. Imports and state
+```python title="calculatorgui.py"
+from tkinter import *
+gui = Tk()
+gui.title("Calculator")
+gui.configure(background="light green")
+gui.geometry("270x180")
 
-### Global State Management
-```python title="calculatorgui.py" showLineNumbers{1}
 solution = ""
+equation = StringVar()
+```
+- `solution` is the current expression as a string.
+- `StringVar` is a Tkinter helper that lets a widget automatically refresh when the variable changes.
 
-def press(num):
-    global solution
-    solution = solution + str(num)
-    equation.set(solution)
+### 2. The display field
+```python title="calculatorgui.py"
+expression_field = Entry(gui, textvariable=equation)
+expression_field.grid(columnspan=4, ipadx=70)
 ```
+- `textvariable=equation` binds the entry to our `StringVar` — any update to `equation` immediately appears in the field.
+- `columnspan=4` makes the entry span the full width of the four-column grid.
 
-Maintains the current expression as a global string, updating the display whenever new input is added.
+### 3. Button callbacks
+```python title="calculatorgui.py"
+def press(value):
+    global solution
+    solution = solution + str(value)
+    equation.set(solution)
 
-### Expression Evaluation
-```python title="calculatorgui.py" showLineNumbers{1}
 def equalpress():
+    global solution
     try:
-        global solution
         total = str(eval(solution))
         equation.set(total)
         solution = ""
-    except:
+    except Exception:
         equation.set(" error ")
         solution = ""
+
+def clear():
+    global solution
+    solution = ""
+    equation.set("")
+```
+`global` is needed because the callbacks modify a module-level variable. (We will fix this with a class later.)
+
+### 4. The button grid
+```python title="calculatorgui.py"
+buttons = [
+    ("1", 2, 0), ("2", 2, 1), ("3", 2, 2), ("+", 2, 3),
+    ("4", 3, 0), ("5", 3, 1), ("6", 3, 2), ("-", 3, 3),
+    ("7", 4, 0), ("8", 4, 1), ("9", 4, 2), ("*", 4, 3),
+    ("0", 5, 0), (".", 5, 1), ("=", 5, 2), ("/", 5, 3),
+]
+for label, row, col in buttons:
+    cmd = equalpress if label == "=" else (lambda v=label: press(v))
+    Button(gui, text=f" {label} ", fg="black", bg="gray",
+           command=cmd, height=1, width=7).grid(row=row, column=col)
+
+Button(gui, text="Clear", command=clear, height=1, width=7).grid(row=6, columnspan=4)
 ```
+Notice **`lambda v=label: press(v)`** — without the `v=label` default-argument capture, every button would call `press(label)` with the *last* label assigned in the loop. This is the classic Python closure trap.
 
-Uses Python's `eval()` function to calculate mathematical expressions with proper error handling for invalid operations.
+### 5. Start the event loop
+```python title="calculatorgui.py"
+gui.mainloop()
+```
 
-### GUI Layout with Grid System
-```python title="calculatorgui.py" showLineNumbers{1}
-gui = Tk()
-gui.configure(background="light green")
-gui.title("Calculator")
-gui.geometry("270x150")
+## Why `eval()` Is Dangerous
 
-expression_field = Entry(gui, textvariable=equation)
-expression_field.grid(columnspan=4, ipadx=70)
+```python title="dangerous.py"
+eval(input())
 ```
+If the user types `__import__('os').system('rm -rf /')`, Python obediently executes it. A pure-math input field is "safe" only as long as you trust whoever can type into it — in a multi-user app, in a web app, **never**.
+
+### Safe alternative: AST evaluator
+The `ast` module parses Python source without executing it. We can walk the tree manually and allow only math nodes:
+
+```python title="safe_eval.py"
+import ast, operator as op
+
+OPS = {
+    ast.Add:  op.add,  ast.Sub: op.sub,
+    ast.Mult: op.mul,  ast.Div: op.truediv,
+    ast.Mod:  op.mod,  ast.Pow: op.pow,
+    ast.USub: op.neg,
+}
+
+def safe_eval(expr: str):
+    tree = ast.parse(expr, mode="eval")
+    def _eval(node):
+        if isinstance(node, ast.Expression):
+            return _eval(node.body)
+        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+            return node.value
+        if isinstance(node, ast.BinOp):
+            return OPS[type(node.op)](_eval(node.left), _eval(node.right))
+        if isinstance(node, ast.UnaryOp):
+            return OPS[type(node.op)](_eval(node.operand))
+        raise ValueError(f"Unsupported: {ast.dump(node)}")
+    return _eval(tree)
+```
+Now `equalpress` calls `safe_eval(solution)` instead of `eval(solution)`. `import os` and any function call are immediately rejected.
+
+## Keyboard Support
+
+Buttons are nice; typing is faster:
+```python title="keys.py"
+def on_key(event):
+    if event.char in "0123456789+-*/.":
+        press(event.char)
+    elif event.keysym in ("Return", "equal"):
+        equalpress()
+    elif event.keysym == "BackSpace":
+        global solution
+        solution = solution[:-1]
+        equation.set(solution)
+    elif event.keysym == "Escape":
+        clear()
 
-Creates a structured calculator layout using Tkinter's grid system for organized button placement.
-
-### Number and Operation Buttons
-```python title="calculatorgui.py" showLineNumbers{1}
-button1 = Button(gui, text=' 1 ', fg='black', bg='gray',
-                 command=lambda: press(1), height=1, width=7)
-button1.grid(row=2, column=0)
+gui.bind("<Key>", on_key)
+```
 
-plus = Button(gui, text=' + ', fg='black', bg='gray',
-              command=lambda: press("+"), height=1, width=7)
-plus.grid(row=2, column=3)
+## Refactor into a Class
+
+Globals are fine for a 50-line script. Past that, wrap state on `self`:
+```python title="oop.py"
+class CalculatorApp:
+    def __init__(self, root):
+        self.solution = ""
+        self.equation = StringVar()
+        self.root = root
+        self._build()
+    def press(self, v):
+        self.solution += str(v); self.equation.set(self.solution)
+    def equalpress(self):
+        try:
+            self.equation.set(str(safe_eval(self.solution)))
+        except Exception:
+            self.equation.set("error")
+        self.solution = ""
+    def clear(self):
+        self.solution = ""; self.equation.set("")
+    def _build(self):
+        # …create widgets, bind callbacks to self.press, etc.
+        ...
 ```
+Now you can run multiple calculator windows side-by-side without state leaks, and unit-test the logic without a window.
 
-Implements individual buttons for numbers (0-9) and operators (+, -, *, /) with lambda functions for command handling.
+## Common Mistakes
 
-### Clear Functionality
-```python title="calculatorgui.py" showLineNumbers{1}
-def clear():
-    global solution
-    solution = ""
-    equation.set("")
-```
+| Problem | Cause | Fix |
+|---|---|---|
+| All buttons type the last label | Closure trap in the loop | `lambda v=label: press(v)` |
+| `5+3` produces `error` | Used `=` immediately after typing — empty solution | Validate before evaluating |
+| Division gives integer | Used `//` or `eval` quirks | `truediv` from `operator` |
+| Decimal point appears twice | No check on `.` | Reject `.` if last operator-separated segment already has one |
+| Keyboard does nothing | Focus is on a button | `gui.focus_set()` or bind on the entry widget |
 
-Provides a reset function to clear both the current expression and the display.
+## Variations to Try
 
-## Features
+### 1. Backspace button
+A `←` button that does `solution = solution[:-1]`.
 
-- **Standard Calculator Layout**: Traditional button arrangement
-- **Basic Arithmetic Operations**: Addition, subtraction, multiplication, division
-- **Decimal Number Support**: Includes decimal point for floating-point calculations
-- **Real-Time Display**: Shows current expression as it's being built
-- **Error Handling**: Displays "error" for invalid expressions
-- **Clear Function**: Reset calculator to initial state
-- **Responsive Interface**: Immediate visual feedback for button presses
+### 2. Scientific mode
+Add buttons for `sin`, `cos`, `tan`, `log`, `sqrt`, `pi`, `e`. Use `math` and route through the safe evaluator with a custom allow-list of function nodes.
 
-## Next Steps
+### 3. Memory keys
+`M+`, `M-`, `MR`, `MC` — store a single number in `self.memory`.
+
+### 4. Parentheses
+Add `(` and `)` buttons; the AST evaluator handles them automatically via standard precedence.
+
+### 5. History panel
+A `Listbox` on the right that records each evaluated expression. Double-click an entry to re-load it into the display.
+
+### 6. Themes
+A "Dark" toggle that switches `bg` and `fg` on every widget. Store the palette in a dict and apply it via a loop.
+
+### 7. ANS variable
+A button (or shortcut) that inserts the last result into the current expression.
+
+### 8. Unit conversions
+Add inches→cm, lbs→kg, etc. (See [Temperature Converter](./tempconv) for the pattern.)
+
+### 9. Plotting
+A `Plot` button that pipes the current expression into matplotlib over a range of x values — a tiny graphing calculator.
 
-### Enhancements
-- Add advanced mathematical functions (sin, cos, tan, log)
-- Implement memory functions (M+, M-, MR, MC)
-- Add keyboard input support
-- Create calculation history feature
-- Implement parentheses for complex expressions
-- Add percentage calculations
-- Include square root and power functions
-- Implement better error messages
-
-### Learning Extensions
-- Study mathematical expression parsing
-- Explore custom number formatting
-- Learn about calculator algorithms
-- Practice with advanced GUI layouts
-- Understand operator precedence rules
-- Explore scientific calculator features
+### 10. CustomTkinter port
+Replace `tkinter` with `customtkinter` for modern rounded buttons and a true dark mode.
+
+## Architectural Notes
+
+A real calculator separates four concerns:
+1. **Tokenizer** — turns `"3+4*2"` into a list of tokens.
+2. **Parser** — turns tokens into a tree honoring precedence.
+3. **Evaluator** — walks the tree producing a number.
+4. **UI** — buttons, display, keys.
+
+Step 1+2 is what `ast.parse(expr, mode="eval")` does for you for free. The AST evaluator above is the smallest possible step 3. The UI is everything we built with Tkinter.
+
+## Real-World Applications
+- Embedded developer tools (a calculator panel inside a larger app).
+- Educational software for arithmetic / algebra.
+- Field calculators in surveying, engineering, finance apps.
+- Touch-screen kiosks for retail (use bigger buttons, no keyboard).
 
 ## Educational Value
+- **Tkinter grid layout** — rows, columns, spans.
+- **Event-driven UI** — every button is a callback.
+- **Closures and the loop-variable trap** — a Python-wide gotcha you should know.
+- **Why `eval` is dangerous** — and a real alternative.
+- **State management** — globals vs. instance attributes.
 
-This project teaches:
-- **GUI Development**: Creating interactive interfaces with buttons and displays
-- **Event Handling**: Managing user interactions and button clicks
-- **State Management**: Maintaining application state across user actions
-- **String Manipulation**: Building and processing mathematical expressions
-- **Error Handling**: Managing invalid input and calculation errors
-- **Grid Layout System**: Organizing GUI components in structured layouts
-- **Lambda Functions**: Using anonymous functions for button commands
-- **Expression Evaluation**: Understanding how calculators process mathematical expressions
-
-Perfect for understanding GUI application development, user interface design, and mathematical computation in programming.
+## Next Steps
+- Replace `eval()` with the **safe AST evaluator** above. (Do this even if no untrusted user can type.)
+- Add **keyboard bindings**.
+- Refactor into a **class**.
+- Add **history** and an **ANS** button.
+- Add **scientific functions** (`sin`, `cos`, `sqrt`).
+- Port the UI to **CustomTkinter** or **PyQt** when you outgrow Tkinter's defaults.
+- See [Simple Calculator](./simplecalculator) for the CLI version with the same math under the hood.
+
+## Conclusion
+You built a real GUI calculator, learned the most-cited Python closure gotcha, and replaced a dangerous one-liner (`eval`) with a safe equivalent. The patterns — `StringVar` for live binding, grid layout, lambda-with-default for loop callbacks — show up in every Tkinter app from here forward. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/calculatorgui.py). Find more GUI projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/currencyconverter.mdx b/src/content/docs/projects/Beginners/currencyconverter.mdx
index 419a420e..2bfbd7b0 100644
--- a/src/content/docs/projects/Beginners/currencyconverter.mdx
+++ b/src/content/docs/projects/Beginners/currencyconverter.mdx
@@ -1,6 +1,6 @@
 ---
 title: Currency Converter
-description: This is a currency converter made in python. It converts the currency from one country to another. 
+description: Build a Python currency converter that scrapes live rates and exchanges between 20+ currencies. Learn requests, BeautifulSoup, API alternatives, caching, error handling, and how to grow it into a real tool.
 sidebar: 
     order: 9
 hero:
@@ -13,34 +13,36 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Currency Converter is a simple python project that converts the currency from one country to another. This a command-line project that is very easy to use and understand. This project is a very simple project that makes a user-friendly interface. This project is very helpful for beginners who want to learn to code in python. This project is very easy to operate and understood by the users. You can access 20 different currencies in this project. You can convert any currency to any currency. 
+A currency converter is the smallest "real" web-aware project you can build. The original version in this tutorial scrapes a public rates calculator with `requests` + `BeautifulSoup`. That works, but scraping is brittle: a single layout change on the site breaks everything. So we will start with the scraper, then refactor to use a **proper JSON API** (no key required), then add caching, batch conversion, and a CLI mode.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Request module
-- BeautifulSoup module
+You will leave comfortable with:
+- HTTP requests with `requests`.
+- HTML parsing with BeautifulSoup — and why a JSON API is better when one exists.
+- Caching responses so you do not re-hit the network for the same query.
+- Robust error handling for offline / 4xx / 5xx scenarios.
+- Building a multi-mode tool (interactive, CLI flags, library).
 
-## Before you Start
-Before starting making this project, you must have python installed on your computer. If you don’t have python installed you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don’t have any code editor or IDE installed you can download Visual Studio Code from [here](https://code.visualstudio.com/download). You must have the request module and BeautifulSoup module installed on your computer. If you don’t have these modules installed you can install them by using the following commands in your terminal. 
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- Internet connection.
+- `pip` available.
 
-```cmd title="command" showLineNumbers{1} {1-2}
-C:\Users\Your Name>pip install requests
-C:\Users\Your Name>pip install beautifulsoup4
+## Install Dependencies
+```cmd title="install"
+pip install requests beautifulsoup4
 ```
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `CurrencyConverter`.
-2. Open the folder in your code editor or IDE.
-3. Create a file named `currencyconverter.py`.
-4. Copy the code given code and paste it in your `currencyconverter.py` file.
+## Part 1 — The Scraper Version
 
-## Write the Code
-1. Copy and paste the following code in your `currencyconverter.py` file.
+### Getting started
+1. Create folder `CurrencyConverter`.
+2. Inside, create `currencyconverter.py`.
+
+### Write the code
 <FileCode file="projects/beginners/currencyconverter.py" lang="python" title="Currency Converter" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `CurrencyConverter`.
+
+### Run it
 ```cmd title="command" showLineNumbers{1} {1}
 C:\Users\Your Name\CurrencyConverter> python currencyconverter.py
 Currency Converter
@@ -48,105 +50,231 @@ Currency Converter
       List of Currencies:
         1. USD - US Dollar
         2. EUR - Euro
-        3. GBP - British Pound
-        4. INR - Indian Rupee
-        5. AUD - Australian Dollar
-        6. CAD - Canadian Dollar
-        7. SGD - Singapore Dollar
-        8. CHF - Swiss Franc
-        9. MYR - Malaysian Ringgit
-        10. JPY - Japanese Yen
-        11. CNY - Chinese Yuan Renminbi
-        12. NZD - New Zealand Dollar
-        13. THB - Thai Baht
-        14. HUF - Hungarian Forint
-        15. AED - Emirati Dirham
-        16. HKD - Hong Kong Dollar
-        17. MXN - Mexican Peso
-        18. ZAR - South African Rand
-        19. PHP - Philippine Peso
-        20. SEK - Swedish Krona
-
-        Don't Enter the Number. Enter the currency code.
+        ...
 
 From Currency: USD
 To Currency: INR
 Amount: 100
 100 USD = 8,309.928657 INR
 ```
-4. You can see the output in the terminal.
 
-## Explanation
-1. First, we have imported the required modules. We have imported the `requests` module and `BeautifulSoup` module. We have imported the `requests` module to request the URL and the `BeautifulSoup` module to parse the HTML.
-```python title="currencyconverter.py" showLineNumbers{1} {1-2}
+## Step-by-Step Explanation
+
+### 1. Imports
+```python title="currencyconverter.py"
 import requests
 from bs4 import BeautifulSoup
 ```
+- `requests` fetches the page.
+- `BeautifulSoup` parses the returned HTML.
 
-2. Then we have created a variable named `url` and assigned the URL to it. We have used `%s` to add the variables in the URL.
-```python title="currencyconverter.py" showLineNumbers{1} {1}
+### 2. Build the URL
+```python title="currencyconverter.py"
 url = "https://www.x-rates.com/calculator/?from=%s&to=%s&amount=%s"
 ```
+`%s` placeholders get filled by the printf-style `%` operator on the next call. F-strings are nicer:
+```python title="fstring.py"
+url = f"https://www.x-rates.com/calculator/?from={src}&to={dst}&amount={amt}"
+```
 
-3. Then we have printed the list of currencies. We have used the `print()` function to print the list of currencies.
-```python title="currencyconverter.py" showLineNumbers{1} {1-40}
-print("Currency Converter")
-print('''
-      List of Currencies:
-        1. USD - US Dollar
-        2. EUR - Euro
-        3. GBP - British Pound
-        4. INR - Indian Rupee
-        5. AUD - Australian Dollar
-        6. CAD - Canadian Dollar
-        7. SGD - Singapore Dollar
-        8. CHF - Swiss Franc
-        9. MYR - Malaysian Ringgit
-        10. JPY - Japanese Yen
-        11. CNY - Chinese Yuan Renminbi
-        12. NZD - New Zealand Dollar
-        13. THB - Thai Baht
-        14. HUF - Hungarian Forint
-        15. AED - Emirati Dirham
-        16. HKD - Hong Kong Dollar
-        17. MXN - Mexican Peso
-        18. ZAR - South African Rand
-        19. PHP - Philippine Peso
-        20. SEK - Swedish Krona
-        
-        Don't Enter the Number. Enter the currency code.
-    ''')
-```
-
-4. Then we have used the `input()` function to get the user input. We have used the `upper()` function to convert the user input to uppercase. We have used the `input()` function to get the user input. We have used the `upper()` function to convert the user input to uppercase.
-```python title="currencyconverter.py" showLineNumbers{1} {1-3}
-from_currency = input("From Currency: ").upper()
-to_currency = input("To Currency: ").upper()
-amount = input("Amount: ")
-```
-
-5. Then we have requested the URL. We have used the `get()` function to request the URL. We have used the `find()` function to find the converted amount. We have used the `text` attribute to get the text from the HTML. We have used the `find()` function to find the converted amount. We have used the `text` attribute to get the text from the HTML.
-```python title="currencyconverter.py" showLineNumbers{1} {1-3}
-response = requests.get(url % (from_currency, to_currency, amount))
+### 3. Collect input
+```python title="currencyconverter.py"
+from_currency = input("From Currency: ").upper().strip()
+to_currency   = input("To Currency: ").upper().strip()
+amount        = input("Amount: ").strip()
+```
+`.upper()` normalizes case; `.strip()` removes accidental whitespace.
+
+### 4. Fetch and parse
+```python title="currencyconverter.py"
+response = requests.get(url % (from_currency, to_currency, amount), timeout=10)
 soup = BeautifulSoup(response.text, "html.parser")
-converted_amount = soup.find("span", class_="ccOutputRslt").text
+result = soup.find("span", class_="ccOutputRslt").text
+print(f"{amount} {from_currency} = {result}")
 ```
+- `timeout=10` prevents the program freezing if the site hangs.
+- `soup.find("span", class_="ccOutputRslt")` locates the result span by its CSS class.
+- `.text` extracts the rendered text content.
+
+## Why Scraping Is Fragile
+
+The selector `class_="ccOutputRslt"` is what breaks first. The instant the site rewrites that markup, your script returns `AttributeError: 'NoneType' object has no attribute 'text'`. Symptoms:
+- Result is `None` even though the page loads in a browser.
+- HTTP 200 but no matching element.
+- Layout shifts to a `<div>` or different class.
+
+**Lesson:** prefer a proper JSON API whenever one exists.
 
-6. Then we have printed the converted amount. We have used the `print()` function to print the converted amount.
-```python title="currencyconverter.py" showLineNumbers{1} {1}
-print(f'{amount} {from_currency} = {converted_amount}')
+## Part 2 — The API Version (Recommended)
+
+Use **exchangerate.host** — free, no key, JSON, stable interface.
+
+```python title="api_version.py"
+import requests
+
+API = "https://api.exchangerate.host/latest"
+
+def convert(amount: float, src: str, dst: str) -> float:
+    r = requests.get(API, params={"base": src, "symbols": dst}, timeout=10)
+    r.raise_for_status()
+    rate = r.json()["rates"][dst]
+    return amount * rate
+
+print(f"{convert(100, 'USD', 'INR'):.2f} INR")
 ```
+- One call, structured response, no HTML parsing.
+- `r.raise_for_status()` raises an exception on 4xx/5xx.
+- `r.json()` decodes the body into a Python dict.
 
-## Next Steps
-Congratulations! 🎉 You have successfully created a Currency Converter in Python. 
+JSON looks like:
+```json title="response.json"
+{ "base": "USD", "rates": { "INR": 83.10 } }
+```
+
+The same site supports historical rates (`/2024-01-15`) and time series (`/timeseries?...`).
+
+## Add Caching
+
+Hitting the network every time is slow and wasteful — exchange rates do not change every second. Cache by source/target/date:
+
+```python title="cache.py"
+from functools import lru_cache
+from datetime import date
+
+@lru_cache(maxsize=128)
+def rate(src: str, dst: str, day: date) -> float:
+    r = requests.get(f"{API}/{day.isoformat()}",
+                     params={"base": src, "symbols": dst}, timeout=10)
+    r.raise_for_status()
+    return r.json()["rates"][dst]
 
-There are many ways to improve this program. Here are some ideas:
-- Add more currencies.
-- Add a GUI to this program.
-- Add a database to this program.
-- Add a history feature to this program.
-- Add a feature to this program to convert the currency of a country to all the other currencies.
-- Add a feature to this program to convert the currency of all the countries to the currency of a country.
+def convert(amount, src, dst):
+    return amount * rate(src.upper(), dst.upper(), date.today())
+```
+`@lru_cache` memoizes results — same arguments → no second network call.
+
+For long-running scripts that survive restarts, write a JSON file:
+```python title="disk_cache.py"
+import json, time, pathlib
+CACHE = pathlib.Path("rates_cache.json")
+TTL = 60 * 60                                  # 1 hour
+def get_rate(src, dst):
+    data = json.loads(CACHE.read_text()) if CACHE.exists() else {}
+    key = f"{src}_{dst}"
+    if key in data and time.time() - data[key]["ts"] < TTL:
+        return data[key]["rate"]
+    rate = fetch_live(src, dst)
+    data[key] = {"rate": rate, "ts": time.time()}
+    CACHE.write_text(json.dumps(data))
+    return rate
+```
+
+## Robust Error Handling
+
+A real tool handles every failure path with a friendly message:
+```python title="errors.py"
+import requests
+try:
+    rate = fetch_rate("USD", "XYZ")
+except requests.ConnectionError:
+    print("No internet connection.")
+except requests.Timeout:
+    print("Request timed out — try again later.")
+except requests.HTTPError as e:
+    print(f"Server returned {e.response.status_code}.")
+except KeyError:
+    print("Unknown currency code.")
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `AttributeError: NoneType` | Scraper selector outdated | Switch to JSON API |
+| `JSONDecodeError` | Body was HTML, not JSON | Confirm endpoint URL; print `r.text` to debug |
+| Same rate cached forever | No TTL | Add expiry to disk cache |
+| Hangs on slow network | No `timeout` | Pass `timeout=10` to every `requests.get` |
+| `100,000 USD` rejected | Comma in number | Strip non-digit characters before `float()` |
+
+## Variations to Try
+
+### 1. CLI mode with `argparse`
+```bash title="cli"
+python currencyconverter.py 100 --from USD --to INR
+```
+```python title="cli.py"
+import argparse
+p = argparse.ArgumentParser()
+p.add_argument("amount", type=float)
+p.add_argument("--from", dest="src", required=True)
+p.add_argument("--to",   dest="dst", required=True)
+args = p.parse_args()
+print(convert(args.amount, args.src, args.dst))
+```
+
+### 2. Batch convert
+Convert one amount into many currencies at once:
+```python title="batch.py"
+TARGETS = ["EUR", "GBP", "INR", "JPY", "CAD"]
+r = requests.get(API, params={"base": "USD", "symbols": ",".join(TARGETS)}).json()
+for code, rate in r["rates"].items():
+    print(f"100 USD = {100 * rate:.2f} {code}")
+```
+
+### 3. GUI version
+See [Currency Exchange Rate Calculator GUI](./currencyexchnageratecalculator) for a Tkinter version with dropdowns.
+
+### 4. Historical chart
+Pull `/timeseries` data and plot with `matplotlib`:
+```python title="chart.py"
+import matplotlib.pyplot as plt
+data = requests.get("https://api.exchangerate.host/timeseries",
+                    params={"start_date":"2025-01-01","end_date":"2025-01-31",
+                            "base":"USD","symbols":"INR"}).json()["rates"]
+dates = sorted(data.keys())
+rates = [data[d]["INR"] for d in dates]
+plt.plot(dates, rates); plt.xticks(rotation=45); plt.tight_layout(); plt.show()
+```
+
+### 5. Crypto support
+Use **CoinGecko's** free API for BTC, ETH, etc.
+
+### 6. Web dashboard
+Wrap with Flask (see [Basic Web Server](./basicwebserver)). Form on a page; POST returns the conversion.
+
+### 7. Live ticker
+Print the rate every 60 seconds; highlight changes with color.
+
+### 8. Telegram bot
+Use `python-telegram-bot` so a chat command `100 USD INR` returns the result.
+
+## Real-World Applications
+- Travel apps that show prices in your home currency.
+- E-commerce checkout flows for international customers.
+- Finance dashboards that consolidate P&L in a base currency.
+- Cryptocurrency portfolio trackers.
+- Anything where users type money and need a quick second opinion.
+
+## Best Practices Demonstrated
+- **API over scraping** when a stable API exists.
+- **Always set a timeout** on network calls.
+- **Cache by key + TTL** to be a polite client.
+- **Catch network errors** specifically — `ConnectionError`, `Timeout`, `HTTPError` mean different things.
+- **Validate currency codes** before sending — fail fast on typos.
+
+## Educational Value
+- HTTP fundamentals and JSON parsing.
+- Web scraping pitfalls and when to avoid it.
+- Caching strategies and TTL design.
+- Building a multi-mode tool (interactive + CLI).
+- Defensive coding around the network.
+
+## Next Steps
+- Build the **API version** above and retire the scraper.
+- Add **disk caching** with TTL.
+- Wrap with **argparse** for scriptable use.
+- Plot **30-day history** with matplotlib.
+- Combine with [Currency Exchange Rate Calculator GUI](./currencyexchnageratecalculator) for a desktop frontend.
 
 ## Conclusion
-In this project, we have learned how to create a Currency Converter in Python. We have learned how to use the `requests` module and `BeautifulSoup` module. We have learned how to request the URL and parse the HTML. We have learned how to get the user input and convert it to uppercase. We have learned how to print the converted amount. We have learned how to create a Currency Converter in Python. To find more projects like this you can visit Python Central Hub.
\ No newline at end of file
+You started by scraping a website, hit the brittleness wall, and rebuilt the same feature against a proper JSON API with caching and clean error handling. The "API over scraping" instinct is one of the most valuable habits you can form. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/currencyconverter.py). Explore more on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/currencyexchnageratecalculator.mdx b/src/content/docs/projects/Beginners/currencyexchnageratecalculator.mdx
index 182d45d6..56423dec 100644
--- a/src/content/docs/projects/Beginners/currencyexchnageratecalculator.mdx
+++ b/src/content/docs/projects/Beginners/currencyexchnageratecalculator.mdx
@@ -1,6 +1,6 @@
 ---
 title: Currency Exchange Rate Calculator GUI
-description: Build a GUI application for real-time currency conversion using live exchange rate APIs
+description: Build a Tkinter currency converter that fetches live exchange rates from a public API. Learn GUI widgets, HTTP requests, JSON parsing, error handling, and how to grow a simple converter into a personal finance tool.
 sidebar:
   order: 52
 hero:
@@ -14,83 +14,258 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Create a professional currency exchange rate calculator with a graphical interface that fetches real-time exchange rates from an API and converts between multiple currencies. This project demonstrates GUI development, API integration, and financial data processing.
+A currency converter is the perfect "small but real" beginner project: it has a user interface, talks to a live API on the internet, parses structured data (JSON), and produces output the user actually cares about. In this tutorial you will build a desktop GUI in Tkinter that lets the user type an amount, pick a source currency and a target currency from dropdowns, and click **Convert** to see today's rate applied.
 
-## Prerequisites
+You will learn:
+- How to build a Tkinter window with labels, entries, dropdowns, and buttons.
+- How to call an HTTP API with `requests` and parse JSON responses.
+- How to handle network errors gracefully so the app never crashes mid-conversation.
+- How to organize widget-driven code with callbacks.
+- How to extend the converter into a tool you might actually use.
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of Tkinter for GUI development
-- Familiarity with HTTP requests and APIs
-- Understanding of JSON data processing
+## Prerequisites
 
-## Getting Started
+- Python 3.6 or above.
+- A text editor or IDE.
+- An internet connection.
+- Comfort installing packages with `pip`.
+- Familiarity with functions and conditionals.
 
-### Create a new project
-1. Create a new project folder and name it `currencyExchangeCalculator`.
-2. Create a new file and name it `currencyexchnageratecalculator.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `currencyexchnageratecalculator.py` file.
+## Install Dependencies
 
-### Install required dependencies
-1. Install requests library for API calls:
-```bash
+```bash title="install"
 pip install requests
 ```
+- **`tkinter`** ships with Python — no install needed.
+- **`requests`** is the de-facto library for HTTP in Python.
+
+## Pick an Exchange-Rate API
+
+There are several free public APIs you can use without an API key:
+
+| API | URL pattern | Notes |
+|---|---|---|
+| **exchangerate-api** | `https://open.er-api.com/v6/latest/USD` | Free tier, no key, daily updates. |
+| **frankfurter.app** | `https://api.frankfurter.app/latest?from=USD&to=EUR` | Open-source, ECB rates. |
+| **Fixer.io** | `https://api.exchangerate.host/latest?base=USD` | Larger currency list. |
+
+For this tutorial we will use **exchangerate.host** (no key required). The response is JSON like:
+```json
+{
+  "base": "USD",
+  "rates": { "EUR": 0.92, "GBP": 0.79, "INR": 83.10, ... }
+}
+```
+
+> 💡 Any API can change its terms. If yours stops working, swap the URL — the parsing code is similar.
+
+## Getting Started
+
+### Create the project
+1. Create a folder named `currency-exchange-calculator`.
+2. Inside it, create `currencyexchnageratecalculator.py`.
+3. Open the folder in your editor.
 
 ### Write the code
-1. Add the following code to your `currencyexchnageratecalculator.py` file.
 <FileCode file="projects/beginners/currencyexchnageratecalculator.py" lang="python" title="Currency Exchange Rate Calculator GUI" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\currencyExchangeCalculator> python currencyexchnageratecalculator.py
-[Currency Exchange Calculator GUI Opens]
-- Enter amount to convert
-- Select base currency from dropdown
-- Select target currency from dropdown
-- Click "Convert" to get real-time exchange rate
-- Result displayed in popup message
-Example: 100 USD to EUR = 85.23 EUR
+
+### Run it
+```bash title="run"
+python currencyexchnageratecalculator.py
+```
+A window appears. Enter `100`, pick USD → EUR, click **Convert**, and a popup shows the result.
+
+## Step-by-Step Explanation
+
+### 1. Import what you need
+```python title="currencyexchnageratecalculator.py"
+import tkinter as tk
+from tkinter import ttk, messagebox
+import requests
+```
+- `tkinter` for the window, `ttk` for *themed* widgets (dropdowns look prettier than the legacy `OptionMenu`), and `messagebox` for the result popup.
+- `requests` for the HTTP call.
+
+### 2. Create the main window
+```python title="currencyexchnageratecalculator.py"
+win = tk.Tk()
+win.title("Currency Exchange Calculator")
+win.geometry("400x300")
+```
+`Tk()` is the root window. `geometry("WxH")` sets a fixed size.
+
+### 3. Build the widgets
+```python title="currencyexchnageratecalculator.py"
+tk.Label(win, text="Amount:").pack()
+amount_entry = tk.Entry(win)
+amount_entry.pack()
+
+CURRENCIES = ["USD", "EUR", "GBP", "INR", "JPY", "AUD", "CAD", "CNY"]
+tk.Label(win, text="From:").pack()
+from_currency = ttk.Combobox(win, values=CURRENCIES)
+from_currency.set("USD")
+from_currency.pack()
+
+tk.Label(win, text="To:").pack()
+to_currency = ttk.Combobox(win, values=CURRENCIES)
+to_currency.set("EUR")
+to_currency.pack()
+```
+- `Entry` is a one-line text input.
+- `Combobox` is a dropdown the user can also type into; `.set(value)` chooses an initial selection.
+- `.pack()` is the simplest of Tkinter's layout managers — it stacks widgets top-to-bottom.
+
+### 4. The conversion callback
+```python title="currencyexchnageratecalculator.py"
+def exchange():
+    try:
+        amount = float(amount_entry.get())
+    except ValueError:
+        messagebox.showerror("Invalid input", "Amount must be a number.")
+        return
+
+    src = from_currency.get()
+    dst = to_currency.get()
+
+    try:
+        url = f"https://api.exchangerate.host/latest?base={src}&symbols={dst}"
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        rates = response.json()["rates"]
+        rate = rates[dst]
+    except requests.exceptions.RequestException as e:
+        messagebox.showerror("Network error", str(e))
+        return
+    except KeyError:
+        messagebox.showerror("Bad response", f"No rate for {dst} found.")
+        return
+
+    converted = amount * rate
+    messagebox.showinfo(
+        "Result",
+        f"{amount:.2f} {src} = {converted:.2f} {dst}  (rate {rate:.4f})",
+    )
 ```
+Three layers of error handling:
+1. **`ValueError`** if the amount field is not a number.
+2. **`RequestException`** if the network is down, the server is unreachable, the request times out, or the API returns 4xx/5xx (because of `raise_for_status()`).
+3. **`KeyError`** if the API responds successfully but does not include the requested currency.
 
-3. **Use the Application**
-   - Enter the amount to convert
-   - Select source currency from dropdown
-   - Select target currency from dropdown
-   - Click "Convert" to get real-time exchange rate
+The `timeout=10` keeps the GUI responsive even if the API hangs.
 
+### 5. Wire the button and start the loop
+```python title="currencyexchnageratecalculator.py"
+tk.Button(win, text="Convert", command=exchange).pack(pady=10)
+win.mainloop()
 ```
+- `command=exchange` registers the callback.
+- `win.mainloop()` enters Tkinter's event loop, the program lives here until the window closes.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| GUI freezes after click | Long HTTP call running on the main thread | Use `threading.Thread` for the request, update the UI via `win.after` |
+| `requests.exceptions.ConnectionError` | No internet, or API down | Show a friendly message; consider caching the last rate |
+| `KeyError: 'EUR'` | Misspelled currency code in the dropdown | Validate codes against a known list |
+| Result shows `9.999999999999999` | Floating-point display | Format with `:.2f` |
+| Multiple Convert clicks stack popups | User clicks while one is showing | Use `messagebox.showinfo`, which is modal — but consider disabling the button until the call completes |
+
+## Variations to Try
+
+### 1. Real-time updates
+Use `win.after(60_000, refresh_rates)` to re-fetch every minute and show a live "last updated" label.
+
+### 2. Live result label instead of popup
+Replace the `messagebox` with a `Label` in the window that updates after each conversion. Better UX.
+
+### 3. Conversion history
+Append each result to a `Listbox`:
+```python title="history.py"
+history_box.insert("end", f"{amount} {src} → {converted:.2f} {dst}")
+```
+Bonus: write the history to `history.csv` on exit.
+
+### 4. Two-way swap button
+A "⇄" button that swaps the From and To selections.
+
+### 5. Charts
+Use **matplotlib** to plot a 30-day history. The API typically supports `/timeseries`:
+```python title="chart.py"
+url = "https://api.exchangerate.host/timeseries?start_date=2025-01-01&end_date=2025-01-31&base=USD&symbols=EUR"
+```
+
+### 6. Larger currency list
+Pull the full list from the API itself:
+```python title="full_list.py"
+all_currencies = requests.get("https://api.exchangerate.host/symbols").json()["symbols"]
+```
+
+### 7. Crypto support
+Use **CoinGecko's** free API (no key required) for BTC, ETH, etc.
+
+### 8. Calculator-style entry
+Replace the single Entry with a numeric keypad of buttons. Helpful for touch-screen kiosks.
+
+### 9. Convert to/from multiple currencies at once
+Instead of a single "To", show a table of values across ten major currencies.
+
+### 10. Offline mode
+Cache the last successful response to `last_rates.json`. If the network fails, fall back to the cache and label the result as "stale".
+
+## Concept Spotlight: HTTP Errors
+
+`requests` returns a `Response` object that *does not* raise on 4xx/5xx by default. Explicit checking is essential:
+
+```python title="errors.py"
+r = requests.get(url, timeout=5)
+print(r.status_code)        # 200 = OK, 404 = not found, 500 = server error
+r.raise_for_status()        # raises HTTPError for 4xx/5xx
+data = r.json()             # raises JSONDecodeError if body isn't JSON
+```
+
+The error categories you should plan for:
+- **Connection errors** — DNS failure, no internet, server unreachable.
+- **Timeout errors** — server took too long.
+- **HTTP errors** — server replied but with an error status.
+- **Decode errors** — server replied with non-JSON content.
+
+`requests.exceptions.RequestException` is the *base* of all of these, so a single `except RequestException` catches everything network-related.
+
+## Best Practices Demonstrated
+
+- **Validate input before making a network call.** Cheap checks first, expensive operations second.
+- **Always set a timeout.** Default is no limit — a hanging server can freeze your GUI forever.
+- **Use `raise_for_status()`** to turn HTTP errors into exceptions you can `except`.
+- **Show errors in the UI, not the terminal.** End users do not read terminals.
+- **Format numbers explicitly.** `:.2f` for currency always.
+
+## Real-World Applications
+
+- Travel apps that show prices in the user's home currency.
+- E-commerce checkout flows handling multiple currencies.
+- Internal finance dashboards showing daily P&L in a base currency.
+- Crypto portfolio trackers.
+- Currency-aware invoice generators.
+
+## Educational Value
 
-## Explanation
-
-1. The `import tkinter as tk` statement imports the Tkinter library for creating the GUI.
-2. The `import requests` statement imports the requests library for making API calls.
-3. The `win = Tk()` creates the main window for the application.
-4. The `win.geometry("700x400")` sets the window size to 700x400 pixels.
-5. The `def exchange():` function handles the currency conversion logic.
-6. The `requests.get()` function fetches real-time exchange rates from the API.
-7. The `response.json()` parses the JSON response from the API.
-8. The `rates[converted_currency]` extracts the specific exchange rate.
-9. The `messagebox.showinfo()` displays the conversion result in a popup.
-10. The `ttk.Combobox()` creates dropdown menus for currency selection.
-11. The `Button()` widget creates the convert button with the exchange function.
-12. The currency list includes major world currencies for conversion.
+This project teaches:
+- **GUI fundamentals** — windows, widgets, layouts, callbacks, event loops.
+- **HTTP and JSON** — talking to the wider web from Python.
+- **Robust error handling** — three layers, friendly messages.
+- **Separation of concerns** — UI building vs. business logic vs. networking.
+- **Working with currency** — formatting, decimal precision.
 
 ## Next Steps
 
-Congratulations! You have successfully created a Currency Exchange Rate Calculator GUI in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add more currencies to the selection list
-- Implement historical exchange rate charts
-- Add currency conversion history tracking
-- Create offline mode with cached rates
-- Implement currency rate alerts and notifications
-- Add calculator-style number input
-- Create currency trend analysis features
-- Add favorite currency pairs
-- Implement rate comparison between different providers
+- Replace `messagebox` popups with an inline result label that updates immediately.
+- Add a "favorites" panel for currency pairs the user converts often.
+- Plug into a **historical-rates** endpoint and draw a chart with matplotlib.
+- Wrap the conversion logic in a class for easier testing.
+- Port the GUI to **CustomTkinter** for a modern look.
+- Add a **command-line mode**: `python currencyexchnageratecalculator.py --amount 100 --from USD --to EUR`.
 
 ## Conclusion
 
-In this project, you learned how to create a Currency Exchange Rate Calculator GUI in Python using Tkinter and API integration. You also learned about working with real-time data, JSON processing, and creating professional GUI applications. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/currencyexchnageratecalculator.py)
+You built a real desktop application that talks to a live web service — the same architecture every modern app uses, just smaller. You handled bad input, network failures, and missing data without crashing the GUI. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/currencyexchnageratecalculator.py). Explore more GUI and API projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/dicerolling.mdx b/src/content/docs/projects/Beginners/dicerolling.mdx
index 9a18bf04..637bfe58 100644
--- a/src/content/docs/projects/Beginners/dicerolling.mdx
+++ b/src/content/docs/projects/Beginners/dicerolling.mdx
@@ -1,6 +1,6 @@
 ---
 title: Dice Rolling Simulator
-description: A simple dice rolling simulator using Python. You can use this to play board games or just for fun. This is a command line program. It helps you to learn about random module in Python.
+description: Build a command-line dice roller in Python. Learn the random module, function design, while loops, input handling, and how to extend a tiny program into a full-featured tabletop helper.
 sidebar: 
     order: 8
 hero:
@@ -13,24 +13,45 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Dice Rolling Simulator is a simple Python program that rolls a dice and gives you a random number between 1 and 6. You can use this to play board games or just for fun. This is a command line program. It helps you to learn about random module in Python. In this article, we will learn how to create a dice rolling simulator using Python. It uses Random module to generate random numbers. Also, we will learn how to create a function in Python. 
+A Dice Rolling Simulator is one of the most rewarding beginner projects because it does something *visibly random* — every run produces a different result. Under the hood it teaches you four core skills you will use forever: importing modules from the standard library, defining your own functions, looping until a condition changes, and parsing user input.
+
+In this project we build a dice roller that:
+- Rolls a virtual six-sided die and prints the result.
+- Lets the user roll again or quit at any time.
+- Is easy to extend to support multiple dice, dice of any number of sides (d4, d20, d100), and even Dungeons & Dragons style notation like `3d6+2`.
+
+By the end you will understand `random.randint`, function definitions with `def`, the `while True` loop, and how a tiny script grows into a real tool.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
+- Python 3.6 or above ([download](https://www.python.org/downloads/)).
+- A code editor or IDE (VS Code, PyCharm, Sublime, etc.).
+- Completed the [Hello World project](./helloworld) — or general comfort running a `.py` file.
+- No external libraries are needed; `random` ships with Python.
+
+## Concepts You Will Use
+
+Before writing code, here is what each piece does conceptually:
+
+- **`random` module** — Python's standard library tool for pseudo-random numbers. It can pick integers, floats, items from a list, shuffle a sequence, and more.
+- **`random.randint(a, b)`** — returns a random integer `N` such that `a ≤ N ≤ b`. Both endpoints are *inclusive*, which is exactly what you want for dice (1 and 6 are valid rolls).
+- **`def`** — defines a function. Functions let you give a *name* to a block of code so you can reuse it.
+- **`while True:`** — an infinite loop. You leave it with a `break` statement when the user wants to quit.
+- **`input(prompt)`** — pauses the program, prints a prompt, waits for the user to press Enter, returns whatever they typed as a string.
+- **`.lower()`** — converts a string to lowercase, so `"Y"` and `"y"` both behave the same way.
 
 ## Getting Started
-#### Create a Project
+
+### Create the project
 1. Create a folder named `dice-rolling-simulator`.
-2. Open the folder in your code editor or IDE.
-3. Create a file named `dicerolling.py`.
-4. Copy the code given and paste it in the `dicerolling.py` file.
+2. Open it in your code editor.
+3. Inside, create a file called `dicerolling.py`.
 
-## Write the Code
-1. Copy and paste the following code in the `dicerolling.py` file.
+### Write the code
+Add the following to `dicerolling.py`:
 <FileCode file="projects/beginners/dicerolling.py" lang="python" title="Dice Rolling" />
-2. Save the file.
-3. Open the terminal and navigate to the project folder `dice-rolling-simulator`.
+
+Save the file. Open the integrated terminal and run:
+
 ```cmd title="command" showLineNumbers{1} {1}
 C:\Users\username\PythonCentralHub\projects\beginners\dice-rolling-simulator> python dicerolling.py
 You rolled 4
@@ -41,44 +62,151 @@ You rolled 5
 Do you want to roll again? (y/n): n
 Thanks for playing!
 ```
-4. You can see the output in the terminal.
 
-## Explanation
-1. First, we need to import the `random` module. We will use this module to generate random numbers.
+Run it several times. Notice the numbers change each run — that is the random module doing its job.
+
+## Step-by-Step Explanation
+
+### 1. Import the random module
 ```python title="dicerolling.py" showLineNumbers{1} {1}
 import random
 ```
+`import` makes another module's code available in yours. After this line, anything inside the `random` module is reachable as `random.something`. The module itself lives somewhere in your Python installation; you do not need to know where.
 
-2. Next, we need to create a function to roll the dice. We will use the `randint()` function from the `random` module to generate a random number between 1 and 6.
+### 2. Define the roll function
 ```python title="dicerolling.py" showLineNumbers{1} {1-2}
 def roll():
     return random.randint(1, 6)
 ```
+- `def roll():` declares a new function named `roll` that takes no arguments.
+- The indented body is the function's code.
+- `return` hands a value back to whoever called the function. Here we return a fresh random integer between 1 and 6.
+- Calling `roll()` now feels like rolling a real die — you do not care *how* it gets a number, only that you get one.
 
-3. Now, we need to call the `roll()` function to roll the dice. We will use a `while` loop to roll the dice until the user wants to stop.
-```python title="dicerolling.py" showLineNumbers{1} {1-7}
+Why bother with a function for one line? Because:
+- It documents intent: reading `roll()` is clearer than reading `random.randint(1, 6)` everywhere.
+- It is easy to change: if you later want a 20-sided die, you change one line.
+
+### 3. Loop until the user stops
+```python title="dicerolling.py" showLineNumbers{1} {1-5}
 while True:
     print(f"You rolled {roll()}")
     play_again = input("Do you want to roll again? (y/n): ")
     if play_again.lower() != "y":
         break
 ```
+- `while True:` starts a loop that never ends *on its own* — you exit it manually.
+- `print(f"You rolled {roll()}")` is an **f-string**. The `f` prefix lets you embed expressions inside `{ }`. `roll()` is called, the result is converted to text, and inserted into the message.
+- `input(...)` shows the prompt and waits.
+- `play_again.lower() != "y"` is the check: if the user did not type `y` (in any case), `break` immediately exits the loop.
 
-4. Finally, we need to print a message to the user.
-```python title="dicerolling.py" showLineNumbers{1} {1-9}
+### 4. Say goodbye
+```python title="dicerolling.py" showLineNumbers{1} {1}
 print("Thanks for playing!")
 ```
+This line runs once, after the loop ends.
 
-## Next Steps
-Congratulations! You have successfully created a dice rolling simulator using Python.
+## Pseudo-Random, Not Truly Random
+
+`random.randint` does not produce truly random numbers — computers cannot. It produces **pseudo-random** numbers from a deterministic algorithm seeded by the current time. For dice this is more than fine. For cryptography, banking, or anything security-sensitive, use the `secrets` module instead.
+
+You can demonstrate the determinism yourself:
+```python title="seeded.py"
+import random
+random.seed(42)
+print(random.randint(1, 6))   # Always prints the same number for seed 42
+```
+Seeding is useful for *reproducible* test runs.
+
+## Common Mistakes
+
+| Problem | Fix |
+|---|---|
+| `NameError: name 'random' is not defined` | You forgot `import random` at the top. |
+| The program crashes after one roll | You used `if play_again == "y": break` — backwards logic. Use `!= "y"` to break. |
+| The program never quits no matter what you type | `"Y"` is not equal to `"y"`. Use `.lower()` to normalize. |
+| `random.randint(1, 6.0)` errors with `TypeError` | `randint` needs integers — use `random.uniform(1, 6)` for floats. |
 
-There are many ways to improve this program. Here are some ideas:
-- Add a feature to roll multiple dice at once.
-- Add a feature to roll a dice with more than 6 sides.
-- Add a feature to roll a dice with different colors.
-- Add a feature to roll a dice with different shapes.
-- Create a GUI version of this program.
-- Create a web version of this program.
+## Variations to Try
+
+### 1. Roll multiple dice at once
+```python title="multi_dice.py"
+def roll_dice(count):
+    return [random.randint(1, 6) for _ in range(count)]
+
+results = roll_dice(3)
+print(f"You rolled: {results}  total: {sum(results)}")
+```
+A **list comprehension** generates `count` rolls in one line, and `sum()` totals them.
+
+### 2. Dice with any number of sides
+```python title="any_sides.py"
+def roll(sides=6):
+    return random.randint(1, sides)
+
+print(roll())      # six-sided
+print(roll(20))    # twenty-sided
+print(roll(100))   # percentile die
+```
+`sides=6` is a **default argument** — if the caller does not specify a value, Python uses 6.
+
+### 3. Parse D&D-style notation (`3d6+2`)
+```python title="dnd_notation.py"
+import re, random
+
+def parse_and_roll(notation):
+    match = re.fullmatch(r"(\d+)d(\d+)([+-]\d+)?", notation.replace(" ", ""))
+    if not match:
+        raise ValueError(f"Bad notation: {notation}")
+    count, sides, modifier = match.groups()
+    rolls = [random.randint(1, int(sides)) for _ in range(int(count))]
+    total = sum(rolls) + (int(modifier) if modifier else 0)
+    return rolls, total
+
+print(parse_and_roll("3d6+2"))
+# Example output: ([4, 2, 5], 13)
+```
+This shows how a simple project naturally grows into using **regular expressions** and **error handling**.
+
+### 4. ASCII-art dice faces
+```python title="ascii_dice.py"
+FACES = {
+    1: ("┌─────────┐", "│         │", "│    ●    │", "│         │", "└─────────┘"),
+    2: ("┌─────────┐", "│  ●      │", "│         │", "│      ●  │", "└─────────┘"),
+    # …add 3, 4, 5, 6
+}
+
+for line in FACES[roll()]:
+    print(line)
+```
+A dictionary maps each face to its ASCII art.
+
+### 5. Statistics over many rolls
+```python title="stats.py"
+from collections import Counter
+rolls = [random.randint(1, 6) for _ in range(10_000)]
+print(Counter(rolls))
+```
+You should see roughly 1666 occurrences of each face — proof the distribution is uniform.
+
+## Real-World Applications
+- **Tabletop games** — replace lost dice, run probability experiments before a game session.
+- **Monte Carlo simulations** — repeated random sampling is the core of physics and finance simulations.
+- **Game development** — every roguelike, RPG, or loot system relies on randomness.
+- **Teaching probability** — let students *see* the law of large numbers by rolling 100,000 dice.
+
+## Features
+- Uses Python's standard library only — no installs.
+- Demonstrates functions, loops, conditionals, and input parsing in under 15 lines.
+- Easy to extend: any-sided dice, multiple dice, parsed notation, GUI.
+
+## Next Steps
+You now have a working dice simulator. Push yourself with one of these challenges:
+- Add an **average** that updates after each roll.
+- Add a **history** of the last 10 rolls.
+- Wrap it in a **Tkinter GUI** with a big "Roll!" button.
+- Build a **web version** with Flask that lets a remote player roll dice in a shared room.
+- Turn it into a **probability tool** that calculates the chance of beating a target with N dice of S sides.
 
 ## Conclusion
-In this article, we have learned how to create a dice rolling simulator using Python. We have used the `random` module to generate random numbers. Also, we have learned how to create a function in Python. To find more projects like this, you can check out the Python Central Hub.
\ No newline at end of file
+In this project you used Python's `random` module to simulate dice, learned to encapsulate behavior in a function, looped until the user wanted to stop, and saw several directions to extend the program. The dice roller is small but it touches every fundamental you need for bigger projects. Find more beginner projects on Python Central Hub and keep that momentum going.
diff --git a/src/content/docs/projects/Beginners/emailsender.mdx b/src/content/docs/projects/Beginners/emailsender.mdx
index 724c0744..71e379c3 100644
--- a/src/content/docs/projects/Beginners/emailsender.mdx
+++ b/src/content/docs/projects/Beginners/emailsender.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Email Sender
-description: A Python GUI application for sending emails using Gmail SMTP with Tkinter interface, featuring email validation and secure authentication.
+description: Build a Python email sender with Tkinter and smtplib. Learn SMTP, Gmail app passwords, HTML emails, attachments, multiple recipients, secrets management, and how to grow it into a real mailer.
 sidebar: 
     order: 20
 hero:
@@ -13,225 +13,267 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Basic Email Sender is a Python application with a graphical user interface that allows users to send emails through Gmail's SMTP server. The application features input validation, secure authentication using app passwords, and a clean Tkinter-based interface. This project demonstrates GUI development, email protocols, regular expressions for validation, and secure communication practices. It's an excellent project for learning about email automation and desktop application development.
+Email is older than the web and still drives most automated notifications, password resets, marketing flows, and alerts. In this project you will build a Tkinter GUI that sends real email via Gmail SMTP. We start with a plain-text version, then upgrade to HTML bodies, multiple recipients, file attachments, retries, secrets management, and end with a sketch of a transactional-email service. Along the way you learn why Gmail wants **app passwords** instead of your real one, and how `smtplib` lays out an email under the hood.
+
+You will learn:
+- The shape of SMTP — connect, STARTTLS, login, MAIL FROM, RCPT TO, DATA, QUIT.
+- Why Gmail blocks plain-password logins and how App Passwords fix it.
+- How `email.mime.*` builds multipart messages.
+- How to validate input safely and handle network errors.
+- How to manage secrets so credentials never sit in source control.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- tkinter module (usually comes pre-installed)
-- smtplib module (built-in)
-- Gmail account with 2-Step Verification enabled
+- Python 3.6 or above.
+- A text editor or IDE.
+- A Gmail account with **2-Step Verification** enabled.
+- An **App Password** generated at <https://myaccount.google.com/apppasswords>.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Set Up Gmail App Password
+1. Visit <https://myaccount.google.com/security>.
+2. Enable **2-Step Verification** (required to access App Passwords).
+3. Go to **App passwords** → generate a new one named "Python Mailer".
+4. Copy the 16-character code. This replaces your normal password in scripts.
+5. **Treat it like a password.** Anyone with this string can send mail as you.
 
-### Gmail App Password Setup
-To use Gmail with this application, you need to set up an App Password:
+## Getting Started
 
-1. Go to your Google Account settings
-2. Click on Security
-3. Under "Signing in to Google," select 2-Step Verification
-4. At the bottom of the page, select App passwords
-5. Enter a name that helps you remember where you'll use the app password
-6. Select Generate
-7. Copy the 16-character code that generates on your device
-8. Use this generated password in the application (not your regular Gmail password)
+### Create the project
+1. Create folder `email-sender`.
+2. Inside, create `emailsender.py`.
 
-For more information: [Google Support - App Passwords](https://support.google.com/mail/?p=InvalidSecondFactor)
+### Write the code
+<FileCode file="projects/beginners/emailsender.py" lang="python" title="Email Sender" />
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `email-sender`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `emailsender.py`.
-4. Copy the given code and paste it in your `emailsender.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `emailsender.py` file.
-<FileCode file="projects/beginners/emailsender.py" lang="python" title="Basic Email Sender" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `email-sender`.
-```cmd title="command" showLineNumbers{1} {1-5}
+### Run it
+```cmd title="command"
 C:\Users\Your Name\email-sender> python emailsender.py
-# A GUI window will open with:
-# - Email input field
-# - Receiver's email field  
-# - Password field
-# - Message field
-# - Send Email button
-# - Exit button
+# GUI opens with sender / receiver / password / message fields and Send button
+```
+
+## SMTP in Seven Lines
+
+The core is shorter than the GUI around it:
+```python title="core.py"
+import smtplib
+
+with smtplib.SMTP("smtp.gmail.com", 587) as server:
+    server.starttls()
+    server.login("you@gmail.com", "16-char-app-password")
+    server.sendmail("you@gmail.com", "friend@example.com",
+                    "Subject: Hello\n\nThis is the body.")
 ```
+Step by step:
+1. **Connect** to Gmail's SMTP on port 587.
+2. **`STARTTLS`** upgrades the connection to encrypted.
+3. **Login** with your address + App Password.
+4. **`sendmail`** delivers the message.
+5. The `with` block automatically issues `QUIT` on exit.
+
+The `Subject:` header is required for Gmail to show a subject line; everything before the blank line is headers, everything after is the body.
 
-## Explanation
+## Step-by-Step (GUI Version)
 
-### Code Breakdown
-1. **Import required modules.**
-```python title="emailsender.py" showLineNumbers{1} {1-5}
-import tkinter as tk # pip install tk
-from tkinter import *
-import smtplib # pip install smtplib
+### 1. Imports
+```python title="emailsender.py"
+import tkinter as tk
 from tkinter import messagebox
-import re
+import smtplib, re
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
 ```
 
-2. **Define the email sending function with validation.**
-```python title="emailsender.py" showLineNumbers{1} {1-10}
-def sendEmail():
+### 2. Build the form
+```python title="emailsender.py"
+root = tk.Tk()
+root.title("Email Sender")
+root.geometry("520x420")
+
+sender_entry   = tk.Entry(root, width=50); sender_entry.pack(pady=5)
+receiver_entry = tk.Entry(root, width=50); receiver_entry.pack(pady=5)
+password_entry = tk.Entry(root, width=50, show="*"); password_entry.pack(pady=5)
+subject_entry  = tk.Entry(root, width=50); subject_entry.pack(pady=5)
+message_text   = tk.Text(root, width=50, height=10); message_text.pack(pady=5)
+```
+`show="*"` masks the password as the user types — a small but expected UX detail.
+
+### 3. Validate and send
+```python title="emailsender.py"
+EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+def send():
+    sender = sender_entry.get().strip()
+    receivers = [r.strip() for r in receiver_entry.get().split(",") if r.strip()]
+    pwd = password_entry.get()
+    subject = subject_entry.get().strip() or "(no subject)"
+    body = message_text.get("1.0", "end").strip()
+
+    if not EMAIL_RE.match(sender):
+        return messagebox.showerror("Error", "Invalid sender address.")
+    for r in receivers:
+        if not EMAIL_RE.match(r):
+            return messagebox.showerror("Error", f"Invalid recipient: {r}")
+    if not pwd or not body:
+        return messagebox.showerror("Error", "Password and body required.")
+
+    msg = MIMEMultipart()
+    msg["From"] = sender
+    msg["To"] = ", ".join(receivers)
+    msg["Subject"] = subject
+    msg.attach(MIMEText(body, "plain"))
+
     try:
-        sender = email.get()
-        rec = receiver.get()
-        pas = password.get()
-        msg = message.get()
-        
-        # Validating the Email
-        if(sender == "Enter Your Email" or rec == "Enter Receiver's Email" or pas == "Enter Your Password" or msg == "Enter Your Message"):
-            messagebox.showerror("Error", "Please Enter All The Fields")
-            return
+        with smtplib.SMTP("smtp.gmail.com", 587) as server:
+            server.starttls()
+            server.login(sender, pwd)
+            server.send_message(msg, from_addr=sender, to_addrs=receivers)
+    except smtplib.SMTPAuthenticationError:
+        return messagebox.showerror("Auth failed", "Wrong password? Use an App Password.")
+    except smtplib.SMTPException as e:
+        return messagebox.showerror("SMTP error", str(e))
+    except Exception as e:
+        return messagebox.showerror("Network error", str(e))
+    messagebox.showinfo("Sent", "Email sent successfully.")
 ```
+`MIMEMultipart` is the foundation for attachments and HTML; even for plain text it costs almost nothing to use.
+
+## HTML Emails
 
-3. **Email validation using regular expressions.**
-```python title="emailsender.py" showLineNumbers{1} {1-8}
-        # Validate Email Using Regular Expression
-        email_regex = re.compile(r"[^@]+@[^@]+\.[^@]+")
-        if not email_regex.match(sender):
-            messagebox.showerror("Error", "Invalid Email")
-            return
-        
-        if not email_regex.match(rec):
-            messagebox.showerror("Error", "Invalid Receiver's Email")
-            return
+To send rich content:
+```python title="html.py"
+html = """<h2>Hello!</h2><p>This is <b>HTML</b> email.</p>
+<p><a href="https://example.com">Click here</a></p>"""
+msg = MIMEMultipart("alternative")
+msg.attach(MIMEText("Plain-text fallback", "plain"))
+msg.attach(MIMEText(html, "html"))
 ```
+The `"alternative"` multipart type tells clients to show **one** of the parts — modern clients use HTML, plain-text-only clients fall back to the text part.
 
-4. **SMTP connection and email sending.**
-```python title="emailsender.py" showLineNumbers{1} {1-6}
-        server = smtplib.SMTP('smtp.gmail.com', 587)
-        server.starttls()
-        server.login(sender, pas)
-        server.sendmail(sender, rec, msg)
-        server.quit()
-        messagebox.showinfo("Success", "Email Sent Successfully")
+## Attachments
+
+```python title="attach.py"
+from email.mime.base import MIMEBase
+from email import encoders
+
+def attach_file(msg, path):
+    with open(path, "rb") as f:
+        part = MIMEBase("application", "octet-stream")
+        part.set_payload(f.read())
+    encoders.encode_base64(part)
+    part.add_header("Content-Disposition",
+                    f'attachment; filename="{os.path.basename(path)}"')
+    msg.attach(part)
+
+attach_file(msg, "report.pdf")
+attach_file(msg, "screenshot.png")
 ```
+Files become base64-encoded MIME parts. Most providers cap attachments around 25 MB.
 
-5. **GUI setup and layout.**
-```python title="emailsender.py" showLineNumbers{1} {1-15}
-root = tk.Tk()
-root.title("Email Sender")
-root.geometry("700x700")
-root.config(background="white")
-
-label_file_explorer = Label(root, text = "Email Sender using Tkinter", width = 100, height = 3, fg = "gray", bg = "whitesmoke")
-
-email = Entry(root, width = 50)
-email.insert(0, "Enter Your Email")
-receiver = Entry(root, width = 50)
-receiver.insert(0, "Enter Receiver's Email")
-password = Entry(root, width = 50)
-password.insert(0, "Enter Your Password")
-message = Entry(root, width = 50)
-message.insert(0, "Enter Your Message")
+## Secret Management
+
+Hard-coding the App Password into `emailsender.py` is the most common security mistake in this project. Better:
+
+```python title="env.py"
+import os
+sender = os.environ["EMAIL_USER"]
+password = os.environ["EMAIL_PASSWORD"]
+```
+Set them once:
+```bash title="bash"
+export EMAIL_USER=you@gmail.com
+export EMAIL_PASSWORD=xxxx-xxxx-xxxx-xxxx
 ```
+Or use **`python-dotenv`** to read from a `.env` file (add `.env` to `.gitignore`).
 
-## Features
-- **Graphical User Interface:** Clean and intuitive Tkinter-based design
-- **Email Validation:** Regular expression-based email format checking
-- **Secure Authentication:** Uses Gmail's SMTP with TLS encryption
-- **Error Handling:** Comprehensive error messages and exception handling
-- **Input Validation:** Ensures all fields are filled before sending
-- **Success Feedback:** Confirms successful email transmission
-- **Field Reset:** Automatically clears and resets fields after sending
-
-## How to Use
-1. **Launch the Application:** Run the Python script to open the email sender window
-2. **Enter Sender Email:** Input your Gmail address
-3. **Enter Receiver Email:** Specify the recipient's email address
-4. **Enter App Password:** Use the generated Gmail app password (not your regular password)
-5. **Write Message:** Type your email message
-6. **Send Email:** Click the "Send Email" button
-7. **Check Status:** Success or error messages will appear in popup dialogs
-
-## Security Features
-- **TLS Encryption:** Uses secure TLS connection for email transmission
-- **App Password Support:** Works with Gmail's 2-Step Verification
-- **Input Validation:** Prevents injection attacks through validation
-- **Error Handling:** Secure error management without exposing sensitive data
-
-## SMTP Configuration
-The application uses Gmail's SMTP server configuration:
-- **Server:** smtp.gmail.com
-- **Port:** 587 (TLS)
-- **Authentication:** Required
-- **Encryption:** STARTTLS
-
-## Common Issues and Solutions
-
-### Authentication Error
-- **Problem:** "Authentication failed"
-- **Solution:** Use App Password instead of regular Gmail password
-- **Steps:** Enable 2-Step Verification and generate App Password
-
-### Connection Error
-- **Problem:** "Connection refused"
-- **Solution:** Check internet connection and firewall settings
-- **Alternative:** Try different network or VPN
-
-### Invalid Email Format
-- **Problem:** "Invalid email" error
-- **Solution:** Ensure email follows standard format (user@domain.com)
+For desktop apps, the OS keychain via **`keyring`** is the right answer:
+```python title="keychain.py"
+import keyring
+keyring.set_password("PCH-mailer", sender, app_password)     # one-time setup
+pwd = keyring.get_password("PCH-mailer", sender)             # later
+```
 
-## Next Steps
-You can enhance this project by:
-- Adding HTML email support for rich formatting
-- Implementing email templates and signatures
-- Adding file attachment functionality
-- Creating an email address book
-- Adding scheduling for delayed email sending
-- Implementing multiple email provider support (Yahoo, Outlook)
-- Adding email encryption and digital signatures
-- Creating batch email sending capabilities
-- Adding email tracking and read receipts
-- Implementing spam filtering and validation
-
-## Enhanced Version Ideas
-```python title="emailsender.py" showLineNumbers{1}
-def enhanced_email_sender():
-    # Features to add:
-    # - HTML email composer
-    # - File attachment browser
-    # - Email templates
-    # - Address book integration
-    # - Email scheduling
-    # - Multiple recipient support
-    pass
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| "Username and Password not accepted" | Used real Gmail password | Generate an App Password |
+| Mail goes to Spam | No proper `From`, no DKIM, plain-text body | Use SendGrid/Mailgun for production |
+| `ConnectionRefusedError` | Wrong port | 587 for STARTTLS, 465 for `smtplib.SMTP_SSL` |
+| Subject missing | Did not add the header | Set `msg["Subject"]` |
+| Emoji breaks subject | Default encoding mismatch | Use `MIMEText(body, _charset="utf-8")` |
+| Multiple recipients only first receives | Passed string, not list | Split on commas and pass a list |
+
+## Variations to Try
+
+### 1. CC and BCC
+```python title="cc_bcc.py"
+msg["Cc"] = "manager@example.com"
+all_recipients = receivers + ["manager@example.com", "hidden@example.com"]
+server.send_message(msg, from_addr=sender, to_addrs=all_recipients)
+```
+BCC is just a recipient with no header — pass to `send_message`'s `to_addrs` but don't add a header.
+
+### 2. Personalized mail merge
+```python title="merge.py"
+for row in csv.DictReader(open("contacts.csv")):
+    body = template.format(**row)
+    send(row["email"], body)
 ```
+Read CSV → format template per row → send.
 
-## Email Security Best Practices
-- **Use App Passwords:** Never use your main Gmail password
-- **Enable 2FA:** Always use two-factor authentication
-- **Validate Inputs:** Sanitize all user inputs
-- **Secure Storage:** Don't store passwords in plain text
-- **Rate Limiting:** Implement sending limits to prevent spam
+### 3. Other providers
+- **Outlook**: `smtp-mail.outlook.com:587`.
+- **Yahoo**: `smtp.mail.yahoo.com:587` (also app passwords).
+- **iCloud**: `smtp.mail.me.com:587`.
 
-## Educational Value
-This project teaches:
-- **GUI Development:** Creating desktop applications with Tkinter
-- **Email Protocols:** Understanding SMTP and email transmission
-- **Regular Expressions:** Pattern matching for validation
-- **Error Handling:** Managing exceptions and user feedback
-- **Security Practices:** Implementing secure authentication
+### 4. Inline images
+Use `MIMEImage` and reference with `<img src="cid:logo">`. The `cid:` matches a `Content-ID` header on the image part.
+
+### 5. Scheduled send
+Combine with [Simple Reminder App](./simplereminderapp) — fire `send()` at a specific time.
+
+### 6. Bounce handling
+Read the SMTP response. `server.send_message` returns a dict of failed recipients.
+
+### 7. Production-grade with SendGrid / Mailgun
+For more than a few emails per day, switch to a transactional-email provider. They handle deliverability, SPF/DKIM signing, bounce processing, and analytics.
+
+### 8. CLI mode with `argparse`
+```bash title="cli"
+mailer.py --to friend@example.com --subject Hi --body "Hello!" --attach report.pdf
+```
+
+### 9. Email server preview with MailHog
+For development: run `mailhog` locally, point SMTP at `localhost:1025`, see every sent email in a web UI. Never accidentally email real users from a dev script.
+
+### 10. Sign and encrypt
+**S/MIME** or **PGP/MIME** for confidential payloads. Heavy but standardized.
+
+## Anti-Spam / Anti-Abuse Notes
+- Gmail caps your sending to ~500 messages/day for personal accounts.
+- Sending more than a handful per minute will get you throttled.
+- Marketing emails *must* include an unsubscribe link by law (CAN-SPAM, GDPR).
+- Always include a real `From` name and reply-to that goes somewhere real.
 
 ## Real-World Applications
-- **Automated Notifications:** Send system alerts and notifications
-- **Marketing Campaigns:** Automated email marketing tools
-- **Personal Automation:** Send regular updates or reminders
-- **Business Communication:** Internal communication tools
-- **Integration Scripts:** Add email functionality to other applications
-
-## Troubleshooting Tips
-- **Test with Known Emails:** Start with your own email addresses
-- **Check Spam Folders:** Sent emails might end up in spam
-- **Verify Credentials:** Double-check app password generation
-- **Network Issues:** Ensure stable internet connection
-- **Gmail Limits:** Be aware of Gmail's sending rate limits
+- **Account flows** — signup confirmations, password resets, 2FA codes.
+- **System alerts** — Cron job failed, disk filling up.
+- **Marketing** — newsletters, drip campaigns (use a provider for these).
+- **Reports** — daily summaries from a script.
+- **Internal tooling** — meeting reminders, expense approvals.
+
+## Educational Value
+- **SMTP protocol** — the wire format underlying every "send email" library.
+- **MIME** — multipart messages, content types, transfer encodings.
+- **Secrets management** — environment variables, keyring, dotenv.
+- **Validation** — regex for email syntax (note: regex *cannot* fully validate; SMTP verification is the only certain way).
+- **Provider quirks** — every SMTP server has its own gotchas; abstract the differences.
+
+## Next Steps
+- Move credentials into **environment variables** or **`keyring`**.
+- Add **attachments** and **HTML body**.
+- Wire up a **CSV-driven mail merge**.
+- Replace `smtplib` with **`yagmail`** for a cleaner Gmail-specific API.
+- Move to **SendGrid** or **Mailgun** for transactional use.
 
 ## Conclusion
-In this project, we learned how to create a Basic Email Sender using Python's Tkinter for the GUI and smtplib for email functionality. We explored secure email authentication, input validation using regular expressions, and error handling techniques. This project demonstrates the integration of multiple Python libraries to create a practical desktop application. The skills learned here are applicable to many automation and communication scenarios in software development. To find more projects like this, you can visit Python Central Hub.
+You built a real email-sending tool from scratch, learned why Gmail demands App Passwords, and saw how MIME multiparts model attachments and HTML bodies. The same patterns scale all the way up to corporate email pipelines — `smtplib` is the standard tool from beginner scripts to systems sending millions of messages a day. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/emailsender.py). Find more automation projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/fibonaccisequence.mdx b/src/content/docs/projects/Beginners/fibonaccisequence.mdx
index 88453771..dac4a80c 100644
--- a/src/content/docs/projects/Beginners/fibonaccisequence.mdx
+++ b/src/content/docs/projects/Beginners/fibonaccisequence.mdx
@@ -1,6 +1,6 @@
 ---
 title: Fibonacci Sequence Generator
-description: A Python program that generates the Fibonacci sequence up to a specified number of terms, demonstrating mathematical sequences and iterative programming concepts.
+description: Generate the Fibonacci sequence in Python — iterative, recursive, memoized, generator, closed-form, and matrix-exponentiation versions. Learn algorithmic trade-offs and the golden ratio.
 sidebar: 
     order: 45
 hero:
@@ -13,33 +13,34 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Fibonacci Sequence Generator is a Python program that generates and displays the famous Fibonacci sequence up to a user-specified number of terms. The Fibonacci sequence is a mathematical series where each number is the sum of the two preceding numbers, starting with 0 and 1. This project demonstrates fundamental programming concepts including loops, variable management, user input handling, and mathematical computations. It's an excellent introduction to sequence generation and iterative algorithms.
+The Fibonacci sequence — `0, 1, 1, 2, 3, 5, 8, 13, 21, …` — is the most famous integer sequence in mathematics. Each number is the sum of the previous two. It is a perfect teaching tool: trivial to define, deeply connected to the golden ratio, and a textbook example for comparing algorithm strategies. In this project you will implement six different ways to generate it — iterative, recursive, memoized recursive, generator-based, closed-form using the golden ratio, and matrix exponentiation — and learn when each one is appropriate.
+
+You will leave understanding:
+- The definition: `F(0) = 0`, `F(1) = 1`, `F(n) = F(n-1) + F(n-2)`.
+- Why naïve recursion is exponentially slow.
+- How memoization turns it into linear time.
+- The golden-ratio closed form (and its precision limits).
+- Matrix exponentiation in `O(log n)` for huge `n`.
+- Why iterative is almost always the right answer in practice.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Basic understanding of mathematical sequences
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with loops, recursion (helpful), and functions.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-Note: This project uses only built-in Python features, so no additional installations are required.
+### Create the project
+1. Create folder `fibonacci-generator`.
+2. Inside, create `fibonacci_sequence_generator.py`.
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `fibonacci-generator`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `fibonacci_sequence_generator.py`.
-4. Copy the given code and paste it in your `fibonacci_sequence_generator.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `fibonacci_sequence_generator.py` file.
-<FileCode file="projects/beginners/fibonacci_sequence_generator.py" lang="python" title="Fibonacci Sequence Generator" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `fibonacci-generator`.
-```cmd title="command" showLineNumbers{1} {1-20}
+### Write the code
+<FileCode file="projects/beginners/fibonacci_sequence_generator.py" lang="python" title="Fibonacci Generator" />
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\fibonacci-generator> python fibonacci_sequence_generator.py
-How many numbers that generates?: 10
+How many numbers? 10
 Fibonacci sequence:
 0
 1
@@ -51,165 +52,240 @@ Fibonacci sequence:
 13
 21
 34
+```
 
-C:\Users\Your Name\fibonacci-generator> python fibonacci_sequence_generator.py
-How many numbers that generates?: 1
-Fibonacci sequence upto 1 :
-0
+## Step-by-Step Explanation
+
+### 1. Iterative version (the default)
+```python title="iterative.py"
+def fib_iter(n: int) -> list[int]:
+    if n <= 0: return []
+    if n == 1: return [0]
+    out = [0, 1]
+    while len(out) < n:
+        out.append(out[-1] + out[-2])
+    return out
+```
+- O(n) time, O(n) space (storing the list).
+- Single allocation, no recursion overhead.
+- This is what 95 % of real-world Fibonacci code looks like.
+
+### 2. Bare minimum — just compute F(n)
+```python title="fib_n.py"
+def fib(n: int) -> int:
+    a, b = 0, 1
+    for _ in range(n):
+        a, b = b, a + b
+    return a
 ```
+- O(n) time, O(1) space.
+- The tuple assignment `a, b = b, a + b` is the Pythonic way to swap-and-update.
 
-## Explanation
+## Other Implementations
 
-### Understanding the Fibonacci Sequence
-The Fibonacci sequence is defined as:
-- F(0) = 0
-- F(1) = 1
-- F(n) = F(n-1) + F(n-2) for n > 1
+### 3. Naïve recursive (DO NOT use for large n)
+```python title="naive_rec.py"
+def fib_rec(n: int) -> int:
+    if n < 2: return n
+    return fib_rec(n - 1) + fib_rec(n - 2)
+```
+- O(2^n) time. `fib_rec(35)` takes seconds; `fib_rec(50)` takes minutes.
+- The same subproblems are recomputed billions of times.
+- Educational only — never ship this.
 
-This produces the sequence: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, ...
+### 4. Memoized recursive
+```python title="memo_rec.py"
+from functools import lru_cache
 
-### Code Breakdown
-1. **Get user input for the number of terms.**
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1} {1}
-n = int(input("How many numbers that generates?: "))
+@lru_cache(maxsize=None)
+def fib_memo(n: int) -> int:
+    if n < 2: return n
+    return fib_memo(n - 1) + fib_memo(n - 2)
 ```
+- O(n) time, O(n) space.
+- One decorator turns exponential into linear.
+- Best example you will ever see of `@lru_cache`'s value.
 
-2. **Initialize the first two Fibonacci numbers and a counter.**
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1} {1-3}
-n1 = 0
-n2 = 1
-count = 0
+### 5. Generator-based (memory-efficient)
+```python title="gen.py"
+def fib_gen():
+    a, b = 0, 1
+    while True:
+        yield a
+        a, b = b, a + b
+
+# usage
+import itertools
+print(list(itertools.islice(fib_gen(), 10)))
 ```
+- O(1) extra memory regardless of how far you go.
+- Lazy — computes only as many as you ask for.
+- Great when you want "the first N matching some condition" without precomputing.
+
+### 6. Closed form (Binet's formula)
+```python title="binet.py"
+import math
+PHI = (1 + math.sqrt(5)) / 2
+PSI = (1 - math.sqrt(5)) / 2
 
-3. **Handle edge cases for invalid input.**
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1} {1-5}
-if n <= 0:
-    print("Please enter a positive integer")
-elif n == 1:
-    print("Fibonacci sequence upto", n, ":")
-    print(n1)
+def fib_binet(n: int) -> int:
+    return round((PHI**n - PSI**n) / math.sqrt(5))
 ```
+- O(1) time (constant-time arithmetic).
+- Loses precision past `n ≈ 70` because of floating-point rounding.
+- Beautiful mathematically; not what you ship.
 
-4. **Generate and display the sequence using a while loop.**
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1} {1-8}
-else:
-    print("Fibonacci sequence:")
-    while count < n:
-        print(n1)
-        nth = n1 + n2
-        n1 = n2
-        n2 = nth
-        count += 1
+### 7. Matrix exponentiation (`O(log n)`)
+```python title="matrix.py"
+def fib_matrix(n: int) -> int:
+    def mat_mul(A, B):
+        return [
+            [A[0][0]*B[0][0] + A[0][1]*B[1][0], A[0][0]*B[0][1] + A[0][1]*B[1][1]],
+            [A[1][0]*B[0][0] + A[1][1]*B[1][0], A[1][0]*B[0][1] + A[1][1]*B[1][1]],
+        ]
+    def mat_pow(M, p):
+        result = [[1, 0], [0, 1]]            # identity
+        while p:
+            if p & 1: result = mat_mul(result, M)
+            M = mat_mul(M, M)
+            p >>= 1
+        return result
+    if n == 0: return 0
+    return mat_pow([[1, 1], [1, 0]], n)[0][1]
 ```
+- O(log n) time using fast exponentiation.
+- Uses arbitrary-precision Python ints — no precision loss for huge n.
+- `fib_matrix(1_000_000)` computes in milliseconds.
+
+## Comparing the Approaches
 
-## Algorithm Explanation
+| Method | Time | Space | When to use |
+|---|---|---|---|
+| Iterative | O(n) | O(1) | Default choice |
+| Naïve recursion | O(2^n) | O(n) | Never (teaching only) |
+| Memoized recursion | O(n) | O(n) | Demonstrating DP / cache |
+| Generator | O(n) total | O(1) | Streaming or unknown count |
+| Binet's formula | O(1)* | O(1) | Tiny n, accept FP error |
+| Matrix exponentiation | O(log n) | O(1) | Massive n |
 
-### Step-by-Step Process
-1. **Initialization:** Set the first two numbers (0, 1) and a counter
-2. **Validation:** Check if the input is valid (positive integer)
-3. **Special Cases:** Handle n=1 separately
-4. **Loop Generation:** Use a while loop to calculate and display each term
-5. **Value Updates:** Update the two previous numbers for the next iteration
+*Constant-time only if you treat float ops as O(1). Above n ≈ 70 it returns wrong values.
+
+## Algorithm Walkthrough — Iterative for n = 5
 
-### Variable Tracking Example
-For n=5:
 ```
-Iteration 1: n1=0, n2=1, nth=1, print(0)
-Iteration 2: n1=1, n2=1, nth=2, print(1)
-Iteration 3: n1=1, n2=2, nth=3, print(1)
-Iteration 4: n1=2, n2=3, nth=5, print(2)
-Iteration 5: n1=3, n2=5, nth=8, print(3)
-Result: 0, 1, 1, 2, 3
+init      a=0  b=1
+step 1    yield 0;  a=1, b=1
+step 2    yield 1;  a=1, b=2
+step 3    yield 1;  a=2, b=3
+step 4    yield 2;  a=3, b=5
+step 5    yield 3;  a=5, b=8
+result:   0, 1, 1, 2, 3
 ```
 
-## Features
-- **User Input Validation:** Handles invalid and edge case inputs
-- **Flexible Output:** Generates any number of Fibonacci terms
-- **Clear Display:** Shows each term on a separate line
-- **Mathematical Accuracy:** Correctly implements the Fibonacci formula
-- **Memory Efficient:** Uses only three variables regardless of sequence length
-- **Educational Value:** Demonstrates iterative algorithm design
-
-## Mathematical Properties
-The Fibonacci sequence has many interesting properties:
-- **Golden Ratio:** The ratio of consecutive terms approaches φ ≈ 1.618
-- **Nature Patterns:** Appears in flower petals, pine cones, and spiral shells
-- **Mathematical Applications:** Used in computer algorithms and financial analysis
-
-## Algorithm Complexity
-- **Time Complexity:** O(n) - linear time
-- **Space Complexity:** O(1) - constant space
-- **Efficiency:** Very efficient for generating sequences
-
-## Common Use Cases
-- **Mathematical Education:** Teaching sequence generation
-- **Algorithm Practice:** Understanding iterative solutions
-- **Number Theory:** Exploring mathematical patterns
-- **Programming Interviews:** Common coding question
-- **Scientific Applications:** Modeling natural phenomena
+## Input Validation
 
-## Next Steps
-You can enhance this project by:
-- Adding a recursive implementation for comparison
-- Creating a GUI version using Tkinter
-- Implementing memoization for optimization
-- Adding visualization with graphs or charts
-- Creating different output formats (list, file, etc.)
-- Adding mathematical analysis (ratios, sums, etc.)
-- Implementing nth Fibonacci number calculation
-- Adding error handling for very large numbers
-- Creating performance benchmarks
-- Adding unit tests for validation
-
-## Alternative Implementations
-
-### Recursive Approach
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1}
-def fibonacci_recursive(n):
-    if n <= 1:
-        return n
-    else:
-        return fibonacci_recursive(n-1) + fibonacci_recursive(n-2)
+```python title="validate.py"
+def get_n():
+    while True:
+        raw = input("How many? ")
+        try:
+            n = int(raw)
+            if n < 0:
+                raise ValueError
+            return n
+        except ValueError:
+            print("Enter a non-negative integer.")
 ```
+Reject negative numbers and non-integers up front.
 
-### List-Based Approach
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1}
-def fibonacci_list(n):
-    fib_list = [0, 1]
-    for i in range(2, n):
-        fib_list.append(fib_list[i-1] + fib_list[i-2])
-    return fib_list[:n]
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `RecursionError` | Naïve recursion past ~1000 | Use the iterative version |
+| Hang on n=40 | Naïve recursion's exponential blow-up | Switch to memoized or iterative |
+| Wrong result for n>70 | Floating-point precision in Binet | Use integer-based methods |
+| `IndexError` for n=0 or n=1 | Hard-coded `out[-2]` | Special-case small n |
+| Memory ballooning for huge n | Storing the full list | Use the generator if you only need streaming |
+
+## The Golden Ratio Connection
+
+The ratio of consecutive Fibonacci numbers approaches **φ ≈ 1.61803398875…**, the golden ratio:
+```python title="phi.py"
+for n in [5, 10, 20, 40, 80]:
+    print(n, fib(n+1) / fib(n))
+# 1.6, 1.617..., 1.6180..., 1.61803..., 1.61803398875...
 ```
+This is *why* Binet's formula works — `φ` is a root of `x² = x + 1`, the characteristic equation of the Fibonacci recurrence.
 
-### Generator Approach
-```python title="fibonacci_sequence_generator.py" showLineNumbers{1}
-def fibonacci_generator(n):
-    a, b = 0, 1
-    for _ in range(n):
-        yield a
-        a, b = b, a + b
+## Variations to Try
+
+### 1. Sum of Fibonacci numbers
+```python title="sum.py"
+def fib_sum(n): return sum(fib_iter(n))
+```
+Surprising identity: `F(0) + F(1) + … + F(n) = F(n+2) - 1`.
+
+### 2. Even-only Fibonacci (Project Euler #2)
+```python title="even.py"
+total = 0
+a, b = 0, 1
+while a < 4_000_000:
+    if a % 2 == 0: total += a
+    a, b = b, a + b
+```
+
+### 3. Plot the sequence
+```python title="plot.py"
+import matplotlib.pyplot as plt
+plt.plot(fib_iter(30), "o-"); plt.yscale("log"); plt.show()
 ```
+On a log scale, Fibonacci grows almost linearly — exponential growth made visual.
+
+### 4. Spiral drawing
+Use `turtle` to draw the famous Fibonacci spiral by chaining quarter-circles whose radii follow the sequence.
+
+### 5. nth Fibonacci modulo m (Pisano period)
+For very large n with a modulus, the sequence is periodic — useful in cryptography and contest programming.
+
+### 6. Tribonacci, Lucas, Pell sequences
+Same recurrence pattern, different starting values. Easy variations to implement once you have Fibonacci.
+
+### 7. Find n such that F(n) > 10^k
+Useful interview question — combine with a generator and a counter.
+
+### 8. Performance benchmark
+Time each method for n in `[10, 30, 100, 1000, 100_000]`. Plot results with matplotlib.
 
-## Performance Considerations
-- **Iterative vs Recursive:** Iterative is more efficient
-- **Memory Usage:** Current implementation uses minimal memory
-- **Large Numbers:** Python handles arbitrarily large integers
-- **Optimization:** Memoization can speed up recursive versions
+### 9. Decimal version
+For really, really huge n, Python's int already supports arbitrary precision. Try `len(str(fib(10_000_000)))` — you will get over 2 million digits.
+
+### 10. Web API
+Wrap with Flask: `GET /fib/<n>` returns JSON `{"n": n, "value": fib(n)}`. See [Basic Web Server](./basicwebserver).
+
+## Real-World Connections
+
+The sequence appears in:
+- **Nature** — sunflower seed spirals, pinecone scales, nautilus shells, flower petals.
+- **Markets** — Elliott Wave theory and Fibonacci retracement levels (anecdotal at best).
+- **Algorithms** — Fibonacci heaps (used in Dijkstra/Prim shortest-path).
+- **Number theory** — Zeckendorf's theorem: every positive integer is a unique sum of non-adjacent Fibonacci numbers.
+- **Computer science** — F-heaps, Fibonacci search, golden-ratio-based hashing.
 
 ## Educational Value
-This project teaches:
-- **Loop Control:** While loops and counters
-- **Variable Management:** Tracking multiple values
-- **Mathematical Sequences:** Understanding patterns
-- **Algorithm Design:** Iterative problem solving
-- **Input Validation:** Handling user input properly
-
-## Real-World Applications
-- **Computer Graphics:** Spiral patterns and fractals
-- **Financial Markets:** Elliott wave theory
-- **Architecture:** Golden ratio in design
-- **Biology:** Population growth models
-- **Algorithms:** Dynamic programming examples
+- **Algorithmic thinking** — six different solutions, six different trade-offs.
+- **Recursion vs. iteration** — both kinds of repetition compared head to head.
+- **Memoization (`@lru_cache`)** — one decorator, exponential speed-up.
+- **Generators** — laziness as a tool.
+- **Closed forms and their limits** — math vs. machine.
+- **Fast exponentiation** — divide-and-conquer over a sequence.
+
+## Next Steps
+- Run a **benchmark harness** comparing iterative, memoized, and matrix versions.
+- Implement **Tribonacci** and **Lucas** sequences using the same patterns.
+- Combine with [Reverse a String](./reversestring) to see another "many ways to solve" project.
+- Read about **Pisano periods** for modular Fibonacci.
+- Try **Project Euler problem #2** using your generator.
 
 ## Conclusion
-In this project, we learned how to generate the Fibonacci sequence using an iterative approach in Python. We explored fundamental programming concepts including loops, variable management, and mathematical computation. The Fibonacci sequence serves as an excellent introduction to algorithm design and demonstrates how simple rules can generate complex and beautiful patterns. This project provides a foundation for understanding more advanced mathematical and algorithmic concepts. To find more projects like this, you can visit Python Central Hub.
+Fibonacci is a one-line problem that pays off in spades the deeper you look. You implemented six solutions, learned why exponential recursion is a punishment, and saw how a single `@lru_cache` line rewrites the algorithm class. The same trade-offs recur in real systems — choosing iterative vs. recursive, caching vs. recomputing, fast paths vs. fallbacks. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/fibonacci_sequence_generator.py). Find more algorithm projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/fileexplorer.mdx b/src/content/docs/projects/Beginners/fileexplorer.mdx
index 146d197c..fc38afcc 100644
--- a/src/content/docs/projects/Beginners/fileexplorer.mdx
+++ b/src/content/docs/projects/Beginners/fileexplorer.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic File Explorer
-description: A simple file explorer application built with Python's Tkinter library that allows users to browse, open, and read text files through a graphical interface.
+description: Build a Tkinter file browser in Python that opens, reads, and edits files. Learn file dialogs, text widgets, encoding handling, error recovery, syntax highlighting, and how to grow it into a real editor.
 sidebar: 
     order: 17
 hero:
@@ -13,161 +13,284 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Basic File Explorer is a graphical file browsing application built using Python's Tkinter library. The application provides a simple and intuitive interface for users to navigate their file system, select files, and view the contents of text files. It features a clean GUI with buttons for browsing files, displaying file paths, and showing file contents in a text area. This project is excellent for beginners to learn GUI development, file handling, and event-driven programming in Python.
+A file explorer is one of the most universally useful desktop GUIs you can build. In this project you will build a Python file viewer with Tkinter that lets the user pick any file via the OS file dialog, then displays its contents in a scrollable text area. Then we grow it: editable buffer, save-back, a directory tree, recent-files list, encoding detection, and a syntax-highlighted code view.
+
+You will learn:
+- How `filedialog` integrates with the native OS picker.
+- How to read text safely with the correct encoding.
+- How to wire scrollbars to a `Text` widget.
+- The `grid` vs `pack` decision for layout.
+- How to add real features (editing, saving, a directory tree) one at a time.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- tkinter module (usually comes pre-installed with Python)
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with most Python installs).
+- Comfort with classes (optional but recommended).
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download). 
+On Linux you may need to install Tkinter separately:
+```bash title="install"
+sudo apt-get install python3-tk        # Debian/Ubuntu
+sudo dnf install python3-tkinter       # Fedora
+```
 
-Note: Tkinter usually comes pre-installed with Python. If you encounter import errors, you may need to install it separately:
+## Getting Started
 
-```cmd title="command" showLineNumbers{1} {1}
-# For Ubuntu/Debian
-sudo apt-get install python3-tk
+### Create the project
+1. Create folder `file-explorer`.
+2. Inside, create `fileexplorer.py`.
 
-# For CentOS/RHEL
-sudo yum install tkinter
-```
+### Write the code
+<FileCode file="projects/beginners/fileexplorer.py" lang="python" title="File Explorer" />
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `file-explorer`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `fileexplorer.py`.
-4. Copy the given code and paste it in your `fileexplorer.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `fileexplorer.py` file.
-<FileCode file="projects/beginners/fileexplorer.py" lang="python" title="Basic File Explorer" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `file-explorer`.
-```cmd title="command" showLineNumbers{1} {1-5}
+### Run it
+```cmd title="command"
 C:\Users\Your Name\file-explorer> python fileexplorer.py
-# A GUI window will open with:
-# - "File Explorer using Tkinter" title
-# - "Browse Files" button
-# - "Exit" button
-# - Text area for displaying file contents
-# - Path display area
+# Window opens with:
+#   - Title bar "File Explorer using Tkinter"
+#   - "Browse Files" button
+#   - "Exit" button
+#   - Large text area
+#   - "Path: ..." label at the bottom
 ```
+Click **Browse Files**, pick any text file, and its content appears in the panel.
 
-## Explanation
-1. Import the required modules.
-```python title="fileexplorer.py" showLineNumbers{1} {1-4}
-import tkinter as tk # pip install tk
-from tkinter import *
-from tkinter import filedialog, Text
-```
+## Step-by-Step Explanation
+
+### 1. Imports and root window
+```python title="fileexplorer.py"
+import tkinter as tk
+from tkinter import filedialog, Text, Label, Button, END
 
-2. Create the main window and initialize lists.
-```python title="fileexplorer.py" showLineNumbers{1} {1-3}
 root = tk.Tk()
-apps = []
+root.title("File Explorer")
+root.geometry("700x700")
+root.config(background="white")
 ```
+- `Tk()` creates the main window.
+- `geometry("WxH")` sets size in pixels.
+- Importing names like `Text`, `Label`, `Button` directly is convenient — but only inside small scripts. For larger projects use `tk.Text`, `tk.Label`, etc.
 
-3. Define the file browsing function.
-```python title="fileexplorer.py" showLineNumbers{1} {1-10}
+### 2. The browse callback
+```python title="fileexplorer.py"
 def browseFiles():
-    output.delete('1.0', END)
-    filename = filedialog.askopenfilename(initialdir = "/", title = "Select a File", filetypes = (("Text files","*.txt*"), ("all files", "*.*")))
-    pathh.config(text = "Path: " + filename)
-    tf = open(filename, encoding="utf8")
-    data = tf.read()
+    output.delete("1.0", END)
+    filename = filedialog.askopenfilename(
+        initialdir="/",
+        title="Select a File",
+        filetypes=(("Text files", "*.txt"), ("All files", "*.*")),
+    )
+    if not filename:
+        return                                # user cancelled
+    path_label.config(text=f"Path: {filename}")
+    try:
+        with open(filename, encoding="utf-8") as f:
+            data = f.read()
+    except UnicodeDecodeError:
+        output.insert(END, "[binary or non-UTF-8 file]")
+        return
     output.insert(END, data)
-    tf.close()
 ```
+Three improvements over the naive version:
+- **Cancel-safe.** `askopenfilename` returns `""` when the user closes the dialog; we bail early.
+- **`with open(...)`** closes the file even on exception.
+- **`UnicodeDecodeError` handler.** Lets the program survive binary or weird-encoding files.
 
-4. Configure the main window.
-```python title="fileexplorer.py" showLineNumbers{1} {1-3}
-root.title("File Explorer")
-root.geometry("700x700")
-root.config(background="white")
+### 3. The widgets
+```python title="fileexplorer.py"
+title_label = Label(root, text="File Explorer using Tkinter",
+                    width=100, height=3, fg="gray", bg="whitesmoke")
+browse_button = Button(root, text="Browse Files", command=browseFiles)
+exit_button   = Button(root, text="Exit", command=root.destroy)
+output        = Text(root, wrap="none")
+path_label    = Label(root, text="Path: ", width=100, height=3, fg="gray", bg="whitesmoke")
 ```
+- `Text(root)` is a multi-line text widget; the line/character coordinates work like `"line.char"` (`"1.0"` means line 1, char 0).
+- `wrap="none"` shows long lines with horizontal scrolling rather than wrapping.
 
-5. Create GUI components.
-```python title="fileexplorer.py" showLineNumbers{1} {1-8}
-label_file_explorer = Label(root, text = "File Explorer using Tkinter", width = 100, height = 3, fg = "gray", bg = "whitesmoke")
+### 4. Layout with grid
+```python title="fileexplorer.py"
+title_label.grid(column=1, row=1)
+browse_button.grid(column=1, row=2)
+exit_button.grid(column=1, row=3)
+output.grid(column=1, row=4)
+path_label.grid(column=1, row=5)
 
-button_explore = Button(root, text = "Browse Files", command = browseFiles)
-exit_button = Button(root, text = "Exit", command = root.destroy)
-output = Text(root)
-pathh = Label(root, text = "Path: ", width = 100, height = 3, fg = "gray", bg = "whitesmoke")
+root.mainloop()
 ```
+`grid` arranges widgets in cells. Even with one column this gives a tidy vertical stack.
 
-6. Arrange components using grid layout.
-```python title="fileexplorer.py" showLineNumbers{1} {1-8}
-label_file_explorer.grid(column = 1, row = 1)
-button_explore.grid(column = 1, row = 2)
-exit_button.grid(column = 1, row = 3)
-output.grid(column = 1, row = 4)
-pathh.grid(column = 1, row = 5)
+## Add Scrollbars
 
-root.mainloop()
+A `Text` widget without scrollbars is unusable for big files. Wire one up:
+```python title="scroll.py"
+vsb = tk.Scrollbar(root, orient="vertical", command=output.yview)
+hsb = tk.Scrollbar(root, orient="horizontal", command=output.xview)
+output.configure(yscrollcommand=vsb.set, xscrollcommand=hsb.set)
+vsb.grid(column=2, row=4, sticky="ns")
+hsb.grid(column=1, row=6, sticky="ew")
 ```
+The bidirectional binding — `command=output.yview` plus `yscrollcommand=vsb.set` — connects scrollbar and text so they stay in sync.
 
-## Features
-- **Graphical User Interface:** Clean and intuitive Tkinter-based GUI
-- **File Browsing:** Navigate through the file system using file dialog
-- **File Type Filtering:** Filter files by type (text files, all files)
-- **File Content Display:** View the contents of selected text files
-- **Path Display:** Show the full path of the selected file
-- **UTF-8 Support:** Handle files with various character encodings
-- **Exit Functionality:** Clean application termination
-
-## How to Use
-1. **Launch the Application:** Run the Python script to open the file explorer window
-2. **Browse Files:** Click the "Browse Files" button to open the file selection dialog
-3. **Select a File:** Navigate through directories and select a file to open
-4. **View Contents:** The file's content will be displayed in the text area
-5. **Check Path:** The full file path will be shown at the bottom
-6. **Exit:** Click the "Exit" button to close the application
-
-## GUI Components Breakdown
-- **Title Label:** Displays the application name
-- **Browse Button:** Opens the file selection dialog
-- **Exit Button:** Closes the application
-- **Text Area:** Shows the content of selected files
-- **Path Label:** Displays the full path of the selected file
-
-## File Type Support
-The current implementation supports:
-- **Text Files (.txt):** Primary file type with dedicated filter
-- **All Files (*.*):** Fallback option for any file type
+## Make It Editable + Save
 
-## Next Steps
-You can enhance this project by:
-- Adding support for more file types (PDF, Word, images)
-- Implementing file editing capabilities
-- Adding a file tree view for better navigation
-- Creating file operations (copy, move, delete, rename)
-- Adding syntax highlighting for code files
-- Implementing search functionality within files
-- Adding recent files history
-- Creating bookmarks for frequently accessed folders
-- Adding file properties display (size, date modified, etc.)
-- Implementing drag and drop functionality
-
-## Error Handling Improvements
-Consider adding these error handling features:
-```python title="fileexplorer.py" showLineNumbers{1}
-def browseFiles():
+Tkinter's `Text` widget is already editable by default. To save changes back:
+```python title="save.py"
+def save_file():
+    if not current_path:
+        save_file_as()
+        return
     try:
-        output.delete('1.0', END)
-        filename = filedialog.askopenfilename(...)
-        if filename:  # Check if file was selected
-            pathh.config(text = "Path: " + filename)
-            with open(filename, encoding="utf8") as tf:
-                data = tf.read()
-                output.insert(END, data)
-    except UnicodeDecodeError:
-        output.insert(END, "Error: Cannot decode file. File may be binary or use different encoding.")
-    except Exception as e:
-        output.insert(END, f"Error opening file: {str(e)}")
+        with open(current_path, "w", encoding="utf-8") as f:
+            f.write(output.get("1.0", END))
+    except OSError as e:
+        path_label.config(text=f"Save failed: {e}")
+
+def save_file_as():
+    path = filedialog.asksaveasfilename(defaultextension=".txt")
+    if path:
+        global current_path
+        current_path = path
+        save_file()
 ```
+- `output.get("1.0", END)` returns the entire text content.
+- `defaultextension=".txt"` ensures users get a sensible extension if they forget.
+
+## Encoding Detection
+
+Real files come in many encodings. **`chardet`** can guess:
+```bash title="install"
+pip install chardet
+```
+```python title="detect.py"
+import chardet
+with open(filename, "rb") as f:
+    raw = f.read()
+enc = chardet.detect(raw)["encoding"] or "utf-8"
+data = raw.decode(enc, errors="replace")
+```
+`errors="replace"` substitutes a replacement character for un-decodable bytes instead of crashing.
+
+## Add a Directory Tree
+
+For a "real" explorer, show a tree on the left:
+```python title="tree.py"
+from tkinter import ttk
+import os
+
+tree = ttk.Treeview(root)
+tree.grid(column=0, row=4, sticky="ns")
+
+def populate(parent, path):
+    for entry in sorted(os.listdir(path)):
+        full = os.path.join(path, entry)
+        node = tree.insert(parent, "end", text=entry, values=[full])
+        if os.path.isdir(full):
+            tree.insert(node, "end")                 # placeholder for expansion
+
+def on_open(event):
+    node = tree.focus()
+    tree.delete(*tree.get_children(node))
+    populate(node, tree.item(node, "values")[0])
+
+tree.bind("<<TreeviewOpen>>", on_open)
+populate("", "/")
+```
+Lazy expansion (insert one placeholder child, populate only when opened) keeps the UI snappy for huge directories.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| App crashes on cancel | `filename` is `""` | `if not filename: return` |
+| `UnicodeDecodeError` on binary file | Default encoding | Use `try/except UnicodeDecodeError` |
+| Old content still shown | Forgot to clear the widget | `output.delete("1.0", END)` first |
+| Scrollbar does not move | Did not wire `yscrollcommand` | Bidirectional binding both ways |
+| Large file freezes UI | Reading 1 GB into a `Text` widget | Stream / paginate, or refuse over a threshold |
+
+## Variations to Try
+
+### 1. Recent files
+Store the last 10 opened paths in a JSON file; show as a dropdown.
+
+### 2. Syntax highlighting
+Use **Pygments** to color Python/JS/HTML code:
+```python title="pygments.py"
+from pygments import lex
+from pygments.lexers import get_lexer_for_filename
+for token, value in lex(data, get_lexer_for_filename(filename)):
+    output.insert(END, value, str(token))
+```
+Define tag colors with `output.tag_configure("Token.Keyword", foreground="blue")`.
+
+### 3. Find / Replace
+A small dialog with two `Entry` widgets and Tkinter's built-in `Text` search:
+```python title="find.py"
+idx = output.search(term, "1.0", stopindex=END)
+if idx:
+    output.tag_add("sel", idx, f"{idx}+{len(term)}c")
+    output.see(idx)
+```
+
+### 4. Multiple tabs
+Use `ttk.Notebook` so each opened file lives in its own tab.
+
+### 5. Image preview
+For `.png/.jpg` files, swap the `Text` widget for a `Label` showing a `PIL.ImageTk.PhotoImage`.
+
+### 6. CSV viewer
+When opening a `.csv`, parse and display in a `ttk.Treeview` table instead of plain text.
+
+### 7. Markdown preview
+On open, render Markdown to HTML with `pip install markdown` and show in a side panel (use `tkhtmlview` for an HTML widget).
+
+### 8. Drag & drop
+With `tkinterdnd2`, dropping a file onto the window opens it.
+
+### 9. Recent edits tracker
+Compare on-open content with on-save content and show diff stats (lines added/removed).
+
+### 10. File operations
+Right-click context menu: Copy, Move, Rename, Delete — wire to `shutil.move`, `os.remove`, etc. Confirm before destructive operations.
+
+## Architecture: Move to a Class
+
+When the script grows past 100 lines, refactor:
+```python title="oop.py"
+class FileExplorer:
+    def __init__(self, root):
+        self.root = root
+        self.current_path = None
+        self._build_ui()
+
+    def _build_ui(self): ...
+    def browse(self): ...
+    def save(self): ...
+```
+Everything else stays the same — but state lives on `self`, not module globals, and you can test the class without launching a window.
+
+## Real-World Applications
+- **In-product file viewers** — log viewers, debug consoles.
+- **Internal tools** — quick text viewers for ops teams.
+- **Educational software** — viewing student submissions.
+- **Configuration editors** — load YAML/INI, validate on save.
+- **Prototype IDEs** — every editor started as a file viewer.
+
+## Educational Value
+- **Tkinter widgets** — buttons, labels, text, frames, scrollbars.
+- **OS file dialogs** — leveraging the native UI.
+- **Encoding handling** — what is at stake when the bytes are not ASCII.
+- **Event-driven design** — callbacks rather than top-down scripts.
+- **Layout reasoning** — `grid` vs `pack`, `sticky`, weights.
+
+## Next Steps
+- Add **scrollbars** (most important quick win).
+- Make the buffer **editable + saveable**.
+- Add **encoding detection** with `chardet`.
+- Add a **directory tree** with `ttk.Treeview`.
+- Layer **syntax highlighting** with Pygments.
+- Refactor into a class.
+- See [Basic Text Editor](./basic-text-editor) for the next evolution — a full editor with undo/redo, find/replace, and a menu bar.
 
 ## Conclusion
-In this project, we learned how to create a Basic File Explorer using Python's Tkinter library. We explored GUI development concepts including event handling, layout management, file dialogs, and text display widgets. This project demonstrates essential skills for desktop application development and provides a foundation for more complex file management applications. The combination of file handling and GUI programming makes this an excellent learning project for intermediate Python developers. To find more projects like this, you can visit Python Central Hub.
+You built a working file viewer, fixed three real-world bugs (cancel, encoding, missing scrollbars), and have a road map for turning it into a real editor. Tkinter is unfashionable but its model — widgets, callbacks, the event loop — matches every other GUI framework you will meet. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/fileexplorer.py). Explore more GUI projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/guessthenumber.mdx b/src/content/docs/projects/Beginners/guessthenumber.mdx
index 1c888599..27d76dbf 100644
--- a/src/content/docs/projects/Beginners/guessthenumber.mdx
+++ b/src/content/docs/projects/Beginners/guessthenumber.mdx
@@ -1,6 +1,6 @@
 ---
 title: Guess the Number Game
-description:  A simple game where the user has to guess a number between 1 and 20. This is a good example of using a while loop with a break statement.
+description: Build the classic "Guess the Number" game in Python. Master loops, conditionals, randomness, input validation, and learn how to extend it into a smarter AI-opponent version.
 sidebar: 
     order: 3
 hero:
@@ -13,27 +13,44 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-This is a simple game where the user has to guess a number between 1 and 20. You will learn how to use a while loop with a break statement. In this application, computer will choose a random number between 1 and 20, and the user will have to guess the number. If the user guesses wrong, the program will tell the user if the guess is too high or too low. If the user guesses correctly, the program will congratulate the user and end the game. If the user fails to guess the number within six tries, the program will tell the user the number and end the game.
+"Guess the Number" is the rite-of-passage game in every beginner curriculum, and for good reason: in a single short script you exercise nearly every fundamental — randomness, looping, branching, user input, type conversion, comparisons, and string formatting. The premise: the computer secretly chooses a number between 1 and 20, the user has six chances to guess it, and after every guess the program tells them whether they were too high or too low.
+
+In this tutorial we will:
+- Build the classic version from scratch.
+- Walk line-by-line through what each statement does.
+- Harden the program against bad input (letters, negative numbers, empty input).
+- Extend it with difficulty levels, score tracking, and a "play again" loop.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
+- Python 3.6 or above.
+- A text editor or IDE.
+- Familiarity with running a Python script (see [Hello World](./helloworld)).
+- Some comfort with `input()`, `print()`, and basic comparisons.
+
+## Concepts You Will Use
+
+- **`random.randint(a, b)`** — picks a random integer between `a` and `b`, inclusive.
+- **`for` loop with `range`** — iterates a fixed number of times.
+- **`if`/`elif`/`else`** — choose between several branches.
+- **`break`** — exit a loop immediately.
+- **Type conversion** — `int(input(...))` turns text into a number.
+- **String concatenation vs. f-strings** — two ways to insert values into messages.
 
 ## Getting Started
-### Create a new project
-1. Create a new project folder and name it `guessTheNumberGame`.
-2. Create a new file and name it `guessTheNumberGame.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `guessTheNumberGame.py` file.
+
+### Create the project
+1. Make a folder named `guess-the-number`.
+2. Inside it, create a file named `guessthenumber.py`.
+3. Open the folder in your editor.
 
 ### Write the code
-1. Add the following code to your `guessTheNumberGame.py` file.
+Paste the following into `guessthenumber.py`:
 <FileCode file="projects/beginners/guessthenumber.py" lang="python" title="Guess The Number" />
-2. Save the file.
-3. Open the terminal and navigate to the project folder.
-4. Run the following command to run the application.
+
+Save, open a terminal in the folder, and run:
+
 ```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\guessTheNumberGame> python guessthenumber.py
+C:\Users\username\Documents\guess-the-number> python guessthenumber.py
 Hello, what is your name?
 Ravi
 Well, Ravi, I am thinking of a number between 1 and 20.
@@ -54,35 +71,166 @@ Take a guess. You have 2 guesses left.
 Good job, Ravi! You guessed my number in 5 guesses.
 ```
 
-## Explanation
-1. The `import random` statement will import the random module into your program. This will allow you to generate random numbers.
-2. The `print('Hello, what is your name?')` statement will print the string `Hello, what is your name?` to the console.
-3. The `name = input()` statement will prompt the user to enter their name and store the value in the `name` variable.
-4. The `print('Well, ' + name + ', I am thinking of a number between 1 and 20.')` statement will print the string `Well, ` followed by the value of the `name` variable, followed by the string `, I am thinking of a number between 1 and 20.` to the console.
-5. The `secretNumber = random.randint(1, 20)` statement will generate a random number between 1 and 20 and store the value in the `secretNumber` variable.
-6. The `for guessesTaken in range(1, 7):` statement will create a for loop that will run six times. The `guessesTaken` variable will store the number of times the loop has run.
-7. The `print('Take a guess. You have ' + str(7 - guessesTaken) + ' guesses left.')` statement will print the string `Take a guess. You have ` followed by the value of the `guessesTaken` variable subtracted from 7, followed by the string ` guesses left.` to the console.
-8. The `guess = int(input())` statement will prompt the user to enter a number and store the value in the `guess` variable.
-9. The `if guess < secretNumber:` statement will check if the value of the `guess` variable is less than the value of the `secretNumber` variable.
-10. The `print('Your guess is too low.')` statement will print the string `Your guess is too low.` to the console.
-11. The `elif guess > secretNumber:` statement will check if the value of the `guess` variable is greater than the value of the `secretNumber` variable.
-12. The `print('Your guess is too high.')` statement will print the string `Your guess is too high.` to the console.
-13. The `else:` statement will run if the `if` and `elif` statements are false.
-14. The `break` statement will end the loop.
-15. The `if guess == secretNumber:` statement will check if the value of the `guess` variable is equal to the value of the `secretNumber` variable.
-16. The `print('Good job, ' + name + '! You guessed my number in ' + str(guessesTaken) + ' guesses.')` statement will print the string `Good job, ` followed by the value of the `name` variable, followed by the string `! You guessed my number in `, followed by the value of the `guessesTaken` variable, followed by the string ` guesses.` to the console.
+Run it a few times. The secret number changes every time.
+
+## Step-by-Step Explanation
+
+### 1. Import randomness
+```python title="guessthenumber.py"
+import random
+```
+The `random` module is part of Python's standard library. After this line, `random.randint(...)` is available.
+
+### 2. Greet the user
+```python title="guessthenumber.py"
+print('Hello, what is your name?')
+name = input()
+print('Well, ' + name + ', I am thinking of a number between 1 and 20.')
+```
+- `input()` waits for the user to press Enter and returns their text as a string.
+- `'Well, ' + name + ', ...'` is **string concatenation** — joining pieces of text with `+`.
+
+> 💡 A more modern alternative is the f-string: `print(f'Well, {name}, I am thinking of a number between 1 and 20.')`
+
+### 3. Pick a secret number
+```python title="guessthenumber.py"
+secretNumber = random.randint(1, 20)
+```
+`random.randint(1, 20)` returns a random integer from 1 to 20 inclusive — both endpoints are possible.
+
+### 4. Loop six times
+```python title="guessthenumber.py"
+for guessesTaken in range(1, 7):
+    print('Take a guess. You have ' + str(7 - guessesTaken) + ' guesses left.')
+    guess = int(input())
+```
+- `range(1, 7)` generates `1, 2, 3, 4, 5, 6` — six iterations.
+- `guessesTaken` is the current attempt number.
+- `7 - guessesTaken` gives the player how many tries remain.
+- `int(input())` reads a line and converts it to an integer. If the user types `"abc"`, this line will crash — we will fix that in the "Robust Input" section below.
+
+### 5. Compare and react
+```python title="guessthenumber.py"
+    if guess < secretNumber:
+        print('Your guess is too low.')
+    elif guess > secretNumber:
+        print('Your guess is too high.')
+    else:
+        break
+```
+The three branches cover every possibility:
+- `<` → too low, keep going.
+- `>` → too high, keep going.
+- otherwise (`==`) → correct, `break` out of the loop.
+
+### 6. Final message
+```python title="guessthenumber.py"
+if guess == secretNumber:
+    print('Good job, ' + name + '! You guessed my number in ' + str(guessesTaken) + ' guesses.')
+else:
+    print('Nope. The number I was thinking of was ' + str(secretNumber))
+```
+If the loop ended because of `break`, the player won. Otherwise they ran out of guesses.
+
+## Strategy: How Many Guesses Should You Need?
+
+With six guesses for a range of 20, the optimal strategy is **binary search** — always guess the middle. Each guess halves the remaining range:
+
+| Guess # | Range | Mid |
+|---|---|---|
+| 1 | 1–20 | 10 |
+| 2 | half | 5 or 15 |
+| 3 | quarter | … |
+| 4–5 | usually solved | |
+
+In general you need about `log₂(n)` guesses for a range of `n` numbers. For 1–20 that is about 4.3, so six guesses is generous.
+
+## Robust Input
+
+The basic version crashes when the user types letters. Replace `int(input())` with a helper:
+
+```python title="safe_input.py"
+def ask_number(prompt, low, high):
+    while True:
+        raw = input(prompt)
+        try:
+            n = int(raw)
+        except ValueError:
+            print("Please enter a whole number.")
+            continue
+        if not (low <= n <= high):
+            print(f"Number must be between {low} and {high}.")
+            continue
+        return n
+```
+Now `guess = ask_number("Your guess: ", 1, 20)` handles every bad input gracefully.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `ValueError: invalid literal for int()` | User typed letters | Wrap in `try`/`except ValueError` |
+| Loop ends but program says "Nope" even when correct | Used `==` inside the loop without `break` | Add `break` in the `else` branch |
+| Cannot concatenate `str` and `int` | `'left: ' + guessesTaken` | Convert with `str(guessesTaken)` or use an f-string |
+| Random number is always the same | You set `random.seed(0)` somewhere | Remove the seed call for true variability |
+
+## Variations to Try
+
+### 1. Difficulty levels
+```python title="difficulty.py"
+levels = {"easy": (1, 10, 6), "medium": (1, 50, 7), "hard": (1, 100, 8)}
+choice = input("Difficulty (easy/medium/hard): ").lower()
+low, high, tries = levels[choice]
+secret = random.randint(low, high)
+```
+
+### 2. Play-again loop
+```python title="replay.py"
+while True:
+    play_game()
+    again = input("Play again? (y/n): ").lower()
+    if again != "y":
+        break
+```
+
+### 3. Track best score
+```python title="best.py"
+best = None
+# after each round:
+if best is None or guessesTaken < best:
+    best = guessesTaken
+    print(f"New best score: {best} guesses!")
+```
+
+### 4. Persistent high-score file
+```python title="persist.py"
+from pathlib import Path
+SCORE_FILE = Path("best_score.txt")
+best = int(SCORE_FILE.read_text()) if SCORE_FILE.exists() else None
+# update and write back:
+if best is None or new_score < best:
+    SCORE_FILE.write_text(str(new_score))
+```
+
+### 5. Reverse the game — you pick, the computer guesses
+See the [Number Guessing Game with AI](./numberguessingwithai) project. The AI uses binary search to guess your number in at most seven tries.
+
+### 6. GUI version with Tkinter
+Replace `input()` and `print()` with an entry widget and a label. A few hours of work and you have a clickable game.
+
+## Common Interview-Style Questions This Project Touches
+- "How would you guess a number between 1 and 1,000,000 with the fewest tries?" → binary search.
+- "Why is `int(input())` dangerous?" → invalid user input can crash the program; use `try`/`except`.
+- "How does Python's `random` module work under the hood?" → Mersenne Twister, pseudo-random.
+
+## Real-World Applications
+- Game development (loot tables, RNG events, procedural generation).
+- Educational tools that teach the binary search algorithm visually.
+- A/B testing assignment when you need a random bucket.
+- Quick demos of probability concepts in classrooms.
 
 ## Next Steps
-Congratulations! You have successfully created a Guess the Number game in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions.
-- Change the number of guesses.
-- Change the range of numbers.
-- Add a high score.
-- Add a timer.
-- Add a GUI.
-- Add a database to store the high score.
-- Add a leaderboard.
-- Add a multiplayer mode.
-- Add a difficulty setting.
+Pick one of the variations above and ship it. Combine two or three for extra credit — for example, difficulty levels + persistent high-score + play-again loop is a complete tiny game. Then move on to projects that combine randomness with state, such as [Hangman](./hangman) or [Blackjack](./blackjack).
 
 ## Conclusion
-In this project, you learned how to create a Guess the Number game in Python. You also learned how to use a while loop with a break statement. You can find the source code [Github](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/guessthenumber.py)
\ No newline at end of file
+You wrote a complete game in roughly fifteen lines of Python, learned how `random.randint` works, looped with `for…range`, branched with `if`/`elif`/`else`, and saw how a small program scales up with input validation and replayability. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/guessthenumber.py). Find more projects like this on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/hangman.mdx b/src/content/docs/projects/Beginners/hangman.mdx
index 630b76f2..e053362c 100644
--- a/src/content/docs/projects/Beginners/hangman.mdx
+++ b/src/content/docs/projects/Beginners/hangman.mdx
@@ -1,6 +1,6 @@
 ---
 title: Hangman Game
-description: A classic word guessing game implemented in Python. Players guess letters to complete a hidden word within a limited number of attempts.
+description: Build the classic Hangman word-guessing game in Python. Learn file I/O, sets for guess tracking, ASCII art for the gallows, replay loops, category selection, and how to grow it into a polished game.
 sidebar: 
     order: 13
 hero:
@@ -13,180 +13,330 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Hangman is a classic word guessing game where players try to guess a hidden word by suggesting letters within a limited number of attempts. This Python implementation uses a text file containing a list of words and randomly selects one for the player to guess. The game provides feedback on correct and incorrect guesses and tracks the number of remaining attempts. This project is excellent for beginners to learn about file handling, string manipulation, and game logic in Python.
+Hangman is the perfect "second game" project. It is more complex than Rock-Paper-Scissors but still fits in one file. You learn file I/O (loading a word list), random selection, sets (tracking guessed letters), string assembly (showing the partially-revealed word), and game-state management (win, lose, keep going). In this tutorial you will build the classic version with a word list, then layer in ASCII-art gallows, input validation, category selection, score tracking, hints, and a replay loop.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- A text file with words (words.txt)
+You will learn:
+- Why `set` is the right structure for "letters already guessed".
+- How to reveal a word letter-by-letter from a hidden secret.
+- How to draw step-by-step ASCII art from a list of stages.
+- How to organize game state into clean functions.
+- How to extend a beginner game with categories, hints, and persistence.
+
+## The Rules
+1. The computer picks a secret word.
+2. The player sees blanks: `_ _ _ _ _ _ _`.
+3. Player guesses one letter at a time.
+4. Correct letters fill in their positions.
+5. Wrong letters cost one "limb" of the hanged figure.
+6. Player wins by completing the word; loses if the figure is fully drawn first.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- A text file of words (we will make one).
+- Comfort with `while` loops, `if/else`, and basic file reading.
 
 ## Getting Started
-#### Create a Project
+
+### Create the project
 1. Create a folder named `hangman-game`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `hangman.py`.
-4. Create a file named `words.txt` and add some words (one word per line).
-5. Copy the given code and paste it in your `hangman.py` file.
-
-#### Create Words File
-Create a `words.txt` file in the same directory and add words like:
-```txt title="words.txt" showLineNumbers{1} {1-10}
-python
-programming
-computer
-science
-technology
-development
-software
-coding
-algorithm
-function
-```
+2. Inside it, create `hangman.py`.
+3. Create `words.txt` next to it. Suggested starter contents:
+   ```txt title="words.txt"
+   python
+   programming
+   computer
+   science
+   technology
+   development
+   software
+   coding
+   algorithm
+   function
+   variable
+   recursion
+   compiler
+   interpreter
+   ```
 
-## Write the Code
-1. Copy and paste the following code in your `hangman.py` file.
-<FileCode file="projects/beginners/hangman.py" lang="python" title="Hangman Game" />
-2. Save the file.
-3. Make sure you have the `words.txt` file in the same directory.
-4. Open the terminal in your code editor or IDE and navigate to the folder `hangman-game`.
-```cmd title="command" showLineNumbers{1} {1-30}
+### Write the code
+<FileCode file="projects/beginners/hangman.py" lang="python" title="Hangman" />
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\hangman-game> python hangman.py
 What is your name? John
-Good Luck !  John
-The game is about to start !
-Let's play Hangman
-Guess the characters
-________
-You have 16 more guesses
-guess a character: p
-p_______
-You have 16 more guesses
-guess a character: r
-pr______
-You have 16 more guesses
-guess a character: o
-pro_____
-You have 16 more guesses
-guess a character: g
-prog____
-You have 16 more guesses
-guess a character: r
-progr___
-You have 16 more guesses
-guess a character: a
-progra__
-You have 16 more guesses
-guess a character: m
-program_
-You have 16 more guesses
-guess a character: m
-programm
-You have 15 more guesses
-guess a character: i
-programmi
-You have 15 more guesses
-guess a character: n
-programming
-You Win
-The word is:  programming
+Good luck, John! Let's play Hangman.
+Word: _ _ _ _ _ _ _
+Guesses left: 6
+Guess a letter: p
+Word: p _ _ _ _ _ _
+Guess a letter: ...
 ```
 
-## Explanation
-1. Import the required modules.
-```python title="hangman.py" showLineNumbers{1} {1-3}
+## Step-by-Step Explanation
+
+### 1. Imports
+```python title="hangman.py"
 import random
 import time
 ```
+`random.choice` picks the word. `time.sleep` adds drama.
+
+### 2. Load and pick a word
+```python title="hangman.py"
+with open("words.txt", encoding="utf-8") as f:
+    words = [line.strip().lower() for line in f if line.strip()]
+word = random.choice(words)
+```
+Reading inside a `with` block ensures the file is closed automatically. The list comprehension strips trailing newlines and skips empty lines.
 
-2. Get the player's name and provide welcome messages.
-```python title="hangman.py" showLineNumbers{1} {1-10}
-name = input("What is your name? ")
-print("Good Luck ! ", name)
+### 3. Game state
+```python title="hangman.py"
+guessed_letters = set()
+wrong = 0
+max_wrong = 6
+```
+Why a **set** for `guessed_letters`?
+- `letter in guessed_letters` is O(1).
+- Adding a duplicate is harmless.
+- It mirrors the natural language of the rules — *"have I guessed this letter already?"*
+
+### 4. Reveal the secret partially
+```python title="hangman.py"
+def display(word: str, guessed: set[str]) -> str:
+    return " ".join(c if c in guessed else "_" for c in word)
+```
+A list/generator comprehension over the secret word: keep characters the player has guessed, otherwise show `_`. `" ".join(...)` spaces them out for readability.
 
-time.sleep(1)
+### 5. The main loop
+```python title="hangman.py"
+while wrong < max_wrong:
+    print(f"\n{display(word, guessed_letters)}")
+    print(f"Guesses left: {max_wrong - wrong}")
+    guess = input("Guess a letter: ").lower().strip()
 
-print("The game is about to start !")
-print("Let's play Hangman")
+    if len(guess) != 1 or not guess.isalpha():
+        print("Enter a single letter.")
+        continue
+    if guess in guessed_letters:
+        print("Already guessed.")
+        continue
 
-time.sleep(1)
+    guessed_letters.add(guess)
+    if guess in word:
+        if all(c in guessed_letters for c in word):
+            print(f"\n🎉 You win! The word was '{word}'.")
+            break
+    else:
+        wrong += 1
+        print("Wrong!")
+else:
+    print(f"\nYou lost. The word was '{word}'.")
 ```
+Several patterns in play:
+- **Input validation** rejects multi-char or non-alphabetic input.
+- **Duplicate detection** uses the set.
+- **Win check** asks *"are every letter of the word now in `guessed`?"* — `all(...)` is the right tool.
+- **`else` clause on a `while`** runs only if the loop ended normally (the player ran out of guesses). It is a lesser-known but elegant feature of Python.
 
-3. Read words from the file and select a random word.
-```python title="hangman.py" showLineNumbers{1} {1-5}
-open_file = open("words.txt", "r")
-words = open_file.readlines()
-word = random.choice(words)
-word = word.lower().strip().replace("\n", "").replace("\r", "").replace(" ", "").replace("-", "")
+## ASCII-Art Gallows
+
+A 7-frame gallows that draws progressively as the player loses:
+
+```python title="gallows.py"
+STAGES = [
+    r"""
+       -----
+       |   |
+           |
+           |
+           |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+           |
+           |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+       |   |
+           |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+      /|   |
+           |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+      /|\  |
+           |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+      /|\  |
+      /    |
+           |
+    =========""",
+    r"""
+       -----
+       |   |
+       O   |
+      /|\  |
+      / \  |
+           |
+    =========""",
+]
+
+print(STAGES[wrong])     # in the main loop
+```
+Six wrong guesses → seven stages (0 wrong = empty gallows, 6 wrong = full hangman). The `r"""..."""` is a raw triple-quoted string — backslashes inside stay literal.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Word contains a newline character | Forgot `.strip()` after `readlines()` | Use the list-comp above |
+| Capital letters never match | Mixed cases | Lowercase both the word and the guess |
+| Pressing Enter empty crashes the game | No length check | Validate `len(guess) == 1` |
+| Counting wrong letters when a duplicate is pressed | No duplicate check | Skip already-guessed letters |
+| Win never triggers | Used `==` instead of `all(... in ...)` | Use `all(c in guessed_letters for c in word)` |
+
+## Variations to Try
+
+### 1. Categories
+Store one word list per category:
+```
+fruits.txt
+animals.txt
+programming.txt
 ```
+Ask the user to pick a category. Each `.txt` becomes a `Path`:
+```python title="categories.py"
+from pathlib import Path
+cats = {p.stem: p for p in Path("words").glob("*.txt")}
+choice = input(f"Pick: {', '.join(cats)}\n> ")
+words = cats[choice].read_text().splitlines()
+```
+
+### 2. Difficulty levels
+- **Easy:** 4–6 letter words, 8 guesses.
+- **Medium:** 7–9 letter words, 6 guesses.
+- **Hard:** 10+ letter words, 5 guesses, only common letters give hints.
 
-4. Initialize game variables.
-```python title="hangman.py" showLineNumbers{1} {1-3}
-print("Guess the characters")
-guesses = ''
-turns = len(word) * 2
+### 3. Hints
+Give a hint after N wrong guesses — reveal one letter automatically:
+```python title="hint.py"
+if wrong == 4:
+    for c in word:
+        if c not in guessed_letters:
+            print(f"Hint: contains '{c}'")
+            guessed_letters.add(c)
+            break
 ```
 
-5. Main game loop - check guesses and display progress.
-```python title="hangman.py" showLineNumbers{1} {1-20}
-while turns > 0:
-    failed = 0
-    for char in word:
-        if char in guesses:
-            print(char, end="")
-        else:
-            print("_", end="")
-            failed += 1
-    
-    if failed == 0:
-        print("\nYou Win")
-        print("The word is: ", word)
+### 4. Score tracking
+A win earns `(letters - wrong) * 10` points. Persist between sessions in a JSON file. See [Personal Diary](./personaldiary) for the same persistence pattern.
+
+### 5. Replay loop
+```python title="replay.py"
+while True:
+    play_round()
+    if input("Play again? (y/n): ").lower() != "y":
         break
 ```
 
-6. Handle user input and game logic.
-```python title="hangman.py" showLineNumbers{1} {1-15}
-guess = input("guess a character: ")
-guesses += guess
-
-if guess not in word:
-    turns -= 1
-    print("Wrong")
-    
-    if turns == 0:
-        print("\nYou Loose")
-        print("\nThe word is: ", word)
-        break
+### 6. Two-player mode
+Player 1 enters the word secretly (`getpass.getpass` hides it from the terminal); Player 2 guesses.
+
+### 7. GUI version
+Tkinter with a letter-grid of buttons and an image-based gallows. See [Basic Music Player](./basicmusicplayer) for the GUI pattern.
+
+### 8. Web version
+Flask plus a single HTML page. The state lives in the user's session. See [Basic Web Server](./basicwebserver).
+
+### 9. Word source from an API
+Pull a random English word from a dictionary API instead of `words.txt`:
+```python title="api_word.py"
+import requests
+word = requests.get("https://random-word-api.herokuapp.com/word").json()[0]
 ```
 
-## Features
-- Random word selection from a text file
-- Limited number of guesses based on word length
-- Real-time progress display with underscores
-- Win/lose conditions with appropriate messages
-- Input validation and feedback
-- Clean and intuitive user interface
-
-## How to Play
-1. Run the program and enter your name
-2. The game will display underscores representing each letter of the hidden word
-3. Guess letters one at a time
-4. Correct guesses reveal the letter's position(s) in the word
-5. Incorrect guesses reduce your remaining attempts
-6. Win by guessing all letters before running out of attempts
-7. Lose if you exhaust all attempts without completing the word
+### 10. Definition reveal
+After the round, look up the word's definition using `pip install nltk` + the WordNet corpus, and show it to teach vocabulary.
+
+## Refactoring with a Class
+
+For a serious version, wrap state in a class:
+
+```python title="hangman_class.py"
+class Hangman:
+    def __init__(self, word: str, max_wrong: int = 6):
+        self.word = word.lower()
+        self.guessed: set[str] = set()
+        self.wrong = 0
+        self.max_wrong = max_wrong
+
+    def guess(self, letter: str) -> str:
+        letter = letter.lower()
+        if letter in self.guessed:
+            return "duplicate"
+        self.guessed.add(letter)
+        if letter not in self.word:
+            self.wrong += 1
+            return "miss"
+        return "hit"
+
+    @property
+    def display(self) -> str:
+        return " ".join(c if c in self.guessed else "_" for c in self.word)
+
+    @property
+    def is_won(self) -> bool:
+        return all(c in self.guessed for c in self.word)
+
+    @property
+    def is_lost(self) -> bool:
+        return self.wrong >= self.max_wrong
+```
+Now the game logic is testable without `input()` — perfect for unit tests.
+
+## Real-World Applications
+- **Vocabulary teaching** — a hangman with curated word lists works in language learning apps.
+- **CAPTCHA-style verification** in a friendly form.
+- **Conference / classroom icebreaker** — group hangman on a projector.
+- **Onboarding gamification** — turn product terminology into a guessing game.
+
+## Educational Value
+This project teaches:
+- **File I/O** — reading lists from text files.
+- **Sets** — O(1) membership tests and natural-language semantics.
+- **String manipulation** — partial reveal, comparison, validation.
+- **Game-state management** — wrong count, guessed letters, win/lose conditions.
+- **Refactoring** — moving from a script to a class for testability.
 
 ## Next Steps
-You can enhance this project by:
-- Adding a graphical hangman drawing for wrong guesses
-- Implementing difficulty levels with different word categories
-- Adding a scoring system based on guesses used
-- Creating a GUI version using Tkinter
-- Adding hint functionality
-- Implementing multiplayer mode
-- Adding word definitions or categories
+- Build the **ASCII-art version** with the `STAGES` list above.
+- Add **categories** and **difficulty levels**.
+- Wrap state in a **`Hangman` class** and add **unit tests** with `pytest`.
+- Build a **GUI** or **web** version.
+- Use a **real word API** so the dictionary never runs out.
 
 ## Conclusion
-In this project, we learned how to create a Hangman game using Python. We covered file handling to read words from a text file, string manipulation for processing the selected word, and game logic for tracking guesses and determining win/lose conditions. This project demonstrates essential programming concepts like loops, conditionals, and user input handling. To find more projects like this, you can visit Python Central Hub.
+You built a complete Hangman game from a 50-line script: file loading, secret picking, partial reveal, input validation, win/lose conditions, and ASCII-art gallows. The same patterns power dozens of guessing games and quiz apps. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/hangman.py). Explore more games on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/helloworld.mdx b/src/content/docs/projects/Beginners/helloworld.mdx
index 44a8e14a..e87901a6 100644
--- a/src/content/docs/projects/Beginners/helloworld.mdx
+++ b/src/content/docs/projects/Beginners/helloworld.mdx
@@ -1,6 +1,6 @@
 ---
 title: Hello World Project
-description: A simple Hello World project to get you started with learning from projects.
+description: A complete beginner's guide to writing, running, and understanding your very first Python program. Learn how Python executes code, what `print()` does behind the scenes, and how to extend your first program.
 sidebar: 
     order: 1
 hero:
@@ -14,30 +14,174 @@ import FileCode from '../../../../components/FileCode.astro'
 
 
 ## Abstract
-Creating a "Hello World" project is a classic and essential first step for anyone learning a new programming language. In this guide, we'll walk through the process of building a simple "Hello World" project using Python. This project serves as a foundation for understanding basic syntax, setting up a development environment, and executing a Python script.
+Writing a "Hello, World!" program is the traditional first step in learning any programming language. It looks trivial, but it teaches you four very real things at once: how to **write** source code, how to **save** it as a file your machine can find, how to **run** it through the Python interpreter, and how to **read** the output. In this tutorial we will go beyond just typing one line. We will explore *why* the program works, what happens when you press Enter, common errors beginners hit on their first day, and several small variations that take you from a single print statement to your first interactive program.
+
+By the end of this tutorial you will be able to:
+- Verify Python is installed on your computer.
+- Create and save a `.py` file.
+- Run a script from the terminal.
+- Understand what `print()` does and how Python evaluates a line of code.
+- Modify the program to take user input and respond.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE (Visual Studio Code, PyCharm, etc.)
+- Python 3.6 or above installed ([download page](https://www.python.org/downloads/)).
+- A text editor or IDE. We recommend [Visual Studio Code](https://code.visualstudio.com/) with the official Python extension.
+- A terminal you are comfortable opening (Command Prompt or PowerShell on Windows, Terminal on macOS/Linux).
+- No previous programming experience required.
+
+## Before You Start
+Open a terminal and confirm Python is on your PATH:
+
+```cmd title="check-python"
+python --version
+```
+
+You should see something like `Python 3.11.4`. If you get *"python is not recognized"* on Windows, re-run the Python installer and check the **"Add Python to PATH"** option, then restart your terminal. On macOS/Linux you may need to use `python3` instead of `python`.
 
 ## Getting Started
-### Create a new project
-1. Open Text Editor or IDE
-2. Select **File** > **New File** from the menu bar
-3. Select **File** > **Save As** from the menu bar
-4. Name the file `hello_world.py`
-5. Select **File** > **Save** from the menu bar
-
-### Write the code
-1. Add the following code to the file:
+
+### Step 1 — Create a project folder
+Keeping each project in its own folder is a habit worth forming on day one. It keeps your scripts organized and prevents naming clashes later.
+
+1. Choose a place on your disk, for example `Documents`.
+2. Create a new folder named `hello-world`.
+3. Open the folder in your editor (in VS Code: **File → Open Folder…**).
+
+### Step 2 — Create the file
+1. In your editor, choose **File → New File**.
+2. Save it immediately with **File → Save As…** as `hello_world.py` inside the `hello-world` folder.
+3. The `.py` extension is important — it tells the operating system and your editor that this is a Python file. Editors use the extension to enable syntax highlighting and Python tooling.
+
+### Step 3 — Write the code
+Add the following code to `hello_world.py`:
 <FileCode file="projects/beginners/helloworld.py" lang="python" title="Hello World" />
-2. Select **File** > **Save** from the menu bar
-3. Select **Terminal** > **New Terminal** from the menu bar
-4. In the terminal, 
+
+Save the file again with **Ctrl+S** (or **Cmd+S** on macOS).
+
+### Step 4 — Run it
+Open the integrated terminal in your editor (**View → Terminal** in VS Code) and run:
+
 ```cmd title="command" showLineNumbers{1} {2}
-C:\Users\username\Documents\hello_world> python hello_world.py
+C:\Users\username\Documents\hello-world> python hello_world.py
 Hello World!
 ```
 
+That `Hello World!` line is your program's output, printed to the screen by the Python interpreter.
+
+## How It Works
+
+A Python source file is just a plain text file. When you type `python hello_world.py`, four things happen behind the scenes:
+
+1. **The interpreter starts.** Your operating system launches the `python` executable.
+2. **It reads your file top-to-bottom.** Python parses the file into tokens (keywords, names, punctuation), then into an internal tree representation called an **AST** (Abstract Syntax Tree).
+3. **It compiles to bytecode.** The AST is compiled into a compact intermediate format. You may notice a `__pycache__` folder appear next to your script — that is the cached bytecode.
+4. **It executes the bytecode.** The Python virtual machine walks the bytecode, sees a call to the built-in `print` function with the string `"Hello World!"`, and writes that string to **standard output** — which your terminal then displays.
+
+The whole pipeline is invisible. From your perspective: you saved a file, ran one command, and saw output. Everything else is Python's job.
+
+### What does `print()` actually do?
+`print` is a **built-in function**. You can call it with any value:
+
+```python title="print-examples"
+print("Hello World!")    # a string
+print(42)                # an integer
+print(3.14 * 2)          # an expression that evaluates first
+print("a", "b", "c")     # multiple values separated by spaces
+```
+
+By default `print` appends a newline character (`\n`) after its output. You can change this with the `end` keyword argument:
+
+```python title="end-arg"
+print("Hello", end=" ")
+print("World!")
+# Output: Hello World!
+```
+
+## Common Mistakes
+
+Beginners often hit one of these on day one. None of them are signs you are bad at programming — every Python developer has seen them.
+
+| Problem | What you typed | What went wrong | Fix |
+|---|---|---|---|
+| `SyntaxError: Missing parentheses in call to 'print'` | `print "Hello"` | Python 2 syntax | Use `print("Hello")` |
+| `NameError: name 'Hello' is not defined` | `print(Hello)` | Missing quotes — Python looked for a variable named `Hello` | Wrap strings in quotes: `print("Hello")` |
+| `python: can't open file 'hello_world.py'` | Ran `python hello_world.py` from wrong folder | Terminal is in a different directory | `cd` into your project folder first |
+| Nothing happens | Forgot to **save** the file | Editor still shows the dot meaning unsaved changes | Save with **Ctrl+S** before running |
+| `IndentationError` | Pasted code with leading spaces | Python is whitespace-sensitive | Remove leading whitespace on top-level statements |
+
+## Variations to Try
+
+Once your first program runs, modify it. Tweaking working code is the fastest way to learn.
+
+### 1. Ask for a name
+```python title="hello_user.py"
+name = input("What is your name? ")
+print("Hello,", name + "!")
+```
+- `input()` pauses the program, waits for the user to type something and press Enter, and returns whatever they typed as a string.
+- `name + "!"` joins two strings using the `+` operator (called **string concatenation**).
+
+### 2. Use an f-string
+F-strings are the modern, readable way to embed values inside strings:
+```python title="f-string.py"
+name = input("Name: ")
+print(f"Hello, {name}! Welcome to Python.")
+```
+The `f` prefix tells Python: *"this string contains expressions in curly braces — evaluate them and insert the result."*
+
+### 3. Greet in multiple languages
+```python title="multilang.py"
+print("Hello, World!")
+print("Hola, Mundo!")
+print("Bonjour le monde!")
+print("こんにちは世界")
+```
+Python source files are UTF-8 by default — non-Latin characters work out of the box.
+
+### 4. Loop a greeting
+```python title="loop.py"
+for i in range(3):
+    print(f"Hello #{i + 1}")
+```
+This introduces the `for` loop and `range()` — two building blocks you will use in nearly every program.
+
+## Running Without the Terminal
+
+If you prefer not to use the terminal:
+
+- **VS Code:** click the ▶ run button in the top-right while `hello_world.py` is open.
+- **PyCharm:** right-click the file in the project tree → **Run 'hello_world'**.
+- **IDLE** (bundled with Python): open the file and press **F5**.
+
+All three do the same thing — they invoke `python hello_world.py` for you and capture the output in a panel.
+
+## Frequently Asked Questions
+
+**Why is it always "Hello, World!"?**
+The phrase comes from Brian Kernighan's 1972 tutorial for the B programming language and was popularized by the 1978 *C Programming Language* book. It became a tradition.
+
+**Do I need to compile Python like C or Java?**
+No. Python compiles to bytecode automatically the first time the file is run and caches it in `__pycache__`. You only run `python hello_world.py`.
+
+**What if I want to share this with someone who does not have Python installed?**
+Look into **PyInstaller** or **Nuitka** — both can package a Python script into a standalone executable. That is far beyond Hello World, but good to know it is possible.
+
+## Educational Value
+Even this tiny program teaches:
+- **File-based source code** — the foundation of every real Python project.
+- **The print function** — output is how programs communicate with humans.
+- **String literals** — your first data type.
+- **Running an interpreter** — the loop you will use thousands of times: edit, save, run, read output, fix.
+- **Reading errors** — error messages are not punishments, they are clues.
+
 ## Next Steps
-Congratulations! You've successfully created a "Hello World" project using Python. Now that you've completed this project, you can continue learning Python by completing the next project in the series on Python Central Hub. You can find the complete source code of this project on [Github](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/helloworld.py).
+You have a working Python development setup and you understand what happened when you ran your first program. From here, try one of the following:
+
+- Modify the program to greet *you* by name.
+- Move on to the next project, **Simple Calculator**, which introduces functions and basic arithmetic.
+- Read about [Python's built-in functions](https://docs.python.org/3/library/functions.html) — `print` is just one of about seventy.
+
+You can find the complete source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/helloworld.py).
+
+## Conclusion
+A one-line program is not the goal. The goal is to make sure your environment works end-to-end: editor saves, interpreter runs, terminal shows output. Once that loop is reliable, every other project on Python Central Hub becomes easier. Celebrate this moment — every programmer alive started exactly where you are right now.
diff --git a/src/content/docs/projects/Beginners/json-data-validator.mdx b/src/content/docs/projects/Beginners/json-data-validator.mdx
index fa7bdd76..abed134c 100644
--- a/src/content/docs/projects/Beginners/json-data-validator.mdx
+++ b/src/content/docs/projects/Beginners/json-data-validator.mdx
@@ -1,6 +1,6 @@
 ---
 title: JSON Data Validator
-description: A comprehensive JSON schema validation tool with custom schema support, batch validation, error reporting, and data generation capabilities
+description: Build a Python JSON Schema validator from scratch. Learn type/constraint validation, path-tracked errors, batch validation, sample-data generation, and how it compares to jsonschema and pydantic.
 sidebar:
   order: 50
 hero:
@@ -13,377 +13,306 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+JSON is the data format of the modern web — APIs, configs, telemetry, NoSQL stores all live in it. But JSON gives you no type safety: a misnamed field or out-of-range number sails through `json.loads()` and silently breaks downstream code hours later. A **schema validator** catches those errors at the boundary, with precise error messages pointing at the offending field. In this project you build one from scratch — type checking, constraints, nested validation, path-tracked errors, batch validation, and sample-data generation — then compare it to the production-grade libraries `jsonschema` and `pydantic`.
 
-A comprehensive JSON schema validation tool that validates JSON data against custom schemas, provides detailed error reporting, supports batch validation, and includes data generation capabilities. This project demonstrates advanced data validation, schema design, and file processing techniques.
+You will leave understanding:
+- The JSON Schema specification (the subset most apps actually use).
+- How to write a small recursive validator.
+- Path-tracked error messages (`root.users[0].email`).
+- The difference between schema-based and class-based validation.
+- When to graduate to `jsonschema` (for spec compliance) or `pydantic` (for type-driven validation).
 
-## 🎯 Project Overview
+## Prerequisites
+- Python 3.7 or above (for `dataclasses`).
+- A text editor or IDE.
+- Familiarity with JSON, dictionaries, and recursive functions.
 
-This project creates a powerful JSON validation system with:
-- Custom JSON schema definition and validation
-- File and string validation capabilities
-- Batch validation for multiple files
-- Detailed error reporting with path information
-- Sample data generation from schemas
-- Validation statistics and reporting
-- Interactive command-line interface
+## Getting Started
 
-## ✨ Features
+### Create the project
+1. Create folder `json-validator`.
+2. Inside, create `jsondatavalidator.py`.
 
-### Schema Management
-- **Custom Schemas**: Define and load custom JSON schemas
-- **File-based Schemas**: Load schemas from JSON files
-- **Built-in Schemas**: Pre-defined schemas for common data types
-- **Schema Information**: View detailed schema structure and requirements
+### Write the code
+<FileCode file="projects/beginners/jsondatavalidator.py" lang="python" title="JSON Validator" />
 
-### Validation Capabilities
-- **File Validation**: Validate JSON files against schemas
-- **String Validation**: Validate JSON strings directly
-- **Batch Validation**: Validate multiple files with pattern matching
-- **Real-time Validation**: Immediate feedback with detailed error messages
-
-### Error Reporting
-- **Detailed Errors**: Path-based error reporting with context
-- **Error Categories**: Type mismatches, missing fields, constraint violations
-- **Validation History**: Track all validation attempts and results
-- **Export Reports**: Generate comprehensive validation reports
+### Run it
+```bash title="run"
+python jsondatavalidator.py
+```
 
-### Data Generation
-- **Sample Data**: Generate valid sample data from schemas
-- **Schema Analysis**: Understand schema structure and requirements
-- **Testing Support**: Create test data for development and testing
+```
+1. Validate file
+2. Validate string
+3. Batch validate
+4. Generate sample
+5. Statistics
+6. Quit
+> 1
+Schema: user
+File: data.json
+✅ Valid
+```
 
-## 🛠️ Technical Implementation
+## A Tiny JSON Schema Example
 
-### Class Structure
-```python title="jsondatavalidator.py" showLineNumbers{1}
-class ValidationError:
-    def __init__(self, path, message, expected=None, actual=None):
-        # Detailed error information with context
-        # Path tracking for nested validation errors
-
-class JSONSchema:
-    def __init__(self, schema):
-        # Schema definition and validation logic
-        # Recursive validation for nested structures
-    
-    def validate(self, data, path="root"):
-        # Main validation entry point
-        # Returns validation status and error list
-
-class JSONDataValidator:
-    def __init__(self):
-        # Validator management and schema storage
-        # Validation history and statistics tracking
+```json title="user_schema.json"
+{
+  "type": "object",
+  "required": ["name", "email", "age"],
+  "properties": {
+    "name":   {"type": "string", "minLength": 2, "maxLength": 50},
+    "email":  {"type": "string", "pattern": "^.+@.+\\..+$"},
+    "age":    {"type": "integer", "minimum": 0, "maximum": 150},
+    "status": {"type": "string", "enum": ["active", "inactive", "pending"]},
+    "tags":   {"type": "array", "items": {"type": "string"}, "maxItems": 10}
+  }
+}
+```
+Matching data:
+```json title="user.json"
+{"name": "Madhur", "email": "m@example.com", "age": 30, "status": "active"}
 ```
 
-### Key Components
-
-#### Schema Validation
-- **Type Checking**: Validate data types (string, number, boolean, array, object)
-- **Constraint Validation**: Check length, range, pattern, and enum constraints
-- **Required Fields**: Ensure all required fields are present
-- **Nested Validation**: Recursive validation for complex data structures
-
-#### Error Handling
-- **Path Tracking**: Precise error location with JSON path notation
-- **Context Information**: Expected vs. actual value reporting
-- **Error Aggregation**: Collect all validation errors in single pass
-- **User-friendly Messages**: Clear, actionable error descriptions
-
-#### Data Processing
-- **JSON Parsing**: Robust JSON file and string parsing
-- **File Operations**: Safe file handling with error recovery
-- **Pattern Matching**: Glob pattern support for batch operations
-- **Data Serialization**: Export validation results and reports
-
-## 🚀 How to Run
-
-1. **Install Python**: Ensure Python 3.7+ is installed (uses built-in modules)
-2. **Run the Validator**:
-   ```bash
-   python jsondatavalidator.py
-   ```
-
-3. **Getting Started**:
-   - Explore pre-loaded sample schemas
-   - Validate sample JSON files
-   - Create custom schemas for your data
-   - Generate sample data for testing
-
-## 💡 Usage Examples
-
-### Basic Validation
-```python title="jsondatavalidator.py" showLineNumbers{1}
-# Create validator instance
-validator = JSONDataValidator()
-
-# Add a simple schema
-user_schema = {
-    "type": "object",
-    "required": ["name", "email"],
-    "properties": {
-        "name": {"type": "string", "minLength": 2},
-        "email": {"type": "string", "pattern": r"^.+@.+\..+$"}
-    }
-}
-validator.add_schema("user", user_schema)
+## Step-by-Step Explanation
 
-# Validate data
-user_data = {"name": "John", "email": "john@example.com"}
-is_valid, errors = validator.validate_data(user_data, "user")
+### 1. The error type
+```python title="error.py"
+from dataclasses import dataclass
 
-if is_valid:
-    print("✅ Validation successful!")
-else:
-    for error in errors:
-        print(f"❌ {error}")
+@dataclass
+class ValidationError:
+    path: str            # e.g. "root.users[0].email"
+    message: str         # e.g. "expected string, got int"
+    expected: str = ""
+    actual: str = ""
+
+    def __str__(self):
+        return f"{self.path}: {self.message}" + (
+            f" (expected {self.expected}, got {self.actual})"
+            if self.expected else "")
 ```
+Path-tracked errors are the single biggest UX improvement over a plain `True/False` validator. Users learn *what* is wrong *where*.
 
-### File Validation
-```python title="jsondatavalidator.py" showLineNumbers{1}
-# Validate JSON file
-is_valid, errors = validator.validate_file("data.json", "user")
+### 2. The validator
+```python title="validator.py"
+import re
+
+TYPE_MAP = {
+    "string": str, "integer": int, "number": (int, float),
+    "boolean": bool, "array": list, "object": dict, "null": type(None),
+}
 
-# Batch validate multiple files
-results = validator.batch_validate("data/*.json", "user")
-for file_path, (is_valid, errors) in results.items():
-    print(f"{file_path}: {'✅' if is_valid else '❌'} ({len(errors)} errors)")
+def validate(data, schema, path="root") -> list[ValidationError]:
+    errors = []
+    expected_type = schema.get("type")
+    if expected_type:
+        py_type = TYPE_MAP.get(expected_type)
+        if py_type and not isinstance(data, py_type):
+            errors.append(ValidationError(path, "wrong type",
+                                          expected=expected_type,
+                                          actual=type(data).__name__))
+            return errors                     # type mismatch — skip further checks
+
+    if expected_type == "string":
+        if "minLength" in schema and len(data) < schema["minLength"]:
+            errors.append(ValidationError(path, f"shorter than {schema['minLength']}"))
+        if "maxLength" in schema and len(data) > schema["maxLength"]:
+            errors.append(ValidationError(path, f"longer than {schema['maxLength']}"))
+        if "pattern" in schema and not re.match(schema["pattern"], data):
+            errors.append(ValidationError(path, f"does not match pattern {schema['pattern']}"))
+        if "enum" in schema and data not in schema["enum"]:
+            errors.append(ValidationError(path,
+                f"not in {schema['enum']}", actual=str(data)))
+
+    elif expected_type in ("integer", "number"):
+        if "minimum" in schema and data < schema["minimum"]:
+            errors.append(ValidationError(path, f"less than {schema['minimum']}"))
+        if "maximum" in schema and data > schema["maximum"]:
+            errors.append(ValidationError(path, f"greater than {schema['maximum']}"))
+
+    elif expected_type == "array":
+        if "minItems" in schema and len(data) < schema["minItems"]:
+            errors.append(ValidationError(path, f"fewer than {schema['minItems']} items"))
+        if "maxItems" in schema and len(data) > schema["maxItems"]:
+            errors.append(ValidationError(path, f"more than {schema['maxItems']} items"))
+        if "uniqueItems" in schema and len(set(map(repr, data))) != len(data):
+            errors.append(ValidationError(path, "items not unique"))
+        if "items" in schema:
+            for i, item in enumerate(data):
+                errors += validate(item, schema["items"], f"{path}[{i}]")
+
+    elif expected_type == "object":
+        for key in schema.get("required", []):
+            if key not in data:
+                errors.append(ValidationError(path, f"missing required '{key}'"))
+        for key, sub in schema.get("properties", {}).items():
+            if key in data:
+                errors += validate(data[key], sub, f"{path}.{key}")
+        if schema.get("additionalProperties") is False:
+            extras = set(data) - set(schema.get("properties", {}))
+            for k in extras:
+                errors.append(ValidationError(path, f"unexpected property '{k}'"))
+
+    return errors
+```
+Two key design points:
+- **One recursive function** handles every level. Nested schemas validate themselves naturally.
+- **Errors accumulate** rather than short-circuiting. Users see *all* problems at once.
+
+### 3. Validate a file
+```python title="validate_file.py"
+import json
+from pathlib import Path
+
+def validate_file(path: str, schema: dict):
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    errors = validate(data, schema)
+    return (not errors), errors
+
+ok, errs = validate_file("user.json", user_schema)
+print("Valid!" if ok else "\n".join(str(e) for e in errs))
 ```
 
-### Schema Management
-```python title="jsondatavalidator.py" showLineNumbers{1}
-# Load schema from file
-validator.load_schema_from_file("user_schema.json", "user")
+### 4. Batch validate with glob patterns
+```python title="batch.py"
+def batch(pattern: str, schema: dict):
+    for p in Path().glob(pattern):
+        ok, errs = validate_file(str(p), schema)
+        print(f"{'✅' if ok else '❌'} {p}  ({len(errs)} errors)")
 
-# Get schema information
-schema_info = validator.get_schema_info("user")
-print(json.dumps(schema_info, indent=2))
+batch("data/*.json", user_schema)
+```
 
-# Generate sample data
-sample_data = validator.create_sample_data("user")
-print(json.dumps(sample_data, indent=2))
+### 5. Generate sample data
+Useful for fixtures and tests:
+```python title="sample.py"
+def sample(schema: dict):
+    t = schema.get("type")
+    if t == "string":  return schema.get("enum", ["example"])[0]
+    if t == "integer": return schema.get("minimum", 0)
+    if t == "number":  return float(schema.get("minimum", 0))
+    if t == "boolean": return True
+    if t == "array":   return [sample(schema["items"])] if "items" in schema else []
+    if t == "object":
+        return {k: sample(v) for k, v in schema.get("properties", {}).items()}
+    return None
 ```
+Run on a schema → get a fully-typed valid JSON example for documentation or tests.
 
-## 🎨 Interactive Features
+## Common Mistakes
 
-### Main Menu Options
-1. **Validate JSON File** - Validate single file against schema
-2. **Validate JSON String** - Validate JSON input directly
-3. **Batch Validate Files** - Validate multiple files with patterns
-4. **Load Schema from File** - Import schema from JSON file
-5. **Add Schema Manually** - Define schema interactively
-6. **View Schema Info** - Explore schema structure
-7. **Generate Sample Data** - Create valid sample data
-8. **View Validation Statistics** - Analytics dashboard
-9. **Export Validation Report** - Generate detailed reports
-10. **List Available Schemas** - View loaded schemas
+| Problem | Cause | Fix |
+|---|---|---|
+| `True` passes `"type": "integer"` check | Python's `bool` is a subclass of `int` | Check `type(x) is int`, not `isinstance` |
+| Pattern always matches | Used `re.match` for partial matches | Use `re.fullmatch` for full-string match |
+| Error message says "root" only | Did not pass path down | Always include `f"{path}.{key}"` in recursive call |
+| Numbers wrongly rejected | Forgot `int + float` for `"number"` | `TYPE_MAP["number"] = (int, float)` |
+| Nested `additionalProperties` not enforced | Only checked at top level | Recurse properly |
+| Schema author typo silently ignored | No schema-of-schemas check | Validate the schema itself before using |
 
-### Pre-loaded Sample Schemas
+## Comparison to Production Libraries
 
-#### User Schema
-```json
-{
-  "type": "object",
-  "required": ["name", "email", "age"],
-  "properties": {
-    "name": {"type": "string", "minLength": 2, "maxLength": 50},
-    "email": {"type": "string", "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"},
-    "age": {"type": "integer", "minimum": 0, "maximum": 150},
-    "status": {"type": "string", "enum": ["active", "inactive", "pending"]}
-  }
-}
+### `jsonschema` (spec-compliant)
+```bash title="install"
+pip install jsonschema
 ```
-
-#### Product Schema
-```json
-{
-  "type": "object",
-  "required": ["name", "price", "category"],
-  "properties": {
-    "name": {"type": "string", "minLength": 1, "maxLength": 100},
-    "price": {"type": "number", "minimum": 0},
-    "category": {"type": "string", "enum": ["electronics", "clothing", "books"]},
-    "tags": {"type": "array", "items": {"type": "string"}, "maxItems": 10}
-  }
-}
+```python title="jsonschema_use.py"
+from jsonschema import validate, ValidationError
+try:
+    validate(instance=data, schema=schema)
+except ValidationError as e:
+    print(e.message, e.absolute_path)
 ```
+Handles full **Draft 2020-12** spec: `$ref`, `oneOf`, `anyOf`, `allOf`, conditional schemas, format checks, custom keywords.
 
-## 🔧 Advanced Features
-
-### Constraint Types
-
-#### String Constraints
-- **minLength/maxLength**: String length validation
-- **pattern**: Regular expression pattern matching
-- **enum**: Allowed values from predefined list
-
-#### Number Constraints
-- **minimum/maximum**: Numeric range validation
-- **type**: Distinguish between integer and float
-
-#### Array Constraints
-- **minItems/maxItems**: Array length validation
-- **items**: Schema for array elements
-- **uniqueItems**: Ensure array elements are unique
-
-#### Object Constraints
-- **required**: List of required properties
-- **properties**: Schema for object properties
-- **additionalProperties**: Control extra properties
-
-### Error Reporting
-```python title="jsondatavalidator.py" showLineNumbers{1}
-# Example validation error
-ValidationError(
-    path="root.users[0].email",
-    message="String does not match pattern",
-    expected="email pattern",
-    actual="invalid-email"
-)
+### `pydantic` (type-driven)
+```bash title="install"
+pip install pydantic
 ```
+```python title="pydantic_use.py"
+from pydantic import BaseModel, Field, EmailStr
 
-### Batch Validation
-```python title="jsondatavalidator.py" showLineNumbers{1}
-# Validate all JSON files in directory
-results = validator.batch_validate("data/*.json", "user")
+class User(BaseModel):
+    name: str = Field(min_length=2, max_length=50)
+    email: EmailStr
+    age: int = Field(ge=0, le=150)
 
-# Advanced pattern matching
-results = validator.batch_validate("**/config.json", "config")
+User.model_validate({"name": "M", "email": "m@x.com", "age": 30})
+# raises ValidationError with errors at .errors()
 ```
+Schemas *are* Python classes. Faster, friendlier, IDE-autocomplete-aware. Used by FastAPI, LangChain, and most modern Python web stacks.
 
-## 📊 Statistics and Reporting
+### When to use which
 
-### Validation Statistics
-```python title="jsondatavalidator.py" showLineNumbers{1}
-{
-  'total_validations': 25,
-  'successful_validations': 20,
-  'failed_validations': 5,
-  'success_rate': 80.0,
-  'schema_usage': {
-    'user': 15,
-    'product': 10
-  },
-  'total_errors': 12,
-  'loaded_schemas': ['user', 'product', 'config']
-}
-```
+| Use | Tool |
+|---|---|
+| Quick one-off check | Build it yourself (this project) |
+| Full JSON Schema compliance | `jsonschema` |
+| Pythonic API definitions | `pydantic` |
+| OpenAPI auto-generation | `pydantic` + FastAPI |
+| Schema generation for non-Python consumers | `jsonschema` (export from `pydantic`) |
 
-### Validation Report
-```json
-{
-  "generated_at": "2024-01-01T12:00:00.000000",
-  "total_validations": 25,
-  "successful_validations": 20,
-  "failed_validations": 5,
-  "results": [
-    {
-      "timestamp": "2024-01-01T12:00:00.000000",
-      "schema_name": "user",
-      "is_valid": true,
-      "error_count": 0,
-      "errors": []
-    }
-  ]
-}
-```
+## Variations to Try
 
-## 🛡️ Error Handling
-
-- **JSON Parsing**: Graceful handling of malformed JSON
-- **File Operations**: Safe file reading with error recovery
-- **Schema Validation**: Comprehensive error checking and reporting
-- **Type Safety**: Runtime type checking and validation
-
-## 📚 Learning Objectives
-
-- **JSON Schema**: Understanding JSON schema specification
-- **Data Validation**: Implementing robust validation logic
-- **Error Handling**: Comprehensive error reporting systems
-- **File Operations**: Safe file handling and processing
-- **Pattern Matching**: Working with glob patterns and regular expressions
-
-## 🎯 Real-world Applications
-
-### API Development
-- Validate API request/response data
-- Ensure data consistency across services
-- Generate API documentation from schemas
-- Create test data for API testing
-
-### Configuration Management
-- Validate application configuration files
-- Ensure required settings are present
-- Check configuration value constraints
-- Generate default configuration templates
-
-### Data Processing
-- Validate data imports and exports
-- Check data quality before processing
-- Ensure data format consistency
-- Generate sample data for testing
-
-## 🚀 Potential Enhancements
-
-1. **JSON Schema Draft Support**: Implement full JSON Schema Draft 7/2019-09
-2. **Custom Validators**: Allow custom validation functions
-3. **Web Interface**: Create Flask web application
-4. **Database Integration**: Store schemas and validation results in database
-5. **CLI Tool**: Command-line interface for automation
-6. **Plugin System**: Extensible validation framework
-7. **Performance Optimization**: Streaming validation for large files
-8. **Schema Registry**: Centralized schema management system
-
-## 🔍 Schema Examples
-
-### Complex Nested Schema
-```python title="jsondatavalidator.py" showLineNumbers{1}
-config_schema = {
-    "type": "object",
-    "required": ["app_name", "version", "database"],
-    "properties": {
-        "app_name": {"type": "string", "minLength": 1},
-        "version": {"type": "string", "pattern": r"^\d+\.\d+\.\d+$"},
-        "database": {
-            "type": "object",
-            "required": ["host", "port"],
-            "properties": {
-                "host": {"type": "string"},
-                "port": {"type": "integer", "minimum": 1, "maximum": 65535},
-                "ssl": {"type": "boolean"}
-            }
-        },
-        "features": {
-            "type": "array",
-            "items": {"type": "string"},
-            "uniqueItems": True
-        }
-    }
-}
-```
+### 1. Custom keywords
+Add `"isEmail"` or `"isUUID"` as schema-level shortcuts that map to specific patterns.
 
-### Sample Generated Data
-```json
-{
-  "app_name": "sample_string",
-  "version": "1.0.0",
-  "database": {
-    "host": "sample_string",
-    "port": 42,
-    "ssl": true
-  },
-  "features": ["sample_string"]
-}
+### 2. `$ref` resolution
+Lets schemas reference each other:
+```json title="ref.json"
+{"address": {"$ref": "#/definitions/address"}}
 ```
 
-## 🏆 Project Completion
+### 3. `oneOf` / `anyOf` / `allOf`
+Compose schemas. Email is "string AND matches email pattern AND length ≤ 254".
 
-This JSON Data Validator demonstrates:
-- ✅ Complete JSON schema validation implementation
-- ✅ Comprehensive error reporting and tracking
-- ✅ Batch processing and file operations
-- ✅ Data generation and schema analysis
-- ✅ Interactive user interface
-- ✅ Statistics and reporting capabilities
+### 4. JSON Schema → markdown docs
+Walk the schema and generate human-readable documentation for an API.
+
+### 5. CLI tool
+```bash title="cli"
+validator schema.json data.json
+validator --watch schema.json incoming/*.json
+```
 
-Perfect for beginners learning data validation concepts and intermediate developers working with JSON data processing and API development!
+### 6. Web service
+Flask endpoint that accepts schema + data and returns `{"valid": bool, "errors": [...]}`. See [Basic Web Server](./basicwebserver).
+
+### 7. Live validation in a GUI
+Tkinter with a JSON text area and a schema dropdown — errors highlight in real time.
+
+### 8. Streaming validation
+Validate huge JSON Lines files line-by-line with `ijson` to keep memory bounded.
+
+### 9. Schema inference
+Read a sample of valid JSON, *infer* a permissive schema from it. Useful for legacy systems with no docs.
+
+### 10. Mock data generation
+`sample(schema)` already does the basic case. Add `random` for varied output, plus locale-aware names/emails via `Faker`.
+
+## Real-World Applications
+- **API request/response validation** — at every layer of a microservices system.
+- **Config-file validation** — fail fast on bad YAML/JSON at startup.
+- **ETL pipelines** — reject malformed records before they corrupt downstream.
+- **CI / data-quality** — automated checks that incoming data matches contract.
+- **Documentation generation** — schemas become user-facing docs automatically.
+- **OpenAPI / Swagger** — REST APIs document themselves via JSON Schema.
+
+## Educational Value
+- **Recursive algorithms** — schema and data are both trees; you walk them in parallel.
+- **Error reporting UX** — path tracking is the difference between debug joy and debug despair.
+- **Standards (JSON Schema spec)** — interoperability with thousands of tools.
+- **Library evaluation** — knowing when "build it yourself" beats "pip install" and vice versa.
+- **Code generation** — from schema to sample, from schema to docs, from schema to types.
+
+## Next Steps
+- Add **`additionalProperties: false`** enforcement throughout.
+- Implement **`$ref`** for cross-schema references.
+- Add **`oneOf` / `anyOf`** support for sum types.
+- Compare your output to **`jsonschema`** on the same data.
+- Re-implement using **`pydantic`** classes and feel the speed.
+- Wrap with a **CLI** or **web frontend**.
+
+## Conclusion
+You built a recursive JSON Schema validator that catches type errors, constraint violations, and missing fields with precise error messages. The same shape (data tree + schema tree + recursive walk) underlies every validator in every web framework. From here, switching to `jsonschema` or `pydantic` is incremental — they speak the same language; they just speak it faster and more completely. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/jsondatavalidator.py). Find more data-tooling projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/morsecodetranslator.mdx b/src/content/docs/projects/Beginners/morsecodetranslator.mdx
index cfad7c51..1cb3f237 100644
--- a/src/content/docs/projects/Beginners/morsecodetranslator.mdx
+++ b/src/content/docs/projects/Beginners/morsecodetranslator.mdx
@@ -1,6 +1,6 @@
 ---
 title: Morse Code Translator
-description: A Python application that translates text to Morse code and vice versa, with audio playback functionality for learning and practicing Morse code communication.
+description: Build a Python translator for text ↔ Morse code with audio playback. Learn dictionary inversion, encoding/decoding patterns, cross-platform audio, real Morse timing, and a Tkinter GUI.
 sidebar: 
     order: 25
 hero:
@@ -13,275 +13,221 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Morse Code Translator is a Python application that provides bidirectional translation between regular text and Morse code. The application features a comprehensive Morse code dictionary, text-to-Morse conversion, Morse-to-text conversion, and audio playback functionality using system beeps. This project demonstrates dictionary manipulation, string processing, audio programming, and menu-driven interface design. It's an excellent tool for learning Morse code and understanding historical communication methods.
+Morse code was the first global digital encoding — used over telegraph wires, ship-to-shore radio, and emergency signaling for over a century. In this project you build a Python translator that converts text to Morse code and back, plays the code as audio beeps using realistic dot-dash-space timing, and supports the full International Morse alphabet including punctuation. Then we add a Tkinter GUI, cross-platform audio (no more Windows-only `winsound`), visual signaling with screen flashes, and an audio decoder that listens to Morse and transcribes it.
+
+You will learn:
+- The exact mapping between characters and Morse symbols.
+- How to invert a dictionary cleanly for reverse lookup.
+- Realistic Morse timing (the 1:3:1:3:7 rule).
+- Cross-platform audio generation with NumPy and sounddevice.
+- How to encode and decode digital signals — a foundation for any communications project.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Windows OS (for winsound module) or alternative audio library
+- Python 3.6 or above.
+- A text editor or IDE.
+- Speakers (for audio playback).
+- Familiarity with dictionaries and string iteration.
+
+## Install Dependencies
+The basic version uses only built-ins. For cross-platform audio:
+```cmd title="install"
+pip install numpy sounddevice
+```
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-**Note:** This project uses the `winsound` module which is Windows-specific. For other operating systems, you can modify the audio playback function to use alternative libraries like `pygame` or `playsound`.
+### Create the project
+1. Create folder `morse-code-translator`.
+2. Inside, create `morsecodetranslator.py`.
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `morse-code-translator`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `morsecodetranslator.py`.
-4. Copy the given code and paste it in your `morsecodetranslator.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `morsecodetranslator.py` file.
-<FileCode file="projects/beginners/morsecodetranslator.py" lang="python" title="Morse Code Translator" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `morse-code-translator`.
-```cmd title="command" showLineNumbers{1} {1-25}
-C:\Users\Your Name\morse-code-translator> python morsecodetranslator.py
-Morse Code Translator
-1. Translate to Morse Code
-2. Translate to Text
-3. Play Morse Code
-4. Exit
-Enter your choice: 1
-Enter the text to translate to Morse Code: HELLO
-Morse Code: .... . .-.. .-.. --- 
+### Write the code
+<FileCode file="projects/beginners/morsecodetranslator.py" lang="python" title="Morse Translator" />
 
-Morse Code Translator
+### Run it
+```cmd title="command"
+C:\Users\Your Name\morse-code-translator> python morsecodetranslator.py
 1. Translate to Morse Code
 2. Translate to Text
 3. Play Morse Code
 4. Exit
-Enter your choice: 2
-Enter the Morse Code to translate to Text: .... . .-.. .-.. ---
+Choice: 1
 Text: HELLO
-
-Morse Code Translator
-1. Translate to Morse Code
-2. Translate to Text
-3. Play Morse Code
-4. Exit
-Enter your choice: 3
-Enter the Morse Code to play: ... --- ...
-# Audio beeps will play the SOS pattern
+Morse: .... . .-.. .-.. ---
 ```
 
-## Explanation
-
-### Morse Code Dictionary
-The application uses a comprehensive dictionary mapping characters to Morse code:
-```python title="morsecodetranslator.py" showLineNumbers{1} {1-10}
-morse_code = {
-    'A': '.-', 'B': '-...', 'C': '-.-.', 'D': '-..', 'E': '.',
-    'F': '..-.', 'G': '--.', 'H': '....', 'I': '..', 'J': '.---',
-    'K': '-.-', 'L': '.-..', 'M': '--', 'N': '-.', 'O': '---',
-    'P': '.--.', 'Q': '--.-', 'R': '.-.', 'S': '...', 'T': '-',
-    'U': '..-', 'V': '...-', 'W': '.--', 'X': '-..-', 'Y': '-.--',
-    'Z': '--..', '0': '-----', '1': '.----', '2': '..---', '3': '...--',
-    '4': '....-', '5': '.....', '6': '-....', '7': '--...', '8': '---..',
-    '9': '----.', ' ': ' ', ',': '--..--', '.': '.-.-.-', '?': '..--..',
-    '/': '-..-.', '-': '-....-', '(': '-.--.', ')': '-.--.-'
+## The Morse Code Table
+
+```python title="codes.py"
+MORSE = {
+    "A": ".-",    "B": "-...",  "C": "-.-.",  "D": "-..",
+    "E": ".",     "F": "..-.",  "G": "--.",   "H": "....",
+    "I": "..",    "J": ".---",  "K": "-.-",   "L": ".-..",
+    "M": "--",    "N": "-.",    "O": "---",   "P": ".--.",
+    "Q": "--.-",  "R": ".-.",   "S": "...",   "T": "-",
+    "U": "..-",   "V": "...-",  "W": ".--",   "X": "-..-",
+    "Y": "-.--",  "Z": "--..",
+    "0": "-----", "1": ".----", "2": "..---", "3": "...--",
+    "4": "....-", "5": ".....", "6": "-....", "7": "--...",
+    "8": "---..", "9": "----.",
+    ".": ".-.-.-", ",": "--..--", "?": "..--..", "/": "-..-.",
+    "(": "-.--.",  ")": "-.--.-", "-": "-....-",
 }
+TEXT = {v: k for k, v in MORSE.items()}     # reverse lookup, built in one line
 ```
-
-### Core Functions
-
-#### 1. Text to Morse Code Translation
-```python title="morsecodetranslator.py" showLineNumbers{1} {1-5}
-def translate_to_morse_code(text):
-    morse_code_text = ''
-    for letter in text:
-        morse_code_text += morse_code[letter.upper()] + ' '
-    return morse_code_text
+The dictionary-comprehension `{v: k for k, v in MORSE.items()}` is the cleanest way to invert a dict.
+
+## Step-by-Step Explanation
+
+### 1. Text → Morse
+```python title="encode.py"
+def to_morse(text: str) -> str:
+    parts = []
+    for ch in text.upper():
+        if ch == " ":
+            parts.append("/")             # word separator
+        elif ch in MORSE:
+            parts.append(MORSE[ch])
+        # silently skip unknown characters
+    return " ".join(parts)
 ```
-
-#### 2. Morse Code to Text Translation
-```python title="morsecodetranslator.py" showLineNumbers{1} {1-15}
-def translate_to_text(morse_code_text):
-    text = ''
-    morse_code_text += ' '
-    letter = ''
-    for symbol in morse_code_text:
-        if symbol != ' ':
-            i = 0
-            letter += symbol
-        else:
-            i += 1
-            if i == 2:
-                text += ' '
+- Letters are separated by **one space**.
+- Words are separated by `" / "` (a slash with spaces around it) — the International convention.
+
+### 2. Morse → Text
+```python title="decode.py"
+def from_morse(morse: str) -> str:
+    out = []
+    for word in morse.split(" / "):
+        letters = []
+        for code in word.split():
+            if code in TEXT:
+                letters.append(TEXT[code])
             else:
-                text += list(morse_code.keys())[list(morse_code.values()).index(letter)]
-                letter = ''
-    return text
+                letters.append("?")        # unknown code
+        out.append("".join(letters))
+    return " ".join(out)
 ```
-
-#### 3. Audio Playback Function
-```python title="morsecodetranslator.py" showLineNumbers{1} {1-8}
-def play_morse_code(morse_code_text):
-    for symbol in morse_code_text:
-        if symbol == '.':
-            winsound.Beep(1000, 100)  # Short beep (dot)
-        elif symbol == '-':
-            winsound.Beep(1000, 300)  # Long beep (dash)
-        else:
-            time.sleep(0.5)  # Pause between letters
+Two split levels: words on `/`, letters on whitespace.
+
+### 3. Audio playback
+The original used Windows-only `winsound`. Here is the cross-platform version using NumPy + sounddevice:
+```python title="play.py"
+import numpy as np
+import sounddevice as sd
+
+UNIT = 0.08            # seconds per "dit" (dot)
+FREQ = 700             # Hz
+
+def tone(seconds):
+    t = np.linspace(0, seconds, int(seconds * 44100), endpoint=False)
+    wave = 0.4 * np.sin(2 * np.pi * FREQ * t)
+    sd.play(wave, 44100); sd.wait()
+
+def silence(seconds):
+    sd.play(np.zeros(int(seconds * 44100)), 44100); sd.wait()
+
+def play_morse(morse: str):
+    for sym in morse:
+        if   sym == ".": tone(UNIT)
+        elif sym == "-": tone(UNIT * 3)
+        elif sym == " ": silence(UNIT * 3)
+        elif sym == "/": silence(UNIT * 7)
+        # intra-character gap (between dots/dashes of a letter) = 1 unit
+        silence(UNIT)
+```
+A clean, smooth sine wave instead of harsh beeps.
+
+## Real Morse Timing — The 1:3:1:3:7 Rule
+
+International Morse defines all durations as multiples of one **"unit"**:
+- **Dot (·)**: 1 unit on.
+- **Dash (−)**: 3 units on.
+- **Intra-character gap** (between dots/dashes of the same letter): 1 unit off.
+- **Inter-character gap** (between letters): 3 units off.
+- **Inter-word gap** (between words): 7 units off.
+
+A speed of "20 WPM" (words per minute) means roughly 60 ms per unit. Slow learners use 100 ms; experts use 30 ms.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `KeyError: 'h'` | Forgot to uppercase | `ch = ch.upper()` |
+| Wrong character on decode | Whitespace mismatch (multiple spaces) | `morse.split()` (splits on any whitespace) |
+| Reverse lookup wrong character | Manual inversion left bugs | Use `{v: k for k, v in MORSE.items()}` |
+| Words run together on decode | No `/` separator | Use `" / "` for word breaks |
+| Audio harsh and clicky | Square-wave beeps | Use a sine wave (NumPy) |
+| Only works on Windows | `winsound` | Use `sounddevice` + NumPy |
+
+## Variations to Try
+
+### 1. Visual flasher
+Replace audio with a Tkinter window that flashes:
+```python title="flash.py"
+def flash(seconds, color="white"):
+    label.config(bg=color); root.update(); time.sleep(seconds)
+    label.config(bg="black"); root.update(); time.sleep(UNIT)
 ```
+Useful for signaling at sea or for accessibility.
 
-## Features
-- **Bidirectional Translation:** Convert text to Morse code and Morse code back to text
-- **Comprehensive Character Set:** Supports letters, numbers, and common punctuation
-- **Audio Playback:** Listen to Morse code with system beeps
-- **Menu-Driven Interface:** Easy-to-use command-line menu system
-- **Recursive Menu:** Continuous operation until user chooses to exit
-- **Case Insensitive:** Handles both uppercase and lowercase input
-- **Real-time Processing:** Instant translation and playback
-
-## Morse Code Reference
-
-### Letters A-Z
-| Letter | Morse | Letter | Morse | Letter | Morse |
-|--------|-------|--------|-------|--------|-------|
-| A | .-    | J | .---  | S | ...   |
-| B | -...  | K | -.-   | T | -     |
-| C | -.-.  | L | .-..  | U | ..-   |
-| D | -..   | M | --    | V | ...-  |
-| E | .     | N | -.    | W | .--   |
-| F | ..-   | O | ---   | X | -..-  |
-| G | --.   | P | .--.  | Y | -.--  |
-| H | ....  | Q | --.-  | Z | --..  |
-| I | ..    | R | .-.   |   |       |
-
-### Numbers 0-9
-| Number | Morse Code | Number | Morse Code |
-|--------|------------|--------|------------|
-| 0 | ----- | 5 | ..... |
-| 1 | .---- | 6 | -.... |
-| 2 | ..--- | 7 | --... |
-| 3 | ...-- | 8 | ---.. |
-| 4 | ....- | 9 | ----. |
-
-### Common Punctuation
-| Symbol | Morse Code | Symbol | Morse Code |
-|--------|------------|--------|------------|
-| . | .-.-.- | ( | -.--. |
-| , | --..-- | ) | -.--.- |
-| ? | ..--.. | - | -....- |
-| / | -..-. |   |        |
-
-## Audio Timing Standards
-- **Dot (.):** 100ms beep at 1000Hz
-- **Dash (-):** 300ms beep at 1000Hz
-- **Letter spacing:** 500ms pause
-- **Word spacing:** Represented by spaces in input
-
-## Use Cases
-- **Emergency Communications:** Learn SOS (... --- ...) and other distress signals
-- **Amateur Radio:** Practice for ham radio licensing
-- **Educational:** Teaching communication history and methods
-- **Military/Naval:** Understanding maritime and military communications
-- **Accessibility:** Alternative communication method for specific needs
+### 2. Tkinter GUI
+A window with a text input, output box, and "To Morse" / "To Text" / "Play" / "Stop" buttons. See [Currency Exchange Rate Calculator GUI](./currencyexchnageratecalculator) for the pattern.
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface with Tkinter or PyQt
-- Implementing adjustable playback speed and frequency
-- Adding visual Morse code display with flashing lights
-- Creating practice modes with random word generation
-- Adding file input/output for batch processing
-- Implementing prosigns (procedural signals) support
-- Adding Morse code keyboard input mode
-- Creating multiplayer Morse code games
-- Adding different audio tones and voices
-- Implementing Morse code over network communication
-
-## Cross-Platform Audio Support
-For non-Windows systems, replace the audio function:
-
-### Using pygame (Cross-platform)
-```python title="morsecodetranslator.py" showLineNumbers{1}
-import pygame
-pygame.mixer.init()
-
-def play_morse_code_pygame(morse_code_text):
-    for symbol in morse_code_text:
-        if symbol == '.':
-            # Generate and play short tone
-            play_tone(1000, 100)
-        elif symbol == '-':
-            # Generate and play long tone
-            play_tone(1000, 300)
-        else:
-            time.sleep(0.5)
-```
+### 3. WAV file export
+Concatenate the audio array and save as `output.wav` with `scipy.io.wavfile.write`.
 
-### Using playsound (Cross-platform)
-```python title="morsecodetranslator.py" showLineNumbers{1}
-from playsound import playsound
-import tempfile
-import wave
+### 4. Audio decoder
+Use `sounddevice.rec` to capture mic input. Detect peaks above a threshold, measure their duration, and classify as dot/dash. Match gaps to find letter and word boundaries. The hardest part is choosing a sensible threshold — adaptive amplitude detection helps.
 
-def create_morse_audio(morse_code_text):
-    # Generate audio file and play
-    pass
-```
+### 5. Adjustable speed
+A `Scale` widget controls WPM. Recalculate `UNIT = 1.2 / wpm` on every change.
 
-## Educational Applications
-- **Morse Code Learning:** Interactive way to learn the code
-- **Historical Education:** Understanding telegraph communication
-- **STEM Projects:** Combining technology with history
-- **Accessibility Training:** Alternative communication methods
-- **Emergency Preparedness:** Learning distress signals
-
-## Advanced Features Ideas
-```python title="morsecodetranslator.py" showLineNumbers{1}
-def enhanced_morse_translator():
-    # Features to implement:
-    # - GUI interface with visual indicators
-    # - Adjustable speed and pitch
-    # - Practice mode with scoring
-    # - File batch processing
-    # - Network transmission
-    # - Visual light patterns
-    pass
-
-class MorseCodeTrainer:
-    def __init__(self):
-        self.difficulty_level = 1
-        self.practice_words = []
-        self.user_stats = {}
-    
-    def generate_practice_session(self):
-        # Create random practice sessions
-        pass
-```
+### 6. Prosigns
+Support `<SK>` (end of contact), `<AR>` (end of message), `<BT>` (new paragraph), `<KN>` (named station only).
 
-## Common Morse Code Phrases
-- **SOS:** ... --- ... (International distress signal)
-- **CQ:** -.-. --.- (General call to any station)
-- **QRT:** --.- .-. - (Stopping transmission)
-- **73:** --... ...-- (Best wishes - amateur radio)
+### 7. Practice mode
+Generate random words; player types what they hear. Score and high-score tracking.
 
-## Performance Considerations
-- **Memory Usage:** Efficient dictionary lookup operations
-- **Audio Quality:** Consistent timing for clear communication
-- **Response Time:** Quick translation for real-time use
-- **Error Handling:** Graceful handling of invalid input
+### 8. Light-pulse output
+Pair with a Raspberry Pi and an LED — physically blink the Morse code.
 
-## Educational Value
-This project teaches:
-- **Dictionary Operations:** Key-value mapping and reverse lookup
-- **String Processing:** Character-by-character text manipulation
-- **Audio Programming:** System sound generation and timing
-- **Menu Design:** User interface and navigation logic
-- **Historical Technology:** Understanding communication evolution
+### 9. Network transmission
+Send Morse over a TCP socket between two computers — a working "telegraph network".
+
+### 10. Multi-language
+Cyrillic, Greek, Japanese Wabun all have their own Morse mappings.
+
+## Common Morse Phrases
+
+| Phrase | Morse | Meaning |
+|---|---|---|
+| **SOS** | `... --- ...` | International distress signal (note: not "Save Our Souls" — chosen for being unambiguous) |
+| **CQ** | `-.-. --.-` | "Calling any station" |
+| **73** | `--... ...--` | "Best regards" — ham radio sign-off |
+| **88** | `---.. ---..` | "Love and kisses" |
+| **QTH** | `--.- - ....` | "What is your location?" |
+| **QRT** | `--.- .-. -` | "Stop transmitting" |
 
 ## Real-World Applications
-- **Emergency Communication:** Backup communication method
-- **Amateur Radio:** Ham radio operation and practice
-- **Maritime Communication:** Ship-to-shore signaling
-- **Aviation:** Aircraft communication protocols
-- **Military Operations:** Field communication training
+- **Amateur radio (ham)** — Morse is still active on shortwave bands.
+- **Aviation** — VOR/NDB navigation beacons identify themselves in Morse.
+- **Emergency signaling** — light/sound SOS without electronics.
+- **Accessibility** — single-switch input device for people with severe motor disabilities.
+- **Education** — teaching encoding, timing, and digital communication concepts.
+
+## Educational Value
+- **Dictionary inversion** — one of the most common Python idioms.
+- **Encoding & decoding** — generalizes to any symbol-substitution cipher.
+- **Audio generation** — sine waves, sample rates, NumPy basics.
+- **Timing-sensitive code** — what real-time means in practice.
+- **Cross-platform thinking** — Windows vs. Linux vs. macOS audio APIs.
+
+## Next Steps
+- Replace **`winsound`** with the **NumPy + sounddevice** version above.
+- Add a **Tkinter GUI** with text fields and a "play" button.
+- Build an **audio decoder** that listens to Morse and transcribes it.
+- Add **adjustable WPM**.
+- Combine with [Basic Music Player](./basicmusicplayer) for richer audio.
 
 ## Conclusion
-In this project, we learned how to create a Morse Code Translator that demonstrates dictionary operations, string processing, and audio programming in Python. The application provides a practical tool for learning and practicing Morse code while showcasing fundamental programming concepts. This project bridges historical communication methods with modern programming techniques, offering both educational value and practical utility. To find more projects like this, you can visit Python Central Hub.
+You built a translator that handles letters, digits, punctuation, and audio playback — the same building blocks every digital communication protocol uses. From the perspective of encoding theory, Morse is the simplest "variable-length prefix code" you can study, and the same principles power UTF-8 and Huffman coding. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/morsecodetranslator.py). Find more encoding projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/movie-recommendation-system.mdx b/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
index 21b72632..82319070 100644
--- a/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
+++ b/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
@@ -1,6 +1,6 @@
 ---
 title: Movie Recommendation System (Basic)
-description: An intelligent movie recommendation system using collaborative filtering, content-based filtering, and hybrid approaches to suggest personalized movie recommendations
+description: Build a Python recommender with collaborative filtering, content-based filtering, and a hybrid model. Learn Pearson similarity, cold-start handling, matrix factorization, and TMDB API integration.
 sidebar:
   order: 48
 hero:
@@ -13,304 +13,262 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A recommendation system is a small but real machine-learning project. In ~300 lines you implement two foundational algorithms — **collaborative filtering** ("users like you also enjoyed...") and **content-based filtering** ("because you liked Action, Sci-Fi..."), then blend them in a **hybrid** model. The data is a list of movies with genres and a user-ratings table. The math is Pearson correlation and weighted scoring. The result genuinely surprises you with non-obvious suggestions.
 
-An intelligent movie recommendation system that provides personalized movie suggestions using multiple recommendation algorithms including collaborative filtering, content-based filtering, and hybrid approaches. This project demonstrates machine learning concepts, data analysis, and recommendation algorithms.
+You will learn:
+- The two foundational recommendation paradigms and their trade-offs.
+- How Pearson correlation measures rating-pattern similarity.
+- Why content-based filtering solves the cold-start problem.
+- How to blend recommenders for robustness.
+- The path from this toy to production-grade matrix factorization (SVD, ALS).
 
-## 🎯 Project Overview
+## Prerequisites
+- Python 3.7 or above (for `dataclasses`).
+- A text editor or IDE.
+- Comfort with classes, dictionaries, and basic statistics.
+- Familiarity with [Personal Diary](./personaldiary) for the JSON-persistence pattern.
 
-This project implements a comprehensive movie recommendation system featuring:
-- User registration and rating system
-- Multiple recommendation algorithms
-- Movie database with genres and ratings
-- Statistical analysis and insights
-- Search and filtering capabilities
-- Data persistence using JSON storage
+## Getting Started
 
-## ✨ Features
+### Create the project
+1. Create folder `movie-recommender`.
+2. Inside, create `movierecommendationsystem.py`.
 
-### Recommendation Algorithms
-- **Collaborative Filtering**: Recommendations based on similar users' preferences
-- **Content-Based Filtering**: Suggestions based on movie genres and user preferences
-- **Hybrid Approach**: Combines both methods for better accuracy
-- **Pearson Correlation**: Measures user similarity for collaborative filtering
+### Write the code
+<FileCode file="projects/beginners/movierecommendationsystem.py" lang="python" title="Movie Recommender" />
 
-### User Management
-- **User Registration**: Create and manage user profiles
-- **Rating System**: Rate movies on a 1-5 scale
-- **Preference Learning**: Automatically discover favorite genres
-- **Rating History**: Track all user ratings and preferences
-
-### Movie Database
-- **Comprehensive Catalog**: Pre-loaded with popular movies
-- **Genre Classification**: Multi-genre support for accurate categorization
-- **Rating Analytics**: Average ratings and rating counts
-- **Search Functionality**: Find movies by title or genre
-
-### Analytics & Insights
-- **Top Rated Movies**: Discover highest-rated films
-- **Statistical Dashboard**: Database statistics and trends
-- **Genre Analysis**: Most popular genres and distributions
-- **User Profiles**: Personal rating history and preferences
-
-## 🛠️ Technical Implementation
-
-### Class Structure
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-class Movie:
-    def __init__(self, movie_id, title, genres, year=None):
-        # Movie metadata and rating management
-        # Automatic rating calculations
-    
-    def add_rating(self, rating):
-        # Add user rating and update averages
-    
-    def to_dict(self):
-        # Serialize movie data for storage
-
-class User:
-    def __init__(self, user_id, name):
-        # User profile and rating management
-        # Favorite genre tracking
-    
-    def rate_movie(self, movie_id, rating):
-        # Rate a movie and update preferences
-    
-    def update_favorite_genres(self, movies):
-        # Analyze ratings to determine favorite genres
-
-class MovieRecommendationSystem:
-    def __init__(self, data_file="movie_data.json"):
-        # Initialize system with data persistence
-        # Load existing data or create sample data
-```
-
-### Key Algorithms
-
-#### Collaborative Filtering
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-def calculate_user_similarity(self, user1_id, user2_id):
-    # Calculate Pearson correlation coefficient
-    # Find users with similar rating patterns
-    # Return similarity score between -1 and 1
-
-def get_user_based_recommendations(self, user_id, limit=10):
-    # Find similar users
-    # Aggregate recommendations from similar users
-    # Weight recommendations by user similarity
-    # Return top-rated movies from similar users
+### Run it
+```bash title="run"
+python movierecommendationsystem.py
 ```
 
-#### Content-Based Filtering
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-def get_content_based_recommendations(self, user_id, limit=10):
-    # Analyze user's favorite genres
-    # Score unrated movies based on genre preferences
-    # Consider movie ratings and popularity
-    # Return movies matching user's taste profile
 ```
-
-#### Hybrid Approach
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-def get_hybrid_recommendations(self, user_id, limit=10):
-    # Combine collaborative and content-based recommendations
-    # Apply weighted scoring (70% collaborative, 30% content-based)
-    # Merge and rank final recommendations
-    # Return diverse, personalized suggestions
-```
-
-## 🚀 How to Run
-
-1. **Install Python**: Ensure Python 3.7+ is installed
-2. **Run the System**:
-   ```bash
-   python movierecommendationsystem.py
-   ```
-
-3. **Getting Started**:
-   - Register as a new user or login with existing ID
-   - Browse and rate some movies to build your profile
-   - Get personalized recommendations
-   - Explore different recommendation types
-
-## 💡 Usage Examples
-
-### Basic Usage
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Create recommendation system
-system = MovieRecommendationSystem()
-
-# Add a new user
-user = system.add_user("John Doe")
-
-# Rate some movies
-system.rate_movie(user.id, 1, 5.0)  # Love "The Shawshank Redemption"
-system.rate_movie(user.id, 3, 4.5)  # Really like "The Dark Knight"
-system.rate_movie(user.id, 6, 4.0)  # Enjoy "Inception"
-
-# Get recommendations
-recommendations = system.get_hybrid_recommendations(user.id, 5)
-for movie in recommendations:
-    print(f"Recommended: {movie}")
+1. Register user
+2. Rate movie
+3. Get recommendations
+4. Browse / search
+5. Statistics
+6. Quit
+> 3
+User ID: 1
+Method: (1) collaborative  (2) content  (3) hybrid: 3
+1. The Dark Knight (4.8 expected)
+2. Pulp Fiction (4.6 expected)
+3. The Matrix (4.5 expected)
 ```
 
-### Advanced Features
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Find similar users
-similarity = system.calculate_user_similarity(user1_id, user2_id)
-print(f"User similarity: {similarity:.2f}")
+## Step-by-Step Explanation
 
-# Get genre-specific movies
-action_movies = system.get_movies_by_genre("Action")
+### 1. Data models
+```python title="models.py"
+@dataclass
+class Movie:
+    id: int
+    title: str
+    genres: list[str]
+    year: int | None = None
+    ratings: list[float] = field(default_factory=list)
 
-# Search for movies
-search_results = system.search_movies("dark knight")
+    @property
+    def avg(self) -> float:
+        return sum(self.ratings) / len(self.ratings) if self.ratings else 0.0
 
-# Get top-rated movies
-top_movies = system.get_top_rated_movies(10, min_ratings=5)
+@dataclass
+class User:
+    id: int
+    name: str
+    ratings: dict[int, float] = field(default_factory=dict)   # {movie_id: rating}
+
+    @property
+    def favorite_genres(self) -> list[str]:
+        scores = {}
+        for mid, r in self.ratings.items():
+            if r >= 4:
+                for g in movie_by_id[mid].genres:
+                    scores[g] = scores.get(g, 0) + 1
+        return sorted(scores, key=scores.get, reverse=True)
 ```
-
-### Analytics
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Get comprehensive statistics
-stats = system.get_movie_statistics()
-print(f"Total movies: {stats['total_movies']}")
-print(f"Most popular genres: {stats['most_common_genres']}")
+`@property` lets `user.favorite_genres` look like an attribute but compute fresh from current ratings every time.
+
+### 2. Pearson similarity
+```python title="pearson.py"
+import math
+
+def pearson(u: User, v: User) -> float:
+    common = set(u.ratings) & set(v.ratings)
+    if len(common) < 2: return 0.0           # too little overlap
+    n = len(common)
+    sum_u = sum(u.ratings[m] for m in common)
+    sum_v = sum(v.ratings[m] for m in common)
+    sq_u  = sum(u.ratings[m] ** 2 for m in common)
+    sq_v  = sum(v.ratings[m] ** 2 for m in common)
+    cross = sum(u.ratings[m] * v.ratings[m] for m in common)
+
+    num = cross - (sum_u * sum_v / n)
+    den = math.sqrt((sq_u - sum_u**2/n) * (sq_v - sum_v**2/n))
+    return num / den if den else 0.0
 ```
-
-## 🎨 Interactive Features
-
-### Main Menu System
-1. **Register/Login User** - User account management
-2. **Browse Movies** - View all movies or filter by genre
-3. **Search Movies** - Find movies by title
-4. **Rate Movie** - Add ratings to build your profile
-5. **Get Recommendations** - Choose from different recommendation types
-6. **View Top Rated Movies** - Discover highly-rated films
-7. **Add New Movie** - Expand the movie database
-8. **View Statistics** - Database analytics and insights
-9. **User Profile** - View your ratings and preferences
-
-### Recommendation Types
-- **User-based**: "Users like you also enjoyed..."
-- **Content-based**: "Because you liked [Genre]..."
-- **Hybrid**: "Personalized for you"
-
-## 📊 Sample Data
-
-The system comes pre-loaded with 20 popular movies including:
-- The Shawshank Redemption (1994) - Drama, Crime
-- The Dark Knight (2008) - Action, Crime, Drama
-- Inception (2010) - Action, Sci-Fi, Thriller
-- Pulp Fiction (1994) - Crime, Drama
-- The Matrix (1999) - Action, Sci-Fi
-
-Each movie includes:
-- Multiple genres for accurate categorization
-- Release year for temporal analysis
-- Pre-generated ratings for immediate functionality
-
-## 🔧 Advanced Features
-
-### Similarity Calculation
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Pearson correlation coefficient for user similarity
-def calculate_user_similarity(self, user1_id, user2_id):
-    # Find movies rated by both users
-    # Calculate correlation between rating patterns
-    # Return similarity score (-1 to 1)
+Pearson correlation is the standard similarity metric for collaborative filtering. It is **bias-aware** — two users with the same shape of opinions but different "harshness" still correlate strongly.
+
+### 3. Collaborative filtering
+```python title="collab.py"
+def collaborative(user: User, movies: dict, users: dict, k: int = 10):
+    scores = {}
+    for other_id, other in users.items():
+        if other_id == user.id: continue
+        sim = pearson(user, other)
+        if sim <= 0: continue
+        for mid, rating in other.ratings.items():
+            if mid in user.ratings: continue          # skip movies user already rated
+            scores.setdefault(mid, [0.0, 0.0])
+            scores[mid][0] += sim * rating            # weighted sum
+            scores[mid][1] += sim                     # normalization factor
+    ranked = sorted(
+        ((mid, num/den) for mid, (num, den) in scores.items() if den > 0),
+        key=lambda x: x[1], reverse=True)
+    return [movies[mid] for mid, _ in ranked[:k]]
 ```
-
-### Preference Learning
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Automatic genre preference detection
-def update_favorite_genres(self, movies):
-    # Analyze highly-rated movies (4.0+)
-    # Calculate average rating per genre
-    # Rank genres by preference strength
+Score = Σ(similarity × their_rating) / Σ similarity. The division produces a number on the rating scale, not just a ranking.
+
+### 4. Content-based filtering
+```python title="content.py"
+def content_based(user: User, movies: dict, k: int = 10):
+    if not user.favorite_genres:
+        return top_rated(movies, k)              # cold-start fallback
+    scores = {}
+    fav = set(user.favorite_genres[:3])
+    for mid, m in movies.items():
+        if mid in user.ratings: continue
+        overlap = len(set(m.genres) & fav)
+        if overlap == 0: continue
+        scores[mid] = overlap * (1 + m.avg)      # boost well-rated matches
+    return [movies[mid] for mid, _ in
+            sorted(scores.items(), key=lambda x: x[1], reverse=True)[:k]]
 ```
-
-### Weighted Recommendations
-```python title="movierecommendationsystem.py" showLineNumbers{1}
-# Hybrid scoring system
-score = (collaborative_score * 0.7) + (content_score * 0.3)
+Score = (genre overlap) × (1 + average rating). New users with no ratings get the top-rated list as a fallback — the **cold-start** solution.
+
+### 5. Hybrid
+```python title="hybrid.py"
+def hybrid(user, movies, users, k=10):
+    collab = collaborative(user, movies, users, k * 2)
+    content = content_based(user, movies, k * 2)
+    score = {}
+    for i, m in enumerate(collab):  score[m.id] = score.get(m.id, 0) + 0.7 * (len(collab) - i)
+    for i, m in enumerate(content): score[m.id] = score.get(m.id, 0) + 0.3 * (len(content) - i)
+    return [movies[mid] for mid, _ in
+            sorted(score.items(), key=lambda x: x[1], reverse=True)[:k]]
 ```
-
-## 📈 Data Structure
-
-### Movie Format
-```json
-{
-  "id": 1,
-  "title": "The Shawshank Redemption",
-  "genres": ["Drama", "Crime"],
-  "year": 1994,
-  "ratings": [5.0, 4.5, 5.0, 4.0],
-  "average_rating": 4.6,
-  "rating_count": 4
-}
-```
-
-### User Format
-```json
-{
-  "id": 1,
-  "name": "John Doe",
-  "ratings": {"1": 5.0, "3": 4.5, "6": 4.0},
-  "favorite_genres": ["Drama", "Action", "Sci-Fi"]
-}
+70 % weight on collaborative, 30 % on content — a typical starting point. Tune empirically.
+
+## The Cold-Start Problem
+
+When a new user joins, collaborative filtering has nothing to work with. Three standard fixes:
+- **Content-based fallback** for the first few ratings.
+- **Onboarding survey** — ask "pick three favorite genres."
+- **Popularity baseline** — show top-rated movies first.
+
+When a new movie is added, the same problem appears from the other side. Content-based handles this fine because the algorithm only needs the new movie's *genres*, not its ratings.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| All recommendations are the same | Tiny rating dataset | Add minimum-overlap threshold, fall back to popularity |
+| Pearson returns NaN | Identical ratings (variance zero) | Guard with `if den == 0` |
+| Recommended movies user already rated | Forgot to filter | Skip `mid in user.ratings` |
+| Bias toward heavy raters | No normalization | Mean-center each user's ratings before similarity |
+| Score scale meaningless | Used Σ instead of weighted average | Divide by Σ similarity |
+| Hybrid no better than collaborative | Wrong weights | Cross-validate on held-out ratings |
+
+## Variations to Try
+
+### 1. Mean-centered Pearson
+Subtract each user's average rating before computing similarity — removes "harsh rater" bias entirely.
+
+### 2. Cosine similarity
+Cheaper than Pearson:
+```python title="cosine.py"
+def cosine(u, v):
+    common = set(u.ratings) & set(v.ratings)
+    if not common: return 0
+    dot = sum(u.ratings[m] * v.ratings[m] for m in common)
+    nu = math.sqrt(sum(u.ratings[m]**2 for m in common))
+    nv = math.sqrt(sum(v.ratings[m]**2 for m in common))
+    return dot / (nu * nv) if nu * nv else 0
 ```
 
-## 🛡️ Error Handling
-
-- **Data Validation**: Validate ratings (1.0-5.0 range)
-- **File Operations**: Handle JSON file errors gracefully
-- **User Input**: Validate all user inputs and provide feedback
-- **Missing Data**: Handle cases with insufficient data for recommendations
-
-## 📚 Learning Objectives
+### 3. Item-based collaborative filtering
+Find movies that are *similar to each other* based on rating patterns. Recommend movies similar to the user's highly-rated ones. Often outperforms user-based at scale.
 
-- **Recommendation Systems**: Understanding different recommendation approaches
-- **Machine Learning Concepts**: Collaborative and content-based filtering
-- **Data Analysis**: Statistical analysis and correlation calculation
-- **User Interface Design**: Interactive command-line applications
-- **Data Persistence**: JSON storage and data management
+### 4. TF-IDF on genres + descriptions
+Pull movie plot summaries from **TMDB** or **OMDb**. Run TF-IDF on the text and use cosine similarity over the resulting vectors. Far richer content-based recommendations.
 
-## 🎯 Algorithm Insights
-
-### Collaborative Filtering Strengths:
-- Discovers unexpected connections
-- Works well with sufficient user data
-- Finds niche preferences
-
-### Content-Based Filtering Strengths:
-- Works for new users with few ratings
-- Transparent reasoning for recommendations
-- Consistent with user preferences
-
-### Hybrid Approach Benefits:
-- Combines strengths of both methods
-- More robust recommendations
-- Better coverage of different scenarios
-
-## 🚀 Potential Enhancements
-
-1. **Machine Learning**: Implement matrix factorization algorithms
-2. **Web Interface**: Create Flask/Django web application
-3. **Database Integration**: Use PostgreSQL or MongoDB
-4. **Real-time Updates**: Live recommendation updates
-5. **Social Features**: Friend recommendations and reviews
-6. **Advanced Analytics**: Recommendation effectiveness metrics
-7. **External APIs**: Integration with TMDB or IMDB
-8. **Deep Learning**: Neural collaborative filtering
-
-## 🏆 Project Completion
-
-This Movie Recommendation System demonstrates:
-- ✅ Multiple recommendation algorithms implementation
-- ✅ User profiling and preference learning
-- ✅ Data persistence and management
-- ✅ Statistical analysis and insights
-- ✅ Interactive user interface
-- ✅ Comprehensive error handling
-
-Perfect for beginners learning recommendation systems and intermediate developers exploring machine learning concepts!
+### 5. Matrix factorization (SVD)
+Decompose the user-item rating matrix into low-rank factors. Use `scipy.sparse.linalg.svds` or the `Surprise` library:
+```bash title="install"
+pip install scikit-surprise
+```
+```python title="surprise.py"
+from surprise import Dataset, Reader, SVD
+algo = SVD()
+algo.fit(Dataset.load_from_df(ratings_df, Reader(rating_scale=(1, 5))).build_full_trainset())
+predicted = algo.predict(user_id, movie_id).est
+```
+This is what Netflix used in their famous prize-winning recommender.
+
+### 6. Implicit feedback
+Switch from explicit ratings (1-5 stars) to implicit (watched / not watched). Different math (ALS instead of SVD) but same shape.
+
+### 7. Diversity & serendipity
+After ranking, post-process to ensure variety — penalize candidates whose genres overlap heavily with already-shown items.
+
+### 8. TMDB API integration
+Replace the hard-coded 20 movies with a fresh feed of currently-popular titles from <https://www.themoviedb.org/documentation/api>.
+
+### 9. Save & evaluate
+Hold out 20 % of ratings; measure RMSE on predicted vs. actual. The standard offline-evaluation pattern.
+
+### 10. Web frontend
+Flask app that renders the user's recommendations with poster art from TMDB. See [Basic Web Server](./basicwebserver).
+
+### 11. Tag-based filtering
+User-added tags ("psychological thriller", "based on a true story") often outperform official genres. Combine.
+
+### 12. Real-time updates
+Re-run recommendations every time a new rating arrives, not just on demand.
+
+## Evaluation Metrics
+
+For any non-trivial recommender, measure:
+- **RMSE** — square root of mean squared prediction error.
+- **MAE** — mean absolute error.
+- **Precision@K** — fraction of top-K recommendations that the user actually liked.
+- **Recall@K** — fraction of liked items that appeared in top-K.
+- **Coverage** — fraction of catalog that ever gets recommended.
+- **Serendipity** — non-obvious good recommendations.
+
+## Real-World Recommender Systems
+- **Netflix** — matrix factorization + deep learning, billions of dollars of ROI.
+- **YouTube** — two-stage: candidate generation → ranking, both neural.
+- **Spotify** — collaborative filtering + audio embeddings.
+- **Amazon** — item-based collaborative filtering ("customers who bought this...").
+- **TikTok** — embedding-based with continuous learning from watch time.
+- **Goodreads / Letterboxd** — explicit ratings, classic CF.
+
+## Educational Value
+- **Collaborative vs. content-based** — two paradigms, different strengths.
+- **Pearson correlation** — a textbook statistic with real predictive power.
+- **Cold-start strategies** — universal recommender system problem.
+- **Hybrid models** — when combining two mediocre models beats either alone.
+- **Evaluation methodology** — train/test splits, held-out ratings.
+
+## Next Steps
+- Implement **item-based** collaborative filtering and compare to user-based.
+- Add **TMDB integration** for live, plot-aware data.
+- Switch to **SVD via `Surprise`** for a real model.
+- Evaluate **RMSE on held-out ratings** to pick the best algorithm.
+- Wrap with a **Flask UI** that renders posters.
+- Cross-link with [Personal Diary](./personaldiary) for the JSON-persistence pattern.
+
+## Conclusion
+You implemented two of the foundational recommendation algorithms and combined them — the same architecture used by the first decade of commercial recommenders. The state of the art has moved on to deep learning, but every modern system still rests on the same two ideas: "users like this one" and "items like this one." Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/movierecommendationsystem.py). Find more ML projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/numberguessingwithai.mdx b/src/content/docs/projects/Beginners/numberguessingwithai.mdx
index 93e37ecd..99c72258 100644
--- a/src/content/docs/projects/Beginners/numberguessingwithai.mdx
+++ b/src/content/docs/projects/Beginners/numberguessingwithai.mdx
@@ -1,6 +1,6 @@
 ---
 title: Number Guessing Game with AI
-description: Play a number guessing game against an AI that uses binary search, then try to beat its score
+description: Build a two-round number guessing game where an AI uses binary search to guess your number, then you try to beat it. Learn algorithms, complexity, and how to think like a computer.
 sidebar:
   order: 50
 hero:
@@ -14,31 +14,60 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Challenge yourself against an AI in a number guessing game! The AI uses binary search to guess your number, then you try to guess the AI's number. Compare rounds to see who wins and learn about efficient algorithms in action.
+This project takes the classic "Guess the Number" game and flips it on its head: first the computer guesses *your* number, then you guess the computer's number, and whoever needs fewer rounds wins. The interesting part is that the computer does not guess randomly — it uses **binary search**, an algorithm that guarantees it can find any integer between 0 and 100 in at most seven guesses. Watching it work is one of the best practical introductions to algorithmic thinking.
+
+You will learn:
+- How **binary search** works step-by-step.
+- Why algorithm choice matters: random guessing might take 100 tries, binary search takes seven.
+- The concept of **logarithmic time complexity** (`O(log n)`).
+- How to structure a two-phase game with score comparison.
+- How to extend the "AI" with more sophisticated strategies.
+
+## Why Binary Search Is Magic
+
+Imagine you are looking for a word in a dictionary. You do not start at "A" and read every page. You open it in the middle. If your word comes later in the alphabet, you ignore the first half and repeat with the second half. Each step halves the problem.
+
+That is exactly what the AI does:
+
+| Round | Range | Mid | Your answer | New range |
+|---|---|---|---|---|
+| 1 | 0–100 | **50** | "lower" | 0–49 |
+| 2 | 0–49 | **25** | "higher" | 26–49 |
+| 3 | 26–49 | **37** | "lower" | 26–36 |
+| 4 | 26–36 | **31** | "higher" | 32–36 |
+| 5 | 32–36 | **34** | "yes" | done |
+
+In **5 guesses** out of 101 possible numbers. Random guessing would have averaged about 50 attempts.
+
+Mathematically, binary search uses about `log₂(n)` guesses for `n` numbers. `log₂(101) ≈ 6.66`, so at most 7 — always.
 
 ## Prerequisites
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Understanding of loops and input/output
-- Familiarity with binary search (helpful)
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort running scripts and reading basic Python.
+- Familiarity with conditionals and loops.
+
+## Concepts You Will Use
+
+- **`random.randint(a, b)`** — pick a random integer for the human-to-guess phase.
+- **`while` loop with a shrinking range** — the core of binary search.
+- **Integer division `//`** — `(low + high) // 2` gives the midpoint without floats.
+- **Input validation** — making sure the player's hint is `h`, `l`, or `y`.
+- **Counter variables** — track how many rounds each side took.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `numberGuessingWithAI`.
-2. Create a new file and name it `numberguessingwithai.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `numberguessingwithai.py` file.
+### Create the project
+1. Create a folder named `number-guessing-ai`.
+2. Inside it, create `numberguessingwithai.py`.
 
 ### Write the code
-1. Add the following code to your `numberguessingwithai.py` file.
 <FileCode file="projects/beginners/numberguessingwithai.py" lang="python" title="Number Guessing Game with AI" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\numberGuessingWithAI> python numberguessingwithai.py
+
+### Run it
+```cmd title="command"
+C:\Users\username\Documents\number-guessing-ai> python numberguessingwithai.py
 Think of a number between 0 and 100!
 Is your number 50? (h/l/y): h
 Is your number 75? (h/l/y): l
@@ -53,32 +82,175 @@ Correct! You guessed my number in 3 rounds!
 You win this round!
 ```
 
-## Explanation
+## Step-by-Step Explanation
+
+### 1. Set up randomness
+```python title="numberguessingwithai.py"
+import random
+```
+Used for the second phase, where you have to guess a random number the computer generates.
+
+### 2. The AI's binary-search loop
+```python title="numberguessingwithai.py"
+low, high = 0, 100
+ai_rounds = 0
+while True:
+    ai_rounds += 1
+    guess = (low + high) // 2
+    response = input(f"Is your number {guess}? (h/l/y): ").lower()
+    if response == "y":
+        break
+    elif response == "h":           # actual number is higher
+        low = guess + 1
+    elif response == "l":           # actual number is lower
+        high = guess - 1
+    else:
+        print("Please answer h, l, or y.")
+        ai_rounds -= 1              # do not count this round
+print(f"I guessed your number in {ai_rounds} rounds!")
+```
+
+How this works:
+- `(low + high) // 2` is the midpoint. `//` is integer division, so the result is always a whole number.
+- If the player says "higher", the answer must be above `guess`, so we set `low = guess + 1`. We use `+ 1` because `guess` itself was just ruled out.
+- If "lower", we set `high = guess - 1` for the same reason.
+- If "yes", we win and `break`.
+- The unknown-input branch undoes the round counter to avoid penalizing the AI for the player's typo.
+
+### 3. The human's turn
+```python title="numberguessingwithai.py"
+secret = random.randint(0, 100)
+human_rounds = 0
+while True:
+    human_rounds += 1
+    try:
+        guess = int(input("Your guess: "))
+    except ValueError:
+        print("Please enter a whole number.")
+        human_rounds -= 1
+        continue
+    if guess == secret:
+        print(f"Correct! You guessed my number in {human_rounds} rounds!")
+        break
+    print("Too low!" if guess < secret else "Too high!")
+```
+- `random.randint(0, 100)` picks the secret number once, before the loop.
+- `int(input(...))` is wrapped in `try/except` so letters or empty input do not crash the game.
+- A ternary expression (`"Too low!" if … else "Too high!"`) avoids the need for a full `if/else` block on that line.
+
+### 4. Pick the winner
+```python title="numberguessingwithai.py"
+if ai_rounds < human_rounds:
+    print("AI wins — it guessed faster.")
+elif human_rounds < ai_rounds:
+    print("You win!")
+else:
+    print("Tie!")
+```
+
+## Complexity Notes
+
+Binary search has time complexity **O(log n)**. For range `n`:
+
+| n | Max rounds (`⌈log₂ n⌉ + 1`) |
+|---|---|
+| 10 | 4 |
+| 100 | 7 |
+| 1,000 | 10 |
+| 1,000,000 | 20 |
+| 1,000,000,000 | 30 |
+
+Doubling the range adds **one** extra round. That is why binary search underlies sorted-collection lookups, version-control bisect, and many machine-learning hyperparameter searches.
+
+Random guessing would be **O(n)** — proportional to the size of the range. Even 1,000 numbers gets painful.
+
+## Robust Input
+
+In the AI phase, an unfair player might say "higher" when their number is actually lower. The AI cannot detect that — the bug shows up as an empty range:
+
+```python title="catch_cheat.py"
+if low > high:
+    print("Hmm, your answers don't add up. Did you switch your number?")
+    break
+```
+
+Add that check inside the AI loop and the game ends gracefully when the search collapses.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| AI keeps guessing the same number | Forgot `+ 1` / `- 1` when shrinking the range | `low = guess + 1` and `high = guess - 1` |
+| Range crashes after many rounds | Player gave conflicting hints | Detect `low > high` and exit politely |
+| AI guesses outside 0–100 | Off-by-one in initial range | Initialize `low, high = 0, 100`, not `1, 99` |
+| Tie always favors AI | You used `<` not `<=` | Use a separate `elif` for the tie case |
+
+## Variations to Try
+
+### 1. Adjustable range
+Ask the player for the range at the start:
+```python title="custom_range.py"
+low_input = int(input("Lower bound: "))
+high_input = int(input("Upper bound: "))
+```
+
+### 2. Best-of-three rounds
+Wrap the whole game in a loop that tracks total wins:
+```python title="series.py"
+ai_wins = human_wins = 0
+for round_num in range(1, 4):
+    play_one_round()
+    # tally
+print(f"Series winner: {'AI' if ai_wins > human_wins else 'You'}")
+```
+
+### 3. Smarter "AI" strategies
+- **Random AI** — guess uniformly at random; great baseline.
+- **Pattern AI** — bias toward numbers humans pick often (lots of 7s and 17s).
+- **Adaptive AI** — track which numbers the player has used in past games and avoid them.
+
+### 4. Hide the binary search behind a "thinking" delay
+```python title="thinking.py"
+import time
+print("Thinking...", end="", flush=True); time.sleep(0.5)
+```
+Adds personality without slowing gameplay.
+
+### 5. Add a GUI
+Tkinter with two number-entry fields and a big "Guess!" button. Display the AI's current range visually.
+
+### 6. Compare algorithms head-to-head
+Run binary search vs. random guessing 10,000 times each, average the rounds, and graph the result with `matplotlib`.
+
+### 7. Multiplayer scoreboard
+Persist round counts in a JSON file. Each session you can see your improvement vs. the AI.
+
+## Real-World Algorithm Examples
+
+Binary search shows up everywhere:
+- **`bisect`** module in Python's standard library — insert into a sorted list in O(log n).
+- **`git bisect`** — finds which commit introduced a bug by binary-searching commits.
+- **Database B-tree indexes** — searches narrow the range repeatedly.
+- **Auto-tuning compilers** — find the largest input size that still fits a time budget.
+- **Numerical methods** — bisection for root-finding (e.g., solving `f(x) = 0`).
+
+## Educational Value
 
-1. The `import random` statement imports the random module for generating random numbers.
-2. The AI uses binary search algorithm to efficiently guess your number.
-3. The `low` and `high` variables maintain the search range for the AI.
-4. The AI starts by guessing the middle value (50) and adjusts based on your response.
-5. Your responses ('h' for higher, 'l' for lower, 'y' for yes) guide the AI's search.
-6. The `random.randint(0, 100)` generates a random number for you to guess.
-7. The program tracks rounds taken by both AI and human player.
-8. Winner determination compares the number of rounds each player needed.
-9. The binary search algorithm guarantees the AI will find any number in at most 7 rounds.
-10. The game demonstrates the efficiency of algorithmic problem-solving vs. human intuition.
+This project teaches:
+- **Algorithmic thinking** — pick a strategy, prove an upper bound, implement it.
+- **Trade-offs** — the AI is fast and fair; a random guesser is simpler but slower.
+- **Logarithmic growth** — intuition for one of the most important concepts in computer science.
+- **State management** — `low` and `high` together represent the AI's belief about the answer.
+- **Robust input handling** — protecting against bad data and inconsistent answers.
 
 ## Next Steps
 
-Congratulations! You have successfully created a Number Guessing Game with AI in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add difficulty levels (change range from 0-100 to larger ranges)
-- Track high scores and statistics across multiple games
-- Add GUI with Tkinter for better user experience
-- Let AI learn from previous games to improve performance
-- Implement different AI strategies (random, pattern-based)
-- Add multiplayer support for multiple human players
-- Create tournament mode with best-of-series gameplay
-- Add sound effects and visual feedback
-- Implement hints system for human player
+- Implement a **graphical version** with a number line that shrinks each round.
+- Build a **command-line tournament**: a dozen different AI strategies competing.
+- Try the **20 Questions** variant: yes/no questions over a database of objects.
+- Read about **interpolation search** — even faster when data is uniformly distributed.
+- Move on to the [Hangman](./hangman) project for a different style of search.
 
 ## Conclusion
 
-In this project, you learned how to create a Number Guessing Game with AI in Python. You also learned about binary search algorithms, human vs. computer problem-solving, and competitive programming concepts. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/numberguessingwithai.py)
+You implemented binary search from scratch, paired it with a human-vs-computer game loop, and saw why one good algorithm beats brute force every time. The same idea — halve the problem at each step — drives most of the fast lookup code you will ever touch. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/numberguessingwithai.py). More beginner projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/paint.mdx b/src/content/docs/projects/Beginners/paint.mdx
index af6f9d9e..4c3eff70 100644
--- a/src/content/docs/projects/Beginners/paint.mdx
+++ b/src/content/docs/projects/Beginners/paint.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Paint Application
-description: Create a digital painting application with color selection, brush tools, and save functionality using Tkinter and PIL
+description: Build a desktop paint program in Python with Tkinter and Pillow. Learn canvas drawing, mouse events, color pickers, brush controls, save-as-image, and how to grow a sketch tool into a full-featured editor.
 sidebar:
   order: 48
 hero:
@@ -14,43 +14,49 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a feature-rich digital painting application with a graphical interface that includes color palettes, brush size controls, eraser tools, canvas background customization, and image saving capabilities. This project demonstrates advanced GUI development, event handling, and image processing.
+A paint program is the perfect mid-level project because it stretches every part of GUI programming: drawing on a canvas, tracking mouse motion, handling many simultaneous widgets, and saving the result to a file. In this project you will build a Tkinter-based paint application with a color palette, an adjustable brush, an eraser, a canvas-color picker, a clear button, and a save-to-JPEG feature.
 
-## Prerequisites
-
-- Basic understanding of Python syntax
-- Knowledge of Tkinter for GUI development
-- Familiarity with event-driven programming
-- Understanding of coordinate systems and graphics
-- Basic knowledge of image processing concepts
+Along the way you will learn:
+- How to capture continuous mouse-drag events with Tkinter bindings.
+- Why drawing a stream of small ovals looks like a smooth brush stroke.
+- How to lay out widgets with frames, grids, and packs.
+- How to capture the canvas as an image via screen grab.
+- How to organize a non-trivial GUI program with a class.
 
-## Getting Started
+## Prerequisites
 
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with classes (or a willingness to learn — we use them here).
+- Familiarity with Tkinter basics. If you have built the [Basic Music Player](./basicmusicplayer) you already know enough.
 
+## Install Pillow
 
-1. **Install Required Dependencies**
-   ```bash
-   pip install pillow
-   # tkinter comes built-in with Python
-   ```
+The save-as-image feature uses **Pillow** (the fork of the classic PIL):
+```bash title="install"
+pip install pillow
+```
+Tkinter itself ships with Python — no install.
 
-2. **Run the Paint Application**
-   ```bash
-   python paint.py
-   ```
+## Getting Started
 
-3. **Start Creating Art**
-   - Select colors from the color palette
-   - Adjust brush size with the scale control
-   - Use the eraser tool for corrections
-   - Save your artwork when finished
+### Create the project
+1. Create a folder named `paint-app`.
+2. Inside it, create `paint.py`.
 
+### Write the code
+<FileCode file="projects/beginners/paint.py" lang="python" title="Paint Application" />
 
+### Run it
+```bash title="run"
+python paint.py
+```
+A window appears with a color palette on the left, a brush-size slider on the right, a clear button at the top, and a large white canvas in the middle. Click and drag to draw.
 
-## Code Explanation
+## Step-by-Step Explanation
 
-### Application Architecture
-```python title="paint.py" showLineNumbers{1}
+### 1. Class skeleton
+```python title="paint.py"
 class Paint:
     def __init__(self, root):
         self.root = root
@@ -58,107 +64,172 @@ class Paint:
         self.root.geometry("800x520")
         self.pen_color = "black"
         self.eraser_color = "white"
+        self.build_ui()
+        self.bind_events()
 ```
-
-Implements a class-based structure for better organization and state management of the painting application.
-
-### Event-Driven Drawing
-```python title="paint.py" showLineNumbers{1}
-self.root.bind("<B1-Motion>", self.paint)
-self.root.bind("<ButtonRelease-1>", self.reset)
-
-def paint(self, event):
-    x1, y1 = (event.x-2), (event.y-2)
-    x2, y2 = (event.x+2), (event.y+2)
-    self.canvas.create_oval(x1, y1, x2, y2, fill=self.pen_color, 
-                           outline=self.pen_color, width=self.canvas_width.get())
+A class lets us **stash state** (pen color, brush size, canvas reference) on `self` without sprinkling globals throughout the code.
+
+### 2. Build the layout
+```python title="paint.py"
+def build_ui(self):
+    self.color_frame = LabelFrame(self.root, text="Colors", padx=5, pady=5)
+    self.color_frame.pack(side=LEFT, fill=Y)
+
+    colors = ["#000000", "#ff0000", "#ff8000", "#ffff00",
+              "#00ff00", "#0080ff", "#0000ff", "#8000ff"]
+    for i, color in enumerate(colors):
+        Button(self.color_frame, bg=color, width=3, bd=2,
+               command=lambda c=color: self.set_pen_color(c)).grid(row=i//2, column=i%2)
+
+    self.canvas_width = Scale(self.root, from_=1, to=100, orient=VERTICAL, label="Size")
+    self.canvas_width.set(5)
+    self.canvas_width.pack(side=RIGHT, fill=Y)
+
+    self.canvas = Canvas(self.root, bg="white")
+    self.canvas.pack(fill=BOTH, expand=True)
 ```
+- `Frame` / `LabelFrame` groups related widgets.
+- The **`command=lambda c=color: ...`** trick is essential: without the default-argument capture, all buttons would end up using the *last* color in the loop.
+- `Scale` is a slider; we use it for brush size.
+- `Canvas` is the drawing surface.
+
+### 3. Bind mouse events
+```python title="paint.py"
+def bind_events(self):
+    self.canvas.bind("<B1-Motion>", self.paint)
+    self.canvas.bind("<ButtonRelease-1>", self.reset)
+```
+- `<B1-Motion>` fires repeatedly while the left mouse button is held and the cursor moves.
+- `<ButtonRelease-1>` fires once when the button is released.
 
-Captures mouse movement and button events to create continuous drawing by placing small overlapping ovals.
-
-### Dynamic Color Palette
-```python title="paint.py" showLineNumbers{1}
-colors = ["#ff0000", "#ff4000", "#ff8000", "#ffbf00", "#ffff00", ...]
-i=j=0
-for color in colors:
-    Button(self.color_frame, bg=color, bd=2, relief=RIDGE, width=3, 
-           command=lambda col=color:self.select_color(col)).grid(row=i, column=j)
+### 4. Paint with overlapping ovals
+```python title="paint.py"
+def paint(self, event):
+    size = self.canvas_width.get()
+    x1, y1 = event.x - size, event.y - size
+    x2, y2 = event.x + size, event.y + size
+    self.canvas.create_oval(x1, y1, x2, y2,
+                            fill=self.pen_color,
+                            outline=self.pen_color)
 ```
+Every mouse-move event draws a small filled oval at the cursor. Because the events fire many times per second, the result *looks* like a continuous brush stroke. With a bigger brush size, the ovals are larger and the stroke gets wider.
 
-Creates a comprehensive color palette with buttons arranged in a grid layout for easy color selection.
+> 💡 For a *truly* continuous line, use `create_line` between the previous and current mouse positions. Track the last point in `self.old_x, self.old_y` and reset them in `reset()`.
 
-### Brush Size Control
-```python title="paint.py" showLineNumbers{1}
-self.canvas_width = Scale(self.root, from_=1, to=100, orient=VERTICAL)
-self.canvas_width.set(1)
-```
+### 5. Color and tool switching
+```python title="paint.py"
+def set_pen_color(self, color):
+    self.pen_color = color
 
-Provides a vertical scale widget for real-time brush size adjustment from 1 to 100 pixels.
+def use_eraser(self):
+    self.pen_color = self.eraser_color    # erase = paint with bg color
 
-### Canvas Background Customization
-```python title="paint.py" showLineNumbers{1}
-def canvas_color(self):
-    color = colorchooser.askcolor(title="Select Color")
-    self.canvas.configure(background=color[1])
-    self.eraser_color = color[1]
+def pick_canvas_color(self):
+    color = colorchooser.askcolor(title="Canvas color")[1]
+    if color:
+        self.canvas.configure(background=color)
+        self.eraser_color = color
 ```
+An eraser is just paint that matches the background. Picking a new canvas color updates the eraser to match.
 
-Allows users to change the canvas background color and automatically updates the eraser color to match.
+### 6. Clear and save
+```python title="paint.py"
+def clear_canvas(self):
+    self.canvas.delete("all")
 
-### Image Saving with Screen Capture
-```python title="paint.py" showLineNumbers{1}
-def save_paint(self):
+def save_canvas(self):
     filename = filedialog.asksaveasfilename(defaultextension=".jpg")
+    if not filename: return
+    self.root.update()                     # ensure window is fully drawn
     x = self.root.winfo_rootx() + self.canvas.winfo_x()
     y = self.root.winfo_rooty() + self.canvas.winfo_y()
     x1 = x + self.canvas.winfo_width()
     y1 = y + self.canvas.winfo_height()
-    PIL.ImageGrab.grab().crop((x,y,x1,y1)).save(filename)
+    ImageGrab.grab(bbox=(x, y, x1, y1)).save(filename)
 ```
+- `delete("all")` removes every drawn item.
+- Saving uses `PIL.ImageGrab.grab` to **screen-capture** the canvas region.
+  - `winfo_rootx/y` give the canvas position in *screen* coordinates (not window coordinates).
+- A more advanced approach maintains a parallel `PIL.Image` and draws into it via `PIL.ImageDraw` — that way the saved image is identical regardless of what is on screen (no risk of capturing an overlapping window).
 
-Implements screen capture technology to save the canvas content as an image file.
+## Common Mistakes
 
-## Features
+| Problem | Cause | Fix |
+|---|---|---|
+| All color buttons paint the same color | Closure captured the loop variable | Use `lambda c=color: ...` to bind early |
+| Brush leaves dotted line | Events fire faster than they can be drawn | Use `create_line` between consecutive points |
+| `ImageGrab.grab()` returns the wrong region | Used canvas-local coordinates | Use `winfo_rootx/y` for screen coordinates |
+| Eraser leaves black on a colored canvas | Eraser color hard-coded to white | Update `self.eraser_color` whenever the canvas color changes |
+| Save dialog hangs | No file extension | Use `asksaveasfilename(defaultextension=".jpg")` |
 
-- **Comprehensive Color Palette**: 27 predefined colors in an organized grid
-- **Variable Brush Size**: Adjustable brush width from 1 to 100 pixels
-- **Eraser Tool**: Switch between drawing and erasing modes
-- **Canvas Customization**: Change background color with color picker
-- **Clear Function**: Reset the entire canvas instantly
-- **Image Saving**: Save artwork as JPEG files
-- **Responsive Drawing**: Smooth, continuous brush strokes
-- **Professional Layout**: Organized toolbar and spacious canvas area
+## Variations to Try
 
-## Next Steps
+### 1. Custom color picker
+Replace the eight preset buttons with a single "Choose color..." button using `colorchooser.askcolor`.
 
-### Enhancements
-- Add different brush shapes (square, triangle, spray)
-- Implement undo/redo functionality
-- Create layers support for complex artwork
-- Add text tool for adding labels
-- Implement zoom in/out functionality
-- Add image loading capabilities
-- Create brush opacity controls
-- Add selection tools (rectangle, lasso)
-
-### Learning Extensions
-- Study advanced image processing with PIL/Pillow
-- Explore vector graphics programming
-- Learn about graphics algorithms and optimization
-- Practice with custom widget development
-- Understand color theory and digital art concepts
-- Explore tablet/stylus input integration
+### 2. Smooth brush lines
+```python title="smooth.py"
+def paint(self, event):
+    if self.old_x and self.old_y:
+        self.canvas.create_line(self.old_x, self.old_y,
+                                event.x, event.y,
+                                width=self.canvas_width.get(),
+                                fill=self.pen_color,
+                                capstyle=ROUND, smooth=True)
+    self.old_x, self.old_y = event.x, event.y
+
+def reset(self, event):
+    self.old_x = self.old_y = None
+```
+A real, smooth brush stroke.
 
-## Educational Value
+### 3. Undo / redo
+Maintain a stack of canvas-item IDs. On undo, `canvas.delete(last_id)`.
+
+### 4. Shape tools
+A toolbar with rectangle, oval, and line tools. On mouse-press record the start point; on release create the shape.
+
+### 5. Text tool
+Click on the canvas → open an `Entry` → press Enter → place the text there.
+
+### 6. Spray paint
+Each mouse event creates a random pattern of small dots inside a radius. Looks more like spray than a brush.
+
+### 7. Layers
+Use multiple `Canvas` widgets stacked together, or maintain an in-memory `PIL.Image` per layer and composite on save.
 
+### 8. Image import
+Use `PIL.Image.open` → `ImageTk.PhotoImage` → `canvas.create_image` to bring an existing picture onto the canvas, then paint over it.
+
+### 9. Touch support
+On a tablet or touch-screen Tkinter receives events the same way. Try it.
+
+### 10. Save as PNG with transparency
+Drop the screen-grab approach and use a parallel `PIL.Image` so the saved PNG truly matches what is drawn — no background bleed.
+
+## Real-World Applications
+- **Image annotation tools** for ML labeling.
+- **Whiteboard apps** for remote teaching.
+- **Quick mockup tools** for designers.
+- **Signature capture** in form-filling apps.
+- **Drawing input** for ML models that take strokes (handwriting recognition, sketch classification).
+
+## Educational Value
 This project teaches:
-- **Advanced GUI Development**: Creating complex interfaces with multiple widget types
-- **Event Handling**: Managing mouse events for interactive drawing
-- **Image Processing**: Working with PIL for screen capture and image manipulation
-- **Coordinate Systems**: Understanding pixel-based positioning and drawing
-- **State Management**: Maintaining application state across user interactions
-- **File Operations**: Implementing save/load functionality with file dialogs
-- **Color Theory**: Working with color systems and user color selection
-- **Object-Oriented Design**: Structuring applications using classes and methods
-
-Perfect for understanding graphics programming, user interface design, and image processing concepts in Python.
+- **Event-driven GUI** — bindings, callbacks, the main loop.
+- **Canvas programming** — creating, deleting, and managing graphic items.
+- **Layout managers** — `pack`, `grid`, frames, side-by-side regions.
+- **State management** — what color, what tool, what size, all stored on `self`.
+- **Cross-library bridges** — Tkinter + Pillow to produce a real file.
+- **Class-based design** — keeping UI code organized.
+
+## Next Steps
+- Add **smooth-brush** drawing using `create_line` as shown above.
+- Implement **undo/redo** with a stack of item IDs.
+- Add a **toolbar** with rectangle, oval, line, and text tools.
+- Replace the screen-grab save with a **PIL-backed image** for true layered drawing.
+- Port the UI to **CustomTkinter** for a modern look.
+- Convert it into a **collaborative whiteboard** with WebSockets — pair the GUI with a Flask backend.
+
+## Conclusion
+You built a real desktop paint app: a canvas, a palette, brush controls, save-as-image, and a class-based architecture you can keep extending. Tkinter shows its age in styling but its power model — widgets, events, the main loop — is identical to what big frameworks use. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/paint.py). Find more GUI projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/passwordstrengthchecker.mdx b/src/content/docs/projects/Beginners/passwordstrengthchecker.mdx
index fce505e0..391453d3 100644
--- a/src/content/docs/projects/Beginners/passwordstrengthchecker.mdx
+++ b/src/content/docs/projects/Beginners/passwordstrengthchecker.mdx
@@ -1,6 +1,6 @@
 ---
 title: Password Strength Checker
-description: A Python application that evaluates password strength by checking for various security criteria including length, character types, and complexity requirements.
+description: Build a real password strength checker in Python. Learn regex, entropy calculation, common-password detection, breach-corpus checking, zxcvbn-style scoring, and Have I Been Pwned integration.
 sidebar: 
     order: 39
 hero:
@@ -13,220 +13,264 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Password Strength Checker is a Python application that evaluates the strength of passwords based on various security criteria. The application checks for minimum length requirements, presence of uppercase and lowercase letters, numbers, and special characters. It provides immediate feedback to users about password weaknesses and suggestions for improvement. This project demonstrates the use of regular expressions, string analysis, and security best practices in Python programming.
+A password strength checker is more nuanced than it looks. Most tutorials count character classes and call it done — *"has uppercase, has digit, has symbol — great password!"* — which classifies `Password1!` as strong even though it appears in every leaked-credentials dump. In this project you will build the rule-based checker first, then layer on **entropy estimation**, a **common-password blacklist**, a **leak-corpus check** against Have I Been Pwned, and a final score modeled on `zxcvbn`.
+
+You will leave understanding:
+- Why character-class rules are necessary but not sufficient.
+- How to compute password entropy.
+- How `zxcvbn` actually scores passwords.
+- How to query Have I Been Pwned safely using **k-anonymity**.
+- How to give *actionable* feedback, not just a "weak/strong" verdict.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
+- Python 3.6 or above.
+- A code editor or IDE.
+- Comfort with regex (`re` module).
+- (Optional) Internet access for the HIBP check.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-Note: This project uses only built-in Python modules (`re` for regular expressions), so no additional installations are required.
+### Create the project
+1. Create folder `password-strength-checker`.
+2. Inside, create `passwordstrengthchecker.py`.
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `password-strength-checker`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `passwordstrengthchecker.py`.
-4. Copy the given code and paste it in your `passwordstrengthchecker.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `passwordstrengthchecker.py` file.
+### Write the code
 <FileCode file="projects/beginners/passwordstrengthchecker.py" lang="python" title="Password Strength Checker" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `password-strength-checker`.
-```cmd title="command" showLineNumbers{1} {1-20}
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\password-strength-checker> python passwordstrengthchecker.py
-Password must contain at least one special character.
-Password must be at least 8 characters long.
-Password must contain at least one uppercase letter.
-Password must contain at least one lowercase letter.
-Password must contain at least one number.
-Password must contain at least one special character.
-Password is strong.
-Password is strong.
+Password: Password123!
+Strong (rule-based)
 ```
 
-## Explanation
-1. Import the required module.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1}
+## Step-by-Step Explanation
+
+### 1. The rule-based checker
+```python title="passwordstrengthchecker.py"
 import re
-```
 
-2. Define the password strength checking function.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1}
-def password_strength_checker(password):
+def rule_based(password: str) -> list[str]:
+    feedback = []
+    if len(password) < 8:
+        feedback.append("Use at least 8 characters.")
+    if not re.search(r"[a-z]", password):
+        feedback.append("Add a lowercase letter.")
+    if not re.search(r"[A-Z]", password):
+        feedback.append("Add an uppercase letter.")
+    if not re.search(r"[0-9]", password):
+        feedback.append("Add a digit.")
+    if not re.search(r"[^A-Za-z0-9]", password):
+        feedback.append("Add a symbol.")
+    return feedback
 ```
+A list of issues is more useful than a single boolean — the user can fix multiple problems in one revision.
 
-3. Check minimum length requirement.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-if len(password) < 8:
-    print("Password must be at least 8 characters long.")
+### 2. Strong vs. weak verdict
+```python title="passwordstrengthchecker.py"
+def strength(password: str) -> tuple[str, list[str]]:
+    issues = rule_based(password)
+    return ("Strong" if not issues else "Weak"), issues
 ```
 
-4. Check for lowercase letters using regular expressions.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-elif not re.search("[a-z]", password):
-    print("Password must contain at least one lowercase letter.")
+### 3. Run it
+```python title="passwordstrengthchecker.py"
+for p in ["Password", "password123", "PASSWORD123",
+          "Password@", "Password123@"]:
+    verdict, issues = strength(p)
+    print(f"{p}: {verdict}")
+    for i in issues: print(f"  - {i}")
 ```
 
-5. Check for uppercase letters.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-elif not re.search("[A-Z]", password):
-    print("Password must contain at least one uppercase letter.")
+## Why Rules Are Not Enough
+
+`Password1!` satisfies every rule above. So does `Qwerty12$`. They are also among the **most common leaked passwords** on Earth. Real strength assessment needs two more inputs:
+
+1. **Common-password lists** — reject anything in the top-N (try `rockyou.txt`, ~14 million).
+2. **Entropy** — measure how much information the password actually carries.
+
+## Entropy Estimation
+
+```python title="entropy.py"
+import math, string
+def entropy_bits(password: str) -> float:
+    pool = 0
+    if any(c.islower() for c in password): pool += 26
+    if any(c.isupper() for c in password): pool += 26
+    if any(c.isdigit() for c in password): pool += 10
+    if any(c in string.punctuation for c in password): pool += len(string.punctuation)
+    return len(password) * math.log2(max(pool, 1))
 ```
+Rough rubric:
+- **< 28 bits** — very weak (crackable in seconds).
+- **28 – 35** — weak (offline crack in minutes).
+- **36 – 59** — reasonable for low-value accounts.
+- **60 – 127** — strong.
+- **≥ 128** — paranoid / master-vault-grade.
+
+A 16-character mix of all four classes lands around 105 bits — well into "strong" territory.
+
+## Common-Password Blacklist
+
+The simplest meaningful upgrade. Get a list (e.g. SecLists' `10-million-password-list-top-1000000.txt`) and:
+```python title="blacklist.py"
+from pathlib import Path
+COMMON = set(Path("top-passwords.txt").read_text().splitlines())
 
-6. Check for numbers.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-elif not re.search("[0-9]", password):
-    print("Password must contain at least one number.")
+def is_common(password: str) -> bool:
+    return password.lower() in COMMON
 ```
+Set lookup is O(1). One million entries fits in ~30 MB of RAM — fine for a desktop tool.
+
+## Have I Been Pwned (k-Anonymity)
+
+[HIBP](https://haveibeenpwned.com/API/v3#PwnedPasswords) lets you check a password against billions of leaked entries **without sending the password itself**:
+
+1. SHA-1 your password.
+2. Send only the **first 5 hex characters** of the hash.
+3. Server returns all hashes starting with that prefix (about 500 per query).
+4. You check locally whether the full hash is in that list.
+
+```python title="hibp.py"
+import hashlib, requests
 
-7. Check for special characters.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-elif not re.search("[_@$]", password):
-    print("Password must contain at least one special character.")
+def hibp_count(password: str) -> int:
+    sha1 = hashlib.sha1(password.encode("utf-8")).hexdigest().upper()
+    prefix, suffix = sha1[:5], sha1[5:]
+    r = requests.get(f"https://api.pwnedpasswords.com/range/{prefix}", timeout=10)
+    r.raise_for_status()
+    for line in r.text.splitlines():
+        s, count = line.split(":")
+        if s == suffix:
+            return int(count)
+    return 0
 ```
+A non-zero count means the password appears in known breaches — *reject it immediately*. Even if it scores high on rules and entropy, attackers will try it first.
 
-8. Confirm strong password.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-2}
-else:
-    print("Password is strong.")
+## Putting It All Together
+
+```python title="full_check.py"
+def full_check(password: str):
+    issues = rule_based(password)
+    bits = entropy_bits(password)
+    common = is_common(password)
+    try:
+        breaches = hibp_count(password)
+    except Exception:
+        breaches = None
+
+    score = 0
+    if len(password) >= 12: score += 1
+    if not issues:          score += 1
+    if bits >= 60:          score += 1
+    if not common:          score += 1
+    if breaches == 0:       score += 1
+
+    levels = ["Very Weak", "Weak", "Fair", "Good", "Strong", "Excellent"]
+    return {
+        "level":   levels[score],
+        "bits":    round(bits, 1),
+        "issues":  issues,
+        "common":  common,
+        "breaches": breaches,
+    }
 ```
+Now `full_check("Password1!")` says "Weak — found in 1.6 million breaches" instead of "Strong — has all four character classes."
+
+## Why You Should Recommend `zxcvbn`
 
-9. Test the function with various passwords.
-```python title="passwordstrengthchecker.py" showLineNumbers{1} {1-7}
-password_strength_checker("Password123")
-password_strength_checker("Password")
-password_strength_checker("password123")
-password_strength_checker("PASSWORD123")
-password_strength_checker("Password@")
-password_strength_checker("Password123@")
-password_strength_checker("Password123@!")
+For a real product use **`zxcvbn-python`** (a Python port of Dropbox's library):
+```bash title="install"
+pip install zxcvbn
 ```
+```python title="zxcvbn_use.py"
+from zxcvbn import zxcvbn
+r = zxcvbn("Tr0ub4dor&3")
+print(r["score"], r["feedback"]["warning"], r["crack_times_display"])
+```
+It models real attacker behavior — dictionary attacks, l33t substitutions, keyboard patterns, dates, repeats — and gives a 0-4 score plus an estimated time to crack at four attack scenarios. Your rule-based code is *educational*; `zxcvbn` is *production*.
 
-## Security Criteria Checked
-The application evaluates passwords based on these criteria:
+## Common Mistakes
 
-### 1. **Length Requirement**
-- Minimum 8 characters
-- Longer passwords provide better security
+| Problem | Cause | Fix |
+|---|---|---|
+| `Password1!` rated strong | Only checked character classes | Add common-password + breach check |
+| HIBP request fails | No internet | Make the breach check optional, surface as "unknown" |
+| Sending password over the network | Naive API design | Use the k-anonymity range API |
+| Locale-specific punctuation missed | Used a fixed regex | Use `re.search(r"[^A-Za-z0-9]", password)` for "any non-alphanumeric" |
+| Logs/print contain the password | Debugging left in | Never log passwords; never even print echoes |
+| Comparing in plain text | Custom logic | Always hash before comparing/storing |
 
-### 2. **Lowercase Letters**
-- Must contain at least one lowercase letter (a-z)
-- Increases character set complexity
+## Variations to Try
 
-### 3. **Uppercase Letters**
-- Must contain at least one uppercase letter (A-Z)
-- Adds to password entropy
+### 1. Pattern detection
+Reject keyboard runs (`qwerty`, `asdf`), repeated characters (`aaa`), and sequences (`12345`).
+```python title="pattern.py"
+import re
+def has_runs(p):
+    return bool(re.search(r"(.)\1\1", p)) or bool(re.search(r"012|123|234|abc|qwe", p.lower()))
+```
 
-### 4. **Numbers**
-- Must contain at least one digit (0-9)
-- Numerical characters increase complexity
+### 2. Dates and years
+A 4-digit substring matching `19xx` or `20xx` is almost certainly a birth year — flag it.
 
-### 5. **Special Characters**
-- Must contain at least one special character (_, @, $)
-- Note: Current implementation checks for limited special characters
+### 3. Personal-info check
+Accept the user's name, email, and birth date; reject any password containing those.
 
-## Features
-- **Comprehensive Checking:** Evaluates multiple security criteria
-- **Immediate Feedback:** Provides specific weakness identification
-- **Regular Expression Power:** Uses regex for pattern matching
-- **Simple Interface:** Easy-to-use function-based approach
-- **Batch Testing:** Can test multiple passwords at once
-- **Clear Messages:** Specific feedback for each security requirement
+### 4. GUI version
+A Tkinter form with a colored progress bar that shifts red → yellow → green as the user types. See [Calculator GUI](./calculatorgui) for the layout pattern.
 
-## Regular Expression Patterns
-The application uses these regex patterns:
+### 5. Web frontend
+Flask + a textarea (see [Basic Web Server](./basicwebserver)). **Never** ship the password to the server unless you absolutely must; do the check in the browser with JS.
 
-- **`[a-z]`:** Matches any lowercase letter
-- **`[A-Z]`:** Matches any uppercase letter
-- **`[0-9]`:** Matches any digit
-- **`[_@$]`:** Matches specific special characters
+### 6. Estimated crack time
+Multiply entropy by hashes-per-second assumptions:
+- Online (1 000 guesses/s): how long to brute force?
+- Offline GPU (1 trillion guesses/s): how long?
 
-## Sample Test Results
-```
-Password123     → Missing special character
-Password        → Too short, missing numbers and special characters
-password123     → Missing uppercase and special characters
-PASSWORD123     → Missing lowercase and special characters
-Password@       → Missing numbers
-Password123@    → Strong password ✓
-Password123@!   → Strong password ✓
-```
+### 7. Suggest a fix
+If the password is too short, append a random word. If a class is missing, insert one. If common, regenerate entirely.
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Implementing a scoring system (weak, medium, strong)
-- Expanding special character requirements
-- Adding checks for common passwords
-- Implementing password generation suggestions
-- Adding dictionary word detection
-- Creating visual strength indicators
-- Adding entropy calculation
-- Implementing sequential character detection
-- Adding customizable security requirements
-
-## Enhanced Version Ideas
-```python title="passwordstrengthchecker.py" showLineNumbers{1}
-def enhanced_password_checker(password):
-    score = 0
-    feedback = []
-    
-    # Length scoring
-    if len(password) >= 12:
-        score += 2
-    elif len(password) >= 8:
-        score += 1
-    else:
-        feedback.append("Password too short")
-    
-    # Character type scoring
-    if re.search("[a-z]", password):
-        score += 1
-    if re.search("[A-Z]", password):
-        score += 1
-    if re.search("[0-9]", password):
-        score += 1
-    if re.search("[!@#$%^&*()_+\-=\[\]{};':\"\\|,.<>\/?]", password):
-        score += 2
-    
-    # Return strength level
-    if score >= 7:
-        return "Very Strong"
-    elif score >= 5:
-        return "Strong"
-    elif score >= 3:
-        return "Medium"
-    else:
-        return "Weak"
+### 8. Pair with the generator
+Cross-reference with [Random Password Generator](./randompasswordgenerator). Show the strength of every generated password.
+
+### 9. Account-wide policy
+Read a config file specifying minimums (length, classes, entropy, max breach count) and enforce them.
+
+### 10. CLI tool
+```bash title="cli"
+strength check "Tr0ub4dor&3"
+strength suggest --length 16 --no-ambig
 ```
 
-## Common Password Weaknesses
-- **Too short:** Less than 8 characters
-- **Single case:** Only uppercase or lowercase
-- **No numbers:** Missing numerical characters
-- **No symbols:** Missing special characters
-- **Dictionary words:** Common words that can be found in dictionaries
-- **Personal info:** Names, birthdays, addresses
-- **Sequential patterns:** 123456, abcdef, qwerty
-
-## Security Best Practices
-- **Use unique passwords:** Different password for each account
-- **Enable 2FA:** Two-factor authentication when available
-- **Regular updates:** Change passwords periodically
-- **Use password managers:** Store complex passwords securely
-- **Avoid personal info:** Don't use easily guessable information
+## Security Best Practices the Tool Should Reinforce
+- **Length over complexity.** A 16-character random passphrase beats `Aa1!Aa1!`.
+- **Unique per service.** Even a strong password is weak if reused across breached sites.
+- **Never trust client-side checks alone.** A web app must enforce policy on the server too.
+- **Treat the input as a secret.** No logging, no caching, no analytics tracking the actual value.
+- **Hash + salt server-side.** Never store passwords plaintext.
+
+## Real-World Applications
+- Signup forms with real-time strength feedback.
+- Password-change flows that reject reuse.
+- IT admin tools that audit a company's password hashes.
+- Onboarding wizards that teach users *why* `Password1!` is weak.
+- Self-service password reset with leak-corpus protection.
 
 ## Educational Value
-This project teaches:
-- **Regular expressions:** Pattern matching in strings
-- **Conditional logic:** Multiple if-elif-else statements
-- **String analysis:** Character type identification
-- **Security concepts:** Password strength principles
-- **Function design:** Modular code organization
+- **Regex** — pattern matching across character classes.
+- **Entropy math** — turning intuition into a number.
+- **k-anonymity** — privacy-preserving lookup design (a wonderful idea worth knowing).
+- **API integration** — calling a real third-party service safely.
+- **UX of security** — actionable feedback vs. red-X verdicts.
+
+## Next Steps
+- Implement the **common-password blacklist** above.
+- Add **HIBP k-anonymity** check.
+- Switch to **`zxcvbn`** for production scoring.
+- Add **pattern detection** (sequences, runs, dates).
+- Build a **GUI** with a colored progress bar.
+- Pair with [Random Password Generator](./randompasswordgenerator) for a complete password tooling pair.
 
 ## Conclusion
-In this project, we learned how to create a Password Strength Checker using Python's regular expression module. We explored pattern matching techniques, security criteria evaluation, and user feedback systems. This project provides valuable insights into cybersecurity practices and demonstrates practical applications of string analysis in Python. The concepts learned here can be extended to more advanced security applications and validation systems. To find more projects like this, you can visit Python Central Hub.
+You built a rule-based password checker, learned why the rules alone are dangerously incomplete, and added entropy + blacklist + breach-corpus checks that turn the tool into something you would actually trust. Real password security is a deceptively deep field, and even a small checker can do a real job — or quietly mislead users. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/passwordstrengthchecker.py). Find more security-focused projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/personaldiary.mdx b/src/content/docs/projects/Beginners/personaldiary.mdx
index f0ac1697..b4a27dab 100644
--- a/src/content/docs/projects/Beginners/personaldiary.mdx
+++ b/src/content/docs/projects/Beginners/personaldiary.mdx
@@ -1,6 +1,6 @@
 ---
 title: Personal Diary Application
-description: Create a digital diary with entry management, search functionality, and mood tracking
+description: Build a CLI diary in Python with mood tracking, full-text search, statistics, and JSON persistence. Learn OOP, file I/O, dataclasses, datetime, and how to grow it into an encrypted journal.
 sidebar:
   order: 55
 hero:
@@ -14,150 +14,279 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a comprehensive personal diary application that allows users to create, store, search, and analyze their daily thoughts and experiences. Features include mood tracking, search functionality, statistics, and persistent JSON storage.
+A personal diary is one of those projects where everything you build is genuinely useful. In this tutorial you will build a command-line journal that lets you write timestamped entries, tag each one with a mood, search through your past, filter by mood, and see stats on your journaling habit. Entries persist between runs via a JSON file you control entirely.
 
-## Prerequisites
+You will learn:
+- How to model entries as a class (and how `@dataclass` cuts that boilerplate).
+- How to read and write JSON with `json.dump` / `json.load`.
+- How to work with timestamps via `datetime`.
+- How to build a clean, menu-driven CLI without spaghetti.
+- How to add real privacy with optional encryption.
 
-- Basic understanding of Python syntax
-- Knowledge of file operations and JSON handling
-- Familiarity with datetime operations
-- Understanding of object-oriented programming
-- Basic knowledge of data structures (lists, dictionaries)
+## Prerequisites
+- Python 3.6 or above (3.7+ recommended for `dataclasses`).
+- A text editor or IDE.
+- Comfort with functions, lists, and dictionaries.
+- Familiarity with running a `.py` file from the terminal.
+
+## Concepts You Will Use
+
+| Concept | Purpose |
+|---|---|
+| **Class** | Group related data (entry fields) and behavior. |
+| **`@dataclass`** | Auto-generate `__init__`, `__repr__`, comparison — less boilerplate. |
+| **`json.dump` / `json.load`** | Persist Python objects to a text file as JSON. |
+| **`datetime`** | Timestamp entries with date and time. |
+| **`Path` / `os.path.exists`** | Detect whether the diary file is new or existing. |
+| **List comprehensions** | Filter and search entries cleanly. |
 
 ## Getting Started
 
+### Create the project
+1. Create a folder named `personal-diary`.
+2. Inside it, create `personaldiary.py`.
+3. (Optional) create `diary.json` — the script will create it for you on first save.
 
+### Write the code
+<FileCode file="projects/beginners/personaldiary.py" lang="python" title="Personal Diary" />
 
-1. **No External Dependencies Required**
-   ```bash
-   # Uses only built-in Python modules
-   ```
+### Run it
+```bash title="run"
+python personaldiary.py
+```
 
-2. **Run the Personal Diary**
-   ```bash
-   python personaldiary.py
-   ```
+```
+1. Add new entry
+2. View all entries
+3. Search entries
+4. Filter by mood
+5. View statistics
+6. Exit
+Choice: 1
+Title: First entry
+Mood (happy/sad/neutral/excited/anxious): happy
+Content (end with empty line):
+> Started my Python diary today.
+>
+Saved.
+```
 
-3. **Start Journaling**
-   - Add new entries with title and content
-   - Select mood for each entry
-   - Use search to find specific entries
-   - View statistics about your journaling habits
+## Step-by-Step Explanation
 
+### 1. The data model
+```python title="personaldiary.py"
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
 
+@dataclass
+class DiaryEntry:
+    title: str
+    content: str
+    mood: str = "neutral"
+    date: str = field(default_factory=lambda: datetime.now().isoformat(timespec="seconds"))
 
-## Code Explanation
+    def to_dict(self):
+        return asdict(self)
 
-### Entry Data Structure
-```python title="personaldiary.py" showLineNumbers{1}
-class DiaryEntry:
-    def __init__(self, date, title, content, mood="neutral"):
-        self.date = date
-        self.title = title
-        self.content = content
-        self.mood = mood
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d)
 ```
+Why `@dataclass`? In one decorator you get:
+- A real `__init__` that accepts each field.
+- A `__repr__` for clean printing.
+- Equality based on field values.
+- Optional default values.
+
+`field(default_factory=...)` is the right way to default a mutable or computed value — it runs each time a new entry is created, so every entry gets its own current timestamp.
+
+### 2. The Diary class
+```python title="personaldiary.py"
+import json
+from pathlib import Path
+
+class Diary:
+    def __init__(self, filename="diary.json"):
+        self.filename = Path(filename)
+        self.entries: list[DiaryEntry] = []
+        self.load()
+
+    def load(self):
+        if self.filename.exists():
+            data = json.loads(self.filename.read_text(encoding="utf-8"))
+            self.entries = [DiaryEntry.from_dict(d) for d in data]
+
+    def save(self):
+        data = [e.to_dict() for e in self.entries]
+        self.filename.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def add(self, entry: DiaryEntry):
+        self.entries.append(entry)
+        self.save()
+```
+Reading and writing the *whole* file each time is fine for personal use — JSON is small and humans like being able to open it in a text editor. If you ever had millions of entries you would swap to SQLite.
 
-Encapsulates diary entries with timestamp, title, content, and mood tracking for comprehensive journaling.
-
-### JSON Persistence
-```python title="personaldiary.py" showLineNumbers{1}
-def save_entries(self):
-    with open(self.filename, 'w') as f:
-        json.dump([entry.to_dict() for entry in self.entries], f, indent=2)
+### 3. Search and filter
+```python title="personaldiary.py"
+def search(self, keyword: str) -> list[DiaryEntry]:
+    k = keyword.lower()
+    return [e for e in self.entries
+            if k in e.title.lower() or k in e.content.lower()]
 
-def load_entries(self):
-    if os.path.exists(self.filename):
-        with open(self.filename, 'r') as f:
-            data = json.load(f)
-            self.entries = [DiaryEntry.from_dict(entry) for entry in data]
+def by_mood(self, mood: str) -> list[DiaryEntry]:
+    return [e for e in self.entries if e.mood == mood]
 ```
-
-Implements data persistence using JSON format for cross-platform compatibility and human readability.
-
-### Search Functionality
-```python title="personaldiary.py" showLineNumbers{1}
-def search_entries(self, keyword):
-    found_entries = []
-    keyword_lower = keyword.lower()
-    
-    for entry in self.entries:
-        if (keyword_lower in entry.title.lower() or 
-            keyword_lower in entry.content.lower()):
-            found_entries.append(entry)
+List comprehensions read like English. The `lower()` calls make search case-insensitive.
+
+### 4. Statistics
+```python title="personaldiary.py"
+from collections import Counter
+
+def stats(self):
+    if not self.entries:
+        return {"total": 0, "moods": {}}
+    moods = Counter(e.mood for e in self.entries)
+    return {
+        "total": len(self.entries),
+        "moods": {m: f"{c} ({c/len(self.entries):.1%})"
+                  for m, c in moods.most_common()},
+        "first": self.entries[0].date,
+        "latest": self.entries[-1].date,
+    }
 ```
-
-Provides case-insensitive search across both titles and content for easy entry retrieval.
-
-### Mood Analytics
-```python title="personaldiary.py" showLineNumbers{1}
-def get_statistics(self):
-    mood_counts = {}
-    for entry in self.entries:
-        mood = entry.mood
-        mood_counts[mood] = mood_counts.get(mood, 0) + 1
-    
-    for mood, count in mood_counts.items():
-        percentage = (count / total_entries) * 100
-        print(f"  {mood}: {count} ({percentage:.1f}%)")
+`Counter` is the right tool any time you find yourself reaching for `dict` plus `+=`.
+
+### 5. The menu loop
+```python title="personaldiary.py"
+def main():
+    diary = Diary()
+    while True:
+        print("\n1. Add  2. View  3. Search  4. By mood  5. Stats  6. Exit")
+        choice = input("Choice: ").strip()
+        if choice == "1":
+            add_entry(diary)
+        elif choice == "2":
+            view_all(diary)
+        elif choice == "3":
+            search_entries(diary)
+        elif choice == "4":
+            filter_by_mood(diary)
+        elif choice == "5":
+            show_stats(diary)
+        elif choice == "6":
+            break
+        else:
+            print("Invalid choice.")
 ```
+Each menu option calls a separate helper function. Each helper does *one* thing. The main loop only routes.
+
+### 6. Multi-line content
+```python title="personaldiary.py"
+def read_multiline(prompt: str) -> str:
+    print(prompt + " (end with an empty line)")
+    lines = []
+    while True:
+        line = input("> ")
+        if line == "":
+            break
+        lines.append(line)
+    return "\n".join(lines)
+```
+This pattern lets users write paragraphs, not just one line. Press Enter on an empty line to finish.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `json.decoder.JSONDecodeError` on first run | File exists but is empty | Check `if self.filename.exists() and self.filename.stat().st_size > 0` |
+| Entries lost after restart | Forgot `self.save()` after adding | Save on every mutating operation, not just exit |
+| Unicode errors | Default encoding mismatch | Always pass `encoding="utf-8"` to read/write |
+| `KeyError` after upgrading the schema | Old file lacks a new field | Use `.get()` in `from_dict` or run a one-shot migration |
+| Search returns nothing | Case mismatch | `.lower()` both sides |
+
+## Variations to Try
+
+### 1. Edit and delete entries
+Number entries when displaying them; let the user type the number to edit or delete.
+
+### 2. Encrypted entries
+A diary should be private. Use **`cryptography.fernet`**:
+```python title="encrypt.py"
+from cryptography.fernet import Fernet
+key = Fernet(...).generate_key()           # store separately!
+cipher = Fernet(key)
+encrypted = cipher.encrypt(content.encode())
+```
+Save `encrypted` instead of the raw content. Decrypt on load. Better: derive the key from a user-provided password using `PBKDF2HMAC`.
+
+### 3. Date filtering
+"Show entries from last week" or "from 2025-01-01 to 2025-01-31".
+```python title="date_range.py"
+from datetime import datetime
+start = datetime.fromisoformat("2025-01-01")
+end   = datetime.fromisoformat("2025-01-31")
+return [e for e in self.entries
+        if start <= datetime.fromisoformat(e.date) <= end]
+```
+
+### 4. Tags / categories
+Add a `tags: list[str]` field; let the user filter by tag the same way as by mood.
+
+### 5. Sentiment analysis
+Use **TextBlob** or **VADER** to compute a sentiment score per entry; correlate it with your self-reported mood.
 
-Analyzes mood patterns and provides statistical insights into emotional trends over time.
-
-### Interactive Menu System
-```python title="personaldiary.py" showLineNumbers{1}
-while True:
-    print("1. Add new entry")
-    print("2. View all entries")
-    print("3. Search entries")
-    print("4. Filter by mood")
-    print("5. View statistics")
-    print("6. Exit")
+### 6. Markdown rendering
+Save entries as Markdown. Export the diary as a single Markdown or HTML file you can print.
+
+### 7. GUI version
+Build a Tkinter UI with a list of dates on the left and the content on the right.
+
+### 8. Cloud backup
+Sync the `diary.json` file to S3 / Google Drive on save. Encrypt before upload.
+
+### 9. Mood chart
+Use **matplotlib** to plot moods over time:
+```python title="chart.py"
+import matplotlib.pyplot as plt
+dates = [e.date for e in diary.entries]
+moods = [e.mood for e in diary.entries]
+plt.plot(dates, moods, marker="o")
+plt.xticks(rotation=45)
+plt.tight_layout(); plt.show()
 ```
 
-Implements user-friendly command-line interface with clear navigation options.
+### 10. Reminder
+Schedule a daily prompt at 9 PM to write today's entry. See [Basic Alarm Clock](./basicalarmclock) for the scheduling idea.
 
-## Features
+## Privacy Considerations
 
-- **Entry Management**: Create, view, and organize diary entries
-- **Mood Tracking**: Record and analyze emotional states over time
-- **Search Functionality**: Find entries by keywords in title or content
-- **Mood Filtering**: View entries by specific emotional states
-- **Statistics Dashboard**: Analyze journaling patterns and mood trends
-- **Persistent Storage**: Automatic saving and loading via JSON files
-- **Date Tracking**: Automatic timestamp recording for all entries
-- **Multi-line Content**: Support for detailed, lengthy diary entries
+A diary on disk is plaintext by default. If you keep anything personal:
+- **Move the diary file out of any auto-synced folder** (Dropbox, OneDrive, iCloud) unless those services are encrypted at rest with your key.
+- **Encrypt at rest** with `cryptography.fernet` and a password-derived key.
+- **Never commit your diary file to Git**. Add `diary.json` to `.gitignore`.
+- **Back up the file** somewhere safe — losing it is permanent.
 
-## Next Steps
+## Real-World Applications
 
-### Enhancements
-- Add entry editing and deletion capabilities
-- Implement password protection and encryption
-- Create backup and export functionality
-- Add photo/image attachments to entries
-- Implement reminder system for regular journaling
-- Create mood visualization with charts
-- Add entry templates for different occasions
-- Implement cloud sync capabilities
-
-### Learning Extensions
-- Study data visualization libraries (matplotlib, plotly)
-- Explore encryption for privacy protection
-- Learn about database integration (SQLite)
-- Practice with GUI development using Tkinter
-- Understand natural language processing for sentiment analysis
-- Explore mobile app development for cross-platform access
+- **Personal journaling** — what this is.
+- **Mood / habit tracking** — bullet-journal-style logs.
+- **Reading log** or **workout log** — same data structure, different fields.
+- **Customer-service ticketing** prototypes — entries are tickets, moods are priorities.
+- **Bug-tracking** for solo projects.
 
 ## Educational Value
+- **Data modeling** with `@dataclass`.
+- **Persistence** with JSON, including schema evolution.
+- **Searching and filtering** with list comprehensions.
+- **Counting and aggregation** with `Counter`.
+- **CLI design** — clear menus, helper functions, no global state.
 
-This project teaches:
-- **Data Persistence**: Saving and loading application data across sessions
-- **Object-Oriented Design**: Creating classes for data modeling and organization
-- **JSON Processing**: Working with structured data formats
-- **Search Algorithms**: Implementing text search and filtering functionality
-- **Statistical Analysis**: Computing and presenting data insights
-- **User Interface Design**: Creating intuitive command-line interactions
-- **File Management**: Handling file operations and error management
-- **Date/Time Handling**: Working with timestamps and date formatting
-
-Perfect for understanding data management, user interaction design, and building personal productivity applications.
+## Next Steps
+- Build the **encryption layer** (`cryptography.fernet`).
+- Add a **edit/delete** flow.
+- Plot mood over time with **matplotlib**.
+- Wrap with a **Tkinter GUI** or a **Flask web app**.
+- Migrate storage from JSON to **SQLite** when you cross a few thousand entries.
+
+## Conclusion
+You built a real productivity tool: timestamped, searchable, statistically aware. The same architecture (data class + persistence + menu loop) underlies thousands of small CLI tools used in the wild. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/personaldiary.py). Explore more on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/quizapp.mdx b/src/content/docs/projects/Beginners/quizapp.mdx
index efba13ca..d89d16a2 100644
--- a/src/content/docs/projects/Beginners/quizapp.mdx
+++ b/src/content/docs/projects/Beginners/quizapp.mdx
@@ -1,6 +1,6 @@
 ---
 title: Basic Quiz Game
-description: An interactive Python quiz application built with Tkinter featuring multiple-choice questions, score tracking, and navigation controls for an engaging learning experience.
+description: Build a Tkinter quiz app in Python with multiple-choice questions, shuffling, scoring, timer, JSON question bank, and a path to multi-category quizzes with explanations and persistence.
 sidebar: 
     order: 22
 hero:
@@ -13,262 +13,291 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Basic Quiz Game is an interactive Python application that presents multiple-choice questions about world capitals through a graphical user interface. Built with Tkinter, the application features question navigation, score tracking, answer validation, and various control options including shuffle, reset, and back functionality. This project demonstrates GUI development, data management, user interaction handling, and educational software design principles.
+A quiz app touches everything: UI widgets, state machines, randomization, scoring, navigation, and (with a bit of work) persistent question banks. In this tutorial you will build a Tkinter quiz game on world capitals with 10 multiple-choice questions, then refactor it from hard-coded arrays into a clean `Question` class, load questions from JSON, add a countdown timer, support multiple categories, and finish with a sketch of a results screen that explains the wrong answers.
+
+You will leave understanding:
+- The radio-button + StringVar pattern for multiple-choice input.
+- Per-question state vs. global score state.
+- Why parallel arrays (`questions[]`, `options[]`, `answers[]`) are fragile and how to fix it.
+- How to load a JSON question bank.
+- How to build a non-blocking countdown timer with `after`.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- tkinter module (usually comes pre-installed)
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with Python; Linux: `sudo apt install python3-tk`).
+- Comfort with Tkinter basics. [Calculator GUI](./calculatorgui) is a softer first project.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-Note: This project uses only built-in Python modules, so no additional installations are required.
+### Create the project
+1. Create folder `quiz-game`.
+2. Inside, create `quizapp.py`.
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `quiz-game`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `quizapp.py`.
-4. Copy the given code and paste it in your `quizapp.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `quizapp.py` file.
-<FileCode file="projects/beginners/quizapp.py" lang="python" title="Basic Quiz Game" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `quiz-game`.
-```cmd title="command" showLineNumbers{1} {1-15}
+### Write the code
+<FileCode file="projects/beginners/quizapp.py" lang="python" title="Quiz App" />
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\quiz-game> python quizapp.py
-# A GUI window will open with:
-# - Question display area
-# - Four multiple-choice radio buttons
-# - Navigation buttons (Next, Back, Reset, Shuffle)
-# - Show Score button
-# - Score tracking functionality
-
-# Example quiz flow:
-Question 1: "What is the Capital of India?"
-Options: New Delhi, Mumbai, Kolkata, Chennai
-Select answer → Click Next → Continue to next question
-Final Score: "Your Score is 8/10"
+# Window opens with:
+#   - Question text at the top
+#   - 4 radio buttons for choices
+#   - Next / Back / Shuffle / Reset / Show Score buttons
 ```
 
-## Explanation
-
-### Code Structure Overview
-The quiz application is organized into several key components:
+## Step-by-Step Explanation
 
-1. **Data Structure:** Questions, options, and answers arrays
-2. **GUI Components:** Labels, radio buttons, and control buttons
-3. **Navigation Logic:** Forward/backward movement through questions
-4. **Score Management:** Tracking correct answers and displaying results
-
-### Data Setup
-1. **Import modules and create main window.**
-```python title="quizapp.py" showLineNumbers{1} {1-8}
+### 1. Imports and root window
+```python title="quizapp.py"
 from tkinter import *
 from tkinter import messagebox
 import random
 
 root = Tk()
 root.title("Quiz App")
-root.geometry("500x500")
-root.resizable(0, 0)
+root.geometry("520x420")
+root.resizable(False, False)
 ```
+A fixed-size window keeps the layout predictable.
 
-2. **Initialize quiz data structures.**
-```python title="quizapp.py" showLineNumbers{1} {1-10}
+### 2. The question bank
+```python title="quizapp.py"
 questions = [
     "What is the Capital of India?",
     "What is the Capital of USA?",
-    "What is the Capital of UK?",
-    # ... more questions
+    # … 8 more
 ]
-
 options = [
     ["New Delhi", "Mumbai", "Kolkata", "Chennai"],
     ["New York", "Washington DC", "California", "Texas"],
-    # ... corresponding options
+    # … 8 more lists
 ]
-
-answers = [0, 1, 0, 0, 0, 0, 0, 0, 0, 0]  # Index of correct answers
+answers = [0, 1, 0, 0, 4, 0, 0, 1, 0, 0]      # index of the correct option per question
 ```
+This **parallel-arrays** layout works but is fragile — changing the order of one list without the others silently corrupts the quiz. The refactor below fixes it.
 
-3. **Core navigation and scoring logic.**
-```python title="quizapp.py" showLineNumbers{1} {1-15}
-def selected():
-    global ans, ques_num, score, ans_list
-    if ques_num == 10:
-        submit.config(text="Finish")
-    if ans == answers[ques_num - 1]:
+### 3. State variables
+```python title="quizapp.py"
+selected = IntVar(value=-1)
+current = 0
+score = 0
+```
+`IntVar` is Tkinter's wrapper that lets the same value drive multiple widgets at once — radio buttons share it.
+
+### 4. UI widgets
+```python title="quizapp.py"
+question_lbl = Label(root, text=questions[current],
+                     font=("Arial", 16, "bold"), wraplength=480, pady=10)
+question_lbl.pack(pady=10)
+
+radios = []
+for i in range(4):
+    rb = Radiobutton(root, text=options[current][i], variable=selected,
+                     value=i, font=("Arial", 12), anchor="w", padx=20)
+    rb.pack(fill="x")
+    radios.append(rb)
+```
+All four radios share `selected`. Whichever one the user clicks sets `selected.get()` to that radio's `value=`.
+
+### 5. Navigation
+```python title="quizapp.py"
+def show_question(idx):
+    question_lbl.config(text=questions[idx])
+    for i, rb in enumerate(radios):
+        rb.config(text=options[idx][i])
+    selected.set(-1)              # clear selection
+
+def next_q():
+    global current, score
+    if selected.get() == -1:
+        return messagebox.showwarning("Pick one", "Select an option first.")
+    if selected.get() == answers[current]:
         score += 1
-        ans_list.append(1)
-    else:
-        ans_list.append(0)
-    ques_num += 1
-    ques.config(text=questions[ques_num - 1])
-    for i in range(4):
-        radio[i].config(text=options[ques_num - 1][i])
-    if ques_num == 11:
-        messagebox.showinfo("Score", f"Your Score is {score}")
+    current += 1
+    if current >= len(questions):
+        messagebox.showinfo("Done", f"Your score: {score}/{len(questions)}")
         root.destroy()
+        return
+    show_question(current)
+
+def shuffle():
+    global current, score
+    combined = list(zip(questions, options, answers))
+    random.shuffle(combined)
+    for i, (q, o, a) in enumerate(combined):
+        questions[i], options[i], answers[i] = q, o, a
+    current = 0; score = 0
+    show_question(current)
 ```
+`zip(questions, options, answers)` is the cleanest way to keep the parallel arrays in sync during a shuffle — pair them up, shuffle once, unzip back.
 
-## Features
-- **10 Geography Questions:** World capitals quiz covering major countries
-- **Multiple Choice Interface:** Four options per question with radio button selection
-- **Score Tracking:** Real-time scoring with final results display
-- **Navigation Controls:** Next, Back, Reset, and Shuffle functionality
-- **Question Shuffling:** Randomize question order for variety
-- **Answer Validation:** Automatic checking and score calculation
-- **User-Friendly Interface:** Clean design with intuitive controls
-
-## Quiz Questions Covered
-The application includes questions about capitals of:
-1. **India** → New Delhi
-2. **USA** → Washington DC
-3. **UK** → London
-4. **China** → Beijing
-5. **Japan** → Tokyo
-6. **Russia** → Moscow
-7. **France** → Paris
-8. **Germany** → Berlin
-9. **Brazil** → Brasilia
-10. **Australia** → Canberra (Sydney in options)
-
-## Control Functions
-
-### Navigation Functions
-- **Next/Submit:** Move to next question or finish quiz
-- **Back:** Return to previous question (with score adjustment)
-- **Reset:** Restart quiz from the beginning
-- **Shuffle:** Randomize question order
-
-### Scoring Functions
-- **Real-time Tracking:** Score updates as questions are answered
-- **Answer History:** Maintains record of correct/incorrect responses
-- **Final Display:** Shows total score at quiz completion
-
-## How to Use
-1. **Start Quiz:** Launch the application to see the first question
-2. **Select Answer:** Click on one of the four radio button options
-3. **Navigate:** Use Next/Back buttons to move through questions
-4. **View Progress:** Current question number and score are tracked
-5. **Shuffle Questions:** Click Shuffle to randomize question order
-6. **Reset:** Start over at any time with the Reset button
-7. **Finish:** Complete all questions to see final score
-8. **Show Score:** View current score at any time
-
-## GUI Layout
-```
-┌─────────────────────────────────────┐
-│          Quiz Question              │
-├─────────────────────────────────────┤
-│  ○ Option A                        │
-│  ○ Option B                        │
-│  ○ Option C                        │
-│  ○ Option D                        │
-├─────────────────────────────────────┤
-│ [Next] [Back] [Reset] [Shuffle]    │
-│ [Show Score]                       │
-└─────────────────────────────────────┘
-```
+### 6. Wire the buttons
+```python title="quizapp.py"
+Button(root, text="Next",    command=next_q).pack(side="left", padx=10, pady=20)
+Button(root, text="Shuffle", command=shuffle).pack(side="left", padx=10, pady=20)
+Button(root, text="Quit",    command=root.destroy).pack(side="right", padx=10, pady=20)
 
-## Next Steps
-You can enhance this project by:
-- Adding more question categories (Science, History, Sports)
-- Implementing a timer for each question
-- Creating difficulty levels (Easy, Medium, Hard)
-- Adding images or multimedia to questions
-- Implementing user registration and profile saving
-- Creating a question bank with random selection
-- Adding detailed explanations for answers
-- Implementing multiple quiz modes (Timed, Survival, Practice)
-- Creating leaderboards and high scores
-- Adding sound effects and animations
-
-## Enhanced Features Ideas
-```python title="quizapp.py" showLineNumbers{1}
-def enhanced_quiz():
-    # Features to add:
-    # - Question categories and filtering
-    # - Timer functionality
-    # - Detailed result analysis
-    # - User profiles and progress tracking
-    # - Question difficulty ratings
-    # - Multimedia support
-    pass
-
-class QuizQuestion:
-    def __init__(self, question, options, answer, category, difficulty):
-        self.question = question
-        self.options = options
-        self.answer = answer
-        self.category = category
-        self.difficulty = difficulty
+root.mainloop()
 ```
 
-## Educational Applications
-- **Geography Learning:** World capitals and countries
-- **Academic Testing:** Create subject-specific quizzes
-- **Training Programs:** Employee knowledge assessment
-- **Language Learning:** Vocabulary and grammar tests
-- **Certification Prep:** Practice exams for various fields
-
-## Customization Options
-### Adding New Questions
-```python title="quizapp.py" showLineNumbers{1}
-new_questions = [
-    "What is the largest planet?",
-    "Who wrote Romeo and Juliet?",
-    # Add more questions
+## Refactor: One Class Per Question
+
+Parallel arrays are an anti-pattern. The fix:
+```python title="oop.py"
+from dataclasses import dataclass
+
+@dataclass
+class Question:
+    text: str
+    options: list[str]
+    correct: int          # index into options
+    explanation: str = "" # shown on the results screen
+
+BANK = [
+    Question("What is the capital of India?",
+             ["New Delhi", "Mumbai", "Kolkata", "Chennai"], 0,
+             "New Delhi has been India's capital since 1911."),
+    Question("What is the capital of USA?",
+             ["New York", "Washington DC", "Chicago", "Los Angeles"], 1,
+             "Washington, D.C. was founded as the capital in 1790."),
+    # …
 ]
+```
+Now each question owns its data. Shuffling is `random.shuffle(BANK)`. Adding an `explanation` to display at the end is a one-line addition.
 
-new_options = [
-    ["Earth", "Jupiter", "Saturn", "Mars"],
-    ["Shakespeare", "Dickens", "Austen", "Tolkien"],
-    # Add corresponding options
-]
+## Load from JSON
 
-new_answers = [1, 0]  # Index of correct answers
+```python title="bank.json"
+[
+  {"text": "Capital of India?", "options": ["New Delhi","Mumbai","Kolkata","Chennai"], "correct": 0, "explanation": "..."},
+  …
+]
+```
+```python title="load.py"
+import json
+from pathlib import Path
+BANK = [Question(**d) for d in json.loads(Path("bank.json").read_text())]
+```
+Non-programmers can now author quizzes by editing the JSON file. Multi-category support is one folder of JSON files.
+
+## Add a Per-Question Timer
+
+```python title="timer.py"
+remaining = 0
+def start_timer(seconds=15):
+    global remaining
+    remaining = seconds
+    tick()
+
+def tick():
+    timer_lbl.config(text=f"{remaining}s")
+    if remaining <= 0:
+        next_q()                    # auto-advance
+        return
+    root.after(1000, decrement)
+
+def decrement():
+    global remaining
+    remaining -= 1
+    tick()
+```
+Call `start_timer()` whenever `show_question` runs. The user has 15 seconds before the answer locks in.
+
+## Results Screen
+
+Instead of a popup, end on a result page that shows what they got right and wrong:
+```python title="results.py"
+def show_results():
+    win = Toplevel(root)
+    win.title("Results")
+    Label(win, text=f"Score: {score}/{len(BANK)}",
+          font=("Arial", 18, "bold")).pack(pady=10)
+    for i, q in enumerate(BANK):
+        correct = q.options[q.correct]
+        yours = q.options[answers_given[i]] if answers_given[i] >= 0 else "—"
+        mark = "✅" if answers_given[i] == q.correct else "❌"
+        Label(win, text=f"{mark} {q.text}\n  You: {yours}  Correct: {correct}\n  {q.explanation}",
+              wraplength=600, justify="left").pack(anchor="w", padx=10)
 ```
+Educational quizzes live or die on the feedback — a results screen that explains wrong answers turns the quiz into a teaching tool.
 
-### Styling Improvements
-```python title="quizapp.py" showLineNumbers{1}
-# Enhanced styling options
-root.config(bg="#f0f0f0")
-question_font = ("Arial", 16, "bold")
-option_font = ("Arial", 12)
-button_style = {"font": ("Arial", 10), "bg": "#4CAF50", "fg": "white"}
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Quiz hangs at last question | Off-by-one — `current > len` after submit | Check `>= len(questions)` |
+| Same question shown twice | Manually tracked index slipped | Use `enumerate` + a single source list |
+| Shuffle desyncs the answer | Shuffled `questions` but not `options` and `answers` | Use the `zip` + `shuffle` pattern, or `Question` objects |
+| `IntVar.get()` returns 0 with nothing selected | Default is 0, indistinguishable from "chose option 0" | Initialize to `-1` and treat as "unanswered" |
+| Timer fires after window closed | Pending `after` callback | Track and cancel with `root.after_cancel(id)` |
+| Score wrong after "Back" | Decrementing not implemented | Either disable Back, or recompute score from a list |
+
+## Variations to Try
+
+### 1. Multiple categories
+A category-picker screen. JSON folder structure:
+```
+banks/
+  geography.json
+  science.json
+  history.json
 ```
 
-## Educational Value
-This project teaches:
-- **GUI Development:** Creating interactive desktop applications
-- **Data Management:** Organizing questions, options, and answers
-- **Event Handling:** Managing user interactions and button clicks
-- **State Management:** Tracking quiz progress and scoring
-- **User Experience Design:** Creating intuitive interfaces
-
-## Common Enhancements
-- **Timer Implementation:** Add countdown for each question
-- **Category Selection:** Allow users to choose question topics
-- **Difficulty Levels:** Implement easy, medium, hard questions
-- **Results Analysis:** Show detailed performance statistics
-- **Data Persistence:** Save scores and progress to files
+### 2. Difficulty levels
+Add `difficulty: int` (1-5) to each `Question`. Pick a subset of questions matching the user's chosen level.
+
+### 3. Image questions
+Each `Question` can have an `image_path`. Display it with `tk.PhotoImage` above the text.
+
+### 4. Audio questions
+Useful for language quizzes — play a `.wav` clip and ask "what did the voice say?". See [Basic Music Player](./basicmusicplayer).
+
+### 5. Score persistence
+Save `(timestamp, category, score)` rows to a JSON file. Show a "high scores" leaderboard at startup.
+
+### 6. Online quiz bank
+Pull questions from <https://opentdb.com> (free trivia API).
+
+### 7. Time per question
+Award more points for faster correct answers. Penalize wrong answers under time pressure to discourage random guessing.
+
+### 8. Adaptive difficulty
+After two correct answers in a row, jump up a difficulty level; after two wrong, drop down. Classic "spaced repetition" lite.
+
+### 9. Multiplayer
+Two players take turns on the same screen, or split-screen with separate scores.
+
+### 10. Quiz editor
+A second Tkinter window where instructors author new questions and save them to the JSON bank.
+
+### 11. Web version
+Flask + Jinja (see [Basic Web Server](./basicwebserver)). State lives in the session.
+
+### 12. Mobile version
+Re-implement in **Kivy** (or wrap the web version as a PWA) to ship to phones.
 
 ## Real-World Applications
-- **Educational Software:** Classroom quiz applications
-- **Training Systems:** Corporate knowledge testing
-- **Certification Tools:** Practice exams for licenses/certifications
-- **Entertainment:** Trivia games and brain teasers
-- **Assessment Tools:** Academic evaluation software
-
-## Performance Considerations
-- **Memory Usage:** Efficient data structure management
-- **Response Time:** Quick GUI updates and navigation
-- **Scalability:** Easy addition of new questions and categories
-- **User Experience:** Smooth interaction and feedback
+- **Education** — flashcard apps, language learning (Duolingo-style).
+- **Corporate training** — compliance and onboarding quizzes.
+- **Certification practice** — AWS / Cisco / Microsoft exam prep.
+- **Trivia games** — bar trivia apps, party games.
+- **Self-assessment** — personality, aptitude, skill measurement.
+
+## Educational Value
+- **Tkinter widgets** — Radiobutton + IntVar.
+- **State management** — current question, score, selected option.
+- **Why objects beat parallel arrays** — a textbook refactor.
+- **Persistence** — JSON-backed question banks.
+- **UX of feedback** — results screens vs. just a number.
+
+## Next Steps
+- Refactor to the **`Question` dataclass** above.
+- Move questions to a **JSON file**; support **multiple categories**.
+- Add a **per-question timer**.
+- Build a **results screen** with explanations.
+- Persist **high scores** to disk.
+- Try the **Open Trivia DB** integration for endless content.
 
 ## Conclusion
-In this project, we learned how to create a Basic Quiz Game using Python's Tkinter library. We explored GUI development, data management, event handling, and user interaction design. This project demonstrates how to create engaging educational software with proper navigation controls and scoring systems. The quiz application serves as an excellent foundation for more complex educational applications and can be easily customized for different subjects and learning objectives. To find more projects like this, you can visit Python Central Hub.
+You built a working quiz app, fixed its biggest weakness (parallel arrays), and have a path from "hard-coded ten capitals" to "multi-category, timed, leaderboard-driven trivia engine." The exact same architecture powers commercial flashcard apps and corporate training systems. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/quizapp.py). Find more games on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/randompasswordgenerator.mdx b/src/content/docs/projects/Beginners/randompasswordgenerator.mdx
index 0f430b2b..774d9753 100644
--- a/src/content/docs/projects/Beginners/randompasswordgenerator.mdx
+++ b/src/content/docs/projects/Beginners/randompasswordgenerator.mdx
@@ -1,6 +1,6 @@
 ---
 title: Random Password Generator
-description: A Python application that generates strong, random passwords with customizable length using letters, numbers, and special characters.
+description: Generate strong random passwords in Python. Learn the difference between random and secrets, why most generators are insecure, password entropy, clipboard helpers, passphrase mode, and a Tkinter GUI version.
 sidebar: 
     order: 16
 hero:
@@ -13,148 +13,258 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Random Password Generator is a simple yet powerful Python application that creates strong, random passwords to help users maintain better security practices. The application generates passwords using a combination of uppercase letters, lowercase letters, numbers, and special characters. Users can specify the desired password length, making it flexible for different security requirements. This project demonstrates working with Python's `random` and `string` modules, user input handling, and string manipulation techniques.
+Most "password generator" tutorials online quietly teach you to write an insecure one. They use Python's `random` module — which is **not** cryptographically secure. In this tutorial we will build the basic version first (so you understand the parts), then fix it with the right module (`secrets`), then go further with entropy calculations, customization flags, clipboard copy, a passphrase mode, and a Tkinter GUI.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
+You will learn:
+- Why `random` is wrong for passwords and `secrets` is right.
+- How to combine character sets (letters, digits, punctuation) cleanly.
+- How to **guarantee** that every required character type is present.
+- How to compute the **entropy** of a password and what that number means.
+- How to copy a generated password to the clipboard and clear it after a delay.
+- How to wrap the whole thing in a tiny GUI.
+
+## The `random` vs. `secrets` Trap
+
+Almost every online tutorial uses:
+```python title="insecure.py"
+import random
+password = ''.join(random.choice(charset) for _ in range(length))   # ❌
+```
+The `random` module uses the **Mersenne Twister** PRNG. It is fast, statistically uniform, and **completely predictable** if you know its state. Given enough output an attacker can reconstruct the seed and predict every future call.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+For anything security-related — passwords, tokens, session IDs, OTP codes — use **`secrets`**:
+```python title="secure.py"
+import secrets, string
+charset = string.ascii_letters + string.digits + string.punctuation
+password = ''.join(secrets.choice(charset) for _ in range(length))   # ✅
+```
+The `secrets` module is a thin wrapper over your OS's cryptographic randomness source (`/dev/urandom` on Unix, `CryptGenRandom` on Windows). It is what every standard-library example for cryptography uses.
 
-Note: This project uses only built-in Python modules (`random` and `string`), so no additional installations are required.
+## Prerequisites
+- Python 3.6 or above (`secrets` was added in 3.6).
+- A code editor or IDE.
+- Familiarity with strings, loops, and the `input()` function.
 
 ## Getting Started
-#### Create a Project
+
+### Create the project
 1. Create a folder named `random-password-generator`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `randompasswordgenerator.py`.
-4. Copy the given code and paste it in your `randompasswordgenerator.py` file.
+2. Inside it, create `randompasswordgenerator.py`.
 
-## Write the Code
-1. Copy and paste the following code in your `randompasswordgenerator.py` file.
+### Write the code
 <FileCode file="projects/beginners/randompasswordgenerator.py" lang="python" title="Random Password Generator" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `random-password-generator`.
-```cmd title="command" showLineNumbers{1} {1-15}
-C:\Users\Your Name\random-password-generator> python randompasswordgenerator.py
-Random Password Generator
-Enter the length of password: 
-12
-K8@mN2$pX9!z
 
+### Run it
+```cmd title="command" showLineNumbers{1} {1-15}
 C:\Users\Your Name\random-password-generator> python randompasswordgenerator.py
 Random Password Generator
-Enter the length of password: 
-16
+Length: 16
 aB3#dE7&hI9@kL2$
-
-C:\Users\Your Name\random-password-generator> python randompasswordgenerator.py
-Random Password Generator
-Enter the length of password: 
-8
-mK9@nP2!
 ```
 
-## Explanation
-1. Import the required modules.
-```python title="randompasswordgenerator.py" showLineNumbers{1} {1-2}
-import random
+## Step-by-Step Explanation
+
+### 1. Pick the right module
+```python title="randompasswordgenerator.py"
+import secrets
 import string
 ```
+- `secrets` for randomness.
+- `string` provides ready-made character classes (`ascii_letters`, `digits`, `punctuation`).
 
-2. Define the main password generation function.
-```python title="randompasswordgenerator.py" showLineNumbers{1} {1-3}
-def randompasswordgenerator():
-    print("Random Password Generator")
-    print("Enter the length of password: ")
+### 2. Build the character set
+```python title="randompasswordgenerator.py"
+ALPHABET = string.ascii_letters + string.digits + string.punctuation
 ```
+Concatenated strings — Python treats this as one big string of characters from which to pick.
 
-3. Get user input for password length.
-```python title="randompasswordgenerator.py" showLineNumbers{1} {1-2}
-length = int(input())
-password = ''
+### 3. Generate
+```python title="randompasswordgenerator.py"
+def generate(length: int = 16) -> str:
+    return "".join(secrets.choice(ALPHABET) for _ in range(length))
 ```
+A generator expression inside `"".join(...)` is the idiomatic way to build a string of N characters.
 
-4. Generate the password using random characters.
-```python title="randompasswordgenerator.py" showLineNumbers{1} {1-3}
-for i in range(length):
-    password += random.choice(string.ascii_letters + string.digits + string.punctuation)
-print(password)
+### 4. Read the length and print
+```python title="randompasswordgenerator.py"
+length = int(input("Length: "))
+print(generate(length))
 ```
 
-5. Execute the function when script is run directly.
-```python title="randompasswordgenerator.py" showLineNumbers{1} {1-2}
-if __name__ == "__main__":
-    randompasswordgenerator()
+## Guarantee Variety
+
+A naive generator may produce a password with no digits. Many password rules require at least one of each type:
+
+```python title="guarantee.py"
+import secrets, string
+
+def generate(length: int = 16) -> str:
+    if length < 4:
+        raise ValueError("length must be ≥ 4 to satisfy character-class rules")
+    pools = [
+        string.ascii_lowercase,
+        string.ascii_uppercase,
+        string.digits,
+        string.punctuation,
+    ]
+    # One mandatory character from each pool…
+    password = [secrets.choice(pool) for pool in pools]
+    # …then fill the rest from the combined alphabet
+    alphabet = "".join(pools)
+    password += [secrets.choice(alphabet) for _ in range(length - len(pools))]
+    secrets.SystemRandom().shuffle(password)   # avoid predictable ordering
+    return "".join(password)
 ```
+Subtle point: do not just *append* one digit at the end — that is a known weakness. We **shuffle** the whole list so the required characters land in random positions.
+
+## Entropy: How Strong Is Strong?
 
-## Character Sets Used
-The password generator uses the following character sets from Python's `string` module:
+Password entropy in bits = `log₂(alphabet_size ** length)`.
 
-- **`string.ascii_letters`:** Both uppercase and lowercase letters (a-z, A-Z)
-- **`string.digits`:** Numbers (0-9)
-- **`string.punctuation`:** Special characters and symbols
+| Alphabet size | Length | Entropy (bits) | Comment |
+|---|---|---|---|
+| 26 (lowercase only) | 8 | ~38 | Crackable in minutes by a GPU |
+| 62 (letters + digits) | 12 | ~71 | Reasonable |
+| 95 (full printable ASCII) | 16 | ~104 | Strong |
+| 95 | 20 | ~131 | Excellent |
 
-This combination ensures strong passwords with high entropy and complexity.
+A function to compute it:
+```python title="entropy.py"
+import math
+def entropy_bits(password: str) -> float:
+    pool = 0
+    if any(c.islower() for c in password): pool += 26
+    if any(c.isupper() for c in password): pool += 26
+    if any(c.isdigit() for c in password): pool += 10
+    if any(c in string.punctuation for c in password): pool += len(string.punctuation)
+    return len(password) * math.log2(max(pool, 1))
 
-## Features
-- **Customizable Length:** Users can specify any password length
-- **Strong Character Mix:** Includes letters, numbers, and special characters
-- **High Randomness:** Uses Python's secure random module
-- **Simple Interface:** Easy-to-use command-line interface
-- **Instant Generation:** Fast password creation
-- **No External Dependencies:** Uses only built-in Python modules
+print(f"{entropy_bits(p):.1f} bits")
+```
+The conventional wisdom: aim for **≥ 80 bits** for important accounts, **≥ 128 bits** for master passwords / vault keys.
 
-## Security Considerations
-- **Character Variety:** Uses all types of characters for maximum security
-- **Randomness:** Each character is independently randomly selected
-- **Length Flexibility:** Supports any length for different security requirements
-- **No Patterns:** Generated passwords have no predictable patterns
+## Avoid Ambiguous Characters
 
-## Password Strength Guidelines
-- **Minimum 8 characters:** For basic security
-- **12+ characters:** For good security
-- **16+ characters:** For excellent security
-- **Include all character types:** Letters, numbers, and symbols
+Some characters are easy to confuse: `0` / `O`, `1` / `l` / `I`. Let the user opt out:
+```python title="no_ambig.py"
+AMBIGUOUS = "0Oo1lI"
+def generate(length, no_ambig=False):
+    pool = ALPHABET
+    if no_ambig:
+        pool = "".join(c for c in pool if c not in AMBIGUOUS)
+    return "".join(secrets.choice(pool) for _ in range(length))
+```
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Implementing password strength indicators
-- Adding options to exclude similar characters (0, O, l, 1)
-- Creating memorable password options (using words + numbers)
-- Adding password history (with secure storage)
-- Implementing copy-to-clipboard functionality
-- Adding batch password generation
-- Creating password validation against common passwords
-- Adding custom character set options
-- Implementing pronunciation guides for generated passwords
-
-## Enhanced Version Ideas
-```python title="randompasswordgenerator.py" showLineNumbers{1}
-def enhanced_password_generator():
-    # Add options for:
-    # - Exclude ambiguous characters
-    # - Ensure at least one of each character type
-    # - Generate multiple passwords at once
-    # - Save passwords to encrypted file
-    pass
+## Copy to Clipboard
+
+Generated passwords are easier to use if they land directly in the clipboard. Two options:
+
+```bash title="install"
+pip install pyperclip
+```
+```python title="clipboard.py"
+import pyperclip
+pyperclip.copy(password)
+print("Copied to clipboard.")
+```
+
+For extra hygiene, clear the clipboard after 30 seconds:
+```python title="clear.py"
+import threading
+def clear_later():
+    pyperclip.copy("")
+threading.Timer(30, clear_later).start()
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Uses `random.choice` | Insecure PRNG | Switch to `secrets.choice` |
+| Required character placed at index 0 every time | Built the password by *appending* required characters | Shuffle after assembly |
+| `int(input())` crashes on letters | No validation | Wrap with `try/except` |
+| Password always rejected by the site | Missing a required character class | Use the "guarantee variety" version |
+| Same password generated twice in a script | Reused a seeded `random` | Never seed `secrets` (it is not seedable) |
+
+## Variations to Try
+
+### 1. Passphrase mode (Diceware)
+Long, memorable, and high-entropy. Five random words from a word list of 7,776 is ~64 bits already.
+```python title="passphrase.py"
+import secrets, pathlib
+WORDS = pathlib.Path("eff_wordlist.txt").read_text().splitlines()
+def passphrase(n=5):
+    return "-".join(secrets.choice(WORDS) for _ in range(n))
+```
+EFF publishes a free word list specifically for this purpose.
+
+### 2. Multiple passwords at once
+```python title="batch.py"
+n = int(input("How many? "))
+for _ in range(n):
+    print(generate(16))
 ```
 
+### 3. Strength meter
+Reuse the entropy function above; rate as Weak / OK / Strong / Excellent.
+
+### 4. CLI flags with argparse
+```bash title="cli"
+python randompasswordgenerator.py --length 20 --no-ambig --count 5
+```
+
+### 5. GUI version
+```python title="gui.py"
+import tkinter as tk
+from tkinter import ttk
+def gen():
+    out_var.set(generate(int(length_var.get())))
+root = tk.Tk()
+length_var = tk.StringVar(value="16")
+out_var = tk.StringVar()
+tk.Entry(root, textvariable=length_var).pack()
+tk.Button(root, text="Generate", command=gen).pack()
+tk.Entry(root, textvariable=out_var, width=40).pack()
+root.mainloop()
+```
+
+### 6. Save to an encrypted vault
+Append generated passwords (with a label) to an encrypted file using `cryptography.fernet`. See [Personal Diary](./personaldiary) for the same encryption idea.
+
+### 7. QR-code output
+Use `pip install qrcode` to render the password as a QR code you can scan to a phone.
+
+### 8. Check against breach corpora
+Send a SHA-1 prefix of the password to **Have I Been Pwned**'s [k-anonymity API](https://haveibeenpwned.com/API/v3#PwnedPasswords) — if it appears in known breaches, regenerate.
+
+## Best Practices for Password Generation
+- **Use `secrets`.** Always. Forever.
+- **Length matters more than complexity.** A long passphrase beats a short symbol soup.
+- **Guarantee character classes** when sites demand them; do not hope randomness gives you one.
+- **Shuffle after assembly** to avoid predictable positions.
+- **Never log generated passwords** anywhere (stdout in a CI run, error message, debug print).
+- **Copy via clipboard, do not save to a plain file.** If you must persist, encrypt.
+
 ## Common Use Cases
-- **User Account Creation:** Generate strong passwords for new accounts
-- **Password Updates:** Create new passwords for existing accounts
-- **Temporary Passwords:** Generate one-time use passwords
-- **API Keys:** Create random strings for API authentication
-- **Security Testing:** Generate test passwords for applications
-
-## Best Practices
-- **Never Reuse:** Generate a unique password for each account
-- **Store Securely:** Use a password manager to store generated passwords
-- **Regular Updates:** Change passwords periodically
-- **Avoid Predictable Patterns:** Use random generation over patterns
-- **Backup Safely:** Keep secure backups of important passwords
+- New account signups.
+- API key / token generation.
+- One-time temporary passwords for password resets.
+- Database / service credentials (developer ergonomics + safety).
+- Wi-Fi guest passwords printed on a slip.
+
+## Educational Value
+- **Cryptographic randomness** — why `random` is the wrong tool.
+- **Entropy** — turning intuition about password strength into a number.
+- **String composition** — building from character classes.
+- **CLI ergonomics** — flags, validation, clipboard integration.
+- **Security mindset** — small choices like "shuffle after assembly" matter.
+
+## Next Steps
+- Switch to `secrets` everywhere immediately.
+- Add **clipboard copy** with auto-clear.
+- Add a **passphrase mode** using the EFF word list.
+- Integrate with **Have I Been Pwned** for compromise checks.
+- Wrap in a **GUI** or build it into a real **password manager** (encrypted vault, master password, search).
 
 ## Conclusion
-In this project, we learned how to create a Random Password Generator using Python's built-in modules. We explored the `random` module for generating random selections and the `string` module for accessing different character sets. This project demonstrates essential security programming concepts and provides a practical tool for everyday use. The simplicity of the implementation makes it an excellent starting point for more advanced security-related projects. To find more projects like this, you can visit Python Central Hub.
+You generated random passwords, then learned why "random" is the wrong word — and rebuilt the generator with `secrets`. You measured entropy, guaranteed variety, copied to the clipboard, and have a roadmap to a real password manager. Security is full of these small, mostly-invisible choices. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/randompasswordgenerator.py). Find more security-focused projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/rockpaperscissors.mdx b/src/content/docs/projects/Beginners/rockpaperscissors.mdx
index d95e157d..826cce3f 100644
--- a/src/content/docs/projects/Beginners/rockpaperscissors.mdx
+++ b/src/content/docs/projects/Beginners/rockpaperscissors.mdx
@@ -1,6 +1,6 @@
 ---
 title: Rock Paper Scissors Game
-description: This is a simple rock paper scissors game made using python. This is a beginner level project. You can find the code for this project on my GitHub. In this project, we will use the random module to generate random numbers and then we will use if-else statements to check the user input and computer generated number and then we will decide the winner.
+description: Build a Rock Paper Scissors game in Python against the computer. Learn random choice, dictionary-driven rules, score tracking, AI strategies, and how to grow a 20-line script into a polished game.
 sidebar: 
     order: 6
 hero:
@@ -13,30 +13,51 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Rock, Paper, Scissors is a hand game played between two people. The game is played by two people using their hands. The players count to three in unison and simultaneously "throw" one of three hand signals that correspond to rock, paper or scissors. The winner is determined by the hand signals thrown by the players. The rules of the game are:
-- Rock wins against scissors.
-- Scissors win against paper.
-- Paper wins against rock.
-- If both players throw the same hand signal, there is no winner and the game is played again.
+Rock Paper Scissors is one of the oldest decision games still in play — and one of the best for teaching beginners how to model rules in code. In this project you will build a command-line version of the game where you play against the computer. Along the way you will learn how to pick a random item from a list, validate user input, model game rules cleanly (avoiding huge `if`/`elif` chains), and grow the program with score keeping, replay, and even a basic AI opponent.
 
-We are going to make a simple rock paper scissors game using python. This is a beginner level project. You can find the code for this project on my GitHub. In this project, we will use the random module to generate random numbers and then we will use if-else statements to check the user input and computer generated number and then we will decide the winner. You are against the computer in this game. The computer will randomly choose between rock, paper and scissors. You will be asked to choose between rock, paper and scissors. The computer will then check your choice against its choice and decide the winner. The game will continue until you decide to quit.
+You will leave this tutorial comfortable with:
+- `random.choice()` for picking from a list.
+- Loops with input validation.
+- Dictionary-driven rules instead of chained conditionals.
+- Counting wins / losses / ties across rounds.
+- The Markov-chain trick that lets an AI start beating humans.
+
+## The Rules
+- **Rock** crushes **Scissors**.
+- **Scissors** cut **Paper**.
+- **Paper** covers **Rock**.
+- Same choice → tie.
+
+That is the entire game. The challenge is encoding those rules so the program is readable and easy to extend (Rock-Paper-Scissors-Lizard-Spock anyone?).
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
+- Python 3.6 or above.
+- A text editor or IDE (VS Code recommended).
+- Comfort running a `.py` file from the terminal.
+- Familiarity with `if`/`elif`/`else` and `input()`.
+
+## Concepts You Will Use
+
+| Concept | Purpose |
+|---|---|
+| **`random.choice(list)`** | Pick a random element from a sequence. |
+| **`.upper()` / `.lower()`** | Normalize user input so case does not matter. |
+| **`while True` + `break`** | Replay loop until the user quits. |
+| **Dictionary lookups** | Replace long `if`/`elif` chains with a clean data structure. |
+| **F-strings** | Format output cleanly. |
 
 ## Getting Started
-#### Create a Project
-1. Create a new folder and name it `rockpaperscissorsgame`.
-2. Open the folder in your code editor.
-3. Create a new file and name it `rockpaperscissors.py`.
-4. Copy the code given at the beginning of this article and paste it in the `rockpaperscissors.py` file.
-
-## Write the Code
-1. Copy and paste the following code in the `rockpaperscissors.py` file.
+
+### Create the project
+1. Make a folder named `rockpaperscissors-game`.
+2. Inside it, create `rockpaperscissors.py`.
+3. Open the folder in your editor.
+
+### Write the code
 <FileCode file="projects/beginners/rockpaperscissors.py" lang="python" title="Rock Paper Scissors" />
-2. Save the File.
-3. Open the terminal and navigate to the `rockpaperscissorsgame` folder.
+
+Save the file, open a terminal in the folder, run:
+
 ```cmd title="command" showLineNumbers{1} {1}
 C:\Users\username\PythonCentralHub\projects\beginners\rockpaperscissorsgame> python rockpaperscissors.py
 Choose Rock, Paper or Scissors: Rock
@@ -44,88 +65,188 @@ Computer chose SCISSORS. You win!
 Do you want to play again? (y/n): y
 Choose Rock, Paper or Scissors: paper
 Computer chose PAPER. It's a tie!
-Do you want to play again? (y/n): y
-Choose Rock, Paper or Scissors: scissors
-Computer chose SCISSORS. It's a tie!
 Do you want to play again? (y/n): n
 Thanks for playing!
 ```
-4. You can see that the game is working as expected. You can play the game as many times as you want. You can also quit the game whenever you want.
 
-## Explanation
-1. We first import the `random` module. We will use this module to generate random numbers.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
+## Step-by-Step Explanation
+
+### 1. Import randomness
+```python title="rockpaperscissors.py"
 import random
 ```
+`random.choice([...])` picks one item from a list uniformly at random.
 
-2. We create a list of options. The computer will randomly choose from this list.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
+### 2. Build the option list
+```python title="rockpaperscissors.py"
 options = ["ROCK", "PAPER", "SCISSORS"]
 ```
+Capitalize all entries up front. Then normalize the user's input to uppercase too — comparisons become trivial.
 
-3. We create a function to play the game. This function will be called whenever we want to play the game.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
-def play():
-```
-
-4. We get the user's choice. We use the `input()` function to get the user's choice. We convert the user's choice to uppercase using the `upper()` function. We store the user's choice in the `user_choice` variable.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
+### 3. Read the player's choice
+```python title="rockpaperscissors.py"
 user_choice = input("Choose Rock, Paper or Scissors: ").upper()
+while user_choice not in options:
+    user_choice = input("Invalid input. Choose Rock, Paper or Scissors: ").upper()
 ```
+The `while` loop is a **validation loop**. It refuses to move on until the user types something valid. No `try/except` needed because we are only checking membership in a list.
 
-5. We get the computer's choice. We use the `random.choice()` function to get the computer's choice. We pass the `options` list as an argument to the `random.choice()` function. We store the computer's choice in the `computer_choice` variable.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
+### 4. Computer picks a choice
+```python title="rockpaperscissors.py"
 computer_choice = random.choice(options)
 ```
 
-6. We check if the user's choice is valid. We use the `while` loop to check if the user's choice is valid. We check if the user's choice is in the `options` list. If the user's choice is not in the `options` list, we ask the user to enter a valid choice. We convert the user's choice to uppercase using the `upper()` function. We store the user's choice in the `user_choice` variable.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
-while user_choice not in options:
-    user_choice = input("Invalid input. Choose Rock, Paper or Scissors: ").upper()
-```
-
-7. We check the user's choice against the computer's choice. We use the `if-elif-else` statements to check the user's choice against the computer's choice. We convert the user's choice to uppercase using the `upper()` function. We convert the computer's choice to uppercase using the `upper()` function. If the user's choice is equal to the computer's choice, we print that it's a tie. If the user's choice is rock and the computer's choice is scissors, we print that the user wins. If the user's choice is paper and the computer's choice is rock, we print that the user wins. If the user's choice is scissors and the computer's choice is paper, we print that the user wins. If the user's choice is not equal to the computer's choice, we print that the user loses.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1-20}
-if user_choice.upper() == computer_choice.upper():
+### 5. Decide the winner
+```python title="rockpaperscissors.py"
+if user_choice == computer_choice:
     print(f"Computer chose {computer_choice}. It's a tie!")
-elif user_choice.upper() == "ROCK" and computer_choice.upper() == "SCISSORS":
-    print(f"Computer chose {computer_choice}. You win!")
-elif user_choice.upper() == "PAPER" and computer_choice.upper() == "ROCK":
-    print(f"Computer chose {computer_choice}. You win!")
-elif user_choice.upper() == "SCISSORS" and computer_choice.upper() == "PAPER":
+elif (user_choice == "ROCK" and computer_choice == "SCISSORS") \
+  or (user_choice == "PAPER" and computer_choice == "ROCK") \
+  or (user_choice == "SCISSORS" and computer_choice == "PAPER"):
     print(f"Computer chose {computer_choice}. You win!")
 else:
     print(f"Computer chose {computer_choice}. You lose!")
 ```
+That `elif` is doing a lot. The next section shows a cleaner way.
 
-8. We play the game. We use the `while` loop to play the game. We call the `play()` function to play the game. We ask the user if they want to play again. If the user enters `y`, we play the game again. If the user enters `n`, we break out of the `while` loop.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1-8}
+### 6. Replay loop
+```python title="rockpaperscissors.py"
 while True:
     play()
-    play_again = input("Do you want to play again? (y/n): ")
-    if play_again.lower() != "y":
+    if input("Do you want to play again? (y/n): ").lower() != "y":
+        print("Thanks for playing!")
         break
 ```
 
-9. We print a message to thank the user for playing the game.
-```python title="rockpaperscissors.py" showLineNumbers{1} {1}
-print("Thanks for playing!")
+## Cleaner Rules with a Dictionary
+
+A growing `elif` chain is a smell. Replace it with a dictionary that maps each choice to "what it beats":
+
+```python title="cleaner_rules.py"
+BEATS = {
+    "ROCK":     "SCISSORS",
+    "SCISSORS": "PAPER",
+    "PAPER":    "ROCK",
+}
+
+def winner(user, computer):
+    if user == computer:
+        return "tie"
+    return "user" if BEATS[user] == computer else "computer"
+```
+Reading top to bottom: *"Rock beats Scissors. Scissors beat Paper. Paper beats Rock."* Adding a new option later (e.g., Lizard, Spock) means **one** more line per option, not a combinatorial explosion of `elif`s.
+
+### Bonus: Rock-Paper-Scissors-Lizard-Spock
+```python title="rpsls.py"
+BEATS = {
+    "ROCK":     ["SCISSORS", "LIZARD"],
+    "PAPER":    ["ROCK", "SPOCK"],
+    "SCISSORS": ["PAPER", "LIZARD"],
+    "LIZARD":   ["PAPER", "SPOCK"],
+    "SPOCK":    ["SCISSORS", "ROCK"],
+}
+
+def winner(user, computer):
+    if user == computer:
+        return "tie"
+    return "user" if computer in BEATS[user] else "computer"
 ```
+Five-option variant from *The Big Bang Theory*. Same code shape, more fun.
+
+## Add Score Tracking
+
+```python title="score.py"
+score = {"user": 0, "computer": 0, "tie": 0}
+
+def play_round():
+    # … existing logic …
+    result = winner(user_choice, computer_choice)
+    score[result] += 1
+    print(f"Score — You: {score['user']}  Computer: {score['computer']}  Ties: {score['tie']}")
+```
+
+After each round you see the running totals. When the user quits, print a final summary.
+
+## A Smarter Computer
+
+Random play means the computer wins 33 % of the time. Humans have patterns. A simple **Markov-chain AI** tracks what the player typed last round and bets on the same again:
+
+```python title="ai.py"
+COUNTER = {"ROCK": "PAPER", "PAPER": "SCISSORS", "SCISSORS": "ROCK"}
+last_user_move = None
+
+def ai_pick():
+    global last_user_move
+    if last_user_move is None:
+        return random.choice(options)
+    return COUNTER[last_user_move]    # counter the player's previous move
+
+# after the round:
+last_user_move = user_choice
+```
+Naive but surprisingly effective — most beginners *do* repeat their previous move. For a real upgrade, track the **transition matrix** (what move follows what) and predict accordingly.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| User typing `rock` is rejected | Forgot `.upper()` | Normalize both sides to one case |
+| Always loses to Scissors | Typo in the rules table | Compare against a single dictionary |
+| Loop never exits | Wrong indentation of `break` | Make sure `break` is inside the `if` |
+| Score persists between runs but should reset | Globals are reused on replay | Reset score inside the replay loop |
+
+## Variations to Try
+
+### 1. Best of N rounds
+First to 3 wins takes the match:
+```python title="bo3.py"
+while score["user"] < 3 and score["computer"] < 3:
+    play_round()
+print("You won the match!" if score["user"] == 3 else "Computer wins the match.")
+```
+
+### 2. Two human players
+Ask each player privately for their move (clear the terminal between turns).
+
+### 3. Animated countdown
+Use `time.sleep` and `print("...", end="\r")` to print *"Rock... Paper... Scissors!"*.
+
+### 4. GUI version
+Tkinter with three big buttons. The label shows the result.
+
+### 5. Network play
+Build a simple Flask backend (see [Basic Web Server](./basicwebserver)) so two players in different places submit moves and the server decides the winner.
+
+### 6. Hand-gesture version
+Use OpenCV to detect the user's hand pose with a webcam. See [Gesture Recognition System](../Advance/gesture_recognition_system) for the techniques.
+
+### 7. Statistics dashboard
+After 100 rounds, plot the user's move distribution. Are you secretly a "rock-loving" player?
+
+## Real-World Applications
+- Tutorial for finite-state game logic.
+- Demonstrations of probability and game-theory mixed strategies.
+- Onboarding example for new game programmers.
+- A great first project for teaching simple AI / pattern detection.
+
+## Best Practices Demonstrated
+- **Normalize input early** so all comparisons assume one form.
+- **Encode rules as data** (a dictionary) instead of code (a chain of `if`s).
+- **Separate the round from the match** — `play_round()` and `play_match()` should be different functions.
+- **Track state explicitly** — score in a dictionary, not three scattered variables.
+
+## Educational Value
+This project teaches:
+- **Game loops** — round, match, replay.
+- **Data-driven rules** — the heart of every config-driven system.
+- **Input validation** — the `while not valid` pattern.
+- **Random vs. deterministic AI** — a fast intro to game-playing agents.
 
 ## Next Steps
-Congratulations on completing this project. You can now move on to the next project where we will make a simple calculator using python. You can find the code for this project on my GitHub. If you like this article, please share it with your friends and colleagues. If you have any questions or suggestions, please let me know in the comments below.
-
-There are some suggestions: 
-- Add a score counter to keep track of the score.
-- Add a timer to limit the time for each round.
-- Add a GUI to make the game more interactive.
-- Add more options to make the game more interesting.
-- Add a database to store the scores.
-- Add a leaderboard to display the top scores.
-- Add a multiplayer mode to play with friends.
-- Add a chat feature to chat with friends while playing the game.
-- Add a voice assistant to make the game more interactive.
-- Add a virtual assistant to play the game with you.
+- Add **score-based difficulty**: after 5 losses, the AI eases off.
+- Implement **tournament mode** with brackets.
+- Wrap state in a `Game` class to learn OOP. See the [Hangman](./hangman) project for a similar refactor.
+- Build a **web version** that two players in different browsers can join.
 
 ## Conclusion
-In this article, we learned how to make a simple rock paper scissors game using python. This is a beginner level project. You can find the code for this project on my GitHub. In this project, we used the random module to generate random numbers and then we used if-else statements to check the user input and computer generated number and then we decided the winner. You can create more projects using python. You can find more projects on Python Central Hub. If you have any questions or suggestions, please let me know in the comments below.
\ No newline at end of file
+You wrote a complete game, refactored its rules into a clean data structure, added score keeping, and even gave the computer a tiny brain. The same patterns — validation loops, dictionary-driven rules, score state — turn up in every game and many non-game projects. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/rockpaperscissors.py). Find more beginner projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/rssfeedreader.mdx b/src/content/docs/projects/Beginners/rssfeedreader.mdx
index 2abc1515..0808f0ca 100644
--- a/src/content/docs/projects/Beginners/rssfeedreader.mdx
+++ b/src/content/docs/projects/Beginners/rssfeedreader.mdx
@@ -1,6 +1,6 @@
 ---
 title: RSS Feed Reader
-description: Create an RSS feed reader that parses and displays news feeds with automatic browser opening
+description: Build a Python RSS reader that fetches, parses, and displays articles from any RSS or Atom feed. Learn the feedparser library, working with structured XML data, and how to extend a console reader into a full-featured news aggregator.
 sidebar:
   order: 51
 hero:
@@ -14,104 +14,258 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build a functional RSS feed reader that fetches content from RSS feeds, parses the data, and displays article information including titles, summaries, publication dates, and authors. The application can automatically open articles in a web browser for detailed reading.
+RSS (Really Simple Syndication) is the oldest still-working standard for publishing a list of articles in a machine-readable format. Most blogs, news sites, podcast hosts, and YouTube channels expose an RSS or Atom feed. In this project you will build a Python program that fetches a feed, parses it, and displays each article's title, summary, publication date, author, and tags — then optionally opens any article in your default browser.
 
-## Prerequisites
+This project teaches:
+- How HTTP and feed formats fit together.
+- How to use the `feedparser` library to handle the messy real-world variations of RSS and Atom.
+- How to extract structured data and present it nicely.
+- How to extend a simple reader into a personalized news aggregator.
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of HTTP requests and web data
-- Familiarity with XML/RSS feed structures
-- Understanding of web scraping concepts
+## What Is RSS?
 
-## Getting Started
+An RSS feed is a single XML document served from a URL. It contains:
+- **Feed-level metadata** — title, description, link to the website, last-updated date.
+- **A list of entries** — each one with its own title, link, summary or content, published date, author, and categories (tags).
+
+When you "subscribe to" a feed, your reader app fetches that URL on a schedule and shows you new entries. There is no signup, no algorithm, no tracking — just a URL.
+
+Feeds typically live at URLs like:
+- `https://news.ycombinator.com/rss`
+- `https://www.reddit.com/r/Python/.rss`
+- `https://feeds.bbci.co.uk/news/rss.xml`
+- `https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID`
+
+## Prerequisites
+
+- Python 3.6 or above.
+- A text editor or IDE.
+- An internet connection.
+- Comfort installing packages with `pip`.
 
-### Create a new project
-1. Create a new project folder and name it `rssFeedReader`.
-2. Create a new file and name it `rssfeedreader.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `rssfeedreader.py` file.
+## Install Dependencies
 
-### Install required dependencies
-1. Install feedparser library:
-```bash
+```bash title="install"
 pip install feedparser
 ```
 
+`feedparser` is the standard Python library for reading both RSS and Atom (a slightly different, newer format). It hides the differences between formats so you only deal with a uniform structure.
+
+## Getting Started
+
+### Create the project
+1. Create a folder named `rss-feed-reader`.
+2. Inside it, create `rssfeedreader.py`.
+3. Open the folder in your editor.
+
 ### Write the code
-1. Add the following code to your `rssfeedreader.py` file.
 <FileCode file="projects/beginners/rssfeedreader.py" lang="python" title="RSS Feed Reader" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\rssFeedReader> python rssfeedreader.py
+
+### Run it
+```bash title="run"
+python rssfeedreader.py
+```
+Sample output:
+```
 Feed Title: Python - Reddit
 Article 1: How to build a web scraper with Python
-Summary: Learn the basics of web scraping...
+Summary: Learn the basics of web scraping using BeautifulSoup...
 Published: Mon, 01 Sep 2025 10:30:00 GMT
 Author: pythondev123
 Tags: programming, python, web-scraping
-[Article opens in browser]
 ```
-   ```bash
-   pip install feedparser
-   ```
 
+## Step-by-Step Explanation
+
+### 1. Import what you need
+```python title="rssfeedreader.py"
+import feedparser
+import webbrowser
 ```
+- `feedparser` does all the HTTP + XML work.
+- `webbrowser` opens URLs in the user's default browser with one call.
 
-## Explanation
+### 2. Fetch and parse the feed
+```python title="rssfeedreader.py"
+url = "https://www.reddit.com/r/Python/.rss"
+feed = feedparser.parse(url)
+```
+A single call. Under the hood `feedparser`:
+1. Sends an HTTP `GET` to the URL.
+2. Reads the response body.
+3. Parses it as XML.
+4. Normalizes the differences between RSS 1.0, RSS 2.0, and Atom into a common object structure.
 
-1. The `import feedparser` statement imports the feedparser library for RSS/Atom feed parsing.
-2. The `import webbrowser` statement imports the webbrowser module for opening URLs.
-3. The `url = 'https://www.reddit.com/r/Python/.rss'` sets the RSS feed URL to parse.
-4. The `feed = feedparser.parse(url)` fetches and parses the RSS feed data.
-5. The `feed['feed']['title']` extracts the main feed title information.
-6. The `for entry in feed['entries']:` loop iterates through all articles in the feed.
-7. The `entry['title']` displays individual article titles.
-8. The `entry['summary']` shows article summaries and descriptions.
-9. The `entry['published']` displays publication dates and timestamps.
-10. The `entry['author']` shows article author information.
-11. The `webbrowser.open(entry['link'])` opens articles in the default browser.
-12. The `entry['tags']` displays article categories and tags.
+The result is an object that *looks like* a dictionary. You can also access values with dot notation: `feed.feed.title`.
 
-## Next Steps
+### 3. Read feed-level metadata
+```python title="rssfeedreader.py"
+print("Feed Title:", feed["feed"]["title"])
+print("Feed Link:", feed["feed"]["link"])
+print("Feed Description:", feed["feed"].get("description", "—"))
+```
+Note `feed["feed"]` — yes, the feed object has a `feed` key for the *feed-level* fields, separate from the list of entries. It is a quirk of `feedparser`'s API.
 
-Congratulations! You have successfully created an RSS Feed Reader in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add GUI interface with Tkinter for better user experience
-- Implement feed subscription management
-- Create article bookmarking and saving features
-- Add search and filtering capabilities
-- Implement offline reading with article caching
-- Create notification system for new articles
-- Add multiple feed sources support
-- Implement article sorting by date or popularity
-- Create custom feed categories and organization
+Using `.get(key, default)` avoids `KeyError` when a feed omits an optional field.
 
-## Conclusion
+### 4. Loop through entries
+```python title="rssfeedreader.py"
+for i, entry in enumerate(feed.entries, start=1):
+    print(f"\nArticle {i}: {entry.title}")
+    print(f"Summary: {entry.get('summary', '')}")
+    print(f"Published: {entry.get('published', 'unknown')}")
+    print(f"Author: {entry.get('author', 'unknown')}")
+    tags = [t.term for t in entry.get('tags', [])]
+    if tags:
+        print(f"Tags: {', '.join(tags)}")
+```
+- `enumerate(..., start=1)` gives you both the index (starting at 1) and the entry.
+- Each entry has at least `title` and `link`. Everything else is optional and varies by source.
+- Tags arrive as a list of objects; `t.term` is the actual tag string.
+
+### 5. Open articles in the browser
+```python title="rssfeedreader.py"
+choice = input("\nEnter article number to open (or press Enter to skip): ")
+if choice.strip().isdigit():
+    n = int(choice) - 1
+    if 0 <= n < len(feed.entries):
+        webbrowser.open(feed.entries[n].link)
+```
+`webbrowser.open(url)` launches your default browser pointed at that URL. Cross-platform with no setup.
 
-In this project, you learned how to create an RSS Feed Reader in Python using the feedparser library. You also learned about web data parsing, XML processing, and browser integration. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/rssfeedreader.py)
-- Add multiple feed aggregation and comparison
-- Include article rating and favorites system
+## Cleaning Up HTML in Summaries
+
+Many feeds put HTML in the summary field — paragraphs, links, embedded images. To show plain text, strip the tags:
+
+```python title="strip_html.py"
+import re
+
+def strip_html(text):
+    return re.sub(r"<[^>]+>", "", text or "").strip()
+
+print(strip_html(entry.summary))
+```
+
+For higher-quality output, use **BeautifulSoup**:
+```python title="bs4_clean.py"
+from bs4 import BeautifulSoup
+text = BeautifulSoup(entry.summary, "html.parser").get_text()
+```
 
-### Learning Extensions
-- Study RSS/Atom feed specifications and standards
-- Explore web scraping for non-RSS content sources
-- Learn about content aggregation algorithms
-- Practice with database integration for article storage
-- Understand feed validation and error handling
-- Explore real-time feed monitoring techniques
+## Handling Network Errors
+
+`feedparser` does not raise on bad URLs; it sets a status. Always check it:
+
+```python title="check_status.py"
+feed = feedparser.parse(url)
+if feed.bozo:                           # bozo flag = something went wrong
+    print(f"Warning: feed may be malformed — {feed.bozo_exception}")
+if not feed.entries:
+    print("No entries found.")
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `KeyError: 'author'` | Feed omits an optional field | Use `entry.get('author', 'unknown')` |
+| `UnicodeEncodeError` printing entries | Terminal cannot render some characters | Set `PYTHONIOENCODING=utf-8` or pipe to a file |
+| Empty `feed.entries` | URL is HTML, not a feed; or site blocks the user agent | Pass a custom `User-Agent` via `feedparser.parse(url, request_headers={...})` |
+| `webbrowser.open` does nothing | Running in a headless environment | Print the URL instead |
+
+## Variations to Try
+
+### 1. Read multiple feeds
+```python title="multi_feed.py"
+FEEDS = [
+    "https://news.ycombinator.com/rss",
+    "https://www.reddit.com/r/Python/.rss",
+    "https://feeds.bbci.co.uk/news/technology/rss.xml",
+]
+for url in FEEDS:
+    feed = feedparser.parse(url)
+    print(f"\n=== {feed.feed.title} ===")
+    for entry in feed.entries[:5]:
+        print(f"  • {entry.title}")
+```
+
+### 2. Sort entries by date
+Use the parsed `published_parsed` field, which is a Python `struct_time`:
+```python title="sort.py"
+import time
+entries = sorted(feed.entries,
+                 key=lambda e: e.get("published_parsed", time.gmtime(0)),
+                 reverse=True)
+```
+
+### 3. Save articles offline
+Write each entry's text content to a file for offline reading:
+```python title="offline.py"
+from pathlib import Path, PurePath
+safe = "".join(c for c in entry.title if c.isalnum() or c == " ")[:80]
+Path(f"articles/{safe}.txt").write_text(entry.summary, encoding="utf-8")
+```
+
+### 4. Show only new articles (since last run)
+Store the timestamp of the last fetch in a file. Filter entries newer than that:
+```python title="incremental.py"
+last_run = float(Path("last_run.txt").read_text() or 0)
+new_entries = [e for e in feed.entries
+               if time.mktime(e.published_parsed) > last_run]
+Path("last_run.txt").write_text(str(time.time()))
+```
+
+### 5. Send a daily email digest
+Combine `feedparser` with `smtplib` (Python's email module) to mail yourself the new entries each morning.
+
+### 6. Build a GUI reader
+Wrap the loop in a Tkinter app with a feed list on the left and articles on the right. See [Simple Blog System](./simple-blog-system) for the layout pattern.
+
+### 7. Convert to OPML
+OPML is the standard format readers use to import/export feed subscriptions. Generate one from your list of URLs.
+
+### 8. Search across feeds
+After fetching, store all entries in a list and let the user filter by keyword:
+```python title="search.py"
+keyword = input("Search: ").lower()
+matches = [e for e in all_entries if keyword in e.title.lower()]
+```
+
+## Best Practices
+
+- **Cache responses.** Hitting the same feed every few seconds is rude. Honor the feed's `etag` and `modified` headers and pass them on subsequent requests so the server can answer with `304 Not Modified`.
+  ```python title="cache.py"
+  feed = feedparser.parse(url, etag=last_etag, modified=last_modified)
+  ```
+- **Set a polite User-Agent** identifying your app and a contact URL.
+- **Limit display length.** Truncate long summaries to keep the terminal readable.
+- **Validate input.** When letting the user open entry N, check N is in range.
+
+## Real-World Applications
+
+- Personal news aggregators (think Feedly, NetNewsWire).
+- Podcast catchers — podcasts publish RSS feeds with `<enclosure>` tags pointing to MP3s.
+- Monitoring tools — turn build-failure feeds, CVE feeds, or pricing feeds into alerts.
+- Content backups — archive a blog by downloading every entry.
+- Cross-posting pipelines — read from one platform's feed, post to another.
 
 ## Educational Value
 
 This project teaches:
-- **Web Data Parsing**: Working with RSS/XML feeds and structured web data
-- **HTTP Requests**: Understanding how to fetch content from web APIs
-- **Data Extraction**: Processing and organizing information from external sources
-- **Browser Integration**: Connecting Python applications with web browsers
-- **Feed Standards**: Learning RSS and Atom feed formats and specifications
-- **Content Aggregation**: Building systems that collect and organize information
-- **Real-Time Data**: Working with live, updating content sources
-- **User Experience**: Creating applications that bridge data and user interaction
-
-Perfect for understanding web data processing, content aggregation, and building practical tools for information consumption.
+- **Working with web data** — HTTP requests are hidden but real.
+- **Structured data extraction** — feeds, JSON APIs, scraped pages all share the same patterns.
+- **Defensive coding** — `entry.get(key, default)` is the difference between robust and brittle.
+- **Module ecosystem** — when to reach for a library (`feedparser`) instead of parsing XML by hand.
+- **User experience** — even a CLI tool benefits from clean formatting and gentle error messages.
+
+## Next Steps
+
+- Build a **subscription manager** that stores feed URLs in a JSON file and lets the user add/remove them.
+- Add a **search index** with `sqlite3` so you can grep entries across hundreds of feeds.
+- Turn it into a **web service** with Flask (see [Basic Web Server](./basicwebserver)) that shows your feeds on a web page.
+- Bridge feeds to **Discord or Slack** with their webhook APIs.
+- Plug into a **TTS engine** (`pyttsx3`) for an audio news briefing.
+
+## Conclusion
+
+A few dozen lines of Python plus `feedparser` is enough to replicate the core of a commercial RSS reader. You learned to fetch a feed, walk its entries, handle missing fields gracefully, and open articles in the browser. The same patterns will serve you anywhere you consume structured data from the web. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/rssfeedreader.py). Explore more projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/simple-blog-system.mdx b/src/content/docs/projects/Beginners/simple-blog-system.mdx
index 8834f717..836a7c9b 100644
--- a/src/content/docs/projects/Beginners/simple-blog-system.mdx
+++ b/src/content/docs/projects/Beginners/simple-blog-system.mdx
@@ -1,6 +1,6 @@
 ---
 title: Simple Blog System
-description: A comprehensive command-line blog management system with post creation, editing, tagging, and export features built with Python
+description: Build a CLI blog manager in Python with posts, tags, search, draft/publish workflow, JSON persistence, and a path to Markdown, SQLite, and a Flask web frontend.
 sidebar:
   order: 47
 hero:
@@ -13,273 +13,301 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A blog system in fewer than 300 lines of Python exercises every fundamental of a real content app: data modeling, persistence, CRUD, search, tags, draft vs. published workflow, statistics, and export. In this tutorial you build a CLI blog manager that stores posts in JSON, supports tags and search, tracks publication status, and exports to plain text or Markdown. Then we discuss the natural growth path: SQLite, Markdown rendering, a Flask web UI, and finally a published static-site generator.
 
-A comprehensive command-line blog management system that allows users to create, edit, manage, and export blog posts with advanced features like tagging, search, and statistics. This project demonstrates content management, data persistence, and search functionality.
+You will learn:
+- Designing a data class for a domain object (`BlogPost`).
+- Persisting a list of objects to JSON safely.
+- Implementing search, tag filtering, and statistics.
+- Building a non-trivial menu-driven CLI without spaghetti.
+- The path from CLI → web app → static site.
 
-## 🎯 Project Overview
+## Prerequisites
+- Python 3.6 or above (3.7+ recommended for `dataclasses`).
+- A text editor or IDE.
+- Comfort with classes, lists, and dictionaries.
+- Familiarity with the [Personal Diary](./personaldiary) project — same JSON + class pattern.
 
-This project creates a complete blog management system with:
-- Post creation and editing capabilities
-- Tag management system
-- Search and filtering functionality
-- Publishing workflow (draft/published states)
-- Statistics and analytics
-- Export functionality
-- Persistent data storage using JSON
+## Getting Started
 
-## ✨ Features
+### Create the project
+1. Create folder `simple-blog`.
+2. Inside, create `simpleblogsystem.py`.
 
-### Post Management
-- **Create Posts**: Write new blog posts with title, content, and author
-- **Edit Posts**: Update existing post content and metadata
-- **Delete Posts**: Remove posts with confirmation
-- **Publishing Workflow**: Draft and publish post states
+### Write the code
+<FileCode file="projects/beginners/simpleblogsystem.py" lang="python" title="Simple Blog System" />
 
-### Organization & Search
-- **Tag System**: Add and remove tags for better organization
-- **Search Posts**: Search by title, content, or author
-- **Filter by Author**: View posts from specific authors
-- **Filter by Tags**: Find posts with specific tags
+### Run it
+```bash title="run"
+python simpleblogsystem.py
+```
 
-### Analytics & Export
-- **Statistics Dashboard**: View blog metrics and analytics
-- **Export Functionality**: Export posts to text files
-- **Most Common Tags**: Track popular tags
-- **Author Analytics**: Monitor author contributions
+```
+1. Create post
+2. List all
+3. Search
+4. View by ID
+5. Edit
+6. Delete
+7. Publish/unpublish
+8. Manage tags
+9. Statistics
+10. Export
+11. Quit
+> 1
+Title: First post
+Author: Madhur
+Content (end with empty line):
+> Hello world.
+>
+Created post 1700000000.
+```
 
-### Data Persistence
-- **JSON Storage**: Automatic saving and loading of blog data
-- **Backup Safety**: Error handling for data operations
-- **Unicode Support**: Handle international characters properly
+## Step-by-Step Explanation
 
-## 🛠️ Technical Implementation
+### 1. The `BlogPost` data class
+```python title="simpleblogsystem.py"
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from time import time as now_ts
 
-### Class Structure
-```python title="simpleblogsystem.py" showLineNumbers{1}
+@dataclass
 class BlogPost:
-    def __init__(self, title, content, author="Anonymous", post_id=None):
-        # Initialize post with metadata
-        # Generate unique ID and timestamps
-    
-    def to_dict(self):
-        # Convert post to dictionary for storage
-    
-    def add_tag(self, tag):
-        # Add tags with duplicate prevention
-    
+    title: str
+    content: str
+    author: str = "Anonymous"
+    id: str = field(default_factory=lambda: str(int(now_ts())))
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    updated_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    tags: list[str] = field(default_factory=list)
+    published: bool = False
+
+    def to_dict(self): return asdict(self)
+    @classmethod
+    def from_dict(cls, d): return cls(**d)
+
+    def add_tag(self, tag: str):
+        tag = tag.strip().lower()
+        if tag and tag not in self.tags:
+            self.tags.append(tag)
+            self.touch()
+
+    def remove_tag(self, tag: str):
+        if tag in self.tags:
+            self.tags.remove(tag)
+            self.touch()
+
+    def update(self, title=None, content=None):
+        if title is not None: self.title = title
+        if content is not None: self.content = content
+        self.touch()
+
     def publish(self):
-        # Change post status to published
-
-class SimpleBlogSystem:
-    def __init__(self, data_file="blog_data.json"):
-        # Initialize blog system with data persistence
-    
-    def create_post(self, title, content, author):
-        # Create and store new blog post
-    
-    def search_posts(self, query):
-        # Implement comprehensive search functionality
-```
+        self.published = True
+        self.touch()
 
-### Key Components
-
-#### Data Models
-- **BlogPost Class**: Represents individual blog posts with metadata
-- **Timestamp Tracking**: Creation and modification timestamps
-- **Unique IDs**: Automatic generation of post identifiers
-- **Status Management**: Draft and published states
-
-#### Storage System
-- **JSON Persistence**: Automatic saving and loading
-- **Error Handling**: Robust file operation error handling
-- **Encoding Support**: UTF-8 encoding for international content
-- **Data Integrity**: Validation and backup mechanisms
-
-#### Search & Filter
-- **Multi-field Search**: Search across title, content, and author
-- **Case-insensitive**: Flexible search matching
-- **Tag Filtering**: Find posts by specific tags
-- **Author Filtering**: View posts from specific authors
-
-## 🚀 How to Run
-
-1. **Install Python**: Ensure Python 3.6+ is installed
-2. **Run the Blog System**:
-   ```bash
-   python simpleblogsystem.py
-   ```
-
-3. **Using the System**:
-   - Follow the interactive menu prompts
-   - Create your first post
-   - Explore all features through the numbered menu
-
-## 💡 Usage Examples
-
-### Creating a New Post
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Create blog system instance
-blog = SimpleBlogSystem()
-
-# Create a new post
-post = blog.create_post(
-    title="My First Blog Post",
-    content="This is the content of my first post...",
-    author="John Doe"
-)
-
-# Add tags
-post.add_tag("python")
-post.add_tag("programming")
-
-# Publish the post
-post.publish()
+    def touch(self):
+        self.updated_at = datetime.now().isoformat()
 ```
-
-### Searching and Filtering
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Search posts by content
-results = blog.search_posts("python programming")
-
-# Get posts by specific author
-author_posts = blog.get_posts_by_author("John Doe")
-
-# Get posts with specific tag
-tagged_posts = blog.get_posts_by_tag("python")
-
-# Get only published posts
-published = blog.get_all_posts(published_only=True)
+`@dataclass` gives us a real constructor, repr, and equality without boilerplate. `field(default_factory=...)` defers default computation so each new post gets its own timestamp and ID.
+
+### 2. The `Blog` system class
+```python title="simpleblogsystem.py"
+import json
+from pathlib import Path
+
+class Blog:
+    def __init__(self, datafile="blog_data.json"):
+        self.datafile = Path(datafile)
+        self.posts: list[BlogPost] = []
+        self.load()
+
+    def load(self):
+        if self.datafile.exists() and self.datafile.stat().st_size > 0:
+            data = json.loads(self.datafile.read_text(encoding="utf-8"))
+            self.posts = [BlogPost.from_dict(d) for d in data]
+
+    def save(self):
+        self.datafile.write_text(
+            json.dumps([p.to_dict() for p in self.posts], indent=2),
+            encoding="utf-8")
+
+    def add(self, post: BlogPost):
+        self.posts.append(post); self.save()
+
+    def by_id(self, post_id: str):
+        return next((p for p in self.posts if p.id == post_id), None)
+
+    def delete(self, post_id: str) -> bool:
+        post = self.by_id(post_id)
+        if post:
+            self.posts.remove(post); self.save(); return True
+        return False
 ```
-
-### Statistics and Analytics
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Get comprehensive statistics
-stats = blog.get_post_statistics()
-print(f"Total posts: {stats['total_posts']}")
-print(f"Published: {stats['published_posts']}")
-print(f"Most common tags: {stats['most_common_tags']}")
+Three patterns to notice:
+- **Load on init**, save on every mutation — never lose data.
+- **`next((... for ... if ...), None)`** is the idiomatic way to find-or-None.
+- **Mutating methods always call `save()`** so the file matches memory.
+
+### 3. Search and filter
+```python title="simpleblogsystem.py"
+def search(self, query: str):
+    q = query.lower()
+    return [p for p in self.posts
+            if q in p.title.lower()
+            or q in p.content.lower()
+            or q in p.author.lower()]
+
+def by_author(self, author: str):
+    return [p for p in self.posts if p.author == author]
+
+def by_tag(self, tag: str):
+    return [p for p in self.posts if tag.lower() in p.tags]
+
+def published_only(self):
+    return [p for p in self.posts if p.published]
 ```
 
-## 🎨 Menu System
-
-### Main Menu Options
-1. **Create New Post** - Write and save a new blog post
-2. **View All Posts** - Display all posts (including drafts)
-3. **View Published Posts** - Show only published content
-4. **Search Posts** - Find posts by keywords
-5. **View Post by ID** - Display specific post
-6. **Edit Post** - Modify existing post content
-7. **Delete Post** - Remove posts with confirmation
-8. **Manage Tags** - Add or remove post tags
-9. **Publish/Unpublish** - Change post publication status
-10. **View Statistics** - Display blog analytics
-11. **Export Posts** - Save posts to external file
-
-### Interactive Features
-- **Multi-line Content**: Support for long-form content entry
-- **Confirmation Prompts**: Safety checks for destructive operations
-- **Input Validation**: Error handling for user input
-- **Status Indicators**: Clear feedback for all operations
-
-## 🔧 Advanced Features
-
-### Export System
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Export all published posts
-blog.export_posts("my_blog_export.txt", published_only=True)
-
-# Export all posts including drafts
-blog.export_posts("complete_backup.txt", published_only=False)
+### 4. Statistics
+```python title="simpleblogsystem.py"
+from collections import Counter
+
+def stats(self):
+    tag_counts = Counter(t for p in self.posts for t in p.tags)
+    return {
+        "total":        len(self.posts),
+        "published":    sum(1 for p in self.posts if p.published),
+        "drafts":       sum(1 for p in self.posts if not p.published),
+        "authors":      len({p.author for p in self.posts}),
+        "top_tags":     tag_counts.most_common(5),
+    }
 ```
 
-### Tag Management
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Add multiple tags
-post.add_tag("python")
-post.add_tag("tutorial")
-post.add_tag("beginner")
-
-# Remove tags
-post.remove_tag("beginner")
-
-# Get posts by tag
-python_posts = blog.get_posts_by_tag("python")
+### 5. Export to text or Markdown
+```python title="simpleblogsystem.py"
+def export(self, filename: str, published_only=True):
+    posts = self.published_only() if published_only else self.posts
+    lines = []
+    for p in posts:
+        lines.append(f"# {p.title}")
+        lines.append(f"_by {p.author} on {p.created_at[:10]}_")
+        if p.tags: lines.append("Tags: " + ", ".join(f"#{t}" for t in p.tags))
+        lines.append(""); lines.append(p.content); lines.append("\n---\n")
+    Path(filename).write_text("\n".join(lines), encoding="utf-8")
 ```
-
-### Content Updates
-```python title="simpleblogsystem.py" showLineNumbers{1}
-# Update post content
-post.update_content(
-    title="Updated Title",
-    content="New content here..."
-)
-
-# Automatic timestamp updating
-print(post.updated_at)  # Shows latest modification time
+The same output is readable as plain text *and* renders nicely on GitHub or any Markdown viewer.
+
+## Multi-line Content
+
+```python title="multiline.py"
+def read_multiline(prompt: str) -> str:
+    print(prompt + " (end with an empty line)")
+    lines = []
+    while True:
+        line = input("> ")
+        if line == "": break
+        lines.append(line)
+    return "\n".join(lines)
 ```
-
-## 📊 Data Structure
-
-### Post Format
-```json
-{
-  "id": "1693123456",
-  "title": "Sample Blog Post",
-  "content": "This is the post content...",
-  "author": "John Doe",
-  "created_at": "2024-01-01T12:00:00.000000",
-  "updated_at": "2024-01-01T12:00:00.000000",
-  "tags": ["python", "programming"],
-  "published": true
-}
+Used in the create-post and edit-post flows so users can write paragraphs.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `json.decoder.JSONDecodeError` on first run | Empty/missing file | Check `stat().st_size > 0` |
+| Duplicate IDs | Reused timestamp | Append a UUID or check uniqueness |
+| Loaded post has wrong field shape | Schema changed | Use `.get()` in `from_dict` or migrate explicitly |
+| Tags case-insensitive matching fails | Mixed case in store | Normalize on `add_tag` (`tag.lower()`) |
+| Lost edits | Forgot `save()` | Save at the end of every mutating method |
+| Slow with 10k posts | Linear scans | Migrate to SQLite with indexes |
+
+## Variations to Try
+
+### 1. Markdown rendering
+`pip install markdown` and convert post content to HTML when exporting:
+```python title="md.py"
+import markdown
+html = markdown.markdown(p.content)
 ```
 
-### Statistics Output
-```python title="simpleblogsystem.py" showLineNumbers{1}
-{
-  'total_posts': 10,
-  'published_posts': 8,
-  'draft_posts': 2,
-  'total_authors': 3,
-  'total_tags': 15,
-  'most_common_tags': [('python', 5), ('tutorial', 3)]
-}
+### 2. Slug-based URLs
+Generate a URL-safe slug from the title (e.g. `My First Post` → `my-first-post`):
+```python title="slug.py"
+import re
+def slugify(s): return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-")
 ```
 
-## 🛡️ Error Handling
+### 3. Static site export
+Iterate posts → render each to an HTML file via a template (Jinja2). The result is a deployable site. Hosts: GitHub Pages, Netlify, Cloudflare Pages — all free.
+
+### 4. RSS feed
+Generate `feed.xml` with the standard RSS 2.0 schema. See [RSS Feed Reader](./rssfeedreader) for the reader side.
 
-- **File Operations**: Graceful handling of file read/write errors
-- **JSON Parsing**: Recovery from corrupted data files
-- **User Input**: Validation and sanitization of all inputs
-- **ID Management**: Duplicate prevention and unique identification
+### 5. Web frontend with Flask
+See [Basic Web Server](./basicwebserver). Two routes: `GET /` for the index, `GET /post/<id>` for individual posts.
 
-## 📚 Learning Objectives
+### 6. Admin authentication
+Protect create/edit/delete with a password. `werkzeug.security.generate_password_hash` is the right tool.
 
-- **Object-Oriented Programming**: Class design and inheritance
-- **File I/O Operations**: JSON data persistence
-- **Data Structures**: Lists, dictionaries, and sets
-- **Error Handling**: Exception management and user feedback
-- **CLI Development**: Interactive command-line interfaces
+### 7. SQLite backend
+JSON works through ~thousands of posts. Past that, swap to SQLite with FTS5 for full-text search:
+```sql title="schema.sql"
+CREATE VIRTUAL TABLE posts USING fts5(title, content, author, tags);
+SELECT * FROM posts WHERE posts MATCH 'python';
+```
+
+### 8. Comments
+Sub-collection per post. Moderation queue, spam filter (`pip install python-akismet`).
+
+### 9. Image upload
+A simple upload endpoint (Flask `request.files`) that saves to `static/uploads/` and returns a Markdown image reference.
 
-## 🎯 Potential Enhancements
+### 10. Multi-author
+Author becomes its own entity with email and avatar. Add an `Author` dataclass and join on `author_id`.
 
-1. **Web Interface**: Add Flask web interface
-2. **Markdown Support**: Rich text formatting
-3. **User Authentication**: Multi-user blog system
-4. **Database Integration**: SQLite or PostgreSQL storage
-5. **RSS Feed**: Generate RSS feeds for published posts
-6. **Comment System**: Add reader comments functionality
-7. **Image Support**: Embed images in posts
-8. **Template System**: Customizable post templates
+### 11. Drafts and scheduling
+Add a `publish_at: datetime | None` field. Background job promotes posts when their time arrives.
 
-## 🏆 Project Completion
+### 12. Templates
+Pre-fill new posts from templates (`how-to-tutorial`, `code-review`, `book-notes`).
 
-This Simple Blog System demonstrates:
-- ✅ Complete CRUD (Create, Read, Update, Delete) operations
-- ✅ Data persistence and management
-- ✅ Advanced search and filtering
-- ✅ Interactive command-line interface
-- ✅ Comprehensive error handling
-- ✅ Professional code organization
+## Architecture Path
 
-Perfect for beginners learning data management and intermediate developers exploring content management systems!
+```
+CLI (JSON)            ← you are here
+   ↓
+CLI (SQLite)
+   ↓
+Flask web (SQLite)
+   ↓
+Flask + JWT auth + API
+   ↓
+Static generator (Hugo / Astro-style) ← optional fork
+```
+Take one step at a time. Trying to jump from a JSON CLI to a multi-tenant Markdown CMS in one go is the usual cause of abandoned blog projects.
+
+## Real-World Applications
+- **Personal knowledge base** — Zettelkasten / digital garden.
+- **Internal wiki** for a team — keep notes versioned, search them.
+- **CMS prototypes** before committing to WordPress/Ghost.
+- **Documentation backends** for small products.
+- **Project journals** — track decisions and rationale per project.
+
+## Educational Value
+- **Domain modeling** — what fields belong on `BlogPost`?
+- **Persistence patterns** — JSON ↔ class via `to_dict` / `from_dict`.
+- **CRUD UX** — confirmations, validation, friendly errors.
+- **Search and filter** — list comprehensions as a query language.
+- **Statistics with `Counter`** — the small standard-library jewel.
+
+## Next Steps
+- Add **Markdown rendering** to the export.
+- Add **slug-based filenames** for static export.
+- Migrate to **SQLite** with FTS5 full-text search.
+- Wrap with **Flask** for a real blog at `localhost:5000`.
+- Add **RSS feed** generation and cross-link with [RSS Feed Reader](./rssfeedreader).
+- Pair with [Personal Diary](./personaldiary) — same architecture, different domain.
+
+## Conclusion
+You built a complete blog manager with CRUD, search, tags, statistics, and export — all backed by a single JSON file you can read in a text editor. Every CMS in the world reuses these primitives; the difference is scale, not concept. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/simpleblogsystem.py). Find more content-management projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/simplecalculator.mdx b/src/content/docs/projects/Beginners/simplecalculator.mdx
index 20cc89f8..be84cfec 100644
--- a/src/content/docs/projects/Beginners/simplecalculator.mdx
+++ b/src/content/docs/projects/Beginners/simplecalculator.mdx
@@ -1,6 +1,6 @@
 ---
 title: Simple Calculator
-description: Create a simple calculator in Python. This is a great project for beginners. You will learn how to use functions, return values, and if statements.
+description: Build a fully functional command-line calculator in Python. Learn functions, return values, conditionals, the math module, input validation, and how to grow a basic script into a robust user tool.
 sidebar: 
     order: 2
 hero:
@@ -14,25 +14,45 @@ import FileCode from '../../../../components/FileCode.astro'
 
 
 ## Abstract
-Creating a simple calculator is a great project for beginners. You will learn how to use functions, return values, and if statements. In this project, you will create a calculator that can add, subtract, multiply, and divide two numbers. You can also calculate the square root of a number and power of a number. This application is a command-line application. You can run this application in the terminal.
+A calculator is the perfect second project. It is small enough to finish in one sitting and large enough to teach you the four pillars of procedural Python: **functions**, **control flow**, **user input**, and **error handling**. In this tutorial you will build a command-line calculator that performs the four basic operations plus square root and exponentiation, runs in a loop until the user chooses to exit, and handles invalid input gracefully.
+
+By the end you will have practiced:
+- Defining and calling functions with parameters and return values.
+- Using the `math` module from Python's standard library.
+- Branching with `if`/`elif`/`else`.
+- Looping with `while True` plus `break`.
+- Converting strings from `input()` into numbers using `float()`.
+- Catching errors with `try`/`except`.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
+- Python 3.6 or above.
+- A text editor or IDE (VS Code recommended).
+- Familiarity with running a Python file from the terminal (see [Hello World](./helloworld)).
+
+## Concepts You Will Use
+
+| Concept | What it is |
+|---|---|
+| **Function** | A reusable named block of code. Defined with `def`. |
+| **Parameter** | A variable a function expects when called. |
+| **Return value** | The result a function hands back with `return`. |
+| **`math` module** | Standard-library module providing `sqrt`, `pow`, `pi`, `log`, etc. |
+| **Type conversion** | Turning a string like `"3.14"` into a float with `float()`. |
+| **Exception** | An error object Python raises when something goes wrong, such as dividing by zero. |
 
 ## Getting Started
-### Create a new project
-1. Create a new project folder and name it `simple-calculator`.
-2. Create a new file and name it `calculator.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Open the `calculator.py` file in your text editor or IDE.
+
+### Create the project
+1. Make a folder named `simple-calculator`.
+2. Inside it, create a file named `calculator.py`.
+3. Open the folder in your code editor.
 
 ### Write the code
-1. Add following code to the `calculator.py` file.
+Paste the following into `calculator.py`:
 <FileCode file="projects/beginners/calculator.py" lang="python" title="Simple Calculator" />
-2. Save the file.
-3. Open the terminal and navigate to the project folder.
-4. Run the following command to run the application.
+
+Save the file. Open the terminal, `cd` to the folder, and run:
+
 ```cmd title="command" showLineNumbers{1}
 C:\Users\username\Documents\simple-calculator> python calculator.py
 Select Operation.
@@ -53,31 +73,173 @@ Are you sure you want to exit? (Y/N): Y
 Exiting...
 ```
 
-## Explanation
-In this application, we create some functions to perform the mathematical operations. We use the `math` module to calculate the square root and power of a number. 
+## Step-by-Step Explanation
+
+### 1. Import the math module
+```python title="calculator.py"
+import math
+```
+The `math` module gives you mathematical helpers you would otherwise have to write yourself. We use `math.sqrt(x)` for square roots and `math.pow(x, y)` for exponentiation. (Python also has the `**` operator for powers, but using `math.pow` keeps the code consistent and explicit.)
+
+### 2. Define one function per operation
+```python title="calculator.py"
+def add(x, y):
+    return x + y
+
+def subtract(x, y):
+    return x - y
+
+def multiply(x, y):
+    return x * y
+
+def divide(x, y):
+    return x / y
+```
+Each function takes two numbers, performs one operation, and returns the result. This is **separation of concerns** — every piece does exactly one thing. It is easier to test, easier to read, and easier to extend.
+
+### 3. The main loop
+```python title="calculator.py"
+while True:
+    print("Select Operation.")
+    print("1. Addition")
+    # …
+    choice = input("Enter Choice (1/2/3/4/5/6/E/R): ")
+```
+`while True` keeps the menu visible until the user explicitly exits. Without the loop, the program would run once and quit — frustrating for anyone doing several calculations in a row.
 
-We use the `while` loop to run the application until the user exits the application. We use the `if` statement to check the user input and perform the operation accordingly. We use the `input()` function to get the user input. We use the `float()` function to convert the user input to a floating-point number. We use the `print()` function to print the output to the terminal. We use the `break` statement to exit the `while` loop. We use the `upper()` function to convert the user input to uppercase. We use the `elif` statement to check multiple conditions. We use the `else` statement to execute the code if the `if` statement condition is `False`. We use the `return` statement to return the value from the function. We use the `def` keyword to define a function. We use the `import` keyword to import the `math` module. We use the `math.sqrt()` function to calculate the square root of a number. We use the `math.pow()` function to calculate the power of a number.
+### 4. Dispatching the choice
+```python title="calculator.py"
+if choice == "1":
+    num1 = float(input("Enter First Number: "))
+    num2 = float(input("Enter Second Number: "))
+    print(num1, "+", num2, "=", add(num1, num2))
+elif choice == "2":
+    # …
+```
+- `input()` always returns a string. `float()` converts it to a floating-point number so arithmetic works.
+- The chain of `if`/`elif`/`else` picks the right function based on the menu choice.
+- An `else` at the bottom handles unknown inputs.
 
-#### The Usage Guide
-- If you want to perform the addition operation, you can press the `1` key. 
-- If you want to perform the subtraction operation, you can press the `2` key.
-- If you want to perform the multiplication operation, you can press the `3` key.
-- If you want to perform the division operation, you can press the `4` key.
-- If you want to calculate the square root of a number, you can press the `5` key.
-- If you want to calculate the power of a number, you can press the `6` key.
-- If you want to exit the application, you can press the `E` or `e` key.
-- If you want to restart the application, you can press the `R` or `r` key.
+### 5. Exit confirmation
+```python title="calculator.py"
+elif choice.upper() == "E":
+    confirm = input("Are you sure you want to exit? (Y/N): ")
+    if confirm.upper() == "Y":
+        print("Exiting...")
+        break
+```
+Using `.upper()` makes the check case-insensitive — `e`, `E`, `y`, and `Y` all work.
+
+## Add Robustness: Error Handling
+
+The version above crashes if a user types `abc` when asked for a number. Add a `try`/`except` block to handle it:
+
+```python title="safer_input.py"
+def get_number(prompt):
+    while True:
+        try:
+            return float(input(prompt))
+        except ValueError:
+            print("Please enter a valid number.")
+```
+Replace each `float(input(...))` call with `get_number("...")`. Now a typo no longer crashes the program — it asks again.
+
+Likewise, division by zero should be friendly, not fatal:
+```python title="safe_divide.py"
+def divide(x, y):
+    if y == 0:
+        return "undefined (cannot divide by zero)"
+    return x / y
+```
+
+## Common Mistakes
+
+| Problem | What happened | Fix |
+|---|---|---|
+| `TypeError: can only concatenate str` | You tried `"=" + add(...)` instead of using `,` in `print` | Use commas in `print` or an f-string |
+| `ValueError: could not convert string to float` | User typed letters | Wrap `float(input(...))` in `try`/`except` |
+| Loop never exits | `break` is indented wrong, or condition is always false | Confirm `break` is inside the `if`, not after it |
+| Decimal results everywhere | Used `float` even for whole numbers | Display with `int(result)` when you know it is whole, or format with `f"{result:.2f}"` |
+
+## Variations to Try
+
+### 1. More operations
+```python title="more_ops.py"
+def modulo(x, y):     return x % y
+def floor_div(x, y):  return x // y
+def factorial(n):     return math.factorial(int(n))
+def log(x):           return math.log(x)
+```
+
+### 2. Refactor with a dispatch dictionary
+A growing `if`/`elif` chain becomes unwieldy. Replace it with a dictionary that maps choices to functions:
+
+```python title="dispatch.py"
+OPERATIONS = {
+    "1": ("Addition", add),
+    "2": ("Subtraction", subtract),
+    "3": ("Multiplication", multiply),
+    "4": ("Division", divide),
+}
+
+choice = input("Choice: ")
+if choice in OPERATIONS:
+    name, func = OPERATIONS[choice]
+    a, b = get_number("a: "), get_number("b: ")
+    print(f"{name}: {func(a, b)}")
+```
+Adding a new operation is now one line.
+
+### 3. Expression evaluator
+Instead of menu-driven input, parse a typed expression like `2 + 3 * 4`:
+```python title="expr.py"
+import ast, operator as op
+
+OPS = {ast.Add: op.add, ast.Sub: op.sub, ast.Mult: op.mul, ast.Div: op.truediv}
+
+def evaluate(node):
+    if isinstance(node, ast.Constant):
+        return node.value
+    if isinstance(node, ast.BinOp):
+        return OPS[type(node.op)](evaluate(node.left), evaluate(node.right))
+    raise ValueError("unsupported")
+
+tree = ast.parse("2 + 3 * 4", mode="eval")
+print(evaluate(tree.body))   # 14
+```
+This safely evaluates math expressions without using the dangerous built-in `eval()`.
+
+### 4. GUI calculator
+Use Tkinter to build buttons in a grid. See the [Calculator GUI](./calculatorgui) project on Python Central Hub for a full walkthrough.
+
+### 5. Calculation history
+Keep a list of past results and let the user reuse the previous answer with `ans`:
+```python title="history.py"
+history = []
+# after each successful calc:
+history.append(result)
+# allow input "ans" to mean history[-1]
+```
+
+## Best Practices Demonstrated
+- **One function, one job.** Each operation is its own function.
+- **Use the standard library.** `math` is already there — do not roll your own square root.
+- **Validate at the boundary.** Convert and check input the moment it enters the program.
+- **Handle errors close to where they happen.** Division by zero is a `divide()` problem, not a *whole program* problem.
+
+## Real-World Applications
+- Interactive shells for scientific work (think mini-REPL).
+- Form back-ends that compute totals from user input.
+- Bot commands (`!calc 2+2`) in Discord/Slack integrations.
+- Foundations for spreadsheet engines and expression evaluators.
 
 ## Next Steps
-You can add more mathematical operations to this application. You can add the following operations to this application.
-- Factorial
-- Logarithm
-- Trigonometric Functions
-- Exponential Functions
-- Hyperbolic Functions
-- Rounding Functions
-- Summation Functions
-- Product Functions
-- More Mathematical Functions
-
-Congratulations 🎉 you have successfully created a simple calculator in Python. You can find the complete source code of this project on [Github](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/calculator.py)
\ No newline at end of file
+Extend the calculator with any of these:
+- **Trigonometry**: `math.sin`, `math.cos`, `math.tan` (remember to convert degrees with `math.radians`).
+- **Memory keys**: `M+`, `M-`, `MR`, `MC` like a real desktop calculator.
+- **Calculation history file**: persist results to `history.txt` so they survive restarts.
+- **Unit conversion mode**: kilometers ↔ miles, kilograms ↔ pounds, etc.
+- **Graphing mode**: pair with `matplotlib` to plot a function the user types.
+
+## Conclusion
+A calculator looks simple, but it is one of the most honest beginner projects: every feature you add forces you to write better code. You used Python's built-in `math` module, separated each operation into its own function, looped a menu, and converted user input safely. Find more progressive beginner projects on Python Central Hub. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/calculator.py).
diff --git a/src/content/docs/projects/Beginners/simplereminderapp.mdx b/src/content/docs/projects/Beginners/simplereminderapp.mdx
index 2e2c2336..3cc6cb78 100644
--- a/src/content/docs/projects/Beginners/simplereminderapp.mdx
+++ b/src/content/docs/projects/Beginners/simplereminderapp.mdx
@@ -1,6 +1,6 @@
 ---
 title: Simple Reminder App
-description: A Python reminder application that sends desktop notifications after a specified time. Perfect for setting quick reminders and staying organized.
+description: Build a Python reminder tool with desktop notifications. Learn time delays, cross-platform alerts, scheduling, persistent multi-reminder support, and how to grow it into a tray-based assistant.
 sidebar: 
     order: 29
 hero:
@@ -13,162 +13,275 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Simple Reminder App is a practical Python application that helps users set reminders with desktop notifications. The app allows users to input a reminder message and specify when they want to be reminded (in minutes). After the specified time, the application displays a desktop notification with the reminder message. This project demonstrates working with time delays, desktop notifications, and user input handling. The app includes versions for both Windows (using plyer) and Mac (using pync).
+A reminder app is a tiny program with huge personal-productivity value: type a message and a delay, and the computer pings you when the time arrives. In this tutorial you will build the single-shot version with `plyer` for desktop notifications, then evolve it into a multi-reminder scheduler that survives restarts, supports absolute times (not just "in N minutes"), runs in the background, and works on Windows, macOS, and Linux.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- plyer module (for Windows)
-- pync module (for Mac)
+You will learn:
+- How `time.sleep` actually works (and when it is the wrong tool).
+- How **`plyer`** abstracts notification systems across operating systems.
+- The trade-offs of `time.sleep` vs. **scheduled-job** libraries.
+- How to persist reminders in JSON so they survive restarts.
+- How to background the process so a closed terminal does not kill your reminders.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download). You must have the required modules installed on your computer. Install the appropriate module based on your operating system:
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- Notifications enabled for Python on your OS.
 
-For Windows:
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\Your Name>pip install plyer
+## Install Dependencies
+```bash title="install"
+pip install plyer
 ```
 
-For Mac:
-```cmd title="command" showLineNumbers{1} {1}
-$ pip install pync
+For native macOS notifications with sound, install **`pync`** instead:
+```bash title="mac"
+pip install pync
 ```
 
 ## Getting Started
-#### Create a Project
-1. Create a folder named `simple-reminder-app`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `simplereminderapp.py`.
-4. Copy the given code and paste it in your `simplereminderapp.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `simplereminderapp.py` file.
+
+### Create the project
+1. Create folder `simple-reminder-app`.
+2. Inside, create `simplereminderapp.py`.
+
+### Write the code
 <FileCode file="projects/beginners/simplereminderapp.py" lang="python" title="Simple Reminder App" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `simple-reminder-app`.
-```cmd title="command" showLineNumbers{1} {1-20}
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\simple-reminder-app> python simplereminderapp.py
 Welcome to the Reminder App!
-This app will remind you about anything you want!
-Let's get started!
-What would you like to be reminded about?
-Enter your reminder: Call mom
-In how many minutes would you like to be reminded?
-Enter minutes: 2
+What would you like to be reminded about? Call mom
+In how many minutes? 2
 Reminder set!
-# ... wait for 2 minutes ...
-# Desktop notification appears: "Reminder: Call mom"
-Reminder: Call mom
+# … 2 minutes pass …
+# Desktop notification pops up: "Reminder: Call mom"
 Reminder Completed!
-Would you like to set another reminder?
-Enter yes or no: no
-Thank you for using the Reminder App!
+Would you like to set another reminder? (y/n) n
+Thanks!
 ```
 
-## Explanation
-1. Import the required modules.
-```python title="simplereminderapp.py" showLineNumbers{1} {1-4}
+## Step-by-Step Explanation
+
+### 1. Imports
+```python title="simplereminderapp.py"
 import time
-import datetime
 from plyer import notification
 ```
+- `time.sleep(seconds)` pauses execution.
+- `notification.notify(...)` pops a desktop alert.
 
-2. Create a utility function for printing with pauses.
-```python title="simplereminderapp.py" showLineNumbers{1} {1-4}
-def print_pause(message_to_print):
-    print(message_to_print)
-    time.sleep(2)
+### 2. The pacing helper
+```python title="simplereminderapp.py"
+def print_pause(message, seconds=1):
+    print(message)
+    time.sleep(seconds)
 ```
+Small pauses between prompts make the CLI feel less robotic.
 
-3. Create the main reminder function.
-```python title="simplereminderapp.py" showLineNumbers{1} {1-15}
+### 3. Collect the reminder
+```python title="simplereminderapp.py"
 def reminder():
-    print_pause("What would you like to be reminded about?")
-    reminder = input("Enter your reminder: ")
-    print_pause("In how many minutes would you like to be reminded?")
-    minutes = input("Enter minutes: ")
+    msg = input("What would you like to be reminded about? ")
+    while True:
+        raw = input("In how many minutes? ")
+        try:
+            minutes = float(raw)
+            if minutes <= 0:
+                raise ValueError("must be positive")
+            break
+        except ValueError:
+            print("Please enter a positive number.")
     print_pause("Reminder set!")
-    time.sleep(int(minutes) * 60)
-    notification.notify(
-        title = "Reminder",
-        message = reminder,
-        timeout = 10
-    )
-    print_pause("Reminder: " + reminder)
-    print_pause("Reminder Completed!")
-    play_again()
+    time.sleep(minutes * 60)
+    notification.notify(title="Reminder", message=msg, timeout=10)
 ```
+- The `while True` loop is the canonical **input validation** pattern.
+- `time.sleep(minutes * 60)` blocks until the time arrives. Simple, but the script is unresponsive while it sleeps — a single typo in the message is unfixable.
 
-4. Create a function to handle multiple reminders.
-```python title="simplereminderapp.py" showLineNumbers{1} {1-15}
+### 4. Replay
+```python title="simplereminderapp.py"
 def play_again():
-    print_pause("Would you like to set another reminder?")
     while True:
-        choice = input("Enter yes or no: ")
-        if choice == "yes":
-            print_pause("Great!")
-            reminder()
-            break
-        elif choice == "no":
-            print_pause("Thank you for using the Reminder App!")
-            break
-        else:
-            print_pause("Please enter yes or no: ")
+        ans = input("Set another reminder? (y/n) ").strip().lower()
+        if ans in ("y", "yes"):
+            return reminder()
+        if ans in ("n", "no"):
+            print("Thanks!")
+            return
+        print("Please answer y or n.")
 ```
 
-5. Create an introduction function and start the app.
-```python title="simplereminderapp.py" showLineNumbers{1} {1-8}
-def intro():
-    print_pause("Welcome to the Reminder App!")
-    print_pause("This app will remind you about anything you want!")
-    print_pause("Let's get started!")
-    reminder()
+## The `time.sleep` Problem
+
+The simple version blocks until the timer fires. While `sleep(120)` runs:
+- You cannot add a second reminder.
+- You cannot cancel it.
+- If the laptop sleeps, the timer pauses too — so a 30-minute reminder might fire 90 minutes late.
+
+For a single quick reminder, this is fine. For anything serious, use a scheduler.
 
-intro()
+## Multi-Reminder Version
+
+Use **threads** so each reminder runs independently:
+
+```python title="multi.py"
+import threading, time
+from plyer import notification
+
+def fire_later(message: str, seconds: float):
+    time.sleep(seconds)
+    notification.notify(title="Reminder", message=message, timeout=10)
+
+def add_reminder(message: str, minutes: float):
+    t = threading.Thread(target=fire_later, args=(message, minutes * 60), daemon=True)
+    t.start()
+    print(f"Scheduled '{message}' in {minutes} minutes.")
+
+while True:
+    cmd = input("> ").strip()
+    if cmd == "quit":
+        break
+    if cmd:
+        msg, mins = cmd.rsplit(" ", 1)
+        add_reminder(msg, float(mins))
 ```
+Now you can keep adding reminders while previous ones wait. `daemon=True` lets the program exit even if reminders are still pending.
+
+## Absolute-Time Reminders
+
+"At 14:30" is often more useful than "in 90 minutes":
+```python title="at_time.py"
+from datetime import datetime, timedelta
+def schedule_at(hhmm: str, message: str):
+    h, m = map(int, hhmm.split(":"))
+    now = datetime.now()
+    target = now.replace(hour=h, minute=m, second=0, microsecond=0)
+    if target <= now:
+        target += timedelta(days=1)
+    seconds = (target - now).total_seconds()
+    add_reminder(message, seconds / 60)
+```
+
+## Persistent Reminders
+
+The thread approach forgets everything on restart. Persist to JSON:
+```python title="persist.py"
+import json, pathlib, time
+STORE = pathlib.Path("reminders.json")
+
+def load():
+    return json.loads(STORE.read_text()) if STORE.exists() else []
+
+def save(reminders):
+    STORE.write_text(json.dumps(reminders))
+
+# at startup, re-schedule each not-yet-fired reminder:
+for r in load():
+    delay = r["due_ts"] - time.time()
+    if delay > 0:
+        add_reminder(r["message"], delay / 60)
+```
+Store entries as `{"message": "...", "due_ts": <unix_ts>}` so absolute time is preserved.
+
+## Cross-Platform Notifications
+
+| OS | What works | Note |
+|---|---|---|
+| Windows 10/11 | `plyer.notification` | Uses Windows Toast notifications. |
+| macOS | `pync` (with sound) | `plyer` works but no sound by default. |
+| Linux | `plyer` (uses `notify-send`) | Requires `notify-send` installed (`sudo apt install libnotify-bin`). |
+
+A graceful fallback to terminal output:
+```python title="fallback.py"
+try:
+    notification.notify(title="Reminder", message=msg, timeout=10)
+except Exception:
+    print(f"\a*** REMINDER: {msg} ***\a")    # \a rings the terminal bell
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Notification never appears | OS notifications muted, or Focus Assist on | Check OS notification settings |
+| `ModuleNotFoundError: plyer` | Not installed in the active interpreter | `pip install plyer` |
+| Timer way off after laptop wake | `time.sleep` pauses during sleep | Use `datetime` comparisons in a loop, or use `schedule` |
+| `ValueError: could not convert string to float` | User typed "five" | Validate input in a loop |
+| Process killed when terminal closes | Foreground script | Run with `nohup`, `pythonw.exe`, or as a service |
+
+## Variations to Try
+
+### 1. Recurring reminders
+```python title="recur.py"
+import schedule, time
+schedule.every().day.at("09:00").do(fire, "Take vitamins")
+while True:
+    schedule.run_pending(); time.sleep(30)
+```
+
+### 2. Snooze button
+On fire, show a notification with a 5-minute snooze option. `plyer` itself does not support actions; use `win10toast-click` (Windows) or `pync` (macOS).
+
+### 3. GUI with Tkinter
+A small window with a Message field, an Entry for minutes, and a "Schedule" button. See [Basic Music Player](./basicmusicplayer) for the GUI pattern.
+
+### 4. System-tray app
+Use `pystray` to put a tray icon with "Add reminder" and "Quit" menu entries — no console window needed.
+
+### 5. Voice reminder
+Use **`pyttsx3`** so the reminder is *spoken* aloud:
+```python title="speak.py"
+import pyttsx3
+engine = pyttsx3.init(); engine.say(msg); engine.runAndWait()
+```
+
+### 6. Cloud sync
+Save reminders to a Firebase/Firestore document so they sync across devices.
+
+### 7. Smart parsing
+`pip install dateparser` lets you type *"tomorrow at 9am"* or *"in 2 hours"*:
+```python title="natural.py"
+import dateparser
+target = dateparser.parse("tomorrow at 9am")
+```
+
+### 8. Telegram / Discord bot
+A bot that accepts `/remind 30 buy bread` from your phone and pings you back when due.
 
-## Platform Support
-This app includes support for both Windows and Mac:
+### 9. Calendar integration
+Pull events from Google Calendar via API; surface them as desktop reminders 5 minutes before each event.
 
-**Windows Version:** Uses the `plyer` library for cross-platform notifications.
+### 10. Pomodoro mode
+A "/pomodoro" command that fires "Time to break!" every 25 minutes and "Back to work!" every 5.
 
-**Mac Version:** Uses the `pync` library for native Mac notifications with sound support.
+## Running as a Background Service
 
-The code includes both implementations - simply uncomment the appropriate version for your operating system.
+So your laptop's terminal is not always open:
+- **Linux:** create a systemd user service that runs the script on boot.
+- **macOS:** add a `launchd` plist with `RunAtLoad`.
+- **Windows:** save as `.pyw` and add a shortcut to `shell:startup`, or use **NSSM** to register as a service.
 
-## Features
-- Set custom reminder messages
-- Specify reminder time in minutes
-- Desktop notifications with title and message
-- Option to set multiple reminders
-- Cross-platform support (Windows and Mac)
-- User-friendly command-line interface
-- Sound notifications (Mac version)
-- 10-second notification timeout
+## Real-World Applications
+- Medication / hydration reminders.
+- Meeting and standup pings.
+- Pomodoro timer for focused work.
+- Calendar-driven alerts beyond what your OS notification center handles.
+- "Brew tea in 4 minutes" — the original killer app.
 
-## How to Use
-1. Run the application
-2. Enter your reminder message when prompted
-3. Specify the number of minutes until the reminder
-4. Wait for the specified time
-5. Receive a desktop notification with your reminder
-6. Choose to set another reminder or exit
+## Educational Value
+- **Time handling** — `time.sleep`, `datetime`, scheduling libraries.
+- **Concurrency basics** — threads for parallel timers.
+- **Cross-platform UX** — when an API silently falls short on one OS.
+- **Persistence** — JSON-backed state so the app survives restarts.
+- **Operational thinking** — what does it mean to keep running after you close the terminal?
 
 ## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Implementing recurring reminders (daily, weekly)
-- Adding sound customization options
-- Creating a web-based version
-- Adding reminder categories and priorities
-- Implementing snooze functionality
-- Adding reminder history and logs
-- Creating mobile app integration
-
-## Troubleshooting
-- **Notifications not appearing:** Make sure notification permissions are enabled for Python on your system
-- **Module import errors:** Ensure you've installed the correct module for your operating system
-- **Sound not working:** Check system volume and notification settings
+- Implement **multi-reminder threads** above.
+- Add **absolute-time** parsing and **persistent storage**.
+- Wrap with a **Tkinter GUI** or a **system-tray icon**.
+- Use **`dateparser`** for natural-language times.
+- Connect to **Google Calendar** for event-driven reminders.
+- See [Basic Alarm Clock](./basicalarmclock) for the polling-loop variant.
 
 ## Conclusion
-In this project, we learned how to create a Simple Reminder App using Python. We explored working with time delays using the `time` module, desktop notifications using platform-specific libraries, and user input handling. This project demonstrates practical application development and cross-platform compatibility considerations. To find more projects like this, you can visit Python Central Hub.
+You built a real reminder tool, learned why `time.sleep` is not the right scheduler, and have a path to a polished tray app. Notification systems, schedulers, and tiny daemons underlie a lot of practical Python work. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/simplereminderapp.py). Explore more productivity projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/simplestopwatch.mdx b/src/content/docs/projects/Beginners/simplestopwatch.mdx
index c4bd526c..9efe2fa7 100644
--- a/src/content/docs/projects/Beginners/simplestopwatch.mdx
+++ b/src/content/docs/projects/Beginners/simplestopwatch.mdx
@@ -1,6 +1,6 @@
 ---
 title: Simple Stopwatch
-description: A Python GUI stopwatch application built with Tkinter that allows users to start, stop, and reset time counting with a clean digital display interface.
+description: Build a Tkinter stopwatch in Python. Learn the event loop, after() scheduling, why time.time() beats counter variables, lap times, HH:MM:SS formatting, keyboard shortcuts, and a CountdownTimer mode.
 sidebar: 
     order: 31
 hero:
@@ -13,255 +13,283 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Simple Stopwatch is a Python GUI application that provides basic stopwatch functionality using Tkinter. The application features a large digital display showing elapsed seconds, along with Start, Stop, and Reset buttons for time control. This project demonstrates GUI development, time handling, event-driven programming, and state management in Python. It's an excellent introduction to creating interactive desktop applications with real-time updates.
+A stopwatch is a deceptively small project — under 50 lines and you have a working app. Behind those lines sit two important Tkinter concepts: the **event loop** and **scheduled callbacks via `after`**. We will start with the naïve counter-variable version (which drifts), fix it with `time.time()` for true elapsed-time accuracy, then add HH:MM:SS formatting, lap times, keyboard shortcuts, persistence between sessions, and a countdown mode.
+
+You will leave understanding:
+- Why a recurring `after(1000, fn)` is not a real 1-second timer.
+- The right way to measure elapsed time (record a start timestamp; subtract from `time.time()`).
+- How to format seconds as `HH:MM:SS`.
+- The lap-time pattern.
+- How to bind keyboard shortcuts to Tkinter buttons.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- tkinter module (usually comes pre-installed)
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with Python; Linux: `sudo apt install python3-tk`).
+- Familiarity with the Tkinter event loop. [Basic Music Player](./basicmusicplayer) is a softer first GUI project.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+## Getting Started
 
-Note: This project uses only built-in Python modules, so no additional installations are required.
+### Create the project
+1. Create folder `simple-stopwatch`.
+2. Inside, create `simplestopwatch.py`.
 
-## Getting Started
-#### Create a Project
-1. Create a folder named `simple-stopwatch`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `simplestopwatch.py`.
-4. Copy the given code and paste it in your `simplestopwatch.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `simplestopwatch.py` file.
+### Write the code
 <FileCode file="projects/beginners/simplestopwatch.py" lang="python" title="Simple Stopwatch" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `simple-stopwatch`.
-```cmd title="command" showLineNumbers{1} {1-10}
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\simple-stopwatch> python simplestopwatch.py
-# A GUI window will open with:
-# - Large digital time display showing "0"
-# - Start button to begin counting
-# - Stop button to pause counting
-# - Reset button to return to zero
-# - Black background with white text for better visibility
+# Window with big "0", Start / Stop / Reset buttons
 ```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Code Breakdown
-1. **Import required modules.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-3}
-import time
-import datetime
+### 1. Imports and root window
+```python title="simplestopwatch.py"
 import tkinter as tk
-```
-
-2. **Set up the main window.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-6}
 root = tk.Tk()
 root.title("Simple Stopwatch")
-root.geometry("500x500")
-root.resizable(False, False)
+root.geometry("400x300")
 root.config(bg="black")
 ```
 
-3. **Define the start function.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-6}
-def start():
-    global running
-    running = True
-    global count
-    count = -1
-    counter()
+### 2. State and label
+```python title="simplestopwatch.py"
+running = False
+count = 0
+label = tk.Label(root, text="0", font=("Helvetica", 80), bg="black", fg="white")
+label.pack(pady=20)
 ```
 
-4. **Implement the counter mechanism.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-8}
-def counter():
-    global running
+### 3. The naïve counter loop
+```python title="simplestopwatch.py"
+def tick():
     global count
     if running:
         count += 1
-        time_label.config(text=str(count))
-        time_label.after(1000, counter)
-```
+        label.config(text=str(count))
+        label.after(1000, tick)        # schedule the next call
+
+def start():
+    global running
+    if not running:
+        running = True
+        tick()
 
-5. **Define stop and reset functions.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-8}
 def stop():
     global running
     running = False
-    
+
 def reset():
     global count
     count = 0
-    time_label.config(text=str(count))
+    label.config(text="0")
 ```
+`after(ms, fn)` tells Tkinter "call `fn` after `ms` milliseconds during the event loop." That is how you do "do something every second" without blocking the UI.
 
-6. **Create and place GUI widgets.**
-```python title="simplestopwatch.py" showLineNumbers{1} {1-10}
-time_label = tk.Label(root, text="0", font=("Helvetica", 80), bg="black", fg="white")
-start_button = tk.Button(root, text="Start", font=("Helvetica", 20), bg="black", fg="white", command=start)
-stop_button = tk.Button(root, text="Stop", font=("Helvetica", 20), bg="black", fg="white", command=stop)
-reset_button = tk.Button(root, text="Reset", font=("Helvetica", 20), bg="black", fg="white", command=reset)
-
-time_label.pack(pady=20)
-start_button.pack(pady=20)
-stop_button.pack(pady=20)
-reset_button.pack(pady=20)
-```
+### 4. Wire the buttons
+```python title="simplestopwatch.py"
+for txt, cmd in [("Start", start), ("Stop", stop), ("Reset", reset)]:
+    tk.Button(root, text=txt, font=("Helvetica", 18),
+              bg="black", fg="white", command=cmd).pack(pady=10)
 
-## Features
-- **Digital Display:** Large, easy-to-read time counter
-- **Start/Stop Functionality:** Control timing with button clicks
-- **Reset Capability:** Return counter to zero instantly
-- **Clean Interface:** Black background with white text for clarity
-- **Fixed Window Size:** Non-resizable window for consistent layout
-- **Real-time Updates:** Counter updates every second automatically
-- **State Management:** Proper handling of running/stopped states
-
-## How It Works
-
-### State Management
-The stopwatch uses global variables to manage its state:
-- **`running`:** Boolean flag indicating if the stopwatch is active
-- **`count`:** Integer storing the current elapsed seconds
-
-### Timer Mechanism
-The application uses Tkinter's `after()` method for timing:
-1. **Start:** Sets `running` to True and begins the counter
-2. **Counter:** Recursively calls itself every 1000ms (1 second)
-3. **Stop:** Sets `running` to False, breaking the recursive loop
-4. **Reset:** Sets count back to 0 and updates display
-
-### Event Flow
-```
-Start Button → running = True → counter() begins
-                ↓
-counter() → updates display → schedules next call (1 second)
-                ↓
-Stop Button → running = False → counter() stops recurring
-                ↓
-Reset Button → count = 0 → display updates to "0"
+root.mainloop()
 ```
 
-## GUI Components
+## The Drift Problem
 
-### Time Display
-- **Font:** Helvetica, size 80 for maximum readability
-- **Colors:** White text on black background
-- **Position:** Centered at the top with padding
+The naïve version is wrong. Two reasons:
 
-### Control Buttons
-- **Start Button:** Begins or resumes timing
-- **Stop Button:** Pauses timing (can be resumed)
-- **Reset Button:** Resets counter to zero
-- **Styling:** Consistent black/white theme
+1. **Tkinter's `after` is not a precise scheduler.** A second's worth of wall-clock might be 1.01s on a busy laptop. After a minute you have drifted by half a second.
+2. **`count` measures "ticks fired", not elapsed time.** If the UI is sluggish, ticks pile up — or skip.
 
-## Use Cases
-- **Exercise Timing:** Track workout durations
-- **Study Sessions:** Monitor focused work periods
-- **Cooking:** Time preparation and cooking processes
-- **Presentations:** Keep track of speaking time
-- **General Timing:** Any activity requiring time measurement
+Fix it by recording a **start timestamp** and computing elapsed time from `time.time()`:
 
-## Next Steps
-You can enhance this project by:
-- Adding millisecond precision for more accurate timing
-- Implementing lap time functionality
-- Adding sound alerts at specific intervals
-- Creating multiple simultaneous timers
-- Adding time formatting (MM:SS or HH:MM:SS)
-- Implementing countdown timer mode
-- Adding keyboard shortcuts for controls
-- Creating customizable themes and colors
-- Adding time logging and history features
-- Implementing export functionality for recorded times
-
-## Enhanced Version Ideas
-```python title="simplestopwatch.py" showLineNumbers{1}
-def enhanced_stopwatch():
-    # Features to add:
-    # - Lap time recording
-    # - Multiple time formats
-    # - Sound notifications
-    # - Customizable themes
-    # - Keyboard shortcuts
-    # - Time export functionality
-    pass
-
-def format_time(seconds):
-    # Convert seconds to HH:MM:SS format
-    hours = seconds // 3600
-    minutes = (seconds % 3600) // 60
-    secs = seconds % 60
-    return f"{hours:02d}:{minutes:02d}:{secs:02d}"
+```python title="fixed.py"
+import time
+start_time = 0.0
+elapsed_at_pause = 0.0
+running = False
+
+def tick():
+    if running:
+        elapsed = (time.time() - start_time) + elapsed_at_pause
+        label.config(text=format_time(elapsed))
+        label.after(50, tick)    # 50 ms = 20 fps; smooth display, irrelevant to accuracy
+
+def start():
+    global running, start_time
+    if not running:
+        running = True
+        start_time = time.time()
+        tick()
+
+def stop():
+    global running, elapsed_at_pause
+    if running:
+        elapsed_at_pause += time.time() - start_time
+        running = False
+
+def reset():
+    global running, elapsed_at_pause
+    running = False
+    elapsed_at_pause = 0
+    label.config(text="00:00.0")
 ```
+Now the displayed time is always accurate to within one frame, regardless of how laggy the UI is.
 
-## Advanced Features Ideas
+## Format Time as HH:MM:SS.t
+
+```python title="format.py"
+def format_time(seconds: float) -> str:
+    h, rem = divmod(int(seconds), 3600)
+    m, s = divmod(rem, 60)
+    tenths = int((seconds - int(seconds)) * 10)
+    return f"{h:02d}:{m:02d}:{s:02d}.{tenths}"
+```
+`divmod(a, b)` returns `(a // b, a % b)` in one call — the standard Python idiom for time-component math.
+
+## Lap Times
+
+A lap button records the current elapsed time without resetting:
+```python title="laps.py"
+laps: list[float] = []
+laps_list = tk.Listbox(root, height=8)
+laps_list.pack(fill="x", padx=20)
 
-### Lap Time Functionality
-```python title="simplestopwatch.py" showLineNumbers{1}
 def add_lap():
-    global count
-    lap_times.append(count)
-    update_lap_display()
+    if not running: return
+    elapsed = (time.time() - start_time) + elapsed_at_pause
+    laps.append(elapsed)
+    n = len(laps)
+    diff = elapsed - (laps[-2] if n > 1 else 0)
+    laps_list.insert("end", f"Lap {n}: {format_time(elapsed)}  (+{format_time(diff)})")
+
+tk.Button(root, text="Lap", command=add_lap).pack(pady=4)
+```
+Each entry shows both the total elapsed and the **split** from the previous lap.
+
+## Keyboard Shortcuts
 
-def show_lap_times():
-    # Display list of recorded lap times
-    pass
+Make Space toggle, R reset, L lap:
+```python title="keys.py"
+def toggle(_event=None):
+    stop() if running else start()
+
+root.bind("<space>", toggle)
+root.bind("<r>", lambda e: reset())
+root.bind("<l>", lambda e: add_lap())
 ```
 
-### Time Formatting
-```python title="simplestopwatch.py" showLineNumbers{1}
-def format_display(seconds):
-    if seconds < 60:
-        return f"{seconds}s"
-    elif seconds < 3600:
-        minutes = seconds // 60
-        secs = seconds % 60
-        return f"{minutes:02d}:{secs:02d}"
-    else:
-        hours = seconds // 3600
-        minutes = (seconds % 3600) // 60
-        secs = seconds % 60
-        return f"{hours:02d}:{minutes:02d}:{secs:02d}"
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Drift after 5 minutes | Counted ticks, not elapsed time | Use `time.time()` reference |
+| Multiple `tick()` chains spawn after rapid Start clicks | No guard on `start()` | `if not running:` before scheduling |
+| Window freezes on heavy work | Did blocking work in callback | Keep callbacks fast; use threads for blocking ops |
+| Reset while running leaves stale tick scheduled | Did not stop the chain | Set `running = False` before resetting |
+| Tenths jitter visibly | Refreshed every 1000 ms | Refresh every 50–100 ms; format with fractional seconds |
+| Numbers misaligned | Variable-width font | Use a monospace font (`Consolas`, `Courier`) |
+
+## Variations to Try
+
+### 1. Countdown timer
+```python title="countdown.py"
+duration = 5 * 60                 # 5 minutes
+def tick():
+    remaining = duration - ((time.time() - start_time) + elapsed_at_pause)
+    if remaining <= 0:
+        label.config(text="00:00.0")
+        notify("Time!")
+        return
+    label.config(text=format_time(remaining))
+    label.after(50, tick)
+```
+Combines neatly with [Basic Alarm Clock](./basicalarmclock).
+
+### 2. Pomodoro mode
+25 minutes of work, 5 minutes break, repeat. Toggle a `phase` state and chain timers.
+
+### 3. Save lap history
+JSON file with timestamp + laps list. Reload on next launch.
+
+### 4. CSV export
+"Export laps" button writes to `laps.csv`.
+
+### 5. Multiple stopwatches
+A `Tab` per stopwatch using `ttk.Notebook`. Each tab keeps its own state.
+
+### 6. Color states
+Green while running, red while stopped, blue at zero. Visual at a glance.
+
+### 7. Sound on lap / finish
+`winsound` on Windows, `playsound` cross-platform. See [Basic Music Player](./basicmusicplayer).
+
+### 8. Voice commands
+`pip install SpeechRecognition` — say "start", "stop", "lap", "reset".
+
+### 9. Race mode
+Two stopwatches in one window, each with its own start/stop button. Show who is ahead.
+
+### 10. Web stopwatch
+Flask plus a tiny page that updates with JS. The server keeps state per session.
+
+## Class-Based Refactor
+
+Globals are fine here, but if you build the multi-stopwatch variant you want state per instance:
+```python title="oop.py"
+class Stopwatch:
+    def __init__(self, parent):
+        self.running = False
+        self.elapsed = 0.0
+        self.start_time = 0.0
+        self.label = tk.Label(parent, text="00:00.0",
+                              font=("Consolas", 60), bg="black", fg="white")
+        self.label.pack()
+    def start(self):
+        if not self.running:
+            self.running = True
+            self.start_time = time.time()
+            self._tick()
+    def _tick(self):
+        if not self.running: return
+        now_elapsed = (time.time() - self.start_time) + self.elapsed
+        self.label.config(text=format_time(now_elapsed))
+        self.label.after(50, self._tick)
+    def stop(self):
+        if self.running:
+            self.elapsed += time.time() - self.start_time
+            self.running = False
+    def reset(self):
+        self.running = False
+        self.elapsed = 0
+        self.label.config(text="00:00.0")
 ```
 
-## Performance Considerations
-- **Memory Usage:** Minimal memory footprint with simple variables
-- **CPU Usage:** Low impact with 1-second intervals
-- **GUI Responsiveness:** Non-blocking timer implementation
-- **Accuracy:** Good for general timing (±1 second precision)
+## Real-World Applications
+- **Workout / interval training**.
+- **Cooking** — multi-timer for parallel dishes.
+- **Productivity** — Pomodoro and time-tracking.
+- **Sports** — race day timing.
+- **Lab experiments** — recording multiple event durations.
+- **Billing** — track time on tasks.
 
 ## Educational Value
-This project teaches:
-- **GUI Development:** Creating interactive desktop applications
-- **Event Handling:** Responding to button clicks and timer events
-- **State Management:** Managing application state with global variables
-- **Timer Programming:** Using `after()` for scheduled updates
-- **Layout Management:** Organizing GUI components with pack()
-
-## Common Improvements
-- **Precision:** Use `time.time()` for sub-second accuracy
-- **Visual Feedback:** Add color changes for different states
-- **User Experience:** Add confirmation dialogs for reset
-- **Accessibility:** Implement keyboard navigation
-- **Persistence:** Save timing sessions to files
+- **Tkinter event loop & `after`** — the cornerstone of any GUI animation.
+- **Time accuracy** — counters drift, timestamps do not.
+- **State management** — `running`, `start_time`, `elapsed_at_pause`.
+- **Formatting** — `divmod` is the right tool for time math.
+- **Keyboard bindings** — usability beyond mouse clicks.
 
-## Real-World Applications
-- **Sports Training:** Track exercise and rest intervals
-- **Productivity:** Implement Pomodoro technique timing
-- **Education:** Time quiz sessions and study periods
-- **Professional:** Track billable work hours
-- **Entertainment:** Game timing and challenges
-
-## Troubleshooting Tips
-- **Timer Not Starting:** Check if `running` variable is properly set
-- **Display Not Updating:** Ensure `after()` method is called correctly
-- **Button Responsiveness:** Verify command functions are properly defined
-- **Window Issues:** Check geometry and resizable settings
+## Next Steps
+- Rewrite using **`time.time()`** for accuracy.
+- Add **`HH:MM:SS.t`** display.
+- Add **lap times** with a Listbox.
+- Add **keyboard shortcuts**.
+- Refactor into a **`Stopwatch` class** and host two of them in one window.
+- Pair with [Basic Alarm Clock](./basicalarmclock) for a countdown / Pomodoro hybrid.
 
 ## Conclusion
-In this project, we learned how to create a Simple Stopwatch using Python's Tkinter library. We explored GUI development concepts including event handling, timer programming, and state management. This project demonstrates how to create responsive, real-time applications with clean user interfaces. The stopwatch serves as an excellent foundation for understanding time-based applications and can be extended with many additional features. To find more projects like this, you can visit Python Central Hub.
+You built a real desktop stopwatch, then fixed the most common time-tracking bug (drift from counting ticks). The same lesson — measure *moments*, not *steps* — applies to nearly every time-sensitive program you will ever write. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/simplestopwatch.py). More GUI projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/tempconv.mdx b/src/content/docs/projects/Beginners/tempconv.mdx
index 02c7e121..791fc57f 100644
--- a/src/content/docs/projects/Beginners/tempconv.mdx
+++ b/src/content/docs/projects/Beginners/tempconv.mdx
@@ -1,6 +1,6 @@
 ---
 title: Temperature Converter
-description: This program converts temperature from Fahrenheit to Celsius and vice versa. This program is written in Python. This is a command line program.
+description: Build a robust Celsius / Fahrenheit / Kelvin / Rankine converter in Python. Learn functions, conversion math, input validation, menu-driven UIs, and how to grow a single-formula script into a complete tool.
 sidebar: 
     order: 4
 hero:
@@ -13,29 +13,50 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-This program converts temperature from Fahrenheit to Celsius and vice versa. This program is written in Python. This is a command line program. This application work on the following formulae:
+Converting between temperature scales is one of the cleanest beginner projects: the math is simple, the use case is real, and there is plenty of room to grow the program. In this tutorial you will build a command-line temperature converter that handles Celsius and Fahrenheit at first, then extend it to Kelvin and Rankine, validate user input, and finish with a refactor that uses a dictionary-driven design — the same pattern professional codebases use to keep menus maintainable.
 
-#### `Celsius = (Fahrenheit - 32) * 5/9`
+By the end you will understand:
+- The four major temperature scales and how they relate.
+- Why `float` is preferred over `int` for measurements.
+- How to organize a script with small, single-purpose functions.
+- How to validate input so the program never crashes.
+- How a dispatch table replaces growing `if`/`elif` chains.
 
-#### `Fahrenheit = (Celsius * 9/5) + 32`
+## The Math
+
+| From → To | Formula |
+|---|---|
+| **Celsius → Fahrenheit** | `F = C × 9/5 + 32` |
+| **Fahrenheit → Celsius** | `C = (F − 32) × 5/9` |
+| **Celsius → Kelvin** | `K = C + 273.15` |
+| **Kelvin → Celsius** | `C = K − 273.15` |
+| **Fahrenheit → Kelvin** | `K = (F − 32) × 5/9 + 273.15` |
+| **Kelvin → Rankine** | `R = K × 9/5` |
+| **Rankine → Fahrenheit** | `F = R − 459.67` |
+
+**Reference points:**
+- Water freezes at 0 °C / 32 °F / 273.15 K.
+- Water boils at 100 °C / 212 °F / 373.15 K.
+- Absolute zero is 0 K / −273.15 °C / −459.67 °F / 0 °R.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
+- Python 3.6 or above.
+- A text editor or IDE (VS Code recommended).
+- Comfort running a Python file from the terminal (see [Hello World](./helloworld)).
+- Basic understanding of functions (see [Simple Calculator](./simplecalculator) if you need a refresher).
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `tempconverter`.
-2. Create a new file inside the `tempconverter` folder and name it `tempconverter.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `tempconverter.py` file.
+
+### Create the project
+1. Create a folder named `tempconverter`.
+2. Inside, create `tempconverter.py`.
+3. Open the folder in your code editor.
 
 ### Write the code
-1. Add the following code to the `tempconverter.py` file.
+Add this to `tempconverter.py`:
 <FileCode file="projects/beginners/tempconverter.py" lang="python" title="Temperature Converter" />
-2. Save the file.
-3. Open the terminal and navigate to the project folder.
-4. Run the following command to execute the program.
+
+Save the file, open a terminal, and run:
 ```cmd title="command" showLineNumbers{1}
 C:\Users\username\Documents\tempconverter> python tempconverter.py 
 Temperature Converter
@@ -43,59 +64,210 @@ Temperature Converter
 2. Fahrenheit to Celsius
 Enter your choice: 1
 Enter temperature in Celsius: 35
-Temperature in Fahrenheit:  95.0
+Temperature in Fahrenheit: 95.0
 ```
 
-## Explanation
-- The `celsius_to_fahrenheit()` function takes a temperature in Celsius as an argument and returns the temperature in Fahrenheit.
-- The `fahrenheit_to_celsius()` function takes a temperature in Fahrenheit as an argument and returns the temperature in Celsius.
-- The `main()` function displays a menu to the user and asks the user to enter a choice. If the user enters 1, the program asks the user to enter a temperature in Celsius and calls the `celsius_to_fahrenheit()` function to convert the temperature from Celsius to Fahrenheit. If the user enters 2, the program asks the user to enter a temperature in Fahrenheit and calls the `fahrenheit_to_celsius()` function to convert the temperature from Fahrenheit to Celsius. If the user enters any other number, the program displays an error message.
-- The `main()` function is called at the end of the program.
+## Step-by-Step Explanation
 
-## Usage
-1. Open the terminal and navigate to the project folder.
-2. Run the following command to execute the program.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\tempconverter> python tempconverter.py
-Temperature Converter
-1. Celsius to Fahrenheit
-2. Fahrenheit to Celsius
-Enter your choice: 1
-Enter temperature in Celsius: 35
-Temperature in Fahrenheit:  95.0
+### 1. Define each conversion as a function
+```python title="tempconverter.py"
+def celsius_to_fahrenheit(c):
+    return c * 9/5 + 32
+
+def fahrenheit_to_celsius(f):
+    return (f - 32) * 5/9
 ```
-In this example, the user enters 1 to convert temperature from Celsius to Fahrenheit. The user enters 35 as the temperature in Celsius. The program calls the `celsius_to_fahrenheit()` function to convert the temperature from Celsius to Fahrenheit and displays the result.
-3. You can also use the program to convert temperature from Fahrenheit to Celsius.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\tempconverter> python tempconverter.py
-Temperature Converter
-1. Celsius to Fahrenheit
-2. Fahrenheit to Celsius
-Enter your choice: 2
-Enter temperature in Fahrenheit: 95
-Temperature in Celsius:  35.0
+Each function does **one** thing. The body is the formula directly. Naming functions after what they do makes the program readable without comments.
+
+### 2. The `main()` menu
+```python title="tempconverter.py"
+def main():
+    print("Temperature Converter")
+    print("1. Celsius to Fahrenheit")
+    print("2. Fahrenheit to Celsius")
+    choice = input("Enter your choice: ")
+    if choice == "1":
+        c = float(input("Enter temperature in Celsius: "))
+        print("Temperature in Fahrenheit:", celsius_to_fahrenheit(c))
+    elif choice == "2":
+        f = float(input("Enter temperature in Fahrenheit: "))
+        print("Temperature in Celsius:", fahrenheit_to_celsius(f))
+    else:
+        print("Invalid choice.")
 ```
-In this example, the user enters 2 to convert temperature from Fahrenheit to Celsius. The user enters 95 as the temperature in Fahrenheit. The program calls the `fahrenheit_to_celsius()` function to convert the temperature from Fahrenheit to Celsius and displays the result.
-4. You can also run the program by double-clicking the `tempconverter.py` file.
+- `input()` always returns a string.
+- `float()` turns that string into a number with a decimal — important because temperatures are rarely whole numbers.
 
-## Next Steps
-Congratulations! You have successfully created a temperature converter program in Python. You can now use this program to convert temperature from Celsius to Fahrenheit and vice versa. 
-
-Here are some ideas to try:
-1. Modify the program to convert temperature from Kelvin to Celsius and vice versa.
-2. Modify the program to convert temperature from Kelvin to Fahrenheit and vice versa.
-3. Modify the program to convert temperature from Celsius to Kelvin and vice versa.
-4. Modify the program to convert temperature from Fahrenheit to Kelvin and vice versa.
-5. Modify the program to convert temperature from Kelvin to Rankine and vice versa.
-6. Modify the program to convert temperature from Rankine to Kelvin and vice versa.
-7. Modify the program to convert temperature from Celsius to Rankine and vice versa.
-8. Modify the program to convert temperature from Rankine to Celsius and vice versa.
-9. Modify the program to convert temperature from Fahrenheit to Rankine and vice versa.
-10. Modify the program to convert temperature from Rankine to Fahrenheit and vice versa.
+### 3. Run the program
+```python title="tempconverter.py"
+main()
+```
+Calling `main()` at the bottom of the file kicks the program off when you run `python tempconverter.py`.
 
-## Conclusion
-In this tutorial, you learned how to create a temperature converter program in Python. You also learned how to convert temperature from Celsius to Fahrenheit and vice versa. You can now use this program to convert temperature from Celsius to Fahrenheit and vice versa. 
+## Why `float`, Not `int`?
+Try replacing `float(...)` with `int(...)`:
+
+```python title="why_float.py"
+int(input("Enter Celsius: "))   # user enters 36.6 → ValueError
+```
 
-You also learned how to use programming to perform calculations. You can use this knowledge to create more programs that perform calculations.
+`int()` refuses fractional input. Real temperatures (body temperature 36.6 °C, room temperature 22.5 °C) are not whole numbers. `float()` accepts both `36` and `36.6`.
+
+## Robust Input
+
+The naive version crashes when the user types `"hot"` instead of a number. Add a helper:
+
+```python title="ask_number.py"
+def ask_number(prompt):
+    while True:
+        raw = input(prompt)
+        try:
+            return float(raw)
+        except ValueError:
+            print(f"'{raw}' is not a valid number. Try again.")
+```
+Use it everywhere you would have written `float(input(...))`:
+```python title="usage.py"
+c = ask_number("Enter temperature in Celsius: ")
+```
+
+You can also reject obvious physics nonsense — no temperature below absolute zero:
+```python title="phys_check.py"
+def celsius_to_kelvin(c):
+    if c < -273.15:
+        raise ValueError("Temperature below absolute zero is impossible.")
+    return c + 273.15
+```
 
-Keep learning and keep building awesome stuff. If you have any questions or feedback, please feel free to send me a message on [Website](https://ravikishan.me/contact). I would love to hear from you. Learn more about tutorial and projects on Python Central Hub.
\ No newline at end of file
+## Refactor: Dispatch Table
+
+When you support seven or eight conversions, a long `if`/`elif` chain becomes painful. Replace it with a dictionary that maps menu labels to conversion functions:
+
+```python title="dispatch.py"
+def c_to_f(c): return c * 9/5 + 32
+def f_to_c(f): return (f - 32) * 5/9
+def c_to_k(c): return c + 273.15
+def k_to_c(k): return k - 273.15
+def f_to_k(f): return c_to_k(f_to_c(f))
+def k_to_f(k): return c_to_f(k_to_c(k))
+
+CONVERSIONS = {
+    "1": ("Celsius → Fahrenheit",  c_to_f, "°C", "°F"),
+    "2": ("Fahrenheit → Celsius",  f_to_c, "°F", "°C"),
+    "3": ("Celsius → Kelvin",      c_to_k, "°C", "K"),
+    "4": ("Kelvin → Celsius",      k_to_c, "K",  "°C"),
+    "5": ("Fahrenheit → Kelvin",   f_to_k, "°F", "K"),
+    "6": ("Kelvin → Fahrenheit",   k_to_f, "K",  "°F"),
+}
+
+def main():
+    while True:
+        print("\nTemperature Converter")
+        for key, (label, _, _, _) in CONVERSIONS.items():
+            print(f"  {key}. {label}")
+        print("  Q. Quit")
+        choice = input("Choice: ").strip()
+        if choice.lower() == "q":
+            break
+        if choice not in CONVERSIONS:
+            print("Invalid choice.")
+            continue
+        label, func, in_unit, out_unit = CONVERSIONS[choice]
+        value = float(input(f"Enter temperature ({in_unit}): "))
+        print(f"{value} {in_unit} = {func(value):.2f} {out_unit}")
+
+main()
+```
+Notice how easy it is to add a new conversion — one entry in the dictionary, one helper function. No menu logic has to change.
+
+## Output Formatting
+
+`print(c_to_f(35))` prints `95.0`. For two decimal places:
+```python title="fmt.py"
+print(f"{c_to_f(35):.2f}")   # 95.00
+```
+The `:.2f` inside the f-string means "format as a float with two digits after the decimal point."
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `TypeError: unsupported operand type(s) for *: 'str' and 'float'` | Forgot to convert `input()` with `float()` | Wrap input in `float(input(...))` |
+| Wrong result like `0 + 32 = 32` for 0 °C → F (looks right but for 100 °C you get 132) | Used `c + 9/5 + 32` instead of `c * 9/5 + 32` | Watch operator precedence; parenthesize when unsure |
+| `ValueError: could not convert string to float: ''` | User pressed Enter without typing | Validate `raw` before converting |
+| Off-by-273 for Kelvin | Used 273 instead of 273.15 | Use the more accurate constant |
+
+## Variations to Try
+
+### 1. Convert multiple values at once
+Accept a comma-separated list:
+```python title="batch.py"
+raw = input("Celsius values, comma separated: ")
+for piece in raw.split(","):
+    c = float(piece.strip())
+    print(f"{c} °C = {c_to_f(c):.2f} °F")
+```
+
+### 2. CLI flags with argparse
+```python title="cli.py"
+import argparse
+parser = argparse.ArgumentParser()
+parser.add_argument("value", type=float)
+parser.add_argument("--from", dest="src", choices=["c","f","k"], required=True)
+parser.add_argument("--to",   dest="dst", choices=["c","f","k"], required=True)
+args = parser.parse_args()
+# dispatch by (args.src, args.dst)
+```
+Now `python tempconverter.py 100 --from c --to f` returns `212.0`.
+
+### 3. GUI version
+Use Tkinter:
+```python title="gui.py"
+import tkinter as tk
+root = tk.Tk()
+entry = tk.Entry(root); entry.pack()
+result = tk.Label(root); result.pack()
+def convert():
+    c = float(entry.get())
+    result.config(text=f"{c_to_f(c):.2f} °F")
+tk.Button(root, text="Convert", command=convert).pack()
+root.mainloop()
+```
+
+### 4. Weather-API integration
+Use `requests` to fetch the current temperature for a city from an API like OpenWeatherMap, then convert and display.
+
+### 5. Unit tests
+```python title="test_conv.py"
+import unittest
+class TestConv(unittest.TestCase):
+    def test_freezing(self):
+        self.assertEqual(c_to_f(0), 32)
+    def test_boiling(self):
+        self.assertEqual(c_to_f(100), 212)
+unittest.main()
+```
+Run with `python test_conv.py`.
+
+## Real-World Applications
+- Weather and forecasting tools.
+- Cooking apps that swap between °C and °F for international recipes.
+- Industrial monitoring dashboards that use Kelvin internally and display in °C.
+- Scientific instruments that report in Kelvin or Rankine.
+- Education — building physical intuition for the scales.
+
+## Best Practices Demonstrated
+- **Single-purpose functions** — each conversion has its own function with a clear name.
+- **Input validation at the boundary** — convert and verify once, trust the value everywhere else.
+- **Dispatch table over `if`/`elif` ladders** — easier to maintain.
+- **Format output explicitly** — `:.2f` produces predictable, readable numbers.
+
+## Next Steps
+- Add Rankine support so the converter handles all four standard scales.
+- Build a GUI with Tkinter for a nicer experience.
+- Add a "smart" mode that auto-detects the unit by suffix (`100C`, `212F`, `300K`).
+- Publish it as a PyPI package called `tempconv`.
+- Pair it with a weather API for live-temperature conversion of any city.
+
+## Conclusion
+Temperature conversion is the perfect playground for practicing functions, math operators, user input, validation, and code refactoring. You started with a 10-line script and finished with a dispatch-table design that scales cleanly. The same dictionary-of-functions pattern shows up in unit converters, command-line tools, and event handlers throughout real-world Python projects. The full source is on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/tempconverter.py). Find more beginner projects on Python Central Hub — and if you have questions, reach out at [ravikishan.me/contact](https://ravikishan.me/contact).
diff --git a/src/content/docs/projects/Beginners/textbasedadventuregame.mdx b/src/content/docs/projects/Beginners/textbasedadventuregame.mdx
index d87399b2..ed77c0c2 100644
--- a/src/content/docs/projects/Beginners/textbasedadventuregame.mdx
+++ b/src/content/docs/projects/Beginners/textbasedadventuregame.mdx
@@ -1,6 +1,6 @@
 ---
 title: Text-Based Adventure Game
-description: Create an interactive story-driven adventure game with choices, inventory system, and branching narratives
+description: Build a branching text adventure in Python with inventory, choices, multiple endings, and a save system. Learn state machines, narrative design, JSON-driven scenes, and how interactive fiction engines actually work.
 sidebar:
   order: 47
 hero:
@@ -14,38 +14,41 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build an engaging text-based adventure game featuring a fantasy story, player choices, inventory management, and multiple endings. This project demonstrates game logic, story branching, state management, and interactive narrative design using only text output and user input.
+Text adventures — *Colossal Cave Adventure*, *Zork*, *Hitchhiker's Guide* — were the first true interactive fiction. They are also one of the best teaching projects in programming because they force you to think about **state** (what the player has, where they are, what they have done) and **flow** (which scene leads to which, under which conditions). In this project you build a fantasy adventure with a cave, a house, a sword, a wicked fairy, multiple endings, and a replay system. Then we refactor it from hard-coded scenes into a JSON-driven engine — the same architecture commercial interactive fiction tools use.
 
-## Prerequisites
+You will learn:
+- How to organize a game as a **finite state machine** of scenes.
+- How to manage **inventory** as a list of strings.
+- How to validate player input cleanly with a `while not valid` loop.
+- How to add **save/load** so a player can resume later.
+- How to extract the story from the code into a data file you can edit without programming.
 
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of functions and control structures
-- Familiarity with lists and string manipulation
-- Understanding of game logic and state management
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with functions, conditionals, and lists.
+- (Bonus) Familiarity with dictionaries and JSON for the engine refactor.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `textBasedAdventureGame`.
-2. Create a new file and name it `textbasedadventuregame.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `textbasedadventuregame.py` file.
+### Create the project
+1. Create a folder named `text-adventure`.
+2. Inside it, create `textbasedadventuregame.py`.
 
 ### Write the code
-1. Add the following code to your `textbasedadventuregame.py` file.
-<FileCode file="projects/beginners/textbasedadventuregame.py" lang="python" title="Text-Based Adventure Game" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\textBasedAdventureGame> python textbasedadventuregame.py
+<FileCode file="projects/beginners/textbasedadventuregame.py" lang="python" title="Text-Based Adventure" />
+
+### Run it
+```bash title="run"
+python textbasedadventuregame.py
+```
+
+```
 You find yourself standing in front of a cave.
 In your hand you hold your trusty (but not very effective) dagger.
 
 Enter 1 to knock on the door of the house.
 Enter 2 to peer into the cave.
-Please enter 1 or 2.
 2
 
 You have found the magical Sword of Ogoroth!
@@ -54,158 +57,253 @@ You are victorious!
 Would you like to play again? (y/n)
 ```
 
-3. **Play the Game**
-   - Read the story text carefully
-   - Make choices by entering numbers (1 or 2)
-   ```
-
-## Explanation
-
-1. The `import time` statement imports the time module for adding pauses between story elements.
-2. The `def print_pause()` function adds dramatic delays to create better story pacing.
-3. The `def intro():` function sets up the initial game world and story context.
-4. The `items = []` list tracks the player's inventory throughout the game.
-5. The `def cave(items):` function handles the cave exploration and item discovery.
-6. The `def house(items):` function manages the house encounter and combat.
-7. The story branches based on whether the player has found the sword.
-8. The `valid_inputs` list ensures players can only enter valid choices.
-9. The `while True:` loops handle input validation and choice repetition.
-10. The `def play_again():` function allows players to restart the adventure.
-11. The game demonstrates consequence-based gameplay with different outcomes.
-12. Multiple endings depend on player preparation and choices made.
-
-## Next Steps
-
-Congratulations! You have successfully created a Text-Based Adventure Game in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add more locations and story branches
-- Implement character stats (health, strength, magic)
-- Create more complex inventory with multiple items
-- Add random events and encounters
-- Implement save/load game functionality
-- Create multiple characters to choose from
-- Add puzzle-solving elements
-- Implement dialogue trees with NPCs
-- Create a larger world map with navigation
-
-## Conclusion
-
-In this project, you learned how to create a Text-Based Adventure Game in Python. You also learned about story branching, state management, inventory systems, and creating interactive narratives. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/textbasedadventuregame.py)
+## Step-by-Step Explanation
 
+### 1. Slow-print for drama
+```python title="textbasedadventuregame.py"
+import time
 
-## Code Explanation
-
-### Story Pacing and Immersion
-```python title="textbasedadventuregame.py" showLineNumbers{1}
-def print_pause(message_to_print):
-    print(message_to_print)
-    time.sleep(2)
+def print_pause(message, seconds=2):
+    print(message)
+    time.sleep(seconds)
 ```
+Without delays, the game prints its entire story in milliseconds and loses all sense of pacing. A short sleep after each message lets the player actually read.
 
-Adds dramatic pauses between story elements to create better pacing and immersion in the narrative.
-
-### Game Introduction
-```python title="textbasedadventuregame.py" showLineNumbers{1}
+### 2. Intro scene
+```python title="textbasedadventuregame.py"
 def intro():
     print_pause("You find yourself standing in an open field, filled with grass and yellow wildflowers.")
     print_pause("Rumor has it that a wicked fairie is somewhere around here...")
     print_pause("In your hand you hold your trusty (but not very effective) dagger.")
 ```
+Plain-text scene-setting. The narrative *is* the gameplay in text adventures, so the writing matters.
 
-Sets up the game world, story context, and initial player state with atmospheric descriptions.
+### 3. Scene with a choice
+```python title="textbasedadventuregame.py"
+def field(items):
+    print_pause("Enter 1 to knock on the door of the house.")
+    print_pause("Enter 2 to peer into the cave.")
+    while True:
+        choice = input("(Please enter 1 or 2.) ").strip()
+        if choice == "1":
+            house(items)
+            break
+        elif choice == "2":
+            cave(items)
+            break
+```
+The `while True` + `if/elif/break` pattern is the canonical way to handle constrained input. Each branch transitions to a different scene function — that is your state machine.
 
-### Inventory System
-```python title="textbasedadventuregame.py" showLineNumbers{1}
+### 4. Inventory drives outcomes
+```python title="textbasedadventuregame.py"
 def cave(items):
     if "Sword of Ogoroth" in items:
         print_pause("You've been here before, and gotten all the good stuff.")
     else:
         print_pause("You have found the magical Sword of Ogoroth!")
         items.append("Sword of Ogoroth")
+    field(items)            # back to the field
 ```
+The `items` list is passed *through* every scene. Picking up an item is one `append` away. Branching on whether you have an item is one `in` check away.
 
-Implements item collection and inventory tracking that affects story outcomes and player capabilities.
+### 5. Combat that depends on preparation
+```python title="textbasedadventuregame.py"
+def house(items):
+    print_pause("You approach the door of the house.")
+    print_pause("From within you hear a sinister cackle. The wicked fairie is inside.")
+    print_pause("You must decide what to do.")
 
-### Branching Combat System
-```python title="textbasedadventuregame.py" showLineNumbers{1}
-if "Sword of Ogoroth" in items:
-    print_pause("The Sword of Ogoroth shines brightly in your hand...")
-    print_pause("You have rid the town of the wicked fairie. You are victorious!")
-else:
-    print_pause("Your dagger is no match for the wicked fairie.")
-    print_pause("You have been defeated!")
+    while True:
+        choice = input("(1) fight  (2) run\n> ")
+        if choice == "1":
+            if "Sword of Ogoroth" in items:
+                print_pause("The Sword of Ogoroth shines brightly in your hand...")
+                print_pause("You have defeated the fairie. Victory!")
+            else:
+                print_pause("Your dagger is no match for the fairie.")
+                print_pause("You have been defeated.")
+            play_again()
+            break
+        elif choice == "2":
+            print_pause("You run back to the field.")
+            field(items)
+            break
 ```
+The same scene has two endings — one rewarding preparation, one punishing recklessness.
+
+### 6. Replay loop
+```python title="textbasedadventuregame.py"
+def play_again():
+    while True:
+        ans = input("Play again? (y/n) ").strip().lower()
+        if ans == "y":
+            play_game()
+            break
+        if ans == "n":
+            print_pause("Thanks for playing!")
+            quit()
+```
+`quit()` terminates the program cleanly when the player is done.
+
+### 7. The top-level driver
+```python title="textbasedadventuregame.py"
+def play_game():
+    items = []
+    intro()
+    field(items)
+
+play_game()
+```
+A fresh `items = []` per game guarantees a clean slate.
+
+## The State Machine View
 
-Creates different story outcomes based on player preparation and choices, demonstrating consequence-based gameplay.
+Even this small game is a graph:
+
+```
+intro → field ──> cave ─→ field (with sword)
+                 ↓
+                 house ──> fight ─→ (win|lose)
+                       └─> run  ─→ field
+```
+
+Every scene is a node. Every choice is an edge. As you add scenes, draw the graph on paper — it stops you writing dead-ends or unreachable scenes.
+
+## Add Save / Load
+
+Players appreciate not losing progress.
+
+```python title="save.py"
+import json
+from pathlib import Path
+
+def save_game(items, location):
+    Path("save.json").write_text(json.dumps({"items": items, "location": location}))
+
+def load_game():
+    if not Path("save.json").exists():
+        return None
+    return json.loads(Path("save.json").read_text())
+```
+Each scene gets a name. The current scene name and the inventory are all that need persisting in a simple game.
+
+## Refactor: Data-Driven Engine
+
+Hard-coded scenes do not scale past 10 nodes. A real engine treats scenes as **data**:
+
+```python title="scenes.json"
+{
+  "field": {
+    "text": "You stand in an open field. A house sits to your left and a cave to your right.",
+    "choices": [
+      { "label": "Knock on the house door", "go": "house" },
+      { "label": "Peer into the cave",      "go": "cave"  }
+    ]
+  },
+  "cave": {
+    "text": "You find the magical Sword of Ogoroth!",
+    "give": "sword",
+    "choices": [{ "label": "Return to the field", "go": "field" }]
+  },
+  "house": {
+    "text": "A wicked fairy lives here.",
+    "choices": [
+      { "label": "Fight", "go": "victory", "require": "sword" },
+      { "label": "Fight", "go": "defeat",  "deny": "sword"    },
+      { "label": "Run",   "go": "field" }
+    ]
+  },
+  "victory": { "text": "You won!", "end": true },
+  "defeat":  { "text": "You lost.", "end": true }
+}
+```
+
+The engine becomes tiny:
+```python title="engine.py"
+import json
+data = json.load(open("scenes.json"))
+state = {"location": "field", "items": []}
 
-### Choice Validation and Loops
-```python title="textbasedadventuregame.py" showLineNumbers{1}
 while True:
-    choice = input("Would you like to (1) fight or (2) run away?")
-    if choice == "1":
-        # Handle fight choice
-        break
-    if choice == "2":
-        # Handle run choice
+    scene = data[state["location"]]
+    print(scene["text"])
+    if scene.get("give"):
+        state["items"].append(scene["give"])
+    if scene.get("end"):
         break
+    options = [c for c in scene["choices"]
+               if c.get("require", None) in (None, *state["items"])
+               and c.get("deny", "__none__") not in state["items"]]
+    for i, c in enumerate(options, 1):
+        print(f"  {i}. {c['label']}")
+    n = int(input("> ")) - 1
+    state["location"] = options[n]["go"]
 ```
+You now write stories in JSON. Game designers (or you, at 2 AM) can iterate on the narrative without touching Python.
 
-Ensures valid input from players and provides clear choice options with proper loop handling.
+## Common Mistakes
 
-### Replay System
-```python title="textbasedadventuregame.py" showLineNumbers{1}
-def play_again():
-    while True:
-        choice = input("Would you like to play again? (y/n)")
-        if choice == "y":
-            play_game()
-            break
-        elif choice == "n":
-            print_pause("Thanks for playing! See you next time.")
-            break
-```
+| Problem | Cause | Fix |
+|---|---|---|
+| Loop never exits | Forgot `break` after a choice handler | Always `break` after dispatching |
+| State leaks between runs | Globals reused | Build state inside `play_game()` |
+| Bad input crashes the game | `int(input())` without `try` | Validate, or only accept letters/specific strings |
+| Scenes call each other recursively forever | No clear terminal scene | Add explicit win/lose endings |
+| Long scenes blur together | No pacing | Add `time.sleep` and section breaks |
 
-Allows players to restart the adventure without relaunching the program.
+## Variations to Try
 
-## Features
+### 1. Health and damage stats
+A `health` attribute that decreases on bad choices and ends the game at 0.
 
-- **Immersive Storytelling**: Rich narrative with atmospheric descriptions
-- **Player Choices**: Multiple decision points affecting story outcomes
-- **Inventory System**: Item collection that changes gameplay possibilities
-- **Multiple Endings**: Different outcomes based on player preparation and choices
-- **Replayability**: Option to play again and try different strategies
-- **Input Validation**: Robust handling of user choices
-- **Progressive Revelation**: Story elements revealed based on player actions
+### 2. NPC dialogue
+A scene where the player chooses what to say; the NPC responds based on prior choices. Track `flags` like `met_wizard = True`.
 
-## Next Steps
+### 3. Random encounters
+With a 25 % chance, an enemy intercepts the player on a path. Use `random.random() < 0.25`.
+
+### 4. Map with directions
+Instead of numbered choices, accept `north`, `south`, `east`, `west`. Store the map as a dict of rooms with `exits`.
+
+### 5. Combat system
+Damage dice (`1d6 + str`), turn-based combat, escape attempts. See [Dice Rolling Simulator](./dicerolling) for the dice mechanic.
+
+### 6. Multiple character classes
+Warrior, mage, rogue — each starts with different equipment and stats; some scenes only unlock for specific classes.
 
-### Enhancements
-- Add more locations and story branches
-- Implement character stats (health, strength, magic)
-- Create more complex inventory with multiple items
-- Add random events and encounters
-- Include puzzle-solving elements
-- Implement save/load game functionality
-- Add character classes and skills
-- Create multiple story campaigns
-
-### Learning Extensions
-- Study advanced narrative design patterns
-- Explore procedural story generation
-- Learn about game state serialization
-- Practice with object-oriented game design
-- Understand random content generation
-- Explore text parsing for natural language input
+### 7. Save slots
+Multiple JSON files (`save1.json`, `save2.json`) plus a menu to pick one.
+
+### 8. Editor mode
+A separate Python script that lets a designer type scenes interactively and append them to `scenes.json`.
+
+### 9. Voice narration
+Pipe each `print_pause` line through `pyttsx3` to read aloud.
+
+### 10. Web port
+Wrap the engine in Flask. Each scene becomes a page; choices become links. The state lives in the user's session.
+
+## Real-World Applications
+- **Onboarding flows** — branching tutorials that adapt to user knowledge.
+- **Chatbots with structured paths** — customer-service trees.
+- **Educational simulations** — choose-your-own-adventure for ethics or training.
+- **Decision-tree visualizations** — the engine is a generic state machine.
+- **Game prototypes** — text mode for everything before art and engines.
 
 ## Educational Value
+- **State machines** — scenes and transitions are an explicit FSM.
+- **Inventory pattern** — applicable to shopping carts, permissions, feature flags.
+- **Branching logic** — what most "config-driven" systems boil down to.
+- **Refactoring from script to engine** — extracting data from code is a fundamental engineering skill.
+- **Narrative design** — pacing, payoff, agency.
 
-This project teaches:
-- **Game Logic Design**: Creating rules and systems for interactive experiences
-- **State Management**: Tracking player progress and inventory across game sessions
-- **Narrative Programming**: Implementing story branching and choice consequences
-- **Input Validation**: Handling user input robustly and providing clear feedback
-- **Function Organization**: Structuring code for complex interactive systems
-- **Flow Control**: Managing program flow through different story paths
-- **User Experience**: Creating engaging and intuitive text-based interfaces
-- **Story Design**: Balancing player agency with narrative structure
-
-Perfect for understanding game development fundamentals, interactive storytelling, and user-driven application design.
+## Next Steps
+- Add **`time.sleep` pacing** everywhere — it transforms the feel.
+- Extend with **save/load**.
+- Refactor to the **JSON-driven engine** above.
+- Write a longer story — 20+ scenes, 3 endings.
+- Try the **`textual`** library for a richer TUI with mouse and color support.
+- Port to Twine or Ink (industry-standard tools) once your story outgrows JSON.
+
+## Conclusion
+You built a complete branching adventure, learned to manage state and inventory, and saw the refactor path from hard-coded scenes to a real data-driven engine. The same patterns underlie every interactive fiction system, chatbot, and onboarding flow. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/textbasedadventuregame.py). Explore more game projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/todo.mdx b/src/content/docs/projects/Beginners/todo.mdx
index a4c19d1a..e31ad2f1 100644
--- a/src/content/docs/projects/Beginners/todo.mdx
+++ b/src/content/docs/projects/Beginners/todo.mdx
@@ -1,6 +1,6 @@
 ---
 title: Todo List Application
-description: Build a comprehensive task management system with file persistence, CRUD operations, and command-line interface
+description: Build a CLI todo manager in Python with persistence, CRUD operations, priorities, due dates, search, and a path to SQLite, JSON, and Tkinter GUI versions.
 sidebar:
   order: 49
 hero:
@@ -13,176 +13,286 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A todo list is the canonical "first useful CLI app". You learn file I/O, input validation, CRUD (Create / Read / Update / Delete), confirmations for destructive operations, and the basic shape of a long-running interactive program. In this project you will build the text-file version, fix several subtle bugs in the naïve approach, then evolve toward a richer todo manager with priorities, due dates, search, JSON storage, SQLite storage, and finally a Tkinter GUI.
 
-Create a fully functional todo list application that allows users to add, view, delete, and manage tasks through a command-line interface. The application features persistent file storage, comprehensive task management operations, and user-friendly confirmation dialogs.
+You will leave comfortable with:
+- Reading and writing text files safely.
+- Persisting state between runs.
+- Implementing CRUD operations.
+- Designing menu-driven CLIs that do not rot as features pile up.
+- Choosing a storage format (text, JSON, SQLite) for the right job.
 
 ## Prerequisites
-
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of file operations (read, write, append)
-- Familiarity with lists and string manipulation
-- Understanding of control structures and loops
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with functions, lists, and basic file I/O.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `todoListApp`.
-2. Create a new file and name it `todo.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into your `todo.py` file.
+### Create the project
+1. Create folder `todo-app`.
+2. Inside, create `todo.py`.
 
 ### Write the code
-1. Add the following code to your `todo.py` file.
 <FileCode file="projects/beginners/todo.py" lang="python" title="Todo List Application" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\todoListApp> python todo.py
+
+### Run it
+```cmd title="command"
+C:\Users\username\Documents\todo-app> python todo.py
 ----------TO DO LIST----------
 1. Add task
 2. Delete task
-3. Show task
-4. exit
-enter the choice: 1
-enter the task: Buy groceries
-Task Added Successfully.
+3. Show tasks
+4. Exit
+Enter the choice: 1
+Enter the task: Buy groceries
+Task added successfully.
+```
 
-enter the choice: 3
-1: Buy groceries
+## Step-by-Step Explanation
 
-enter the choice: 4
+### 1. Add a task
+```python title="todo.py"
+def add_task():
+    task = input("Enter task: ").strip()
+    if not task:
+        print("Empty task ignored.")
+        return
+    with open("todo.txt", "a", encoding="utf-8") as f:
+        f.write(task + "\n")
+    print("Task added.")
 ```
+Three things matter:
+- `"a"` mode **appends** instead of overwriting.
+- `with open(...)` guarantees the file is closed even on exception.
+- `encoding="utf-8"` makes the program work for non-English tasks.
 
-3. **Use the Application**
-   - Choose operations from the main menu (1-4, E, R, H)
-   - Add tasks with descriptive names
-   - View your current task list
-   - Delete individual tasks or clear all tasks
+### 2. View tasks
+```python title="todo.py"
+def view_tasks():
+    if not os.path.exists("todo.txt"):
+        print("No tasks yet.")
+        return
+    with open("todo.txt", encoding="utf-8") as f:
+        tasks = [line.rstrip("\n") for line in f if line.strip()]
+    if not tasks:
+        print("No tasks found.")
+        return
+    for i, t in enumerate(tasks, start=1):
+        print(f"{i}. {t}")
+```
+- `enumerate(..., start=1)` gives 1-based numbering for the user.
+- Empty lines are filtered out.
 
-## Code Explanation
+### 3. Delete a task
+```python title="todo.py"
+def delete_task():
+    tasks = read_tasks()
+    if not tasks:
+        print("Nothing to delete.")
+        return
+    show(tasks)
+    try:
+        n = int(input("Number to delete: "))
+    except ValueError:
+        print("Enter a number.")
+        return
+    if not 1 <= n <= len(tasks):
+        print("Out of range.")
+        return
+    removed = tasks.pop(n - 1)
+    write_tasks(tasks)
+    print(f"Deleted: {removed}")
+```
+Reading the whole file, mutating in memory, and writing it back is fine for tens or hundreds of tasks. SQLite becomes preferable past that.
 
-### File-Based Persistence
-```python title="todo.py" showLineNumbers{1}
-def add_task():
-    task = input("Enter Task: ")
-    with open("todo.txt", "a") as f:
-        f.write(task + "\n")
-    print("Task Added Successfully.")
+### 4. Confirm destructive operations
+```python title="todo.py"
+def delete_all():
+    if input("Are you sure? (y/n) ").lower() != "y":
+        print("Cancelled.")
+        return
+    open("todo.txt", "w").close()
+    print("All tasks deleted.")
 ```
+A `y/n` confirmation prevents accidental wipes.
 
-Uses text file storage to maintain tasks between application sessions, ensuring data persistence.
-
-### Task Viewing with Numbering
-```python title="todo.py" showLineNumbers{1}
-def view_task():
-    with open("todo.txt", "r") as f:
-        tasks = f.readlines()
-        if len(tasks) == 0:
-            print("No Tasks Found.")
-        else:
-            for i in range(len(tasks)):
-                print(str(i + 1) + ". " + tasks[i].strip("\n"))
+### 5. The main loop
+```python title="todo.py"
+def main():
+    while True:
+        print("\n1. Add  2. Delete  3. View  4. Clear all  5. Exit")
+        choice = input("> ").strip()
+        if choice == "1": add_task()
+        elif choice == "2": delete_task()
+        elif choice == "3": view_tasks()
+        elif choice == "4": delete_all()
+        elif choice == "5": break
+        else: print("Invalid choice.")
 ```
 
-Displays tasks in a numbered list format for easy reference and selection.
+## Bugs in the Naïve Version
 
-### Safe Task Deletion
-```python title="todo.py" showLineNumbers{1}
-def delete_task():
-    with open("todo.txt", "r") as f:
-        tasks = f.readlines()
-        # Display current tasks
-        task_no = int(input("Enter Task Number to Delete: "))
-        if task_no > len(tasks):
-            print("Invalid Task Number.")
-        else:
-            del tasks[task_no - 1]
-            with open("todo.txt", "w") as f:
-                for task in tasks:
-                    f.write(task)
+The most common errors in beginner todo apps:
+1. **No `strip()` on read lines** — `"Buy bread\n"` and `"Buy bread"` look identical but are not equal.
+2. **`open(...)` without `with`** — leaks file descriptors on exception.
+3. **No empty-task check** — pressing Enter creates blank tasks that confuse `delete`.
+4. **No off-by-one guard** — `tasks[task_no]` instead of `tasks[task_no - 1]` deletes the wrong row.
+5. **No encoding** — the program breaks the moment someone adds an emoji or accented character.
+
+The version above fixes all five.
+
+## Add Priorities and Due Dates
+
+Plain text loses structure the moment you want anything richer than a string. Move to JSON:
+```python title="json_store.py"
+from pathlib import Path
+import json
+STORE = Path("todo.json")
+
+def read_tasks():
+    return json.loads(STORE.read_text(encoding="utf-8")) if STORE.exists() else []
+
+def write_tasks(tasks):
+    STORE.write_text(json.dumps(tasks, indent=2), encoding="utf-8")
+
+def add(title, priority="medium", due=None):
+    tasks = read_tasks()
+    tasks.append({"title": title, "priority": priority,
+                  "due": due, "done": False})
+    write_tasks(tasks)
 ```
+Each task is a dict with `title`, `priority`, `due` (ISO date), and `done`. Now you can:
+- Filter by priority.
+- Sort by due date.
+- Mark tasks done without deleting them.
+- Show only open tasks.
+
+## Search and Filter
 
-Implements safe task removal with validation and immediate file updates.
+```python title="filter.py"
+def search(keyword):
+    return [t for t in read_tasks() if keyword.lower() in t["title"].lower()]
 
-### Confirmation Dialogs
-```python title="todo.py" showLineNumbers{1}
-def delete_all_task():
-    confirm = input("Are you sure you want to delete all tasks? (Y/N): ")
-    if confirm in ("Y", "y"):
-        with open("todo.txt", "w") as f:
-            f.write("")
-        print("All Tasks Deleted Successfully.")
+def by_priority(priority):
+    return [t for t in read_tasks() if t["priority"] == priority and not t["done"]]
+
+def overdue():
+    today = date.today().isoformat()
+    return [t for t in read_tasks() if t["due"] and t["due"] < today and not t["done"]]
 ```
 
-Provides user confirmation for destructive operations to prevent accidental data loss.
+## Migrate to SQLite
 
-### Application Control
-```python title="todo.py" showLineNumbers{1}
-def exit():
-    confirm = input("Are you sure you want to exit? (Y/N): ")
-    if confirm in ("Y", "y"):
-        print("Exiting...")
-        time.sleep(1)
-        sys.exit()
+When you cross a thousand tasks, JSON's "rewrite the whole file" model gets slow. SQLite handles thousands trivially:
+```python title="sqlite_store.py"
+import sqlite3, contextlib
+DB = "todo.db"
+with contextlib.closing(sqlite3.connect(DB)) as db:
+    db.execute("""CREATE TABLE IF NOT EXISTS tasks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title TEXT NOT NULL,
+        priority TEXT DEFAULT 'medium',
+        due TEXT,
+        done INTEGER DEFAULT 0,
+        created TEXT DEFAULT CURRENT_TIMESTAMP
+    )""")
+    db.commit()
+```
+Queries become SQL:
+```python title="queries.py"
+db.execute("INSERT INTO tasks(title, priority, due) VALUES(?, ?, ?)",
+           (title, priority, due))
+db.execute("UPDATE tasks SET done = 1 WHERE id = ?", (task_id,))
+rows = db.execute("SELECT * FROM tasks WHERE done = 0 ORDER BY due").fetchall()
 ```
+Now you have indexes, transactions, and concurrent-read support for free.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Crash on first run | File does not exist | `if not Path("todo.txt").exists()` |
+| Tasks show with trailing newline | Did not strip | `line.rstrip("\n")` |
+| `IndexError` on delete | Off-by-one | `tasks.pop(n - 1)` and range check |
+| Non-English text shows mojibake | Default encoding | Pass `encoding="utf-8"` everywhere |
+| File grows forever | Never truly cleared | `open("todo.txt", "w").close()` truncates |
+| Two instances corrupt the file | No locking | Use SQLite for multi-process |
+
+## Variations to Try
 
-Manages application lifecycle with graceful exit confirmation.
-
-### Main Program Loop
-```python title="todo.py" showLineNumbers{1}
-while True:
-    choice = input("Enter Choice (1/2/3/4/E/R/H): ")
-    if choice == "1":
-        add_task()
-    elif choice == "2":
-        view_task()
-    # ... other choices
+### 1. Mark as done (instead of delete)
+Add a `done` flag. Show with strikethrough characters:
+```python title="strike.py"
+title = "".join(c + "̶" for c in task["title"])
 ```
 
-Implements continuous operation loop with clear menu options and input validation.
+### 2. Edit a task
+Prompt for a number, then a new title; rewrite in place.
 
-## Features
+### 3. Tags / categories
+A `tags: list[str]` field. Filter by tag with `t for t in tasks if tag in t["tags"]`.
 
-- **Persistent Storage**: Tasks saved to file system survive application restarts
-- **CRUD Operations**: Complete Create, Read, Update, Delete functionality
-- **User-Friendly Interface**: Clear menu system with numbered options
-- **Input Validation**: Handles invalid choices and task numbers gracefully
-- **Confirmation Dialogs**: Prevents accidental deletion of tasks
-- **Help System**: Built-in help explaining all available operations
-- **Application Control**: Exit and restart functionality with confirmations
+### 4. Smart input
+`pip install dateparser` lets users type `"finish report next friday"` and parse out a due date.
 
-## Next Steps
+### 5. Recurring tasks
+A `recurrence` field (`daily`, `weekly`). When marked done, schedule the next occurrence automatically.
+
+### 6. Reminders
+Combine with [Simple Reminder App](./simplereminderapp) — when a task's `due` arrives, fire a desktop notification.
 
-### Enhancements
-- Add task due dates and reminders
-- Implement task priorities (high, medium, low)
-- Create task categories or tags
-- Add task completion status tracking
-- Implement search and filter functionality
-- Create backup and restore features
-- Add task editing capabilities
-- Include task creation timestamps
-
-### Learning Extensions
-- Study database integration (SQLite)
-- Explore GUI development with Tkinter
-- Learn about task scheduling with datetime
-- Practice with JSON data storage
-- Understand regular expressions for search
-- Explore web-based todo applications
+### 7. Sync across devices
+Save the JSON file to a synced folder (Dropbox/iCloud) or push to a small Flask backend (see [Basic Web Server](./basicwebserver)) so multiple devices see the same list.
+
+### 8. CLI flags
+With **argparse** or **Typer**:
+```bash title="cli"
+todo add "Buy bread" --priority high --due 2025-06-01
+todo list --priority high
+todo done 3
+```
+
+### 9. GUI version
+A Tkinter window with a list of tasks, checkboxes for done, and an entry field. See [Basic Music Player](./basicmusicplayer) for the GUI pattern.
+
+### 10. TUI version
+**`rich`** or **`textual`** for a colorful in-terminal UI with keyboard navigation.
+
+### 11. Export
+"Export to CSV" / "Export to Markdown" — useful for sharing or backup.
+
+### 12. Statistics
+Show "completed this week", "average completion time", "most common priority".
+
+## Best Practices Demonstrated
+- **Confirm destructive operations** before performing them.
+- **Validate input** at the boundary (numeric, in-range, non-empty).
+- **Always use `with open(...)`** for file I/O.
+- **Pass `encoding="utf-8"`** explicitly on every text file.
+- **Move from text → JSON → SQLite** as needs grow; do not skip ahead.
+
+## Real-World Applications
+- Personal task management.
+- Team shared todo (with the Flask variant).
+- Bug-tracker prototypes for small projects.
+- Shopping list / grocery apps.
+- Build-step tracker for repetitive workflows.
 
 ## Educational Value
+- **CRUD operations** — the foundation of every data app.
+- **File I/O** — text vs. JSON vs. SQLite trade-offs.
+- **Input validation** — handling the messy reality of humans typing.
+- **Confirmation flows** — UX for irreversible actions.
+- **Refactoring** — going from a 50-line script to a tested, indexed, multi-user app.
+
+## Next Steps
+- Add **mark as done** (without deletion).
+- Switch storage to **JSON**, then **SQLite**.
+- Add **priorities, due dates, tags**.
+- Wrap with a **Tkinter GUI** or a **Flask web app**.
+- Layer **reminders** (cross-link with [Simple Reminder App](./simplereminderapp)).
+- See [Todo List GUI](./todolist) for the next step.
 
-This project teaches:
-- **File I/O Operations**: Reading from and writing to text files
-- **Data Persistence**: Maintaining application data between sessions
-- **CRUD Operations**: Implementing complete data management functionality
-- **Input Validation**: Handling user input safely and providing feedback
-- **Application Architecture**: Organizing code into focused functions
-- **User Experience**: Creating intuitive command-line interfaces
-- **Error Handling**: Managing edge cases and invalid operations
-- **Control Flow**: Managing complex program flow with menus and confirmations
-
-Perfect for understanding data management, file operations, and user interface design in console applications.
+## Conclusion
+You built a complete todo app and learned the path from a text file to a proper relational schema. Every project you write from here will reuse these CRUD, persistence, and confirmation patterns. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/todo.py). Explore more productivity projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/todolist.mdx b/src/content/docs/projects/Beginners/todolist.mdx
index 3025f1b2..58818ff7 100644
--- a/src/content/docs/projects/Beginners/todolist.mdx
+++ b/src/content/docs/projects/Beginners/todolist.mdx
@@ -1,6 +1,6 @@
 ---
-title: Todo List Application
-description:  A simple Todo List Application using Python. In this project, you can add, delete, and view the list of tasks. This is a command line based application and uses the txt file to store the tasks.
+title: Todo List Application (CLI)
+description: Build a polished CLI todo manager in Python with text-file storage, priorities, due dates, completion tracking, and a path to JSON, SQLite, and Tkinter. Companion to the simpler todo.py walkthrough.
 sidebar: 
     order: 4
 hero:
@@ -13,310 +13,296 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-This is a simple Todo List Application using Python. In this project, you can add, delete, and view the list of tasks. This is a command line based application and uses the txt file to store the tasks. For the features, you can add a task, delete a task, and view the list of tasks. The application will store the tasks in the txt file and will read the tasks from the txt file. The application will also check if the txt file exists or not. If the txt file does not exist, then the application will create a new txt file and store the tasks in it. The application will also check if the task is already present in the txt file or not. If the task is already present in the txt file, then the application will not add the task to the txt file. The application will also check if the task is present in the txt file or not. If the task is not present in the txt file, then the application will not delete the task from the txt file.
+The Todo List Application is the canonical first useful program in any language. It exercises file I/O, persistence, CRUD operations, input validation, menu design, and confirmation flows in under 150 lines. In this expanded tutorial you build the polished command-line version with **Add / View / Delete / Delete-all / Exit / Restart / Help** commands stored in a plain `todo.txt`, then evolve toward a real productivity tool: priorities, due dates, completion marks, JSON storage, SQLite, and a Tkinter GUI.
+
+You will learn:
+- Robust file I/O with `with open` and UTF-8 encoding.
+- The full CRUD cycle on a flat text file.
+- Why confirmation flows matter for destructive operations.
+- The architectural path from `todo.txt` → JSON → SQLite.
+- How to grow a 30-line script into a tool you would actually use.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
+- Python 3.6 or above.
+- A text editor or IDE.
+- Comfort with `input`, `if/elif/else`, and `while`.
+- Familiarity with the lighter [Todo (basics)](./todo) walkthrough.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it as `todo`.
-2. Create a new file and name it as `todo.py`.
-3. Create a new file and name it as `todo.txt`.
-4. Open the project folder in the text editor or IDE.
-5. Copy the code from `todo.py` and paste it into `todo.py` file.
+
+### Create the project
+1. Create folder `todo-list`.
+2. Inside, create `todo.py`.
+3. The script will create `todo.txt` on first save.
 
 ### Write the code
-1. Add the following code to the `todo.py` file.
 <FileCode file="projects/beginners/todo.py" lang="python" title="Todo List App" />
-2. Save the File.
-3. Open the terminal and navigate to the project folder.
-4. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
+
+### Run it
+```cmd title="command"
 C:\Users\username\Documents\todo> python todo.py
 Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 1
-Add Task
----------
-Enter Task: Going for the google summit
+1. Add task   2. View task   3. Delete task   4. Delete all
+E. Exit       R. Restart     H. Help
+Enter Choice: 1
+Enter Task: Going for the Google summit
 Task Added Successfully.
-Enter Choice (1/2/3/4/E/R/H): 2
-View Task
----------
-1. Going for the google summit
-Enter Choice (1/2/3/4/E/R/H): 3
-Delete Task
-------------
-1. Going for the google summit
-Enter Task Number to Delete: 1
-Task Deleted Successfully.
-Enter Choice (1/2/3/4/E/R/H): 2
-View Task
----------
-No Tasks Found.
-Enter Choice (1/2/3/4/E/R/H): H
-Help
-----
-Add Task: Add a task to the todo list.
-View Task: View all tasks in the todo list.
-Delete Task: Delete a task from the todo list.
-Delete All Task: Delete all tasks from the todo list.
-Exit: Exit the application.
-Restart: Restart the application.
-Help: View help.
-Enter Choice (1/2/3/4/E/R/H): E
-Exit
------
-Are you sure you want to exit? (Y/N): Y
-Exiting...
 ```
-5. You can view the tasks in the `todo.txt` file.
-```txt title="todo.txt" showLineNumbers{1}
-Going for the google summit
+
+## Step-by-Step Explanation
+
+### 1. Imports
+```python title="todo.py"
+import os, sys, time
 ```
+- `os` for the restart trick.
+- `sys` for `sys.exit()`.
+- `time` for the sleep before restart.
 
-## Explanation
-1. The `import os` statement will import the `os` module.
-2. The `import time` statement will import the `time` module.
-3. The `import sys` statement will import the `sys` module.
-4. The `import datetime` statement will import the `datetime` module.
-5. The `def add_task():` statement will define a function named `add_task`. It will add a task to the todo list. It will take no parameters.
-6. `add_task()` function write the task to the `todo.txt` file using the `with open("todo.txt", "a") as f:` statement. It append the task at the end of the file.
-7. The `def view_task():` statement will define a function named `view_task`. It will view all tasks in the todo list. It will take no parameters.
-8. `view_task()` function read the tasks from the `todo.txt` file using the `with open("todo.txt", "r") as f:` statement.
-9. The `def delete_task():` statement will define a function named `delete_task`. It will delete a task from the todo list. It will take no parameters.
-10. `delete_task()` function read the tasks from the `todo.txt` file using the `with open("todo.txt", "r") as f:` statement. It will ask the user to enter the task number to delete. It will delete the task from the `todo.txt` file using the `del tasks[task_no - 1]` statement.
-11. The `def delete_all_task():` statement will define a function named `delete_all_task`. It will delete all tasks from the todo list. It will take no parameters.
-12. `delete_all_task()` function read the tasks from the `todo.txt` file using the `with open("todo.txt", "r") as f:` statement. It will ask the user to confirm the deletion of all tasks. It will delete all tasks from the `todo.txt` file using the `with open("todo.txt", "w") as f:` statement.
-13. The `def exit():` statement will define a function named `exit`. It will exit the application. It will take no parameters. It will ask the user to confirm the exit. It will exit the application using the `sys.exit()` statement.
-14. The `def restart():` statement will define a function named `restart`. It will restart the application. It will take no parameters. It will ask the user to confirm the restart. It will restart the application using the `os.system("python todo.py")` statement.
-15. The `def help():` statement will define a function named `help`. It will display the help. It will take no parameters. It will display the help using the `print()` statement. It helps the user to use the application.
-16. The `print("Todo Application")` statement will display the Todo Application text on the screen.
-17. We are going to use `while` loop to run the application continuously. The `while True:` statement will create an infinite loop.
-18. When the user wants to exit the application, then the `sys.exit()` statement will exit the application.
-
-## Usage
-1. Open the terminal and navigate to the project folder.
-2. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\hello_world> python todo.py
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 
+### 2. Add a task
+```python title="todo.py"
+def add_task():
+    task = input("Enter task: ").strip()
+    if not task:
+        print("Empty task ignored.")
+        return
+    with open("todo.txt", "a", encoding="utf-8") as f:
+        f.write(task + "\n")
+    print("Task added.")
 ```
-3. Enter the choice and press the enter key.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\hello_world> python todo.py
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 1
+- `"a"` opens for append — does not erase existing content.
+- `.strip()` removes trailing whitespace including the newline from Enter.
+- Empty task guard avoids accidental blank entries.
+
+### 3. View tasks
+```python title="todo.py"
+def view_tasks():
+    if not os.path.exists("todo.txt") or os.path.getsize("todo.txt") == 0:
+        print("No tasks yet.")
+        return
+    with open("todo.txt", encoding="utf-8") as f:
+        tasks = [line.rstrip("\n") for line in f if line.strip()]
+    for i, t in enumerate(tasks, start=1):
+        print(f"{i}. {t}")
 ```
+- `enumerate(..., start=1)` gives 1-based numbering for the user.
+- The filter `if line.strip()` skips blank lines that may sneak in.
 
-4. If you enter `1` and press the enter key, then the application will add a task to the todo list.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 1
-Add Task
----------
-Enter Task: Going for the google summit
-Task Added Successfully.
-Enter Choice (1/2/3/4/E/R/H): 
+### 4. Delete by number
+```python title="todo.py"
+def delete_task():
+    if not os.path.exists("todo.txt"):
+        print("Nothing to delete."); return
+    with open("todo.txt", encoding="utf-8") as f:
+        tasks = [line.rstrip("\n") for line in f if line.strip()]
+    if not tasks:
+        print("Nothing to delete."); return
+    for i, t in enumerate(tasks, 1): print(f"{i}. {t}")
+    try:
+        n = int(input("Number to delete: "))
+    except ValueError:
+        print("Enter a whole number."); return
+    if not 1 <= n <= len(tasks):
+        print("Out of range."); return
+    removed = tasks.pop(n - 1)
+    with open("todo.txt", "w", encoding="utf-8") as f:
+        f.writelines(t + "\n" for t in tasks)
+    print(f"Deleted: {removed}")
 ```
+The "load all, mutate, write all back" pattern is fine for small files (thousands of lines). Beyond that, SQLite is the right answer.
 
-5. If you enter `2` and press the enter key, then the application will view all tasks in the todo list.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 2
-View Task
----------
-1. Going for the google summit
-Enter Choice (1/2/3/4/E/R/H): 
+### 5. Delete all (with confirmation)
+```python title="todo.py"
+def delete_all():
+    if input("Delete EVERY task? (Y/N): ").strip().lower() != "y":
+        print("Cancelled."); return
+    open("todo.txt", "w").close()
+    print("All tasks deleted.")
 ```
+Confirmation flows are not optional — accidental "delete all" is the #1 way users lose data.
 
-6. If you enter `3` and press the enter key, then the application will delete a task from the todo list. Application shows the list of tasks and asks the user to enter the task number to delete.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 3
-Delete Task
-------------
-1. Going for the google summit
-Enter Task Number to Delete: 1
-Task Deleted Successfully.
-Enter Choice (1/2/3/4/E/R/H): 
+### 6. Exit, Restart, Help
+```python title="todo.py"
+def exit_app():
+    if input("Exit? (Y/N): ").strip().lower() == "y":
+        print("Goodbye.")
+        sys.exit()
+
+def restart():
+    if input("Restart? (Y/N): ").strip().lower() == "y":
+        print("Restarting..."); time.sleep(1)
+        os.execv(sys.executable, [sys.executable] + sys.argv)
+
+def show_help():
+    print("Add / View / Delete / Delete All / Exit / Restart / Help")
 ```
+- **`sys.exit()`** is the clean way to quit.
+- **`os.execv`** replaces the current process with a fresh interpreter — true restart with no state.
 
-7. If you enter `4` and press the enter key, then the application will delete all tasks from the todo list. Application shows the list of tasks and asks the user to confirm the deletion of all tasks.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 4
-Delete All Task
-----------------
-1. Going for the google summit
-Are you sure you want to delete all tasks? (Y/N): Y
-All Tasks Deleted Successfully.
-Enter Choice (1/2/3/4/E/R/H): 
+### 7. The main loop
+```python title="todo.py"
+while True:
+    choice = input("Choice (1/2/3/4/E/R/H): ").strip().upper()
+    if   choice == "1": add_task()
+    elif choice == "2": view_tasks()
+    elif choice == "3": delete_task()
+    elif choice == "4": delete_all()
+    elif choice == "E": exit_app()
+    elif choice == "R": restart()
+    elif choice == "H": show_help()
+    else: print("Invalid choice.")
 ```
+`.strip().upper()` makes `e`, `E`, `e `, ` E ` all equivalent.
 
-8. If you enter `E` or `e` and press the enter key, then the application will exit.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): E
-Exit
------
-Are you sure you want to exit? (Y/N): Y
-Exiting...
+## Architecture: From txt → JSON → SQLite
+
+A `todo.txt` is great for ≤ ~500 tasks. Pain points beyond that:
+- No structured fields — priority, due date, tags, status.
+- Editing a single task means rewriting the whole file.
+- Concurrent access from two terminals corrupts it.
+
+### Step 1: JSON
+```python title="json_store.py"
+import json
+from pathlib import Path
+
+STORE = Path("todo.json")
+def read():
+    return json.loads(STORE.read_text(encoding="utf-8")) if STORE.exists() else []
+def write(tasks):
+    STORE.write_text(json.dumps(tasks, indent=2), encoding="utf-8")
+
+def add(title, priority="medium", due=None):
+    tasks = read()
+    tasks.append({
+        "id": len(tasks) + 1,
+        "title": title, "priority": priority, "due": due, "done": False,
+    })
+    write(tasks)
 ```
 
-9. If you enter `R` or `r` and press the enter key, then the application will restart.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): R
-Restart
---------
-Are you sure you want to restart? (Y/N): Y
-Restarting...
+### Step 2: SQLite
+```python title="sqlite_store.py"
+import sqlite3
+db = sqlite3.connect("todo.db")
+db.execute("""CREATE TABLE IF NOT EXISTS tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    priority TEXT DEFAULT 'medium',
+    due TEXT,
+    done INTEGER DEFAULT 0,
+    created TEXT DEFAULT CURRENT_TIMESTAMP
+)""")
+db.execute("INSERT INTO tasks(title, priority) VALUES(?, ?)", ("Buy bread", "high"))
+db.commit()
+
+# query
+for row in db.execute("SELECT id, title FROM tasks WHERE done = 0 ORDER BY due"):
+    print(row)
 ```
+Now you have indexes, transactions, concurrent reads, and SQL queries — all from one Python module.
 
-10. If you enter `H` or `h` and press the enter key, then the application will display the help.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): H
-Help
-----
-Add Task: Add a task to the todo list.
-View Task: View all tasks in the todo list.
-Delete Task: Delete a task from the todo list.
-Delete All Task: Delete all tasks from the todo list.
-Exit: Exit the application.
-Restart: Restart the application.
-Help: View help.
-Enter Choice (1/2/3/4/E/R/H): 
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `FileNotFoundError` on first run | File created lazily | Guard with `os.path.exists` |
+| Tasks shown with trailing newline | Forgot to strip | `line.rstrip("\n")` |
+| `IndexError` on delete | Off-by-one | `tasks.pop(n - 1)` with range check |
+| Mojibake on non-English tasks | Default encoding | Always `encoding="utf-8"` |
+| Empty task added on Enter-only | No empty check | `if not task: return` |
+| Two terminals corrupt the file | No locking | Move to SQLite for concurrent access |
+| Restart leaves stale state | Manual reset of globals incomplete | Use `os.execv` for clean restart |
+
+## Variations to Try
+
+### 1. Mark done (instead of delete)
+Add a `done` flag. Show `[x]` or `[ ]` prefix. Filter with `view --pending`.
+
+### 2. Priorities
+`high`, `medium`, `low` — sort by priority on view.
+
+### 3. Due dates
+`due: YYYY-MM-DD`. Highlight overdue in red on output.
+```python title="overdue.py"
+from datetime import date
+RED, RESET = "\033[91m", "\033[0m"
+overdue = task["due"] and task["due"] < date.today().isoformat()
+print(f"{RED if overdue else ''}{task['title']}{RESET if overdue else ''}")
 ```
 
-11. If you enter any other choice and press the enter key, then the application will display the invalid choice message.
-```cmd title="command" showLineNumbers{1}
-Todo Application
-----------------
-Select Operation.
-1. Add Task
-2. View Task
-3. Delete Task
-4. Delete All Task
-E. Exit
-R. Restart
-H. Help
-Enter Choice (1/2/3/4/E/R/H): 5
-Invalid Choice.
-Enter Choice (1/2/3/4/E/R/H): 
+### 4. Tags
+A `tags: list[str]` field. Filter with `view --tag work`.
+
+### 5. Search
+`view --search keyword`.
+
+### 6. Edit
+"Edit task #3" → prompt for new title.
+
+### 7. Recurring tasks
+`recurrence: daily | weekly | monthly`. On complete, schedule the next occurrence.
+
+### 8. Reminders
+Combine with [Simple Reminder App](./simplereminderapp) — fire a desktop notification when `due` arrives.
+
+### 9. CLI flags with `argparse` or `typer`
+```bash title="cli"
+todo add "Buy bread" --priority high --due 2026-06-01
+todo list --pending --tag groceries
+todo done 3
+todo delete 5
 ```
 
-## Next Steps
-Congratulations you have successfully created a Todo List Application using Python. Experiment with the code and try to modify it.
-
-Here are a few suggestions:
-1. Add a feature to edit a task.
-2. Add a feature to sort the tasks.
-3. Add a feature to search for a task.
-4. Add a feature to add a task to a specific position.
-5. Add a feature to add a task to a specific date.
-6. Add a feature to add a task to a specific time.
-7. Add a feature to add a task to a specific date and time.
-8. Add a feature to add a task to a specific date and time and set a reminder.
-9. Add a feature to add a task to a specific date and time and set a reminder and repeat the task.
-10. Add a feature to add a task to a specific date and time and set a reminder and repeat the task and set a priority.
+### 10. GUI version
+Tkinter window with a `Listbox` of tasks, checkboxes for done, and an entry field for new tasks.
 
-## Conclusion
-In this project, You learned how to build a Todo List Application using Python. You also learned how to add a task, view a task, delete a task, and delete all tasks.
+### 11. Web frontend
+Flask app (see [Basic Web Server](./basicwebserver)) with HTMX or React, JSON API in the middle.
 
-You also learned how to use the `os` module, `time` module, `sys` module, and `datetime` module. You also learned how to use the `with` statement. You also learned how to use the `while` loop. You also learned how to use the `if` statement. You also learned how to use the `elif` statement. You also learned how to use the `else` statement. You also learned how to use the `def` statement. You also learned how to use the `print()` function. You also learned how to use the `input()` function. You also learned how to use the `open()` function. You also learned how to use the `del` statement. You also learned how to use the `sys.exit()` function. You can find more information about the `os` module, `time` module, `sys` module, and `datetime` module on the official [Python documentation website](https://docs.python.org/3/library/). 
+### 12. Sync across devices
+Write the JSON to a shared cloud folder (Dropbox / iCloud) or push to a server. Eventual-consistency conflict resolution.
 
-Keep experimenting with the code and try to modify it. Find more tutorials on the Python Central Hub.
\ No newline at end of file
+### 13. Pomodoro integration
+"Start working on task #3" → 25-minute timer fires, breaks logged.
+
+### 14. Statistics
+Tasks completed this week / month. Streaks, longest-pending task, average time-to-done.
+
+### 15. Export
+`todo export markdown > tasks.md` → renders nicely on GitHub.
+
+## Companion Tutorial
+
+This page covers the **more detailed CLI walkthrough**. For the *introduction* with a simpler scope, see [Todo (basics)](./todo) — same script, simpler narrative. For the **GUI version**, see the upcoming "Todo Tkinter" project.
+
+## Best Practices Demonstrated
+- **Always `with open(...)`** for file I/O.
+- **`encoding="utf-8"` always** to avoid silent corruption.
+- **Confirm destructive operations.**
+- **Validate input** at the moment it enters.
+- **Migrate storage as you grow** — txt → JSON → SQLite, never the reverse.
+
+## Real-World Applications
+- Personal task management.
+- Project to-do lists.
+- Quick reminders before they become reminders.
+- Shopping / grocery lists.
+- Bug tracker prototypes for solo projects.
+
+## Educational Value
+- **CRUD operations** on a flat text file.
+- **Defensive UX** — confirmations, validations, friendly errors.
+- **Storage trade-offs** — text vs. JSON vs. SQLite.
+- **Process control** — `sys.exit`, `os.execv`, `time.sleep`.
+
+## Next Steps
+- Add **mark-as-done** (don't delete).
+- Migrate to **JSON storage**.
+- Add **priorities and due dates**.
+- Wrap with a **Tkinter GUI**.
+- Layer **reminders** via [Simple Reminder App](./simplereminderapp).
+- Cross-link with [Todo (basics)](./todo) for the simpler intro.
+
+## Conclusion
+You built a complete CLI todo manager with persistence, CRUD, and confirmation flows — the same architecture used by every text-file-backed productivity tool from `taskwarrior` to early WordPress drafts. Every step beyond (priorities, due dates, GUIs, sync) reuses these primitives. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/todo.py). Explore more productivity projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/urlshorter.mdx b/src/content/docs/projects/Beginners/urlshorter.mdx
index 84620edc..d390f88f 100644
--- a/src/content/docs/projects/Beginners/urlshorter.mdx
+++ b/src/content/docs/projects/Beginners/urlshorter.mdx
@@ -1,6 +1,6 @@
 ---
 title: URL Shortener
-description: A simple URL shortener application using Python that converts long URLs into short, shareable links using the pyshorteners library.
+description: Build a Python URL shortener using pyshorteners (TinyURL, Bitly) and then build your own from scratch with Flask + base62 encoding. Learn third-party APIs, error handling, and how short links actually work.
 sidebar: 
     order: 15
 hero:
@@ -13,149 +13,272 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-URL Shortener is a simple Python application that converts long URLs into short, manageable links using the `pyshorteners` library. The application supports multiple URL shortening services including TinyURL and Bitly. This project demonstrates working with external APIs, URL manipulation, and third-party libraries. Users can input a long URL and receive a shortened version that redirects to the original link, making it perfect for sharing on social media or in constrained spaces.
+A URL shortener compresses a long URL like `https://example.com/very/long/path?query=1&foo=2` into something like `https://tinyurl.com/abc123`. The short link redirects to the original when clicked. In this tutorial you will start by using the **`pyshorteners`** library to talk to existing services (TinyURL, Bitly), then go deeper and build **your own** shortener with Flask, SQLite, and a base62 encoder — the same architecture every commercial shortener uses.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- pyshorteners module
-- Internet connection
+You will learn:
+- How third-party APIs wrap real services.
+- How HTTP redirects work.
+- How short codes are generated and looked up.
+- Why custom shorteners need careful URL validation.
+- How to add analytics (click counts, referrers) and rate limiting.
 
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download). You must have the pyshorteners module installed on your computer. You can install it using the following command:
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- An internet connection (for the third-party portion).
+- Comfort with `pip install` and basic web concepts.
 
-```cmd title="command" showLineNumbers{1} {1}
-C:\Users\Your Name>pip install pyshorteners
+## Install Dependencies
+```cmd title="install"
+pip install pyshorteners
+```
+For the "build your own" section later:
+```cmd title="install"
+pip install flask
 ```
 
-For Bitly integration (optional), you'll need to:
-1. Create a free account at [Bitly](https://bitly.com/)
-2. Get your API key from the Bitly developer dashboard
-3. Replace the placeholder API key in the code
+## Part 1 — Use a Third-Party Service
 
-## Getting Started
-#### Create a Project
+### Getting started
 1. Create a folder named `url-shortener`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `urlshorter.py`.
-4. Copy the given code and paste it in your `urlshorter.py` file.
+2. Inside it, create `urlshorter.py`.
 
-## Write the Code
-1. Copy and paste the following code in your `urlshorter.py` file.
+### Write the code
 <FileCode file="projects/beginners/urlshorter.py" lang="python" title="URL Shortener" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `url-shortener`.
+
+### Run it
 ```cmd title="command" showLineNumbers{1} {1-10}
 C:\Users\Your Name\url-shortener> python urlshorter.py
 Enter URL: https://www.example.com/very/long/url/with/many/parameters?param1=value1&param2=value2
-Short URL:  https://tinyurl.com/abc123def
+Short URL: https://tinyurl.com/abc123def
+```
 
-C:\Users\Your Name\url-shortener> python urlshorter.py
-Enter URL: https://github.com/Ravikisha/PythonCentralHub
-Short URL:  https://tinyurl.com/pythonhub123
+## Step-by-Step Explanation
+
+### 1. Import the library
+```python title="urlshorter.py"
+import pyshorteners
 ```
 
-## Explanation
-1. Import the required module.
-```python title="urlshorter.py" showLineNumbers{1} {1}
-import pyshorteners # pip install pyshorteners
+### 2. Validate and shorten
+```python title="urlshorter.py"
+url = input("Enter URL: ").strip()
+if not (url.startswith("http://") or url.startswith("https://")):
+    raise SystemExit("URL must start with http:// or https://")
+
+shortener = pyshorteners.Shortener()
+short_url = shortener.tinyurl.short(url)
+print("Short URL:", short_url)
 ```
+- TinyURL needs no API key.
+- Bitly does — set up an API token and use `pyshorteners.Shortener(api_key="...")`.
 
-2. Get the URL input from the user.
-```python title="urlshorter.py" showLineNumbers{1} {1}
-url = input("Enter URL: ")
+### 3. Handle network errors
+```python title="urlshorter.py"
+from pyshorteners.exceptions import ShorteningErrorException, ExpandingErrorException
+import requests
+
+try:
+    short_url = shortener.tinyurl.short(url)
+except (ShorteningErrorException, requests.RequestException) as e:
+    print("Could not shorten:", e)
 ```
 
-3. Create a shortener object and generate short URL using TinyURL.
-```python title="urlshorter.py" showLineNumbers{1} {1-3}
-shortener = pyshorteners.Shortener()
-shortURL = shortener.tinyurl.short(url)
+## What `pyshorteners` Supports
+
+| Service | Needs API key? |
+|---|---|
+| TinyURL | No |
+| Is.gd | No |
+| V.gd | No |
+| Clck.ru | No |
+| Chilp.it | No |
+| Bitly | Yes |
+| QR.net | No |
+| Owly | Yes |
+| Cuttly | Yes |
+
+Switching service is just changing the attribute: `shortener.isgd.short(url)`, `shortener.bitly.short(url)`, etc.
+
+## Part 2 — Build Your Own Shortener
+
+Using a service is fine. Building one yourself is far more educational and gives you full control.
+
+### How a real shortener works
+
+1. User submits a long URL.
+2. Server stores `{ short_code → long_url }` in a database.
+3. Server returns `https://short.example.com/<short_code>`.
+4. When that short URL is visited, the server looks up the code and returns an **HTTP 302 redirect** to the long URL.
+
+The short code is usually a base62 (`0-9a-zA-Z`) encoding of an auto-incrementing ID — 6 characters yields ~57 billion possible URLs.
+
+### Code
+```python title="own_shortener.py"
+from flask import Flask, request, redirect, jsonify
+import sqlite3, string, secrets
+
+app = Flask(__name__)
+ALPHABET = string.ascii_letters + string.digits   # 62 characters
+
+def init_db():
+    with sqlite3.connect("urls.db") as db:
+        db.execute("""CREATE TABLE IF NOT EXISTS urls (
+            code TEXT PRIMARY KEY,
+            url  TEXT NOT NULL,
+            clicks INTEGER DEFAULT 0
+        )""")
+
+def new_code(length=6):
+    return "".join(secrets.choice(ALPHABET) for _ in range(length))
+
+@app.post("/shorten")
+def shorten():
+    long_url = request.json["url"].strip()
+    if not long_url.startswith(("http://", "https://")):
+        return jsonify(error="URL must include http:// or https://"), 400
+    with sqlite3.connect("urls.db") as db:
+        # generate codes until one is unique
+        while True:
+            code = new_code()
+            try:
+                db.execute("INSERT INTO urls(code, url) VALUES(?, ?)",
+                           (code, long_url))
+                break
+            except sqlite3.IntegrityError:
+                continue
+    return jsonify(short=f"{request.host_url}{code}")
+
+@app.get("/<code>")
+def follow(code):
+    with sqlite3.connect("urls.db") as db:
+        row = db.execute("SELECT url FROM urls WHERE code=?", (code,)).fetchone()
+        if not row:
+            return "Not found", 404
+        db.execute("UPDATE urls SET clicks = clicks + 1 WHERE code=?", (code,))
+    return redirect(row[0], code=302)
+
+if __name__ == "__main__":
+    init_db()
+    app.run(debug=True)
+```
+
+Test it:
+```bash title="test"
+curl -X POST http://localhost:5000/shorten -H "Content-Type: application/json" \
+     -d '{"url":"https://python.org"}'
+# {"short":"http://localhost:5000/aB3xY9"}
+
+curl -I http://localhost:5000/aB3xY9
+# HTTP/1.1 302 FOUND
+# Location: https://python.org
 ```
 
-4. Alternative Bitly implementation (commented out).
-```python title="urlshorter.py" showLineNumbers{1} {1-3}
-# bitlyShortener = pyshorteners.Shortener(api_key='your_api_key_here')
-# shortURL = bitlyShortener.bitly.short(url)
+### Why base62
+
+- **62 chars** (`0–9 a–z A–Z`) is URL-safe and case-sensitive.
+- 6 characters = `62 ** 6 ≈ 57 billion` possible short URLs.
+- 8 characters = `218 trillion`. Plenty.
+
+Some shorteners use a **counter** (auto-increment ID) encoded as base62, which guarantees uniqueness without retries.
+
+## Validating URLs Properly
+
+User input is a frequent vector for **open-redirect** attacks. Validate:
+
+```python title="validate.py"
+from urllib.parse import urlparse
+
+def is_valid_url(u: str) -> bool:
+    try:
+        p = urlparse(u)
+        return p.scheme in {"http", "https"} and bool(p.netloc) and "." in p.netloc
+    except Exception:
+        return False
 ```
+Reject `javascript:`, `data:`, `file:` schemes — they would let an attacker craft phishing-style short links.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `pyshorteners.exceptions.ShorteningErrorException` | Provider down, malformed URL, rate-limited | Catch and retry/back off |
+| Same short code generated for two URLs | Did not check uniqueness | `INSERT` with `PRIMARY KEY` on code → catch `IntegrityError` |
+| Redirect goes nowhere | Returned a 200 with the URL in the body | Return `redirect(url, code=302)` |
+| Open redirect to `javascript:` | No URL validation | Whitelist `http/https` schemes only |
+| Database lock errors | SQLite with concurrent writers | Use a real DB (Postgres) for multi-process deployments |
+
+## Variations to Try
 
-5. Display the shortened URL.
-```python title="urlshorter.py" showLineNumbers{1} {1}
-print("Short URL: ", shortURL)
+### 1. Custom aliases
+Let the user request `/mylink` instead of a random code:
+```python title="alias.py"
+alias = request.json.get("alias")
+if alias and not db.execute("SELECT 1 FROM urls WHERE code=?", (alias,)).fetchone():
+    code = alias
 ```
 
-## Supported Services
-This URL shortener supports multiple services:
-
-### TinyURL (Default)
-- **Pros:** No API key required, simple to use
-- **Cons:** Limited customization options
-- **Usage:** Included in the default code
-
-### Bitly
-- **Pros:** Custom short URLs, analytics, branded links
-- **Cons:** Requires API key registration
-- **Usage:** Uncomment the Bitly section and add your API key
-
-### Other Supported Services
-The `pyshorteners` library also supports:
-- Is.gd
-- V.gd
-- QR.net
-- Chilp.it
-- Clck.ru
-- And many more!
-
-## Features
-- Convert long URLs to short, shareable links
-- Support for multiple URL shortening services
-- Simple command-line interface
-- No database required
-- Instant URL conversion
-- Works with any valid HTTP/HTTPS URL
-- Cross-platform compatibility
-
-## How to Use
-1. Run the application
-2. Enter the long URL you want to shorten
-3. Press Enter to get the shortened URL
-4. Copy and share the short URL
-5. The short URL will redirect to the original long URL when clicked
-
-## API Key Setup (For Bitly)
-To use Bitly services:
-1. Visit [Bitly Developer](https://dev.bitly.com/)
-2. Create a free account
-3. Generate an API access token
-4. Replace `'your_api_key_here'` with your actual API key
-5. Uncomment the Bitly code section
+### 2. Expiration dates
+Add `expires_at TIMESTAMP NULL`. On follow, return 410 Gone if expired.
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Creating a web application using Flask
-- Implementing URL validation
-- Adding custom short URL aliases
-- Creating a URL history database
-- Adding QR code generation for short URLs
-- Implementing click analytics
-- Adding bulk URL shortening
-- Creating browser extension integration
-
-## Error Handling
-Consider adding error handling for:
-- Invalid URLs
-- Network connectivity issues
-- API rate limits
-- Service unavailability
-
-Example enhanced version:
-```python title="urlshorter.py" showLineNumbers{1}
-try:
-    shortURL = shortener.tinyurl.short(url)
-    print("Short URL: ", shortURL)
-except Exception as e:
-    print("Error creating short URL:", str(e))
+### 3. Click analytics
+You already store `clicks`. Add a `/stats/<code>` endpoint that returns total clicks plus, optionally, referrer breakdown.
+
+### 4. QR code
+```python title="qr.py"
+import qrcode
+img = qrcode.make(short_url)
+img.save("link.png")
 ```
 
+### 5. Password-protected links
+Add a `password_hash` column. Before redirecting, require the user to enter a password.
+
+### 6. Bulk shortening
+Accept a list of URLs and return short versions in one call.
+
+### 7. Rate limiting
+Use `flask-limiter` to cap to e.g. 10 requests/minute per IP.
+
+### 8. Domain restrictions
+Allow shortening only for specific domains — useful for company-internal use.
+
+### 9. CLI
+Wrap the API client with `argparse`:
+```bash title="cli"
+python shorten.py https://example.com --alias homepage
+```
+
+### 10. Deployment
+Run behind **gunicorn** + **nginx**, point a domain like `short.example.com` at it, and you have your own production shortener for ~$5/month.
+
+## Privacy and Security Notes
+
+- **Short URLs are public.** Anyone who guesses the code can follow the link. Do not embed sensitive paths.
+- **Phishing risk.** Short links hide their destination — bad actors abuse this. Consider a preview page (`/p/<code>`) that shows the destination before redirecting.
+- **Log retention.** Server access logs reveal who clicked what. Decide your retention policy.
+- **Open-redirect** is the classic shortener vulnerability — validate schemes carefully.
+
+## Real-World Applications
+- Social-media sharing (Twitter character limits used to drive this).
+- Email and SMS marketing — short, trackable URLs.
+- QR codes that point to a short URL you can rebind later.
+- Branded short links (e.g., `nyti.ms` for the New York Times).
+- Internal tooling — share links to dashboards without copying 200-character URLs.
+
+## Educational Value
+- **Third-party APIs** — calling, error handling, swap-ability.
+- **HTTP redirects** — status codes and what they mean.
+- **Encoding schemes** — base62 versus base64 versus hex.
+- **Database integrity** — unique constraints and how to handle collisions.
+- **Web security basics** — open redirect, input validation, abuse vectors.
+
+## Next Steps
+- Build the **Flask version** above; deploy it somewhere free (Render, Fly.io).
+- Add **analytics** with referrers, country (via MaxMind GeoIP), and time series.
+- Add a **web frontend** with a form and a copy-to-clipboard button.
+- Add **authentication** so each user only sees their own links.
+- Layer on **rate limiting** and **captcha** before opening to the public.
+
 ## Conclusion
-In this project, we learned how to create a URL Shortener using Python and the `pyshorteners` library. We explored working with external APIs, URL manipulation, and third-party service integration. This project demonstrates how to leverage existing services to create useful applications quickly and efficiently. The skills learned here can be applied to other API-based projects and web service integrations. To find more projects like this, you can visit Python Central Hub.
+You used a third-party shortener and learned how the *actual* underlying mechanism works — a database lookup and an HTTP 302. Building your own version is one of the most concise demonstrations of how the modern web composes simple parts into useful services. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/urlshorter.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/webpagecontentdownloader.mdx b/src/content/docs/projects/Beginners/webpagecontentdownloader.mdx
index 91a21ca0..14626d6d 100644
--- a/src/content/docs/projects/Beginners/webpagecontentdownloader.mdx
+++ b/src/content/docs/projects/Beginners/webpagecontentdownloader.mdx
@@ -1,6 +1,6 @@
 ---
 title: Web Page Content Downloader
-description: A simple Python application that downloads and saves web page content to a local file using urllib library for web scraping and content extraction.
+description: Build a Python tool that downloads web page content, handles encoding, redirects, retries, large files, and produces clean local mirrors. Learn urllib vs requests, streaming, and ethical archiving.
 sidebar: 
     order: 11
 hero:
@@ -13,218 +13,235 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Web Page Content Downloader is a simple Python application that fetches and saves the HTML content of web pages to local files. Using Python's built-in `urllib` library, this program demonstrates basic web scraping concepts, HTTP requests, and file handling. Users can input any URL and specify a filename to save the web page's source code locally. This project is an excellent introduction to web data extraction and provides the foundation for more advanced web scraping applications.
+Saving a web page to disk is the simplest "real" web project: one HTTP request, one file write. But the gap between "works on `example.com`" and "works on any URL" hides every web-programming concept in one place — encoding, redirects, retries, timeouts, errors, streaming large files, and politeness toward servers. In this tutorial you build the trivial 3-line version with `urllib`, then evolve to a robust downloader using `requests`, streaming for large responses, retry policies, progress bars, and a mirror mode that downloads HTML plus its referenced assets.
+
+You will leave understanding:
+- The HTTP request/response cycle.
+- Why default `urllib` is fine for toys and `requests` is the standard for real code.
+- How content encoding (`gzip`, `br`), character encoding, and redirects all bite naïve scripts.
+- How to stream large responses without loading them into memory.
+- The ethics and legality of downloading — robots.txt, rate limits, copyright.
 
 ## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- Internet connection
-
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
-
-Note: This project uses only built-in Python modules (`urllib`), so no additional installations are required.
-
-## Getting Started
-#### Create a Project
-1. Create a folder named `web-content-downloader`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `webpagecontentdownloader.py`.
-4. Copy the given code and paste it in your `webpagecontentdownloader.py` file.
-
-## Write the Code
-1. Copy and paste the following code in your `webpagecontentdownloader.py` file.
-<FileCode file="projects/beginners/webpagecontentdownloader.py" lang="python" title="Web Page Content Downloader" />
-2. Save the file.
-3. Open the terminal in your code editor or IDE and navigate to the folder `web-content-downloader`.
-```cmd title="command" showLineNumbers{1} {1-10}
+- Python 3.6 or above.
+- A text editor or IDE.
+- Internet connection.
+- Comfort with file I/O.
+
+## Part 1 — The Trivial Version
+
+`urllib` ships with Python so no install is needed.
+
+### Create the project
+1. Create folder `web-content-downloader`.
+2. Inside, create `webpagecontentdownloader.py`.
+
+### Write the code
+<FileCode file="projects/beginners/webpagecontentdownloader.py" lang="python" title="Web Page Downloader" />
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\web-content-downloader> python webpagecontentdownloader.py
 Enter the URL: https://www.example.com
 Enter the file name: example.html
-# The program will download the web page content and save it to example.html
-
-C:\Users\Your Name\web-content-downloader> python webpagecontentdownloader.py
-Enter the URL: https://www.python.org
-Enter the file name: python_homepage.html
-# The content of python.org will be saved to python_homepage.html
+# Page content saved to example.html
 ```
 
-## Explanation
+## Step-by-Step Explanation (Trivial Version)
 
-### Code Breakdown
-1. **Import the required urllib modules.**
-```python title="webpagecontentdownloader.py" showLineNumbers{1} {1}
-import urllib.request, urllib.error, urllib.parse
-```
-
-2. **Get user input for URL and filename.**
-```python title="webpagecontentdownloader.py" showLineNumbers{1} {1-2}
-url = input('Enter the URL: ')
-fileName = input('Enter the file name: ')
-```
+```python title="trivial.py"
+import urllib.request
 
-3. **Make HTTP request and read the response.**
-```python title="webpagecontentdownloader.py" showLineNumbers{1} {1-2}
+url = input("URL: ")
+filename = input("Filename: ")
 response = urllib.request.urlopen(url)
-webContent = response.read().decode('utf-8')
+data = response.read().decode("utf-8")
+with open(filename, "w", encoding="utf-8") as f:
+    f.write(data)
 ```
+- `urlopen` sends a `GET` and returns a file-like object.
+- `read()` slurps the **entire response** into memory.
+- `.decode("utf-8")` turns the bytes into a Python string — **fails for non-UTF-8 pages**, which is most of the legacy web.
+
+This version works only when the URL is reachable, the page is UTF-8, smaller than your RAM, and does not redirect.
 
-4. **Save the content to a local file.**
-```python title="webpagecontentdownloader.py" showLineNumbers{1} {1-3}
-f = open(fileName, 'w')
-f.write(webContent)
-f.close()
+## Part 2 — Robust Version with `requests`
+
+```bash title="install"
+pip install requests
 ```
 
-### How It Works
-1. **URL Input:** User provides the web page URL to download
-2. **HTTP Request:** Program sends a GET request to the specified URL
-3. **Content Retrieval:** Server responds with the web page's HTML content
-4. **Decoding:** Raw bytes are decoded to UTF-8 text format
-5. **File Saving:** Content is written to a user-specified local file
-
-## Features
-- **Simple Interface:** Easy-to-use command-line input
-- **Universal URL Support:** Works with any accessible web page
-- **Custom File Naming:** User specifies the output filename
-- **UTF-8 Encoding:** Properly handles various character sets
-- **Built-in Libraries:** Uses only Python standard library
-- **Lightweight:** Minimal code for maximum functionality
-
-## urllib Library Components
-
-### urllib.request
-- **urlopen():** Opens URLs and returns response objects
-- **Request handling:** Manages HTTP requests
-
-### urllib.error
-- **Exception handling:** Manages URL-related errors
-- **Error types:** HTTPError, URLError
-
-### urllib.parse
-- **URL parsing:** Breaks down URL components
-- **URL encoding:** Handles special characters
-
-## Common Use Cases
-- **Website Backup:** Save local copies of web pages
-- **Content Analysis:** Analyze HTML structure and content
-- **Web Development:** Study other websites' source code
-- **Research:** Collect web data for analysis
-- **Offline Reading:** Download content for offline access
-
-## Sample Downloaded Content
-When you download a web page, you'll get the raw HTML:
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Example Domain</title>
-    <meta charset="utf-8" />
-    <!-- CSS and meta tags -->
-</head>
-<body>
-    <div>
-        <h1>Example Domain</h1>
-        <p>This domain is for use in illustrative examples...</p>
-    </div>
-</body>
-</html>
+```python title="robust.py"
+import requests, sys
+from urllib.parse import urlparse
+
+def download(url: str, filename: str | None = None) -> str:
+    if not url.startswith(("http://", "https://")):
+        url = "https://" + url
+    try:
+        r = requests.get(url, timeout=30, headers={"User-Agent": "PCH-Downloader/1.0"})
+        r.raise_for_status()
+    except requests.HTTPError as e:
+        print(f"HTTP {e.response.status_code}: {e.response.reason}")
+        sys.exit(1)
+    except requests.RequestException as e:
+        print(f"Network error: {e}")
+        sys.exit(1)
+
+    filename = filename or (urlparse(url).path.rsplit("/", 1)[-1] or "page.html")
+    encoding = r.encoding or r.apparent_encoding or "utf-8"
+    with open(filename, "w", encoding=encoding) as f:
+        f.write(r.text)
+    print(f"Saved {len(r.text):,} chars to {filename}")
+    return filename
+```
+What this fixes:
+- **Custom User-Agent.** Default `python-requests/...` is widely blocked.
+- **Timeout.** No hanging on slow servers.
+- **`raise_for_status()`** turns 4xx/5xx into exceptions.
+- **`r.encoding` + `r.apparent_encoding`.** First trusts the server's `Content-Type` header; falls back to `chardet`-based guess.
+- **URL auto-completion.** `example.com` → `https://example.com`.
+- **Smart filename.** Derives from URL path if not provided.
+
+## Stream Large Files
+
+`requests.get(...).text` loads everything into RAM. For PDFs, ZIPs, or images, **stream** instead:
+```python title="stream.py"
+def download_large(url: str, filename: str, chunk: int = 8192):
+    with requests.get(url, stream=True, timeout=30) as r:
+        r.raise_for_status()
+        total = int(r.headers.get("Content-Length", 0))
+        done = 0
+        with open(filename, "wb") as f:
+            for piece in r.iter_content(chunk_size=chunk):
+                if not piece: continue
+                f.write(piece)
+                done += len(piece)
+                if total:
+                    pct = done * 100 // total
+                    print(f"\r{pct}%  ({done:,}/{total:,} bytes)", end="", flush=True)
+        print()
+```
+`stream=True` defers the body download. `iter_content` yields it in chunks so memory stays flat regardless of file size.
+
+For a real progress bar, use **`tqdm`**:
+```python title="tqdm.py"
+from tqdm import tqdm
+with requests.get(url, stream=True) as r, open(filename, "wb") as f:
+    bar = tqdm(total=int(r.headers["Content-Length"]), unit="B", unit_scale=True)
+    for chunk in r.iter_content(8192):
+        f.write(chunk); bar.update(len(chunk))
+    bar.close()
 ```
 
-## Error Handling Considerations
-The current implementation is basic. Consider adding error handling for:
-- Invalid URLs
-- Network connectivity issues
-- Permission denied errors
-- Encoding problems
+## Retries with Back-off
 
-## Enhanced Version with Error Handling
-```python title="webpagecontentdownloader.py" showLineNumbers{1}
-import urllib.request, urllib.error, urllib.parse
+Transient errors (5xx, network blips) should retry; permanent ones (404) should not:
+```python title="retry.py"
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
 
-def download_webpage():
-    try:
-        url = input('Enter the URL: ')
-        fileName = input('Enter the file name: ')
-        
-        # Validate URL format
-        if not url.startswith(('http://', 'https://')):
-            url = 'https://' + url
-        
-        response = urllib.request.urlopen(url)
-        webContent = response.read().decode('utf-8')
-        
-        with open(fileName, 'w', encoding='utf-8') as f:
-            f.write(webContent)
-        
-        print(f"Successfully downloaded content to {fileName}")
-        
-    except urllib.error.HTTPError as e:
-        print(f"HTTP Error: {e.code} - {e.reason}")
-    except urllib.error.URLError as e:
-        print(f"URL Error: {e.reason}")
-    except Exception as e:
-        print(f"An error occurred: {e}")
+retry = Retry(total=5, backoff_factor=1,
+              status_forcelist=[502, 503, 504], allowed_methods=["GET"])
+adapter = HTTPAdapter(max_retries=retry)
+session = requests.Session()
+session.mount("https://", adapter)
+session.mount("http://", adapter)
+r = session.get(url, timeout=30)
+```
+`backoff_factor=1` means waits of 1, 2, 4, 8, 16 seconds between retries.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `UnicodeDecodeError` | Forced `utf-8` on non-UTF-8 page | Use `r.encoding` / `r.apparent_encoding` |
+| 403 Forbidden | Default User-Agent blocked | Send a real header |
+| Hangs indefinitely | No timeout | `timeout=30` |
+| MemoryError on 4 GB ZIP | `r.text` loads everything | `stream=True` + `iter_content` |
+| File not saved cross-platform | `\` in filename | Use `urllib.parse.quote` or `Path` |
+| Directory traversal | User-supplied filename `"../../etc/passwd"` | Sanitize with `os.path.basename` |
+
+## Variations to Try
+
+### 1. Mirror mode
+Pull the HTML, parse with BeautifulSoup, then download every `<img>`, `<script>`, `<link rel=stylesheet>` and rewrite the HTML to point at the local copies. Result: a fully self-contained `index.html` plus an `assets/` folder.
+
+### 2. Recursive crawl
+Follow internal `<a>` links up to depth N. See [Basic Web Crawler](./basicwebcrawler) for the proper queue + visited-set pattern.
+
+### 3. Authentication
+`requests.get(url, auth=("user", "pass"))` for HTTP Basic; or use session cookies for login forms.
+
+### 4. Robots.txt compliance
+Use `urllib.robotparser` to honor crawl directives before downloading:
+```python title="robots.py"
+from urllib.robotparser import RobotFileParser
+rp = RobotFileParser()
+rp.set_url(urlparse(url)._replace(path="/robots.txt").geturl())
+rp.read()
+if not rp.can_fetch("PCH-Downloader/1.0", url):
+    print("robots.txt forbids this URL"); return
 ```
 
-## Next Steps
-You can enhance this project by:
-- Adding error handling and validation
-- Supporting different file formats (PDF, images, etc.)
-- Implementing progress bars for large downloads
-- Adding batch URL processing
-- Creating a GUI version using Tkinter
-- Adding website authentication support
-- Implementing download resume functionality
-- Adding content filtering and parsing
-- Creating automated scheduling for downloads
-- Adding compression for downloaded files
-
-## Legal and Ethical Considerations
-- **Respect robots.txt:** Check website's robot exclusion protocol
-- **Rate Limiting:** Don't overwhelm servers with requests
-- **Copyright:** Respect intellectual property rights
-- **Terms of Service:** Follow website usage policies
-- **Personal Use:** Ensure downloads are for legitimate purposes
-
-## Advanced Features Ideas
-```python title="webpagecontentdownloader.py" showLineNumbers{1}
-def advanced_downloader():
-    # Features to implement:
-    # - Multiple file format support
-    # - Recursive website downloading
-    # - Content filtering by tags
-    # - Download progress tracking
-    # - Automatic file organization
-    pass
+### 5. JSON-aware mode
+If `Content-Type` is `application/json`, pretty-print with `json.dumps(r.json(), indent=2)`.
+
+### 6. PDF extraction
+`pip install pypdf`. After download, extract text and save side-by-side as `.txt`.
+
+### 7. Headless browser
+Some pages are JavaScript-rendered and arrive empty via `requests`. Switch to **Playwright** to get the rendered DOM.
+
+### 8. Resume support
+For broken downloads, use HTTP `Range` headers:
+```python title="resume.py"
+existing = os.path.getsize(filename) if os.path.exists(filename) else 0
+r = requests.get(url, headers={"Range": f"bytes={existing}-"}, stream=True)
+mode = "ab" if r.status_code == 206 else "wb"
 ```
 
+### 9. Batch from a file
+Read URLs from `urls.txt` and download all (with rate limiting).
+
+### 10. GUI version
+Tkinter window with URL entry, save-as button, and progress bar. See [Currency Exchange Rate Calculator GUI](./currencyexchnageratecalculator) for the pattern.
+
+## Ethical & Legal Notes
+
+- **Read the ToS.** Many sites forbid bulk downloading.
+- **Respect `robots.txt`.** It is the standard signal.
+- **Identify yourself** with a real `User-Agent` plus contact info.
+- **Rate-limit aggressively** when crawling many pages — 1 request per second is friendly.
+- **Copyright applies** to downloaded content; for personal study most uses are fine, redistribution is not.
+- **Never bypass paywalls** or login walls without explicit permission.
+
 ## Security Considerations
-- **URL Validation:** Verify URLs before downloading
-- **File Path Safety:** Prevent directory traversal attacks
-- **Content Scanning:** Check for malicious content
-- **HTTPS Preference:** Use secure connections when possible
+- **Validate URLs** — refuse `file:`, `javascript:`, `data:` schemes if users supply URLs.
+- **Sanitize filenames** with `os.path.basename` to block directory traversal.
+- **Scan downloaded executables** before running them — `requests` does not check for malware.
+- **Pin TLS** for sensitive endpoints with `verify=` and a CA bundle.
+
+## Real-World Applications
+- Personal-page archive ("save for offline reading").
+- Migration tools — copying content from a CMS to a static site.
+- SEO audits — pull pages locally for parsing.
+- Dataset construction for ML — but check licenses.
+- One-off data extraction for research.
 
 ## Educational Value
-This project teaches:
-- **HTTP Requests:** Understanding web communication
-- **File I/O:** Reading from web and writing to files
-- **Text Encoding:** Handling different character sets
-- **Error Handling:** Managing network-related exceptions
-- **Web Scraping Basics:** Foundation for data extraction
-
-## Performance Considerations
-- **Memory Usage:** Large pages may consume significant memory
-- **Network Speed:** Download time depends on content size and connection
-- **File Size:** Consider compression for large downloads
-- **Timeout Settings:** Handle slow or unresponsive servers
+- **HTTP fundamentals** — GET, status codes, headers.
+- **Encoding awareness** — content vs. character encoding.
+- **Streaming** — when memory is finite and the file is not.
+- **Error taxonomy** — `HTTPError`, `Timeout`, `ConnectionError` mean different things.
+- **Politeness** — the principle that scales when you scale up.
 
-## Real-World Applications
-- **Data Collection:** Gather information for research
-- **Website Monitoring:** Track changes in web content
-- **Content Archiving:** Create backups of important pages
-- **SEO Analysis:** Study competitor websites
-- **Development Tools:** Download resources for local development
+## Next Steps
+- Replace **`urllib` → `requests`** for everything.
+- Add **streaming + progress bar**.
+- Add **retries with exponential backoff**.
+- Build the **mirror mode** that downloads referenced assets.
+- Compare with [Basic Web Crawler](./basicwebcrawler) for multi-page traversal.
 
 ## Conclusion
-In this project, we learned how to create a Web Page Content Downloader using Python's built-in urllib library. We explored fundamental web scraping concepts, HTTP requests, and file handling. This simple yet powerful tool demonstrates how to interact with web servers and save content locally. The project provides an excellent foundation for more advanced web scraping and data collection applications. Understanding these concepts is essential for web development, data analysis, and automation tasks. To find more projects like this, you can visit Python Central Hub.
+You upgraded a trivial download script into a robust, polite, streaming, resumable, retrying downloader. Every web-aware program you ever write reuses these patterns — fail safely, respect the server, never load more than you need. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/webpagecontentdownloader.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/webpagescrapernotifications.mdx b/src/content/docs/projects/Beginners/webpagescrapernotifications.mdx
index 7c46243c..15b718e9 100644
--- a/src/content/docs/projects/Beginners/webpagescrapernotifications.mdx
+++ b/src/content/docs/projects/Beginners/webpagescrapernotifications.mdx
@@ -1,6 +1,6 @@
 ---
 title: Web Page Scraper with Notifications
-description: Monitor web pages for changes and receive notifications via email or desktop alerts
+description: Build a Python monitor that watches a web page for changes and alerts you via desktop, email, Slack, or Discord. Learn hashing, scheduling, SMTP, webhooks, and how to make a polite content tracker.
 sidebar:
   order: 53
 hero:
@@ -14,164 +14,273 @@ import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
 
-Build an automated web page monitoring system that scrapes websites for content changes and sends notifications through multiple channels including email and desktop alerts. This project demonstrates web scraping, automation, content comparison, and notification systems.
+Some sites change rarely but matter when they do — a course catalog opens new spots, a product comes back in stock, a status page goes red, a government form gets a new revision. In this project you build an automated watcher that fetches a URL on a schedule, compares the content to the last fetch using an MD5 hash, and **pings you** when something changes through one or more channels: desktop notification, email, Slack webhook, or Discord webhook.
 
-## Prerequisites
+You will learn:
+- How to detect change cheaply with **content hashing**.
+- How to scope monitoring to a single CSS selector instead of the whole page.
+- How to send notifications via four different channels.
+- How to schedule recurring jobs with the `schedule` library.
+- How to design a polite watcher that does not get banned.
 
-- Basic understanding of Python syntax
-- Knowledge of web scraping concepts
-- Familiarity with HTTP requests and HTML parsing
-- Understanding of email protocols and SMTP
-- Basic knowledge of scheduling and automation
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- An internet connection.
+- (Optional) An SMTP account (Gmail app password works) and/or a Slack/Discord webhook URL.
+
+## Install Dependencies
+```bash title="install"
+pip install requests beautifulsoup4 schedule plyer
+```
+- **`requests`** — fetch the page.
+- **`beautifulsoup4`** — extract content from HTML.
+- **`schedule`** — run a job every N minutes.
+- **`plyer`** — cross-platform desktop notifications.
 
 ## Getting Started
 
+### Create the project
+1. Create folder `webpage-monitor`.
+2. Inside, create `webpagescrapernotifications.py`.
 
+### Write the code
+<FileCode file="projects/beginners/webpagescrapernotifications.py" lang="python" title="Web Page Monitor" />
 
-1. **Install Required Dependencies**
-   ```bash
-   pip install requests beautifulsoup4 schedule plyer
-   ```
-
-2. **Configure Email Settings (Optional)**
-   - Set up Gmail app password for notifications
-   - Update email configuration in the script
-   - Test email functionality
-
-3. **Run the Web Page Monitor**
-   ```bash
-   python webpagescrapernotifications.py
-   ```
-
-4. **Customize Monitoring**
-   - Change the URL to monitor your desired website
-   - Adjust checking intervals (default: 30 minutes)
-   - Configure notification preferences
+### Run it
+```bash title="run"
+python webpagescrapernotifications.py
+```
+The script polls the target URL every 30 minutes (by default), hashes the content, and notifies you when the hash changes from the previous run.
 
+## Step-by-Step Explanation
 
+### 1. Class skeleton
+```python title="webpagescrapernotifications.py"
+import hashlib, time, smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+import requests
+from bs4 import BeautifulSoup
+import schedule
 
-## Code Explanation
+class WebPageMonitor:
+    def __init__(self, url, selector=None, email_config=None):
+        self.url = url
+        self.selector = selector              # optional CSS selector to scope changes
+        self.email_config = email_config
+        self.previous_hash = None
+```
 
-### Web Page Content Extraction
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
+### 2. Fetch and extract content
+```python title="webpagescrapernotifications.py"
 def get_page_content(self):
-    response = requests.get(self.url)
+    response = requests.get(self.url, timeout=15, headers={
+        "User-Agent": "WebPageMonitor/1.0 (+you@example.com)"
+    })
     response.raise_for_status()
-    soup = BeautifulSoup(response.content, 'html.parser')
-    content = soup.get_text().strip()
-    return content
+    soup = BeautifulSoup(response.content, "html.parser")
+    if self.selector:
+        node = soup.select_one(self.selector)
+        if node is None:
+            raise ValueError(f"Selector '{self.selector}' not found")
+        return node.get_text(separator=" ", strip=True)
+    return soup.get_text(separator=" ", strip=True)
 ```
+- A custom `User-Agent` identifies the bot — many sites block default Python requests.
+- `selector` lets you watch only the relevant part of the page. Without it, every footer copyright year change triggers an alert.
 
-Uses BeautifulSoup to parse HTML and extract text content for comparison detection.
-
-### Content Change Detection
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
-def get_content_hash(self, content):
-    return hashlib.md5(content.encode()).hexdigest()
+### 3. Hash to detect change
+```python title="webpagescrapernotifications.py"
+def get_hash(self, content):
+    return hashlib.md5(content.encode("utf-8")).hexdigest()
+```
+MD5 is **not** secure for cryptography but is perfect for change detection — it is fast and the input is not adversarial.
 
+### 4. The check
+```python title="webpagescrapernotifications.py"
 def check_for_changes(self):
-    current_content = self.get_page_content()
-    current_hash = self.get_content_hash(current_content)
-    
-    if current_hash != self.previous_content:
-        print("Content change detected!")
+    try:
+        content = self.get_page_content()
+    except Exception as e:
+        print(f"[error] {e}")
+        return
+    current_hash = self.get_hash(content)
+    if self.previous_hash is None:
+        self.previous_hash = current_hash
+        print("First check — baseline recorded.")
+        return
+    if current_hash != self.previous_hash:
+        print("Change detected!")
+        self.notify("Page changed", f"Content hash changed for {self.url}")
+        self.previous_hash = current_hash
+    else:
+        print("No change.")
 ```
+Notice we **do not** alert on the first check — that would always fire on startup. We only alert on transitions.
 
-Generates MD5 hashes of page content to efficiently detect any changes without storing full content.
-
-### Email Notification System
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
-def send_notification_email(self, subject, message):
+### 5. Email notification
+```python title="webpagescrapernotifications.py"
+def send_email(self, subject, body):
+    cfg = self.email_config
     msg = MIMEMultipart()
-    msg['From'] = self.email_config['from_email']
-    msg['To'] = self.email_config['to_email']
-    msg['Subject'] = subject
-    
-    server = smtplib.SMTP(self.email_config['smtp_server'], self.email_config['smtp_port'])
-    server.starttls()
-    server.login(self.email_config['from_email'], self.email_config['password'])
-    server.sendmail(self.email_config['from_email'], self.email_config['to_email'], text)
+    msg["From"] = cfg["from_email"]
+    msg["To"] = cfg["to_email"]
+    msg["Subject"] = subject
+    msg.attach(MIMEText(body, "plain"))
+    with smtplib.SMTP(cfg["smtp_server"], cfg["smtp_port"]) as server:
+        server.starttls()
+        server.login(cfg["from_email"], cfg["password"])
+        server.send_message(msg)
 ```
-
-Implements SMTP email sending with proper authentication and formatting for change notifications.
-
-### Desktop Notification Integration
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
-def send_desktop_notification(self, title, message):
-    import plyer
-    plyer.notification.notify(
-        title=title,
-        message=message,
-        timeout=10
-    )
+For Gmail:
+- `smtp_server = "smtp.gmail.com"`, `smtp_port = 587`.
+- Use an **App Password** (Google Account → Security → 2-Step Verification → App passwords), **not** your real Gmail password.
+
+### 6. Desktop notification
+```python title="webpagescrapernotifications.py"
+def send_desktop(self, title, message):
+    from plyer import notification
+    notification.notify(title=title, message=message, timeout=10)
 ```
+Works on Windows, macOS, and many Linux desktops via `notify-send`.
 
-Provides cross-platform desktop notifications using the plyer library for immediate alerts.
-
-### Automated Scheduling
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
-def start_monitoring(self, interval_minutes=30):
+### 7. Schedule the job
+```python title="webpagescrapernotifications.py"
+def start(self, interval_minutes=30):
     schedule.every(interval_minutes).minutes.do(self.check_for_changes)
-    
+    print(f"Monitoring {self.url} every {interval_minutes} minutes. Ctrl+C to stop.")
     while True:
         schedule.run_pending()
         time.sleep(1)
 ```
+`schedule.every().X.minutes.do(fn)` registers a recurring job. The `while True` loop is the "tick" — it wakes up every second to see if any jobs are due.
 
-Implements continuous monitoring with configurable intervals using the schedule library.
+## Webhook Notifications (Slack / Discord)
 
-### Object-Oriented Architecture
-```python title="webpagescrapernotifications.py" showLineNumbers{1}
-class WebPageMonitor:
-    def __init__(self, url, email_config=None):
-        self.url = url
-        self.email_config = email_config
-        self.previous_content = None
+Webhooks are the easiest cross-team alert channel. Create one in your workspace settings, then:
+
+```python title="slack.py"
+def send_slack(self, text):
+    requests.post(self.slack_webhook_url, json={"text": text}, timeout=10)
+
+def send_discord(self, text):
+    requests.post(self.discord_webhook_url, json={"content": text}, timeout=10)
 ```
+A single line carries the alert — no SMTP setup, no app passwords.
+
+## Smarter Change Detection
 
-Uses class-based design for better organization and state management across monitoring sessions.
+Plain hashes flag any change — even a refreshed CSRF token. Strategies to reduce noise:
 
-## Features
+1. **Scope with a CSS selector.** Watch only `#main-content`, not the whole page.
+2. **Strip noisy elements before hashing:**
+   ```python title="strip.py"
+   for tag in soup.select("script, style, .ads, .timestamp"): tag.decompose()
+   ```
+3. **Diff instead of hash.** When the hash changes, compute a unified diff to *show* what changed:
+   ```python title="diff.py"
+   import difflib
+   diff = "\n".join(difflib.unified_diff(
+       old.splitlines(), new.splitlines(), lineterm=""))[:1500]
+   self.notify("Page changed", diff)
+   ```
+4. **Threshold-based.** Ignore changes under N characters using `difflib.SequenceMatcher.ratio()`.
+
+## Polite Scraping Checklist
+
+Before pointing this at a production site:
+- **Respect `robots.txt`.** Use `urllib.robotparser` to check before fetching.
+- **Set a real `User-Agent`** including contact info.
+- **Use a reasonable interval.** 30 minutes is friendly; 30 seconds is hostile.
+- **Honor rate limits.** Back off on 429 responses.
+- **Read the Terms of Service.** Some sites explicitly forbid automated monitoring.
+- **Stop immediately** if asked.
+
+A monitor that hammers a small site at 1 Hz can take it offline. Be a good citizen.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Always fires on startup | Compared against `None` | Skip the first iteration; record baseline only |
+| Email login fails | Used real password on Gmail | Generate an **App Password** |
+| 403 Forbidden | Default Python User-Agent | Set a real header |
+| Notifications fire constantly | Hashing the whole page including timestamps | Scope with a selector or strip dynamic elements |
+| Crash freezes loop | Network error inside the job | Wrap the job body in `try/except` |
+| Process killed when terminal closes | Run as a foreground process | Use `nohup`, `tmux`, `systemd`, or run as a Windows service |
+
+## Variations to Try
+
+### 1. Multiple URLs at once
+```python title="multi.py"
+sites = [WebPageMonitor(u) for u in URL_LIST]
+for s in sites:
+    schedule.every(30).minutes.do(s.check_for_changes)
+```
 
-- **Automated Web Scraping**: Continuously monitors specified web pages
-- **Change Detection**: Uses content hashing for efficient change identification
-- **Multiple Notification Channels**: Supports email and desktop notifications
-- **Configurable Intervals**: Customizable monitoring frequency
-- **Error Handling**: Robust handling of network and parsing errors
-- **Cross-Platform Support**: Works on Windows, macOS, and Linux
-- **Email Integration**: SMTP support for Gmail and other providers
-- **Content Hashing**: Efficient comparison without storing full content
+### 2. Track specific values
+Use a regex to extract a number (price, stock count) and only alert if it crosses a threshold:
+```python title="price.py"
+import re
+price = float(re.search(r"\$([0-9.]+)", content).group(1))
+if price < TARGET_PRICE:
+    self.notify("Price drop!", f"Now ${price}")
+```
 
-## Next Steps
+### 3. Screenshot diff
+Use **Playwright** to render the page and save a screenshot. Compute pixel difference with Pillow.
 
-### Enhancements
-- Add support for monitoring specific page elements (CSS selectors)
-- Implement webhook notifications for integration with other services
-- Create a web dashboard for managing multiple monitored sites
-- Add database storage for change history and analytics
-- Implement different notification types (SMS, Slack, Discord)
-- Create configuration file support for managing multiple sites
-- Add image/screenshot comparison capabilities
-- Implement rate limiting and respectful scraping practices
-
-### Learning Extensions
-- Study advanced web scraping techniques and anti-bot measures
-- Explore headless browsers (Selenium, Playwright) for dynamic content
-- Learn about web scraping ethics and legal considerations
-- Practice with database integration for historical data
-- Understand caching strategies for efficient monitoring
-- Explore real-time monitoring with WebSocket connections
+### 4. Web dashboard
+Pair with Flask (see [Basic Web Server](./basicwebserver)) — a page that lists all monitored URLs, last-check time, and recent history.
+
+### 5. SQLite history
+Persist every check (timestamp, hash, change?) for later analysis.
+
+### 6. Pushover / Pushbullet / Telegram
+Three more notification channels with simple APIs.
+
+### 7. Headless browser
+Some sites are JavaScript-rendered. Replace `requests` with **Playwright** so you scrape the *rendered* DOM.
+
+### 8. RSS-aware mode
+If the site has an RSS feed (see [RSS Feed Reader](./rssfeedreader)), use that instead of scraping — far more reliable.
+
+### 9. Selector tester
+A small CLI that lets you try CSS selectors against a URL interactively before wiring them into the monitor.
+
+### 10. Docker container
+Pack the script in a Dockerfile and deploy to a tiny VPS so it runs 24/7 without keeping your laptop on.
+
+## Privacy & Operational Notes
+- **Do not put secrets in source.** Read SMTP passwords and webhook URLs from environment variables: `os.environ["SMTP_PASSWORD"]`.
+- **Add `*.json`, `.env`, `credentials.*` to `.gitignore`.**
+- **Log carefully.** Avoid printing full page content to disk when debugging is over.
+- **Rotate webhook URLs** if you suspect leaks.
+
+## Real-World Applications
+- **In-stock alerts** — bicycles, GPUs, concert tickets.
+- **Status pages** — pre-empt outages by watching `/status`.
+- **Job boards** — be first to apply to new listings.
+- **Course availability** — universities, training platforms.
+- **Government forms** — get notified when a deadline or form changes.
+- **Pricing intelligence** — track competitor prices (within Terms of Service).
 
 ## Educational Value
+- **HTTP & HTML parsing** — fetch and extract relevant text.
+- **Hashing** — fingerprinting for cheap comparison.
+- **Scheduling** — moving from a one-shot script to a long-running service.
+- **Notifications** — multiple channels, each with different trade-offs.
+- **Defensive coding** — failures must not kill the loop.
+- **Operational thinking** — running a real background process, not just a script.
 
-This project teaches:
-- **Web Scraping**: Extracting and processing data from websites
-- **Content Comparison**: Efficiently detecting changes in large datasets
-- **Automation**: Building systems that run continuously without human intervention
-- **Notification Systems**: Implementing multiple communication channels
-- **Email Programming**: Working with SMTP protocols and email formatting
-- **Scheduling**: Creating time-based automation with proper resource management
-- **Error Handling**: Managing network failures and parsing errors gracefully
-- **Object-Oriented Design**: Structuring applications for maintainability and reusability
-
-Perfect for understanding automation, web data monitoring, and building practical tools for content tracking and alerting systems.
+## Next Steps
+- Add **CSS selector scoping** to reduce noise.
+- Wire up **Slack/Discord** webhooks alongside email.
+- Persist history to **SQLite** for analysis.
+- Containerize with **Docker** and deploy to a cheap VPS.
+- Pair with [Email Sender](./emailsender) for richer email alerts.
+- Extend with **diff snippets** in the notification body.
+
+## Conclusion
+You built a real automation tool: it watches the web for you, sleeps politely between checks, alerts you through whichever channel you prefer, and recovers gracefully from network hiccups. Hash-based change detection, scheduling, and webhook notifications show up in nearly every monitoring system in production. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/webpagescrapernotifications.py). Explore more automation projects on Python Central Hub.
diff --git a/src/content/docs/projects/Beginners/wordcounter.mdx b/src/content/docs/projects/Beginners/wordcounter.mdx
index 028744c7..278e12bb 100644
--- a/src/content/docs/projects/Beginners/wordcounter.mdx
+++ b/src/content/docs/projects/Beginners/wordcounter.mdx
@@ -1,6 +1,6 @@
 ---
 title: Word Counter
-description: A Python application that counts and analyzes word frequency in text files, displaying the most common words using two different implementation approaches.
+description: Build a Python word-frequency analyzer. Learn file I/O, Counter, dictionary counting, text preprocessing (lowercasing, punctuation, stop words), n-grams, and how to visualize results with a word cloud.
 sidebar: 
     order: 33
 hero:
@@ -13,177 +13,254 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Word Counter is a Python application that analyzes text files to count word frequency and identify the most commonly used words. The project demonstrates two different implementation approaches: using Python's built-in `Counter` class from the `collections` module, and implementing a custom solution using dictionaries and sorting. This application is excellent for text analysis, content research, and understanding data processing concepts in Python.
+A word counter answers a simple question — *"which words appear most often in this text?"* — and ends up teaching you nearly every fundamental of text processing: file I/O, tokenization, normalization, counting with dictionaries, and producing readable output. In this project you will build the program two different ways (with `collections.Counter` and from scratch with a plain dictionary), then add real text-preprocessing (lowercasing, punctuation stripping, stop-word filtering, n-grams) and finally generate a word cloud image of the results.
 
-## Prerequisites
-- Python 3.6 or above
-- A code editor or IDE
-- A text file for analysis (text.txt)
-
-## Before you Start
-Before starting this project, you must have Python installed on your computer. If you don't have Python installed, you can download it from [here](https://www.python.org/downloads/). You must have a code editor or IDE installed on your computer. If you don't have any code editor or IDE installed, you can download Visual Studio Code from [here](https://code.visualstudio.com/download).
+You will leave comfortable with:
+- Reading files with `open()` and the `with` block.
+- Tokenizing text into words.
+- Counting with both `Counter` and a manual dictionary.
+- Sorting by value with `sorted(..., key=lambda x: x[1], reverse=True)`.
+- Preprocessing text — the difference between a noisy and a useful word count.
+- N-gram analysis for spotting phrases, not just words.
 
-Note: This project uses only built-in Python modules (`collections`), so no additional installations are required.
+## Prerequisites
+- Python 3.6 or above.
+- A code editor or IDE.
+- A text file to analyze. Anything from your own writing to a public-domain book from [Project Gutenberg](https://www.gutenberg.org).
 
 ## Getting Started
-#### Create a Project
+
+### Create the project
 1. Create a folder named `word-counter`.
-2. Open the folder in your favorite code editor or IDE.
-3. Create a file named `wordcounter.py`.
-4. Create a file named `text.txt` with some sample text to analyze.
-5. Copy the given code and paste it in your `wordcounter.py` file.
-
-#### Create Sample Text File
-Create a `text.txt` file in the same directory with sample content:
-```txt title="text.txt" showLineNumbers{1} {1-5}
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
-Etiam at pharetra velit. Donec mattis lacus vel tortor elementum, 
-in tincidunt ligula tristique. Fusce commodo eget odio eget feugiat. 
-Etiam id porta lacus. Python is a great programming language. 
-Python makes text analysis easy and fun.
-```
-
-## Write the Code
-1. Copy and paste the following code in your `wordcounter.py` file.
+2. Inside it, create `wordcounter.py`.
+3. Add a sample `text.txt` file in the same folder. Suggested contents:
+   ```txt title="text.txt"
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+   Etiam at pharetra velit. Donec mattis lacus vel tortor elementum,
+   in tincidunt ligula tristique. Fusce commodo eget odio eget feugiat.
+   Etiam id porta lacus. Python is a great programming language.
+   Python makes text analysis easy and fun.
+   ```
+
+### Write the code
 <FileCode file="projects/beginners/wordcounter.py" lang="python" title="Word Counter" />
-2. Save the file.
-3. Make sure you have the `text.txt` file in the same directory.
-4. Open the terminal in your code editor or IDE and navigate to the folder `word-counter`.
-```cmd title="command" showLineNumbers{1} {1-15}
+
+### Run it
+```cmd title="command"
 C:\Users\Your Name\word-counter> python wordcounter.py
 [('et', 3), ('sed', 3), ('in', 3), ('vel', 2), ('sit', 2), ('amet,', 2), ('Etiam', 2), ('lacus', 2), ('vitae', 2), ('mauris', 2)]
-[('et', 3), ('sed', 3), ('in', 3), ('vel', 2), ('sit', 2), ('amet,', 2), ('Etiam', 2), ('lacus', 2), ('vitae', 2), ('mauris', 2)]
 ```
 
-## Explanation
+## Two Approaches
 
-### Method 1: Using Counter Class
-1. Import the Counter class from collections module.
-```python title="wordcounter.py" showLineNumbers{1} {1}
+### Method 1 — Using `collections.Counter`
+```python title="method1.py"
 from collections import Counter
+
+with open("text.txt", encoding="utf-8") as f:
+    words = f.read().split()
+
+counts = Counter(words)
+print(counts.most_common(10))
 ```
+- `Counter(words)` counts every distinct item.
+- `.most_common(N)` returns the top N as `(word, count)` tuples.
+- Three lines of logic. This is the right tool.
+
+### Method 2 — Manual Dictionary
+Useful for **understanding** the algorithm:
+```python title="method2.py"
+counts = {}
+for word in words:
+    counts[word] = counts.get(word, 0) + 1
 
-2. Open and read the text file.
-```python title="wordcounter.py" showLineNumbers{1} {1-5}
-text = open('text.txt', 'r')
-allWords = text.read()
-words = allWords.split()
+top = sorted(counts.items(), key=lambda kv: kv[1], reverse=True)
+print(top[:10])
 ```
+- `dict.get(key, default)` is the safe way to read-and-default.
+- `sorted(..., key=lambda kv: kv[1], reverse=True)` sorts by *count*, not by word.
 
-3. Create a Counter object and find most common words.
-```python title="wordcounter.py" showLineNumbers{1} {1-3}
-counter = Counter(words)
-print(counter.most_common(10))
-text.close()
+### Why `Counter` wins
+- Less code, less to get wrong.
+- Implemented in C — faster than the manual loop.
+- Supports `.most_common`, addition (`c1 + c2`), subtraction, and many other operations out of the box.
+
+The manual approach is still worth knowing because real interviews still ask it, and because every dictionary-counting pattern in the wild looks like this.
+
+## Step-by-Step Explanation
+
+### 1. Open the file safely
+```python title="wordcounter.py"
+with open("text.txt", encoding="utf-8") as f:
+    text = f.read()
 ```
+The `with` block guarantees the file is closed even if an error happens later. Always pass `encoding="utf-8"` unless you know otherwise — the platform default (cp1252 on Windows, utf-8 elsewhere) is a frequent bug source.
 
-### Method 2: Using Dictionary Approach
-1. Initialize an empty dictionary.
-```python title="wordcounter.py" showLineNumbers{1} {1}
-words2 = {}
+### 2. Split into words
+```python title="wordcounter.py"
+words = text.split()
 ```
+`split()` with no arguments splits on any run of whitespace — spaces, tabs, newlines. Good enough for a first pass, but it keeps punctuation glued to words (`amet,` and `amet` are different).
 
-2. Count words manually using a loop.
-```python title="wordcounter.py" showLineNumbers{1} {1-6}
-for word in words:
-    if word not in words2:
-        words2[word] = 1
-    else:
-        words2[word] += 1
+### 3. Count and rank
+```python title="wordcounter.py"
+counts = Counter(words)
+top = counts.most_common(10)
+for word, n in top:
+    print(f"{word:15} {n}")
 ```
+`f"{word:15}"` pads the word to 15 characters wide, producing a tidy column-aligned table.
+
+## Real Preprocessing
+
+The raw counts above are noisy:
+- **Case mismatch:** `Python` and `python` are different.
+- **Punctuation glued on:** `amet,` ≠ `amet`.
+- **Stop words dominate:** `the`, `and`, `is` overwhelm everything interesting.
+
+Fix all three:
+
+```python title="preprocess.py"
+import re
+from collections import Counter
+
+STOP_WORDS = {
+    "the","a","an","and","or","but","of","in","on","at","to","for","with",
+    "is","are","was","were","be","been","being","i","you","he","she","it","we","they",
+    "this","that","these","those","as","by","from","up","down","out","so","not"
+}
+
+def tokenize(text: str) -> list[str]:
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9\s']", " ", text)   # keep apostrophes for contractions
+    return [w for w in text.split() if w and w not in STOP_WORDS]
 
-3. Sort and display results.
-```python title="wordcounter.py" showLineNumbers{1} {1-2}
-sorted_words = sorted(words2.items(), key=lambda x: x[1], reverse=True)
-print(sorted_words[:10])
+with open("text.txt", encoding="utf-8") as f:
+    words = tokenize(f.read())
+print(Counter(words).most_common(20))
 ```
+A simple stop-word list cuts most of the noise. For serious work use **NLTK's** list (`from nltk.corpus import stopwords`).
 
-## Features
-- **Dual Implementation:** Shows two different approaches to solve the same problem
-- **File Processing:** Reads and analyzes text from external files
-- **Word Frequency Analysis:** Counts occurrences of each word
-- **Top Words Display:** Shows the most frequently used words
-- **Sorting Capabilities:** Orders results by frequency
-- **Simple Interface:** Easy-to-understand command-line output
+## N-grams: Counting Phrases
 
-## How It Works
+A bigram is a pair of consecutive words. Counting them surfaces common phrases:
+```python title="ngrams.py"
+def ngrams(words: list[str], n: int) -> list[tuple]:
+    return [tuple(words[i:i+n]) for i in range(len(words) - n + 1)]
 
-### Step-by-Step Process
-1. **File Reading:** Opens and reads the entire text file
-2. **Text Splitting:** Breaks the text into individual words
-3. **Word Counting:** Counts the frequency of each word
-4. **Sorting:** Orders words by frequency (highest to lowest)
-5. **Display:** Shows the top 10 most common words
+bigrams = Counter(ngrams(words, 2))
+print(bigrams.most_common(10))
+# [(('python', 'is'), 5), (('text', 'analysis'), 3), ...]
+```
+Trigrams (`n=3`) reveal even more — useful for catching named entities ("New York City") and idioms.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `UnicodeDecodeError` | Wrong encoding | Always `encoding="utf-8"` |
+| `Python` and `python` counted separately | No lowercasing | `text.lower()` before splitting |
+| `amet,` and `amet` separate | Punctuation glued on | Strip with `re.sub(r"[^a-z0-9\s']", " ", text)` |
+| Top words are all `the`, `and`, `of` | No stop-word filter | Skip a stop-word set |
+| `Counter` not sorted by frequency | Iterated a `Counter` directly (insertion order) | Use `.most_common()` |
+| Counts wrong on a huge file | Loaded all into memory unnecessarily | Stream line-by-line: `for line in f: ...` |
 
-### Data Structures Used
-- **Counter (Method 1):** Specialized dictionary for counting objects
-- **Dictionary (Method 2):** Manual implementation of word counting
-- **List:** Stores individual words after splitting
-- **Tuple:** Stores word-count pairs in results
+## Variations to Try
 
-## Sample Output Analysis
-For a typical text analysis, you might see results like:
+### 1. Word cloud
+```bash title="install"
+pip install wordcloud matplotlib
 ```
-[('the', 15), ('and', 12), ('to', 10), ('of', 8), ('a', 7), ('in', 6), ('is', 5), ('it', 4), ('that', 4), ('for', 3)]
+```python title="cloud.py"
+from wordcloud import WordCloud
+import matplotlib.pyplot as plt
+cloud = WordCloud(width=800, height=400, background_color="white").generate_from_frequencies(Counter(words))
+plt.imshow(cloud); plt.axis("off"); plt.savefig("cloud.png", dpi=150)
 ```
 
-This tells us:
-- "the" appears 15 times (most frequent)
-- "and" appears 12 times (second most frequent)
-- And so on...
+### 2. Unique-word ratio (lexical diversity)
+```python title="diversity.py"
+diversity = len(set(words)) / len(words)
+print(f"Lexical diversity: {diversity:.2%}")
+```
+A high ratio means a rich vocabulary; a low ratio means a lot of repetition.
 
-## Use Cases
-- **Content Analysis:** Analyze blog posts, articles, or documents
-- **SEO Research:** Identify keyword density and frequency
-- **Academic Research:** Analyze literary texts or research papers
-- **Social Media:** Analyze hashtag or keyword trends
-- **Writing Improvement:** Identify overused words in your writing
+### 3. Word-length distribution
+```python title="lengths.py"
+lengths = Counter(len(w) for w in words)
+for k in sorted(lengths):
+    print(f"{k:2} chars: {'#' * lengths[k]}")
+```
 
-## Next Steps
-You can enhance this project by:
-- Adding a GUI interface using Tkinter
-- Supporting multiple file formats (PDF, Word, etc.)
-- Implementing word filtering (stop words removal)
-- Adding visualization with charts and graphs
-- Creating word clouds for visual representation
-- Adding text preprocessing (lowercase, punctuation removal)
-- Implementing n-gram analysis (2-word, 3-word phrases)
-- Adding statistical analysis (average word length, etc.)
-- Creating comparison between multiple documents
-- Adding sentiment analysis capabilities
-
-## Enhanced Version Ideas
-```python title="wordcounter.py" showLineNumbers{1}
-def enhanced_word_counter():
-    # Features to add:
-    # - Remove punctuation and convert to lowercase
-    # - Filter out common stop words
-    # - Support for different file formats
-    # - Export results to CSV or JSON
-    # - Word length analysis
-    # - Unique word percentage
-    pass
-```
-
-## Text Preprocessing Improvements
-Consider adding these preprocessing steps:
-- **Lowercase conversion:** Treat "The" and "the" as the same word
-- **Punctuation removal:** Clean "word," to "word"
-- **Stop word filtering:** Remove common words like "the", "and", "is"
-- **Stemming:** Reduce words to their root form
+### 4. Compare two documents
+```python title="compare.py"
+a = Counter(tokenize(open("a.txt").read()))
+b = Counter(tokenize(open("b.txt").read()))
+print("In A but not B:", (a - b).most_common(10))
+```
+
+### 5. Read PDFs
+```bash title="install"
+pip install pypdf
+```
+```python title="pdf.py"
+from pypdf import PdfReader
+text = "\n".join(p.extract_text() or "" for p in PdfReader("file.pdf").pages)
+```
+
+### 6. Streaming counts for huge files
+```python title="stream.py"
+counts = Counter()
+with open("big.txt", encoding="utf-8") as f:
+    for line in f:
+        counts.update(tokenize(line))
+```
+Memory stays constant even for multi-gigabyte inputs.
+
+### 7. Export to CSV
+```python title="csv_export.py"
+import csv
+with open("out.csv", "w", newline="", encoding="utf-8") as f:
+    csv.writer(f).writerows(counts.most_common())
+```
+
+### 8. Real NLP with NLTK or spaCy
+Stop words, stemming (`run`, `running`, `runs` → `run`), lemmatization, named-entity recognition. A few extra lines unlock major analytical power.
+
+### 9. Web frontend
+Wrap with Flask (see [Basic Web Server](./basicwebserver)): paste text, get back top words and a generated word cloud image.
+
+### 10. Concordance
+For any word, print every sentence it appears in — a basic literary-analysis tool.
 
 ## Performance Considerations
-- **Large Files:** Use generators for memory-efficient processing
-- **Encoding:** Handle different text encodings (UTF-8, ASCII, etc.)
-- **Error Handling:** Manage file not found and permission errors
+
+For text up to ~100 MB, the simple `Counter(text.split())` is plenty fast (a few seconds). Beyond that:
+- Stream line-by-line (see Variation 6) to keep memory bounded.
+- Use `re.findall(r"\w+", line)` instead of `.split()` — it tokenizes and strips punctuation in one step.
+- For multi-gigabyte corpora consider **DuckDB**'s `read_csv` with SQL aggregation, or `pandas` with chunked CSV reads.
+
+## Real-World Applications
+- **SEO research** — keyword density on a page.
+- **Plagiarism detection** — fingerprinting documents by word frequencies.
+- **Stylometry** — identifying authors by their word patterns.
+- **Content auditing** — finding overused words in your own writing.
+- **Spam filtering** — Naive Bayes spam classifiers count exactly like this.
+- **Search engines** — inverted indexes start with the same per-document word counts.
 
 ## Educational Value
-This project teaches:
-- **File I/O operations:** Reading and processing text files
-- **Data structures:** Dictionaries, lists, and tuples
-- **String manipulation:** Splitting and processing text
-- **Sorting algorithms:** Custom sorting with lambda functions
-- **Module usage:** Working with the collections module
+- **File I/O** — reading text safely and with the right encoding.
+- **Text preprocessing** — the gap between *raw text* and *useful data*.
+- **`Counter`** — one of the most useful classes in the standard library.
+- **Sorting with a key** — a pattern you will reuse for the rest of your career.
+- **Generators and streaming** — memory matters at scale.
+
+## Next Steps
+- Combine with [Personal Diary](./personaldiary): analyze your own journal entries for mood and themes over time.
+- Plug the n-gram code into a markov-chain text generator for fun.
+- Build a **Flask** front-end and host it publicly.
+- Move to **spaCy** for named-entity recognition and proper tokenization.
+- Compare classic literature texts — easy way to learn distributed text analysis without distributed systems.
 
 ## Conclusion
-In this project, we learned how to create a Word Counter using Python's built-in data structures and modules. We explored two different implementation approaches, demonstrating both the convenience of specialized classes like Counter and the educational value of implementing algorithms manually. This project provides a foundation for more advanced text analysis and natural language processing applications. To find more projects like this, you can visit Python Central Hub.
+You counted words two ways, learned why preprocessing turns garbage counts into useful insight, and saw the path from a 5-line script to a real text-analysis pipeline. The same algorithms power search engines, spam filters, and SEO tools. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/beginners/wordcounter.py). Find more text-processing projects on Python Central Hub.

From 91ffc7f4e97d4cb055492ee7ba1cf040774ffdc7 Mon Sep 17 00:00:00 2001
From: Ravi Kishan <ravikishan63392@gmail.com>
Date: Mon, 1 Jun 2026 11:52:41 +0530
Subject: [PATCH 2/2] adding the new pages and enhance the tutorials

---
 .github/workflows/ci.yml                      |  28 +
 astro.config.mjs                              | 127 +++--
 firebase/firestore.rules.example              |  20 +
 firebase/functions/index.example.js           |  56 ++
 lib/mermaid/remake.ts                         |  26 +-
 lib/mermaid/render-diagram.ts                 |  13 +-
 package-lock.json                             |  46 +-
 package.json                                  |   2 +-
 public/scripts/main.js                        |  24 +-
 public/scripts/sidebar-enhance.js             | 180 +++++++
 public/scripts/toast.js                       |  49 +-
 src/components/Contact.astro                  | 175 +++++--
 src/components/DataCampExercise.astro         |   3 +-
 src/components/Feedback.astro                 | 183 +++++--
 src/components/Footer.astro                   |  83 ++-
 src/components/Head.astro                     |  73 +++
 src/components/Sidebar.astro                  | 113 ++++
 src/components/YoutuberCard.astro             |  15 +-
 src/content/docs/404.mdx                      |  30 ++
 .../docs/projects/Beginners/emailsender.mdx   |   4 +-
 .../Beginners/movie-recommendation-system.mdx |   2 +-
 .../docs/projects/Beginners/quizapp.mdx       |   2 +-
 .../projects/intermediate/ai-task-manager.mdx | 364 ++++---------
 .../projects/intermediate/anagram-game.mdx    | 173 +++++--
 .../projects/intermediate/anagram_game.mdx    | 101 ----
 .../intermediate/basic-chatroom-app.mdx       | 184 +++++--
 .../basic-file-version-control-system.mdx     | 164 ++++--
 .../intermediate/basic_chatroom_app.mdx       | 108 ----
 .../basic_file_version_control_system.mdx     | 100 ----
 .../intermediate/basic_ocr_with_tesseract.mdx | 207 ++++++--
 .../cryptocurrency-portfolio-tracker.mdx      | 257 ++++++++--
 .../intermediate/ecommerce-analytics.mdx      | 352 +++++--------
 .../intermediate/ecommerce-website.mdx        | 198 +++++--
 .../intermediate/ecommerce_website.mdx        | 116 -----
 .../file-synchronization-tool.mdx             | 170 ++++--
 .../file_synchronization_tool.mdx             |  99 ----
 .../intermediate/github-profile-viewer.mdx    | 155 ++++--
 .../intermediate/github_profile_viewer.mdx    |  96 ----
 .../intermediate/gui-sql-database-viewer.mdx  | 198 +++++--
 .../intermediate/gui_sql_database_viewer.mdx  | 104 ----
 .../image-recognition-with-opencv.mdx         | 249 +++++----
 .../image_recognition_with_opencv.mdx         | 105 ----
 .../interactive-periodic-table.mdx            | 169 ++++--
 .../interactive_periodic_table.mdx            |  98 ----
 .../intermediate/ml-model-trainer.mdx         | 485 +++++-------------
 .../intermediate/multiplayer-tic-tac-toe.mdx  | 182 +++++--
 .../intermediate/multiplayer_tic_tac_toe.mdx  | 103 ----
 .../projects/intermediate/news-aggregator.mdx | 185 +++++--
 .../projects/intermediate/news_aggregator.mdx | 107 ----
 .../intermediate/personal-finance-tracker.mdx | 353 +++++--------
 .../intermediate/portfolio-website.mdx        | 300 ++++++-----
 .../qr-code-attendance-system.mdx             | 171 ++++--
 .../qr_code_attendance_system.mdx             | 105 ----
 .../intermediate/quiz-game-with-timer.mdx     | 189 +++++--
 .../intermediate/quiz_game_with_timer.mdx     | 109 ----
 .../real-time-chat-application.mdx            | 192 +++++--
 .../real_time_chat_application.mdx            | 108 ----
 .../projects/intermediate/rest-api-server.mdx | 316 ++++++------
 .../intermediate/simple-blog-with-flask.mdx   | 202 ++++++--
 .../simple-weather-forecast-app.mdx           | 177 +++++--
 .../intermediate/simple_blog_with_flask.mdx   | 106 ----
 .../simple_weather_forecast_app.mdx           |  97 ----
 .../intermediate/social-media-analytics.mdx   | 337 ++++--------
 .../projects/intermediate/url-expander.mdx    | 178 +++++--
 .../intermediate/url-shortener-analytics.mdx  | 327 +++++-------
 .../projects/intermediate/url_expander.mdx    |  96 ----
 .../weather-app-with-voice-commands.mdx       | 157 ++++--
 .../weather_app_with_voice_commands.mdx       | 105 ----
 .../intermediate/web-scraping-pipeline.mdx    | 466 +++++------------
 src/content/docs/tutorials/Boolean.mdx        |  73 +++
 src/content/docs/tutorials/Comment.mdx        |  61 +++
 src/content/docs/tutorials/DataType.mdx       |  63 +++
 .../docs/tutorials/Datatype Casting.mdx       |  31 +-
 src/content/docs/tutorials/GetStarted.mdx     |  49 +-
 src/content/docs/tutorials/Input.mdx          |  39 ++
 src/content/docs/tutorials/Installation.mdx   |  56 ++
 src/content/docs/tutorials/Introduction.mdx   |  96 +++-
 .../tutorials/Modern Python/Concurrency.mdx   | 260 ++++++++++
 .../tutorials/Modern Python/Dataclasses.mdx   | 268 ++++++++++
 .../Modern Python/F-Strings Deep Dive.mdx     | 209 ++++++++
 .../tutorials/Modern Python/Networking.mdx    | 224 ++++++++
 .../Modern Python/Type Hints and typing.mdx   | 286 +++++++++++
 .../Virtual Environments and pip.mdx          | 186 +++++++
 .../Modern Python/Walrus Operator.mdx         | 170 ++++++
 src/content/docs/tutorials/Numbers.mdx        |  76 ++-
 src/content/docs/tutorials/Print.mdx          |  54 ++
 .../Python Comprehensions/Comprehensions.mdx  | 294 +++++++++++
 .../Context Managers.mdx                      | 296 +++++++++++
 .../Exception Handling.mdx                    | 385 ++++++++++++++
 .../Python Function/Args and Kwargs.mdx       | 285 ++++++++++
 .../Python Function/Function Annotations.mdx  |   4 +
 .../Closures and Scope.mdx                    | 326 ++++++++++++
 .../Map Filter Reduce.mdx                     | 270 ++++++++++
 .../Recursion.mdx                             | 261 ++++++++++
 .../Iterators and Generators.mdx              | 341 ++++++++++++
 .../Argparse and sys.argv.mdx                 | 216 ++++++++
 .../tutorials/Python Standard Library/CSV.mdx | 233 +++++++++
 .../Python Standard Library/Collections.mdx   | 261 ++++++++++
 .../Python Standard Library/Date and Time.mdx | 305 +++++++++++
 .../Itertools and Functools.mdx               | 270 ++++++++++
 .../Python Standard Library/JSON.mdx          | 267 ++++++++++
 .../Python Standard Library/Logging.mdx       | 224 ++++++++
 .../Math Random Statistics.mdx                | 230 +++++++++
 .../Python Standard Library/Pathlib.mdx       | 222 ++++++++
 .../Python Standard Library/Pickle.mdx        | 210 ++++++++
 .../Regular Expressions.mdx                   | 313 +++++++++++
 .../Python Standard Library/SQLite3.mdx       | 270 ++++++++++
 .../Testing with unittest and pytest.mdx      | 295 +++++++++++
 .../Python Strings/Formatting String.mdx      |   4 +
 .../Python Variables/Global Variables.mdx     |  27 +
 .../Python Variables/Multiple Assignment.mdx  |  31 ++
 .../Python Variables/Naming Convention.mdx    |  39 +-
 .../Python Variables/Variable Assignment.mdx  |  47 +-
 src/content/docs/tutorials/Syntax.mdx         |  92 +++-
 src/pages/rss.xml.js                          |  27 +
 src/styles/global.css                         |  21 +
 116 files changed, 13359 insertions(+), 5082 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 firebase/firestore.rules.example
 create mode 100644 firebase/functions/index.example.js
 create mode 100644 public/scripts/sidebar-enhance.js
 create mode 100644 src/components/Head.astro
 create mode 100644 src/components/Sidebar.astro
 delete mode 100644 src/content/docs/projects/intermediate/anagram_game.mdx
 delete mode 100644 src/content/docs/projects/intermediate/basic_chatroom_app.mdx
 delete mode 100644 src/content/docs/projects/intermediate/basic_file_version_control_system.mdx
 delete mode 100644 src/content/docs/projects/intermediate/ecommerce_website.mdx
 delete mode 100644 src/content/docs/projects/intermediate/file_synchronization_tool.mdx
 delete mode 100644 src/content/docs/projects/intermediate/github_profile_viewer.mdx
 delete mode 100644 src/content/docs/projects/intermediate/gui_sql_database_viewer.mdx
 delete mode 100644 src/content/docs/projects/intermediate/image_recognition_with_opencv.mdx
 delete mode 100644 src/content/docs/projects/intermediate/interactive_periodic_table.mdx
 delete mode 100644 src/content/docs/projects/intermediate/multiplayer_tic_tac_toe.mdx
 delete mode 100644 src/content/docs/projects/intermediate/news_aggregator.mdx
 delete mode 100644 src/content/docs/projects/intermediate/qr_code_attendance_system.mdx
 delete mode 100644 src/content/docs/projects/intermediate/quiz_game_with_timer.mdx
 delete mode 100644 src/content/docs/projects/intermediate/real_time_chat_application.mdx
 delete mode 100644 src/content/docs/projects/intermediate/simple_blog_with_flask.mdx
 delete mode 100644 src/content/docs/projects/intermediate/simple_weather_forecast_app.mdx
 delete mode 100644 src/content/docs/projects/intermediate/url_expander.mdx
 delete mode 100644 src/content/docs/projects/intermediate/weather_app_with_voice_commands.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Concurrency.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Dataclasses.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/F-Strings Deep Dive.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Networking.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Type Hints and typing.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Virtual Environments and pip.mdx
 create mode 100644 src/content/docs/tutorials/Modern Python/Walrus Operator.mdx
 create mode 100644 src/content/docs/tutorials/Python Comprehensions/Comprehensions.mdx
 create mode 100644 src/content/docs/tutorials/Python Context Managers/Context Managers.mdx
 create mode 100644 src/content/docs/tutorials/Python Exception Handling/Exception Handling.mdx
 create mode 100644 src/content/docs/tutorials/Python Function/Args and Kwargs.mdx
 create mode 100644 src/content/docs/tutorials/Python Functional Programming/Closures and Scope.mdx
 create mode 100644 src/content/docs/tutorials/Python Functional Programming/Map Filter Reduce.mdx
 create mode 100644 src/content/docs/tutorials/Python Functional Programming/Recursion.mdx
 create mode 100644 src/content/docs/tutorials/Python Iterators and Generators/Iterators and Generators.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Argparse and sys.argv.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/CSV.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Collections.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Date and Time.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Itertools and Functools.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/JSON.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Logging.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Math Random Statistics.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Pathlib.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Pickle.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Regular Expressions.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/SQLite3.mdx
 create mode 100644 src/content/docs/tutorials/Python Standard Library/Testing with unittest and pytest.mdx
 create mode 100644 src/pages/rss.xml.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..1a5322f4
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, prod]
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Runs `astro check && astro build` (see package.json "build" script).
+      - name: Build
+        run: npm run build
diff --git a/astro.config.mjs b/astro.config.mjs
index baec7464..64877c26 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -61,8 +61,14 @@ export default defineConfig({
       logo: {
         src: "./src/assets/pythonlogo.png",
       },
+      // Show "Last updated" on content pages, derived from git history.
+      lastUpdated: true,
       components: {
         Footer: "./src/components/Footer.astro",
+        // Injects per-page JSON-LD structured data.
+        Head: "./src/components/Head.astro",
+        // Adds sidebar search + collapse/expand-all with persisted state.
+        Sidebar: "./src/components/Sidebar.astro",
       },
       favicon: "./src/assets/favicon.ico",
       social: {
@@ -133,13 +139,17 @@ export default defineConfig({
             src: "/scripts/main.js",
           },
         },
-        {
-          tag: "meta",
-          attrs: {
-            name: "google-adsense-account",
-            content: import.meta.env.VITE_GOOGLE_ADSENSE,
-          },
-        },
+        ...(import.meta.env.VITE_GOOGLE_ADSENSE
+          ? [
+              {
+                tag: "meta",
+                attrs: {
+                  name: "google-adsense-account",
+                  content: import.meta.env.VITE_GOOGLE_ADSENSE,
+                },
+              },
+            ]
+          : []),
         {
           tag: "meta",
           attrs: {
@@ -215,13 +225,17 @@ export default defineConfig({
               "Python, Python Projects, Python Central Hub, Python Central Hub Projects, Python Central Hub Tutorials, Python Central Hub Guides, Python Central Hub Reference, Python Tutorial, Python tutorials, Python programming, Learn Python, Python for beginners, Python code examples, Python development, Python projects,Python programming language, Python tips and tricks,Python resources,Python learning platform,Python coding lessons,Python programming for beginners,Python programming exercises,Python coding practice,Python syntax,Python libraries,Python community,Python best practices,Python coding challenges",
           },
         },
-        {
-          tag: "meta",
-          attrs: {
-            name: "monetag",
-            content: `${import.meta.env.VITE_MONETAG}`
-          }
-        },
+        ...(import.meta.env.VITE_MONETAG
+          ? [
+              {
+                tag: "meta",
+                attrs: {
+                  name: "monetag",
+                  content: `${import.meta.env.VITE_MONETAG}`,
+                },
+              },
+            ]
+          : []),
         {
           tag: "meta",
           attrs: {
@@ -251,27 +265,39 @@ export default defineConfig({
           },
         },
         {
-          tag: "meta",
-          attrs: {
-            name: "theme-color",
-            content: "#e7c384",
-          },
-        },
-        {
-          tag: "script",
+          tag: "link",
           attrs: {
-            async: true,
-            src: `https://www.googletagmanager.com/gtag/js?id=${import.meta.env.VITE_GOOGLE_ANALYTICS
-              }`,
+            rel: "alternate",
+            type: "application/rss+xml",
+            title: "Python Central Hub RSS Feed",
+            href: "/rss.xml",
           },
         },
         {
-          tag: "script",
+          tag: "meta",
           attrs: {
-            async: true,
-            src: "/scripts/gtag.js",
+            name: "theme-color",
+            content: "#e7c384",
           },
         },
+        ...(import.meta.env.VITE_GOOGLE_ANALYTICS
+          ? [
+              {
+                tag: "script",
+                attrs: {
+                  async: true,
+                  src: `https://www.googletagmanager.com/gtag/js?id=${import.meta.env.VITE_GOOGLE_ANALYTICS}`,
+                },
+              },
+              {
+                tag: "script",
+                attrs: {
+                  async: true,
+                  src: "/scripts/gtag.js",
+                },
+              },
+            ]
+          : []),
         {
           tag: "script",
           attrs: {
@@ -280,16 +306,19 @@ export default defineConfig({
             src: "/scripts/mermaid.js",
           },
         },
-        {
-          tag: "script",
-          attrs: {
-            async: true,
-            src: `https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${import.meta.env.VITE_GOOGLE_ADSENSE
-              }`,
-            crossorigin: "anonymous",
-          },
-        },
-        
+        ...(import.meta.env.VITE_GOOGLE_ADSENSE
+          ? [
+              {
+                tag: "script",
+                attrs: {
+                  async: true,
+                  src: `https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${import.meta.env.VITE_GOOGLE_ADSENSE}`,
+                  crossorigin: "anonymous",
+                },
+              },
+            ]
+          : []),
+
         {
           tag: "link",
           attrs: {
@@ -323,7 +352,27 @@ export default defineConfig({
     tailwind({
       applyBaseStyles: false,
     }),
-    sitemap(),
+    sitemap({
+      // Give index/guides/tutorials higher priority than deep pages and
+      // stamp a build-time lastmod so crawlers see fresh dates.
+      serialize(item) {
+        const url = item.url;
+        if (url === `${site}/`) {
+          item.priority = 1.0;
+        } else if (url.includes("/guides/")) {
+          item.priority = 0.9;
+        } else if (url.includes("/tutorials/")) {
+          item.priority = 0.8;
+        } else if (url.includes("/projects/")) {
+          item.priority = 0.7;
+        } else {
+          item.priority = 0.6;
+        }
+        item.changefreq = "weekly";
+        item.lastmod = new Date().toISOString();
+        return item;
+      },
+    }),
     robotsTxt(),
     markdownIntegration(),
   ],
diff --git a/firebase/firestore.rules.example b/firebase/firestore.rules.example
new file mode 100644
index 00000000..f777afd9
--- /dev/null
+++ b/firebase/firestore.rules.example
@@ -0,0 +1,20 @@
+rules_version = '2';
+
+// EXAMPLE Firestore rules. The public web SDK config in Contact.astro /
+// Feedback.astro is client-visible, so without rules anyone can write freely.
+//
+// Recommended: deny direct client writes and route submissions through the
+// `submitForm` Cloud Function (see functions/index.example.js), which validates
+// the reCAPTCHA token server-side. The function uses the Admin SDK and bypasses
+// these rules.
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // Block all direct client reads/writes to form collections.
+    match /contact/{doc} {
+      allow read, write: if false;
+    }
+    match /feedback/{doc} {
+      allow read, write: if false;
+    }
+  }
+}
diff --git a/firebase/functions/index.example.js b/firebase/functions/index.example.js
new file mode 100644
index 00000000..dbf2731f
--- /dev/null
+++ b/firebase/functions/index.example.js
@@ -0,0 +1,56 @@
+/**
+ * Reference Cloud Function for validating reCAPTCHA v3 tokens before allowing
+ * a write to Firestore. This is an EXAMPLE — deploy it under your own Firebase
+ * Functions project and wire the client forms to POST here instead of writing
+ * to Firestore directly, OR call it from a Firestore `onCreate` trigger.
+ *
+ * Setup:
+ *   1. firebase init functions
+ *   2. Copy this file to functions/index.js (adjust as needed)
+ *   3. Set the secret:  firebase functions:config:set recaptcha.secret="YOUR_SECRET"
+ *   4. firebase deploy --only functions
+ *
+ * The client forms (Contact.astro / Feedback.astro) attach a `recaptchaToken`
+ * field. Validate it here; reject low scores / failed verifications.
+ */
+
+const functions = require("firebase-functions");
+const admin = require("firebase-admin");
+
+admin.initializeApp();
+
+const MIN_SCORE = 0.5;
+
+async function verifyToken(token) {
+  const secret = functions.config().recaptcha.secret;
+  const res = await fetch("https://www.google.com/recaptcha/api/siteverify", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: `secret=${encodeURIComponent(secret)}&response=${encodeURIComponent(token)}`,
+  });
+  const data = await res.json();
+  return data.success === true && (data.score ?? 0) >= MIN_SCORE;
+}
+
+// HTTPS callable: client posts { collection, payload, recaptchaToken }.
+exports.submitForm = functions.https.onCall(async (data) => {
+  const { collection, payload, recaptchaToken } = data || {};
+
+  if (!["contact", "feedback"].includes(collection)) {
+    throw new functions.https.HttpsError("invalid-argument", "Bad collection.");
+  }
+  if (!recaptchaToken || !(await verifyToken(recaptchaToken))) {
+    throw new functions.https.HttpsError(
+      "permission-denied",
+      "reCAPTCHA verification failed."
+    );
+  }
+
+  const { recaptchaToken: _omit, ...clean } = payload || {};
+  await admin
+    .firestore()
+    .collection(collection)
+    .add({ ...clean, createdAt: admin.firestore.FieldValue.serverTimestamp() });
+
+  return { ok: true };
+});
diff --git a/lib/mermaid/remake.ts b/lib/mermaid/remake.ts
index 95f7cac7..de86022f 100644
--- a/lib/mermaid/remake.ts
+++ b/lib/mermaid/remake.ts
@@ -68,10 +68,28 @@ function plugin() {
         // or this keep running puppeeter ?
         // Also, disabling it prevent a bug which doesn't
         // occur in the regular component.
-        const html = await renderDiagram({
-          config: {},
-          code: node.value,
-        }).then((diagram) => diagram);
+        let html: string;
+        try {
+          html = await renderDiagram({
+            config: {},
+            code: node.value,
+          }).then((diagram) => diagram);
+        } catch (err) {
+          // A single bad diagram must not kill the whole build/page.
+          // Emit the original mermaid source so the author can debug it.
+          const message = err instanceof Error ? err.message : String(err);
+          console.warn(`[mermaid] Failed to render diagram: ${message}`);
+          const escaped = node.value
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+          parent.children.splice(index, 1, {
+            type: "html",
+            value: `<!-- mermaid render failed: ${message.replace(/--+/g, "—")} -->\n<pre class="mermaid-error"><code>${escaped}</code></pre>`,
+            position: node.position,
+          });
+          return;
+        }
 
         parent.children.splice(index, 1, {
           type: "html",
diff --git a/lib/mermaid/render-diagram.ts b/lib/mermaid/render-diagram.ts
index 331be0e4..5c10b962 100644
--- a/lib/mermaid/render-diagram.ts
+++ b/lib/mermaid/render-diagram.ts
@@ -60,8 +60,19 @@ export default async function renderDiagram({ config, code }: any) {
   return false;
   */
 
+  // Provide a text alternative for screen readers. The mermaid client script
+  // renders an <svg> into this <pre>; the role/aria-label survive on the element
+  // so assistive tech can still describe the diagram from its source.
+  const ariaLabel = code
+    .trim()
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\s+/g, " ");
+
   const htmlCode = `
-<pre class="mermaid" style="all: initial; width: 100%;display: flex; flex-direction: column; justify-content: center;align-items: center;">
+<pre class="mermaid" role="img" aria-label="Diagram: ${ariaLabel}" style="all: initial; width: 100%;display: flex; flex-direction: column; justify-content: center;align-items: center;">
   ${code.trimStart()}
 </pre>
   `;
diff --git a/package-lock.json b/package-lock.json
index 6cd34707..12dba59a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,6 +9,7 @@
       "version": "0.0.1",
       "dependencies": {
         "@astrojs/check": "^0.3.1",
+        "@astrojs/rss": "^3.0.0",
         "@astrojs/sitemap": "^3.0.3",
         "@astrojs/starlight": "^0.12.0",
         "@astrojs/starlight-tailwind": "^2.0.1",
@@ -16,7 +17,6 @@
         "@astropub/md": "^0.3.0",
         "astro": "^3.2.3",
         "astro-robots-txt": "^1.0.0",
-        "pythoncentralhub": "file:",
         "sharp": "^0.32.5",
         "shiki": "^0.14.5",
         "tailwindcss": "^3.3.5",
@@ -715,6 +715,16 @@
         "node": ">=6"
       }
     },
+    "node_modules/@astrojs/rss": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@astrojs/rss/-/rss-3.0.0.tgz",
+      "integrity": "sha512-PMX8iqByk9gtOrusikten/oF5uHjOCZigL6RuXFBUu+xtdKQxXzfIohJ99V2haA4FJjVDyibDTGzXR81POBMxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-xml-parser": "^4.2.7",
+        "kleur": "^4.1.5"
+      }
+    },
     "node_modules/@astrojs/sitemap": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/@astrojs/sitemap/-/sitemap-3.0.3.tgz",
@@ -4729,6 +4739,24 @@
       "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
       "dev": true
     },
+    "node_modules/fast-xml-parser": {
+      "version": "4.5.6",
+      "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-4.5.6.tgz",
+      "integrity": "sha512-Yd4vkROfJf8AuJrDIVMVmYfULKmIJszVsMv7Vo71aocsKgFxpdlpSHXSaInvyYfgw2PRuObQSW2GFpVMUjxu9A==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "strnum": "^1.0.5"
+      },
+      "bin": {
+        "fxparser": "src/cli/cli.js"
+      }
+    },
     "node_modules/fastq": {
       "version": "1.15.0",
       "license": "ISC",
@@ -8001,10 +8029,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/pythoncentralhub": {
-      "resolved": "",
-      "link": true
-    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "funding": [
@@ -9446,6 +9470,18 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/strnum": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/strnum/-/strnum-1.1.2.tgz",
+      "integrity": "sha512-vrN+B7DBIoTTZjnPNewwhx6cBA/H+IS7rfW68n7XxC1y7uoiGQBxaKzqucGUgavX15dJgiGztLJ8vxuEzwqBdA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/NaturalIntelligence"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/style-to-object": {
       "version": "0.4.4",
       "license": "MIT",
diff --git a/package.json b/package.json
index 5a06e3ba..c2459034 100644
--- a/package.json
+++ b/package.json
@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "@astrojs/check": "^0.3.1",
+    "@astrojs/rss": "^3.0.0",
     "@astrojs/sitemap": "^3.0.3",
     "@astrojs/starlight": "^0.12.0",
     "@astrojs/starlight-tailwind": "^2.0.1",
@@ -18,7 +19,6 @@
     "@astropub/md": "^0.3.0",
     "astro": "^3.2.3",
     "astro-robots-txt": "^1.0.0",
-    "pythoncentralhub": "file:",
     "sharp": "^0.32.5",
     "shiki": "^0.14.5",
     "tailwindcss": "^3.3.5",
diff --git a/public/scripts/main.js b/public/scripts/main.js
index 1ece05ba..a117cf2b 100644
--- a/public/scripts/main.js
+++ b/public/scripts/main.js
@@ -1,4 +1,24 @@
-// for every code segment there is a data-rehype-pretty-code-fragment and also a after element which is a copy button 
+// for every code segment there is a data-rehype-pretty-code-fragment and also a after element which is a copy button
 // so i need to write the logic where when user clicks on the copy button the code segment is copied to the clipboard
 // Legacy code-block title-bar click-to-copy removed.
-// Copy is now handled by explicit buttons (e.g. the python playground toolbar).
\ No newline at end of file
+// Copy is now handled by explicit buttons (e.g. the python playground toolbar).
+
+// Skip-to-content link for keyboard users. Injected as the first focusable
+// element so Tab on page load lands here, letting users bypass the nav.
+(function () {
+  function addSkipLink() {
+    if (document.querySelector(".skip-to-content")) return;
+    var target = document.getElementById("_top") || document.querySelector("main");
+    if (target && !target.id) target.id = "_top";
+    var link = document.createElement("a");
+    link.href = "#" + (target && target.id ? target.id : "_top");
+    link.className = "skip-to-content";
+    link.textContent = "Skip to content";
+    document.body.insertBefore(link, document.body.firstChild);
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", addSkipLink);
+  } else {
+    addSkipLink();
+  }
+})();
\ No newline at end of file
diff --git a/public/scripts/sidebar-enhance.js b/public/scripts/sidebar-enhance.js
new file mode 100644
index 00000000..36f905f4
--- /dev/null
+++ b/public/scripts/sidebar-enhance.js
@@ -0,0 +1,180 @@
+// Sidebar enhancements: live search, collapse/expand-all, and persisted
+// collapse state across page loads. Operates on Starlight's default sidebar
+// markup (ul.top-level > li > details/summary | a) rendered inside
+// .sidebar-content. No build-time coupling; runs on every full page load.
+(function () {
+  var STORAGE_KEY = "pch-sidebar-collapsed";
+
+  function ready(fn) {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", fn);
+    } else {
+      fn();
+    }
+  }
+
+  function loadState() {
+    try {
+      return JSON.parse(localStorage.getItem(STORAGE_KEY)) || {};
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function saveState(state) {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+    } catch (e) {
+      /* storage unavailable / full — ignore */
+    }
+  }
+
+  // Stable key for a <details> group: ancestor group labels joined by " / ".
+  function groupKey(details) {
+    var labels = [];
+    var cur = details;
+    while (cur) {
+      var summary = cur.querySelector(":scope > summary");
+      var span = summary && summary.querySelector(".group-label span");
+      labels.unshift(span ? span.textContent.trim() : "");
+      cur = cur.parentElement ? cur.parentElement.closest("details") : null;
+    }
+    return labels.join(" / ");
+  }
+
+  function init() {
+    var root = document.querySelector(".sidebar-content");
+    if (!root) return;
+    var list = root.querySelector("ul.top-level");
+    var search = document.getElementById("pch-sidebar-search");
+    var toggleAll = document.getElementById("pch-sidebar-toggle-all");
+    var noResults = document.getElementById("pch-sidebar-noresults");
+    if (!list) return;
+
+    var allDetails = function () {
+      return Array.prototype.slice.call(list.querySelectorAll("details"));
+    };
+
+    // --- Persisted collapse state ---------------------------------------
+    var state = loadState();
+
+    // Apply saved state. Never collapse a group that holds the current page.
+    allDetails().forEach(function (d) {
+      var key = groupKey(d);
+      if (!(key in state)) return;
+      var hasCurrent = !!d.querySelector('[aria-current="page"]');
+      if (state[key] === false && !hasCurrent) {
+        d.open = false;
+      } else if (state[key] === true) {
+        d.open = true;
+      }
+    });
+
+    // Persist on every user toggle.
+    allDetails().forEach(function (d) {
+      d.addEventListener("toggle", function () {
+        if (search && search.value.trim()) return; // ignore search-driven toggles
+        state[groupKey(d)] = d.open;
+        saveState(state);
+        syncToggleAllLabel();
+      });
+    });
+
+    // --- Collapse / Expand all ------------------------------------------
+    function syncToggleAllLabel() {
+      if (!toggleAll) return;
+      var anyOpen = allDetails().some(function (d) {
+        return d.open;
+      });
+      var label = toggleAll.querySelector(".pch-toggle-label");
+      if (label) label.textContent = anyOpen ? "Collapse all" : "Expand all";
+      toggleAll.setAttribute("aria-expanded", anyOpen ? "true" : "false");
+    }
+
+    if (toggleAll) {
+      toggleAll.addEventListener("click", function () {
+        var anyOpen = allDetails().some(function (d) {
+          return d.open;
+        });
+        var open = !anyOpen; // if any open -> collapse all, else expand all
+        allDetails().forEach(function (d) {
+          d.open = open;
+          state[groupKey(d)] = open;
+        });
+        saveState(state);
+        syncToggleAllLabel();
+      });
+      syncToggleAllLabel();
+    }
+
+    // --- Live search -----------------------------------------------------
+    // Returns true if the li (link or group) matches and should stay visible.
+    function filterLi(li, q) {
+      var details = li.querySelector(":scope > details");
+      if (details) {
+        var childMatch = false;
+        var childItems = details.querySelectorAll(":scope > ul > li");
+        Array.prototype.forEach.call(childItems, function (child) {
+          if (filterLi(child, q)) childMatch = true;
+        });
+        // Group label itself can match too.
+        var lbl = details.querySelector(":scope > summary .group-label span");
+        var selfMatch = lbl && lbl.textContent.toLowerCase().indexOf(q) !== -1;
+        var visible = childMatch || selfMatch;
+        li.classList.toggle("pch-hidden", !visible);
+        if (visible) details.open = true; // expand to reveal matches
+        return visible;
+      }
+      var link = li.querySelector(":scope > a");
+      var match = link && link.textContent.toLowerCase().indexOf(q) !== -1;
+      li.classList.toggle("pch-hidden", !match);
+      return !!match;
+    }
+
+    function restoreFromState() {
+      allDetails().forEach(function (d) {
+        var key = groupKey(d);
+        var hasCurrent = !!d.querySelector('[aria-current="page"]');
+        if (key in state) {
+          d.open = state[key] === true || hasCurrent;
+        }
+      });
+    }
+
+    if (search) {
+      search.addEventListener("input", function () {
+        var q = search.value.trim().toLowerCase();
+        if (!q) {
+          // clear filter, restore persisted collapse state
+          Array.prototype.forEach.call(
+            list.querySelectorAll("li.pch-hidden"),
+            function (li) {
+              li.classList.remove("pch-hidden");
+            }
+          );
+          restoreFromState();
+          syncToggleAllLabel();
+          if (noResults) noResults.hidden = true;
+          return;
+        }
+        var any = false;
+        var topItems = list.querySelectorAll(":scope > li");
+        Array.prototype.forEach.call(topItems, function (li) {
+          if (filterLi(li, q)) any = true;
+        });
+        if (noResults) noResults.hidden = any;
+      });
+
+      // Esc clears the search.
+      search.addEventListener("keydown", function (e) {
+        if (e.key === "Escape" && search.value) {
+          e.preventDefault();
+          search.value = "";
+          search.dispatchEvent(new Event("input"));
+        }
+      });
+    }
+  }
+
+  ready(init);
+})();
diff --git a/public/scripts/toast.js b/public/scripts/toast.js
index 027cc490..146fcb52 100644
--- a/public/scripts/toast.js
+++ b/public/scripts/toast.js
@@ -21,21 +21,41 @@
   }
 
   function show(opts){
-    const { title = '', description = '', variant = 'info', duration = 4000 } = opts || {};
+    const { title = '', description = '', variant = 'info', duration = 4000, html = false } = opts || {};
     const root = ensureRoot();
     const toast = document.createElement('div');
     toast.className = `toast toast--${variant} toast-show`;
 
-    toast.innerHTML = `
-      <div class="toast-icon">${iconForVariant(variant)}</div>
-      <div class="toast-body">
-        <div class="toast-title">${escapeHtml(title)}</div>
-        ${description ? `<div class="toast-desc">${escapeHtml(description)}</div>` : ''}
-      </div>
-      <button class="toast-close" aria-label="Dismiss">\u2715</button>
-    `;
+    // Build DOM structure without ever injecting untrusted strings as markup.
+    const icon = document.createElement('div');
+    icon.className = 'toast-icon';
+    icon.textContent = iconForVariant(variant);
+
+    const body = document.createElement('div');
+    body.className = 'toast-body';
+
+    const titleEl = document.createElement('div');
+    titleEl.className = 'toast-title';
+    // Markup only via explicit opt-in. Default is safe text.
+    if(html){ titleEl.innerHTML = title; } else { titleEl.textContent = title; }
+    body.appendChild(titleEl);
+
+    if(description){
+      const descEl = document.createElement('div');
+      descEl.className = 'toast-desc';
+      if(html){ descEl.innerHTML = description; } else { descEl.textContent = description; }
+      body.appendChild(descEl);
+    }
+
+    const closeBtn = document.createElement('button');
+    closeBtn.className = 'toast-close';
+    closeBtn.setAttribute('aria-label', 'Dismiss');
+    closeBtn.textContent = '\u2715';
+
+    toast.appendChild(icon);
+    toast.appendChild(body);
+    toast.appendChild(closeBtn);
 
-    const closeBtn = toast.querySelector('.toast-close');
     const hide = (animate=true)=>{
       if(!toast.__hidden){
         toast.__hidden = true;
@@ -62,14 +82,5 @@
     };
   }
 
-  function escapeHtml(s){
-    return String(s)
-      .replace(/&/g,'&amp;')
-      .replace(/</g,'&lt;')
-      .replace(/>/g,'&gt;')
-      .replace(/"/g,'&quot;')
-      .replace(/'/g,'&#039;');
-  }
-
   window.toast = window.toast || { show };
 })();
diff --git a/src/components/Contact.astro b/src/components/Contact.astro
index 700bd111..04837113 100644
--- a/src/components/Contact.astro
+++ b/src/components/Contact.astro
@@ -1,5 +1,7 @@
 ---
-
+// reCAPTCHA v3 site key (optional). Exposed to the client only when set.
+// Set PUBLIC_RECAPTCHA_SITE_KEY in your environment to enable bot protection.
+const recaptchaSiteKey = import.meta.env.PUBLIC_RECAPTCHA_SITE_KEY;
 ---
 
 <section class="bg-white dark:bg-gray-900">
@@ -11,19 +13,36 @@
       Suggestions? We'd love to hear from you. Send us a message and we'll
       respond as soon as possible.
     </p>
-    <form class="space-y-8" id="contactForm" method="POST">
+    <noscript>
+      <p
+        class="mb-6 p-3 rounded-lg text-center text-sm bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-200"
+      >
+        This contact form requires JavaScript to be enabled. Please enable
+        JavaScript, or email us directly at
+        <a class="underline" href="mailto:ravikishan63392@gmail.com"
+          >ravikishan63392@gmail.com</a
+        >.
+      </p>
+    </noscript>
+    <form
+      class="space-y-8"
+      id="contactForm"
+      method="POST"
+      data-recaptcha-key={recaptchaSiteKey ?? ""}
+    >
       <div>
         <label
           for="email"
           class="block mb-2 text-lg font-bold font-poppins text-gray-900 dark:text-gray-300"
-          >Your email</label
+          >Your email <span class="text-red-500" aria-hidden="true">*</span></label
         >
         <input
           type="email"
           id="email"
           name="email"
+          aria-required="true"
           class="shadow-sm bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-primary-500 focus:border-primary-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-primary-500 dark:focus:border-primary-500 dark:shadow-sm-light"
-          placeholder="name@flowbite.com"
+          placeholder="you@example.com"
           required
         />
       </div>
@@ -31,14 +50,15 @@
         <label
           for="name"
           class="block mb-2 text-lg font-bold font-poppins text-gray-900 dark:text-gray-300"
-          >Name</label
+          >Name <span class="text-red-500" aria-hidden="true">*</span></label
         >
         <input
           type="text"
           id="name"
           name="name"
+          aria-required="true"
           class="block p-3 w-full text-sm text-gray-900 bg-gray-50 rounded-lg border border-gray-300 shadow-sm focus:ring-primary-500 focus:border-primary-500 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-primary-500 dark:focus:border-primary-500 dark:shadow-sm-light"
-          placeholder="John Doe"
+          placeholder="Your full name"
           required
         />
       </div>
@@ -46,25 +66,41 @@
         <label
           for="message"
           class="block mb-2 text-lg font-bold font-poppins text-gray-900 dark:text-gray-300"
-          >Your message</label
+          >Your message <span class="text-red-500" aria-hidden="true">*</span></label
         >
         <textarea
           id="message"
           rows="6"
           name="message"
+          aria-required="true"
           class="block p-2.5 w-full text-sm text-gray-900 bg-gray-50 rounded-lg shadow-sm border border-gray-300 focus:ring-primary-500 focus:border-primary-500 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-primary-500 dark:focus:border-primary-500"
-          placeholder="Leave a comment..."
+          placeholder="Describe your issue, question, or feedback..."
           required></textarea>
       </div>
+      <div id="contactFormError" role="alert" aria-live="polite" class="sr-only"></div>
       <button
+        id="contactSubmit"
         type="submit"
-        class="py-3 px-5 text-sm font-medium text-center text-gray-900 dark:text-white rounded-lg bg-primary-700 sm:w-fit hover:bg-primary-800 focus:ring-4 focus:outline-none focus:ring-primary-300 dark:bg-primary-600 dark:hover:bg-primary-700 dark:focus:ring-primary-800 cursor-pointer"
-        >Send message</button
+        class="inline-flex items-center justify-center gap-2 py-3 px-5 text-sm font-medium text-center text-gray-900 dark:text-white rounded-lg bg-primary-700 sm:w-fit hover:bg-primary-800 focus:ring-4 focus:outline-none focus:ring-primary-300 dark:bg-primary-600 dark:hover:bg-primary-700 dark:focus:ring-primary-800 cursor-pointer disabled:opacity-60 disabled:cursor-not-allowed"
       >
+        <span
+          id="contactSpinner"
+          class="hidden w-4 h-4 border-2 border-current border-t-transparent rounded-full animate-spin"
+          aria-hidden="true"></span>
+        <span id="contactSubmitText">Send message</span>
+      </button>
     </form>
   </div>
 </section>
 
+{recaptchaSiteKey && (
+  <script
+    is:inline
+    src={`https://www.google.com/recaptcha/api.js?render=${recaptchaSiteKey}`}
+    async
+  />
+)}
+
 <script type="module">
   // Import the functions you need from the SDKs you need
   // @ts-ignore
@@ -95,41 +131,66 @@
   const db = getFirestore(app);
 
   function uuidv4() {
-    return Date.now().toString(36) + Math.random().toString(36).substr(2);
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    // Fallback for very old browsers.
+    return Date.now().toString(36) + Math.random().toString(36).slice(2);
   }
 
-  // Reference messages collection
-  // var messagesRef = firebase.database().ref("contact");
-
-  // Listen for form submit
   // @ts-ignore
-  document.getElementById("contactForm").addEventListener("submit", submitForm);
-
-  // Submit form
+  const form = document.getElementById("contactForm");
   // @ts-ignore
-  function submitForm(e) {
-    e.preventDefault();
-
-    // Get values
-    var name = getInputVal("name");
-    var email = getInputVal("email");
-    var message = getInputVal("message");
-
-    // Save message
-    saveMessage(name, email, message);
+  const submitBtn = document.getElementById("contactSubmit");
+  // @ts-ignore
+  const spinner = document.getElementById("contactSpinner");
+  // @ts-ignore
+  const submitText = document.getElementById("contactSubmitText");
+  // @ts-ignore
+  const errorRegion = document.getElementById("contactFormError");
+  // @ts-ignore
+  const recaptchaKey = form ? form.dataset.recaptchaKey : "";
 
-    //show alert
-    alert(
-      "Thank you for your message! We will get back to you as soon as possible."
-    );
+  // Notify the user via toast (if available) and the aria-live region.
+  // @ts-ignore
+  function notify(title, description, variant) {
+    // @ts-ignore
+    if (window.toast && typeof window.toast.show === "function") {
+      // @ts-ignore
+      window.toast.show({ title, description, variant });
+    }
+    if (errorRegion) {
+      // @ts-ignore
+      errorRegion.textContent = description || title;
+    }
+  }
 
+  // @ts-ignore
+  function setLoading(isLoading) {
+    if (!submitBtn || !spinner || !submitText) return;
+    // @ts-ignore
+    submitBtn.disabled = isLoading;
+    spinner.classList.toggle("hidden", !isLoading);
     // @ts-ignore
-    const form = document.getElementById("contactForm");
+    submitText.textContent = isLoading ? "Sending..." : "Send message";
+  }
+
+  // Fetch a reCAPTCHA v3 token (empty string if not configured/available).
+  // @ts-ignore
+  async function getRecaptchaToken() {
     // @ts-ignore
-    form.reset();
+    if (!recaptchaKey || !window.grecaptcha) return "";
+    try {
+      // @ts-ignore
+      await new Promise((resolve) => window.grecaptcha.ready(resolve));
+      // @ts-ignore
+      return await window.grecaptcha.execute(recaptchaKey, { action: "contact" });
+    } catch {
+      return "";
+    }
   }
 
-  // Function to get get form values
+  // Function to get form values
   // @ts-ignore
   function getInputVal(id) {
     const element = document.getElementById(id);
@@ -139,11 +200,51 @@
 
   // Save message to firebase
   // @ts-ignore
-  function saveMessage(name, email, message) {
-    setDoc(doc(db, "contact", uuidv4()), {
+  async function saveMessage(name, email, message, recaptchaToken) {
+    await setDoc(doc(db, "contact", uuidv4()), {
       name: name,
       email: email,
       message: message,
+      recaptchaToken: recaptchaToken,
+      createdAt: new Date().toISOString(),
     });
   }
+
+  // Submit form
+  // @ts-ignore
+  async function submitForm(e) {
+    e.preventDefault();
+    if (errorRegion) errorRegion.textContent = "";
+    setLoading(true);
+
+    try {
+      const name = getInputVal("name");
+      const email = getInputVal("email");
+      const message = getInputVal("message");
+      const recaptchaToken = await getRecaptchaToken();
+
+      await saveMessage(name, email, message, recaptchaToken);
+
+      notify(
+        "Message sent",
+        "Thank you for your message! We will get back to you as soon as possible.",
+        "success"
+      );
+      // @ts-ignore
+      if (form) form.reset();
+    } catch (err) {
+      console.error("[contact] submit failed:", err);
+      notify(
+        "Something went wrong",
+        "We couldn't send your message. Please try again later.",
+        "error"
+      );
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Listen for form submit
+  // @ts-ignore
+  if (form) form.addEventListener("submit", submitForm);
 </script>
diff --git a/src/components/DataCampExercise.astro b/src/components/DataCampExercise.astro
index f5d1c5bb..6f572122 100644
--- a/src/components/DataCampExercise.astro
+++ b/src/components/DataCampExercise.astro
@@ -211,7 +211,8 @@ window.addEventListener("DOMContentLoaded", function () {
       // ── Auto-resize iframe from postMessage ────────────────────────────────
       function onMsg(e) {
         const data = e && e.data;
-        if (!data || data.type !== "pythoncentralhub-dcl-height") return;
+        if (!data || typeof data !== "object") return;
+        if (data.type !== "pythoncentralhub-dcl-height") return;
         const id = data.id;
         const height = Number(data.height);
         if (!id || !Number.isFinite(height) || height <= 0) return;
diff --git a/src/components/Feedback.astro b/src/components/Feedback.astro
index a66f0742..763dccb3 100644
--- a/src/components/Feedback.astro
+++ b/src/components/Feedback.astro
@@ -1,12 +1,20 @@
 ---
-
+// reCAPTCHA v3 site key (optional). Exposed to the client only when set.
+const recaptchaSiteKey = import.meta.env.PUBLIC_RECAPTCHA_SITE_KEY;
 ---
 
 <div class="app">
   <h1>Was this page helpful?</h1>
   <p>Let us know how we did</p>
 
-  <form class="container" id="contactForm">
+  <noscript>
+    <p
+      class="block mb-4 p-3 rounded-lg text-center text-sm bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-200"
+    >
+      Submitting feedback requires JavaScript to be enabled.
+    </p>
+  </noscript>
+  <form class="container" id="feedbackForm" data-recaptcha-key={recaptchaSiteKey ?? ""}>
     <div class="item">
       <label for="0">
         <input class="radio" type="radio" name="feedback" id="0" value="1" />
@@ -46,13 +54,14 @@
       <label
         for="email"
         class="block mb-2 text-start text-sm font-poppins font-bold text-gray-900 dark:text-white"
-        >Email</label
+        >Email <span class="text-red-500" aria-hidden="true">*</span></label
       >
       <input
         type="email"
         id="email"
+        aria-required="true"
         class="bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500"
-        placeholder="john@email.com"
+        placeholder="you@example.com"
         required
         name="email"
       />
@@ -60,24 +69,32 @@
 
     <div class="w-full flex flex-col mb-4 justify-start">
       <label
-        for="first_name"
+        for="comment"
         class="block mb-2 text-start text-sm font-poppins font-bold text-gray-900 dark:text-white"
-        >Comment</label
+        >Comment <span class="text-red-500" aria-hidden="true">*</span></label
       >
       <textarea
         id="comment"
+        aria-required="true"
         class="bg-gray-50 border border-gray-300 text-gray-900 text-sm rounded-lg focus:ring-blue-500 focus:border-blue-500 block w-full p-2.5 dark:bg-gray-700 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white dark:focus:ring-blue-500 dark:focus:border-blue-500"
-        placeholder="Write some about you opinion...."
+        placeholder="Share your opinion about this page..."
         required
         name="comment"></textarea>
     </div>
 
+    <div id="feedbackFormError" role="alert" aria-live="polite" class="sr-only"></div>
+
     <div class="flex justify-end w-full">
       <button
+        id="feedbackSubmit"
         type="submit"
-        class="bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline cursor-pointer"
+        class="inline-flex items-center justify-center gap-2 bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline cursor-pointer disabled:opacity-60 disabled:cursor-not-allowed"
       >
-        Submit
+        <span
+          id="feedbackSpinner"
+          class="hidden w-4 h-4 border-2 border-current border-t-transparent rounded-full animate-spin"
+          aria-hidden="true"></span>
+        <span id="feedbackSubmitText">Submit</span>
       </button>
     </div>
   </form>
@@ -116,14 +133,21 @@
     align-items: center;
     user-select: none;
   }
+  /* Keep radios in the DOM & focusable (was display:none) so keyboard
+     users can tab to them; visually hidden behind the emoji label. */
   .radio {
-    display: none;
+    position: absolute;
+    opacity: 0;
+    width: 1px;
+    height: 1px;
+    margin: 0;
   }
   .radio ~ span {
     font-size: 3rem;
     filter: grayscale(100);
     cursor: pointer;
     transition: 0.3s;
+    border-radius: 0.5rem;
   }
 
   .radio:checked ~ span {
@@ -131,6 +155,12 @@
     font-size: 4rem;
   }
 
+  /* Visible focus ring for keyboard users. */
+  .radio:focus-visible ~ span {
+    outline: 2px solid var(--sl-color-accent-high);
+    outline-offset: 4px;
+  }
+
   @media screen and (max-width: 500px) {
     .item {
       width: 50px;
@@ -145,6 +175,14 @@
   }
 </style>
 
+{recaptchaSiteKey && (
+  <script
+    is:inline
+    src={`https://www.google.com/recaptcha/api.js?render=${recaptchaSiteKey}`}
+    async
+  />
+)}
+
 <script type="module">
   // @ts-ignore
   import { initializeApp } from "https://www.gstatic.com/firebasejs/10.7.2/firebase-app.js";
@@ -175,51 +213,120 @@
 
   // @ts-ignore
   function uuidv4() {
-    return Date.now().toString(36) + Math.random().toString(36).substr(2);
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    // Fallback for very old browsers.
+    return Date.now().toString(36) + Math.random().toString(36).slice(2);
   }
 
-  // Reference messages collection
-  // var messagesRef = firebase.database().ref("contact");
-
-  // Listen for form submit
   // @ts-ignore
-  document.getElementById("contactForm").addEventListener("submit", submitForm);
-
-  // Submit form
+  const form = document.getElementById("feedbackForm");
   // @ts-ignore
-  function submitForm(e) {
-    e.preventDefault();
+  const submitBtn = document.getElementById("feedbackSubmit");
+  // @ts-ignore
+  const spinner = document.getElementById("feedbackSpinner");
+  // @ts-ignore
+  const submitText = document.getElementById("feedbackSubmitText");
+  // @ts-ignore
+  const errorRegion = document.getElementById("feedbackFormError");
+  // @ts-ignore
+  const recaptchaKey = form ? form.dataset.recaptchaKey : "";
 
-    // Get values
+  // @ts-ignore
+  function notify(title, description, variant) {
     // @ts-ignore
-    var feedback = this.feedback.value;
+    if (window.toast && typeof window.toast.show === "function") {
+      // @ts-ignore
+      window.toast.show({ title, description, variant });
+    }
+    if (errorRegion) {
+      // @ts-ignore
+      errorRegion.textContent = description || title;
+    }
+  }
+
+  // @ts-ignore
+  function setLoading(isLoading) {
+    if (!submitBtn || !spinner || !submitText) return;
     // @ts-ignore
-    var email = this.email.value;
+    submitBtn.disabled = isLoading;
+    spinner.classList.toggle("hidden", !isLoading);
     // @ts-ignore
-    var comment = this.comment.value;
-
-    // Save message
-    saveMessage(feedback, email, comment);
-
-    //show alert
-    alert(
-      "Thank you for your feedback. We will use it to improve our website."
-    );
+    submitText.textContent = isLoading ? "Submitting..." : "Submit";
+  }
 
-    // Clear form
-    // @ts-ignore
-    const contactForm = document.getElementById("contactForm");
+  // @ts-ignore
+  async function getRecaptchaToken() {
     // @ts-ignore
-    contactForm.reset();
+    if (!recaptchaKey || !window.grecaptcha) return "";
+    try {
+      // @ts-ignore
+      await new Promise((resolve) => window.grecaptcha.ready(resolve));
+      // @ts-ignore
+      return await window.grecaptcha.execute(recaptchaKey, { action: "feedback" });
+    } catch {
+      return "";
+    }
   }
 
   // Save message to firebase
   // @ts-ignore
-  function saveMessage(feedback, email, comment) {
-    setDoc(doc(db, "feedback", uuidv4()), {
+  async function saveMessage(feedback, email, comment, recaptchaToken) {
+    await setDoc(doc(db, "feedback", uuidv4()), {
       feedback: feedback,
       email: email,
       comment: comment,
+      recaptchaToken: recaptchaToken,
+      createdAt: new Date().toISOString(),
     });
   }
+
+  // Submit form
+  // @ts-ignore
+  async function submitForm(e) {
+    e.preventDefault();
+    if (errorRegion) errorRegion.textContent = "";
+
+    // @ts-ignore
+    const feedbackField = this.feedback;
+    // @ts-ignore
+    const feedback = feedbackField ? feedbackField.value : "";
+    if (!feedback) {
+      notify("Please rate us", "Select an emoji before submitting.", "error");
+      return;
+    }
+    setLoading(true);
+
+    try {
+      // @ts-ignore
+      const email = this.email.value;
+      // @ts-ignore
+      const comment = this.comment.value;
+      const recaptchaToken = await getRecaptchaToken();
+
+      await saveMessage(feedback, email, comment, recaptchaToken);
+
+      notify(
+        "Feedback received",
+        "Thank you for your feedback. We will use it to improve our website.",
+        "success"
+      );
+      // @ts-ignore
+      if (form) form.reset();
+    } catch (err) {
+      console.error("[feedback] submit failed:", err);
+      notify(
+        "Something went wrong",
+        "We couldn't submit your feedback. Please try again later.",
+        "error"
+      );
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  // Listen for form submit
+  // @ts-ignore
+  if (form) form.addEventListener("submit", submitForm);
 </script>
diff --git a/src/components/Footer.astro b/src/components/Footer.astro
index e7a79508..4de61952 100644
--- a/src/components/Footer.astro
+++ b/src/components/Footer.astro
@@ -90,6 +90,11 @@ import BuyMeCoffee from "./BuyMeCoffee.astro";
     cursor: pointer;
     transition: all 0.2s ease-in-out;
   }
+  #print:focus-visible,
+  #share:focus-visible {
+    outline: 2px solid var(--sl-color-accent-high);
+    outline-offset: 2px;
+  }
   #printIcon,
   #shareIcon {
     transition: all 0.2s ease-in-out;
@@ -102,11 +107,66 @@ import BuyMeCoffee from "./BuyMeCoffee.astro";
   }
 </style>
 
+<style is:global>
+  /* Print: hide site chrome, show only the article content. No DOM mutation. */
+  @media print {
+    header.header,
+    nav.sidebar,
+    .sidebar-pane,
+    .right-sidebar,
+    .right-sidebar-container,
+    .pagination-links,
+    starlight-menu-button,
+    site-search,
+    .mobile-preferences,
+    #optionButtons,
+    #feedback,
+    #buymecoffee,
+    .sl-flex.print-hide {
+      display: none !important;
+    }
+
+    .main-pane {
+      width: 100% !important;
+      max-width: 100% !important;
+    }
+
+    main,
+    .main-frame {
+      padding: 0 !important;
+      margin: 0 !important;
+    }
+
+    body {
+      background: #fff !important;
+      color: #000 !important;
+    }
+  }
+</style>
+
 <script>
   const share = document.getElementById("share");
   const shareText = document.getElementById("shareText");
   const shareIcon = document.getElementById("shareIcon");
   if (share && shareText && shareIcon) {
+    const copyFallback = () => {
+      navigator.clipboard
+        .writeText(window.location.href)
+        .then(() => {
+          shareText.innerText = "Link copied!";
+          shareIcon.style.fill = "#90EE90";
+          (window as any).toast?.show({
+            title: "Link copied",
+            description: "Page URL copied to clipboard.",
+            variant: "success",
+          });
+        })
+        .catch(() => {
+          shareText.innerText = "Error!";
+          shareIcon.style.fill = "#FF7F7F";
+        });
+    };
+
     share.addEventListener("click", () => {
       if (navigator.share) {
         navigator
@@ -119,32 +179,21 @@ import BuyMeCoffee from "./BuyMeCoffee.astro";
             shareIcon.style.fill = "#90EE90";
           })
           .catch(() => {
-            shareText.innerText = "Error!";
-            shareIcon.style.fill = "#FF7F7F";
+            // User abort or unsupported share target → fall back to copy.
+            copyFallback();
           });
       } else {
-        shareText.innerText = "Not supported!";
-        shareIcon.style.fill = "#FF7F7F";
+        copyFallback();
       }
     });
   }
 
   const print = document.getElementById("print");
-  const printText = document.getElementById("printText");
-  const printIcon = document.getElementById("printIcon");
-  const heading = document.getElementById("_top");
-
-  const mainPage = document.querySelector(".main-pane");
 
   function printPage() {
-    if (heading && mainPage && print && printText && printIcon) {
-      const mainContent = document.body.innerHTML;
-      const printContent = mainPage as HTMLElement;
-      document.body.innerHTML = printContent.innerHTML;
-      window.print();
-      document.body.innerHTML = mainContent;
-      window.location.reload();
-    }
+    // No DOM mutation / reload. The @media print stylesheet hides chrome,
+    // leaving only the main content visible for the native print dialog.
+    window.print();
   }
   if (print) {
     print.addEventListener("click", printPage);
diff --git a/src/components/Head.astro b/src/components/Head.astro
new file mode 100644
index 00000000..a329d8e8
--- /dev/null
+++ b/src/components/Head.astro
@@ -0,0 +1,73 @@
+---
+import type { Props } from "@astrojs/starlight/props";
+import Default from "@astrojs/starlight/components/Head.astro";
+
+const { entry } = Astro.props;
+const data = entry?.data ?? ({} as Record<string, any>);
+
+const siteUrl = Astro.site?.href?.replace(/\/$/, "") ?? "";
+const pageUrl = new URL(Astro.url.pathname, Astro.site ?? Astro.url).href;
+const path = Astro.url.pathname;
+
+// Map the content section to a schema.org type.
+let articleType = "TechArticle";
+if (path.includes("/tutorials/")) articleType = "TechArticle";
+else if (path.includes("/projects/")) articleType = "HowTo";
+else if (path.includes("/guides/")) articleType = "TechArticle";
+
+const article = {
+  "@context": "https://schema.org",
+  "@type": articleType,
+  headline: data.title ?? "Python Central Hub",
+  description: data.description ?? "",
+  url: pageUrl,
+  inLanguage: "en",
+  author: { "@type": "Person", name: "Ravi Kishan" },
+  publisher: {
+    "@type": "Organization",
+    name: "Python Central Hub",
+    url: siteUrl,
+  },
+};
+
+// Build a BreadcrumbList from the URL path segments.
+const segments = path.split("/").filter(Boolean);
+let acc = "";
+const breadcrumbItems = [
+  {
+    "@type": "ListItem",
+    position: 1,
+    name: "Home",
+    item: `${siteUrl}/`,
+  },
+  ...segments.map((seg, i) => {
+    acc += `/${seg}`;
+    const name = decodeURIComponent(seg)
+      .replace(/[-_]/g, " ")
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+    return {
+      "@type": "ListItem",
+      position: i + 2,
+      name,
+      item: `${siteUrl}${acc}/`,
+    };
+  }),
+];
+
+const breadcrumbs = {
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  itemListElement: breadcrumbItems,
+};
+---
+
+<Default {...Astro.props}><slot /></Default>
+
+<script type="application/ld+json" set:html={JSON.stringify(article)} is:inline />
+{segments.length > 0 && (
+  <script
+    type="application/ld+json"
+    set:html={JSON.stringify(breadcrumbs)}
+    is:inline
+  />
+)}
diff --git a/src/components/Sidebar.astro b/src/components/Sidebar.astro
new file mode 100644
index 00000000..2f75e42a
--- /dev/null
+++ b/src/components/Sidebar.astro
@@ -0,0 +1,113 @@
+---
+// Custom sidebar override: adds a search box + collapse/expand-all control
+// above Starlight's default sidebar, then renders the default sidebar
+// unchanged. Behaviour lives in /scripts/sidebar-enhance.js.
+import type { Props } from "@astrojs/starlight/props";
+import Default from "@astrojs/starlight/components/Sidebar.astro";
+---
+
+<div class="pch-sidebar-tools">
+  <div class="pch-search-row">
+    <i class="fas fa-search pch-search-icon" aria-hidden="true"></i>
+    <input
+      id="pch-sidebar-search"
+      class="pch-sidebar-search"
+      type="search"
+      placeholder="Search menu…"
+      aria-label="Search sidebar menu"
+      autocomplete="off"
+    />
+  </div>
+  <button
+    id="pch-sidebar-toggle-all"
+    class="pch-sidebar-toggle-all"
+    type="button"
+    aria-expanded="true"
+  >
+    <i class="fas fa-angles-up" aria-hidden="true"></i>
+    <span class="pch-toggle-label">Collapse all</span>
+  </button>
+  <p id="pch-sidebar-noresults" class="pch-sidebar-noresults" hidden>
+    No matching pages
+  </p>
+</div>
+
+<Default {...Astro.props}><slot /></Default>
+
+<script src="/scripts/sidebar-enhance.js"></script>
+
+<style is:global>
+  .pch-sidebar-tools {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    margin-bottom: 0.25rem;
+  }
+
+  .pch-search-row {
+    position: relative;
+    display: flex;
+    align-items: center;
+  }
+
+  .pch-search-icon {
+    position: absolute;
+    inset-inline-start: 0.6rem;
+    font-size: 0.8rem;
+    color: var(--sl-color-gray-3);
+    pointer-events: none;
+  }
+
+  .pch-sidebar-search {
+    width: 100%;
+    padding: 0.45rem 0.6rem 0.45rem 1.9rem;
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: 0.5rem;
+    background-color: var(--sl-color-black);
+    color: var(--sl-color-white);
+    font-size: var(--sl-text-sm);
+    line-height: 1.4;
+  }
+
+  .pch-sidebar-search:focus {
+    outline: none;
+    border-color: var(--sl-color-text-accent);
+    box-shadow: 0 0 0 1px var(--sl-color-text-accent);
+  }
+
+  .pch-sidebar-search::placeholder {
+    color: var(--sl-color-gray-3);
+  }
+
+  .pch-sidebar-toggle-all {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    align-self: flex-start;
+    padding: 0.3rem 0.6rem;
+    border: 1px solid var(--sl-color-hairline);
+    border-radius: 0.5rem;
+    background-color: transparent;
+    color: var(--sl-color-gray-1);
+    font-size: var(--sl-text-xs);
+    cursor: pointer;
+  }
+
+  .pch-sidebar-toggle-all:hover,
+  .pch-sidebar-toggle-all:focus-visible {
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-text-accent);
+  }
+
+  .pch-sidebar-noresults {
+    margin: 0;
+    padding: 0.25rem 0.1rem;
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-3);
+  }
+
+  /* Search filtering: hidden sidebar entries. */
+  .sidebar-content li.pch-hidden {
+    display: none;
+  }
+</style>
diff --git a/src/components/YoutuberCard.astro b/src/components/YoutuberCard.astro
index 0867e466..ffcb093f 100644
--- a/src/components/YoutuberCard.astro
+++ b/src/components/YoutuberCard.astro
@@ -8,12 +8,12 @@ const {coverImg, profileImg, name, channelLink} = Astro.props;
     max-width: 700px;
     width: 100%;
     overflow: hidden;
-    background: #fff;
+    background: var(--sl-color-bg-nav);
     border-radius: 10px;
     box-shadow: 0 0 20px rgba(0, 0, 0, 0.5);
     display: flex;
     flex-direction: column;
-    color: #222;
+    color: var(--sl-color-text);
   }
 
   .card-image img {
@@ -34,7 +34,7 @@ const {coverImg, profileImg, name, channelLink} = Astro.props;
     margin-left: auto;
     margin-right: auto;
     border-radius: 100px;
-    border: 10px solid #fff;
+    border: 10px solid var(--sl-color-bg-nav);
     transition-duration: 0.4s;
     transition-property: transform;
   }
@@ -53,7 +53,7 @@ const {coverImg, profileImg, name, channelLink} = Astro.props;
   .card-content h3 {
     font-size: 25px;
     text-align: center;
-    color: #222;
+    color: var(--sl-color-text);
     font-family: "Poppins", sans-serif;
     font-weight: bold;
     margin-top: -20px;
@@ -83,21 +83,22 @@ const {coverImg, profileImg, name, channelLink} = Astro.props;
   <div class="card-image">
     <img
       src=`${coverImg}`
-      alt=`${coverImg}-${name}`
+      alt={`${name} channel cover image`}
     />
   </div>
   <div class="profile-image">
     <img
       src=`${profileImg}`
-      alt=`${profileImg}-${name}`
+      alt={`${name} profile picture`}
     />
   </div>
   <div class="card-content">
     <h3>
         {name}
     </h3>
-    <a class="subscribe" 
+    <a class="subscribe"
     target="_blank"
+    rel="noopener noreferrer"
     href=`${channelLink}`>Subscribe</a>
   </div>
 </div>
diff --git a/src/content/docs/404.mdx b/src/content/docs/404.mdx
index 073cc1d7..6e083de6 100644
--- a/src/content/docs/404.mdx
+++ b/src/content/docs/404.mdx
@@ -17,4 +17,34 @@ hero:
       icon: github
 ---
 
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
+## Looking for something?
+
+Use the search bar at the top of the page, or jump straight to one of our main
+sections:
+
+<CardGrid>
+  <LinkCard
+    title="Guides"
+    description="Set up Python and learn the fundamentals."
+    href="/guides/home/"
+  />
+  <LinkCard
+    title="Tutorials"
+    description="Step-by-step lessons on core Python topics."
+    href="/tutorials/introduction/"
+  />
+  <LinkCard
+    title="Projects"
+    description="Hands-on projects from beginner to advanced."
+    href="/projects/beginners/helloworld/"
+  />
+  <LinkCard
+    title="Reference"
+    description="Quick lookups, cheat sheets, and more."
+    href="/reference/contact/"
+  />
+</CardGrid>
+
+Think this page should exist? [Open an issue or edit it on GitHub](https://github.com/Ravikisha/PythonCentralHub/issues/new).
diff --git a/src/content/docs/projects/Beginners/emailsender.mdx b/src/content/docs/projects/Beginners/emailsender.mdx
index 71e379c3..deb64db5 100644
--- a/src/content/docs/projects/Beginners/emailsender.mdx
+++ b/src/content/docs/projects/Beginners/emailsender.mdx
@@ -26,10 +26,10 @@ You will learn:
 - Python 3.6 or above.
 - A text editor or IDE.
 - A Gmail account with **2-Step Verification** enabled.
-- An **App Password** generated at <https://myaccount.google.com/apppasswords>.
+- An **App Password** generated at [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords).
 
 ## Set Up Gmail App Password
-1. Visit <https://myaccount.google.com/security>.
+1. Visit [myaccount.google.com/security](https://myaccount.google.com/security).
 2. Enable **2-Step Verification** (required to access App Passwords).
 3. Go to **App passwords** → generate a new one named "Python Mailer".
 4. Copy the 16-character code. This replaces your normal password in scripts.
diff --git a/src/content/docs/projects/Beginners/movie-recommendation-system.mdx b/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
index 82319070..8a612135 100644
--- a/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
+++ b/src/content/docs/projects/Beginners/movie-recommendation-system.mdx
@@ -223,7 +223,7 @@ Switch from explicit ratings (1-5 stars) to implicit (watched / not watched). Di
 After ranking, post-process to ensure variety — penalize candidates whose genres overlap heavily with already-shown items.
 
 ### 8. TMDB API integration
-Replace the hard-coded 20 movies with a fresh feed of currently-popular titles from <https://www.themoviedb.org/documentation/api>.
+Replace the hard-coded 20 movies with a fresh feed of currently-popular titles from [themoviedb.org/documentation/api](https://www.themoviedb.org/documentation/api).
 
 ### 9. Save & evaluate
 Hold out 20 % of ratings; measure RMSE on predicted vs. actual. The standard offline-evaluation pattern.
diff --git a/src/content/docs/projects/Beginners/quizapp.mdx b/src/content/docs/projects/Beginners/quizapp.mdx
index d89d16a2..908e163f 100644
--- a/src/content/docs/projects/Beginners/quizapp.mdx
+++ b/src/content/docs/projects/Beginners/quizapp.mdx
@@ -257,7 +257,7 @@ Useful for language quizzes — play a `.wav` clip and ask "what did the voice s
 Save `(timestamp, category, score)` rows to a JSON file. Show a "high scores" leaderboard at startup.
 
 ### 6. Online quiz bank
-Pull questions from <https://opentdb.com> (free trivia API).
+Pull questions from [opentdb.com](https://opentdb.com) (free trivia API).
 
 ### 7. Time per question
 Award more points for faster correct answers. Penalize wrong answers under time pressure to discourage random guessing.
diff --git a/src/content/docs/projects/intermediate/ai-task-manager.mdx b/src/content/docs/projects/intermediate/ai-task-manager.mdx
index a9fc9d79..c3305eb8 100644
--- a/src/content/docs/projects/intermediate/ai-task-manager.mdx
+++ b/src/content/docs/projects/intermediate/ai-task-manager.mdx
@@ -1,6 +1,6 @@
 ---
 title: AI-Powered Task Management System
-description: Build an intelligent task management system with machine learning-powered priority prediction, natural language processing, collaborative features, and real-time web interface
+description: Build an ML-driven task manager in Python — predict task priority with TF-IDF + logistic regression on combined text and engineered features, VADER sentiment, NLP time-estimate extraction, bcrypt auth, and a real-time Flask-SocketIO interface.
 sidebar:
   order: 65
 hero:
@@ -13,288 +13,146 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This is a task manager that *learns*. Instead of you setting priorities by hand, a machine-learning model reads each task's title and description and predicts how urgent it is — trained on your own completed tasks. Under the hood it blends classic NLP (TF-IDF text vectorization, VADER sentiment, keyword and regex feature extraction) with a logistic-regression classifier, then wraps it in a collaborative, real-time Flask-SocketIO app with proper bcrypt authentication. It's the project that shows how "AI features" are actually built: feature engineering + a simple model + a feedback loop.
 
-Create an intelligent task management system that uses machine learning to predict task priorities, performs sentiment analysis on task descriptions, provides AI-powered productivity recommendations, and offers real-time collaborative features through a modern web interface. This project demonstrates advanced AI integration, web development, and database design.
+You will leave understanding:
+- How to turn free text into model features with **TF-IDF**, and combine them with **hand-engineered numeric features**.
+- Why logistic regression is a fine first classifier for priority prediction.
+- The **bootstrap-with-synthetic-data** trick for cold-start ML.
+- How the app does auth **correctly** (bcrypt) — the contrast to weaker demos in this track.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Strong understanding of Python syntax and OOP concepts
-- Knowledge of machine learning concepts and scikit-learn
-- Familiarity with web development using Flask and SocketIO
-- Understanding of natural language processing
-- Experience with SQL databases and user authentication
-- Basic knowledge of JavaScript and real-time web applications
+- Python 3.8 or above.
+- A text editor or IDE.
+- `pip install scikit-learn nltk textblob flask flask-socketio bcrypt pandas numpy`.
+- NLTK data: the code auto-downloads `vader_lexicon`, `punkt`, `stopwords`.
+- ML basics (vectorization, train/test split, classification) — see [ML Model Trainer](./ml-model-trainer).
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `aiTaskManager`.
-2. Create a new file and name it `aitaskmanager.py`.
-3. Install required dependencies: `pip install flask flask-socketio scikit-learn nltk textblob pandas bcrypt`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `aitaskmanager.py` file.
+### Create the project
+1. Create a folder named `ai-task-manager`.
+2. Inside it, create `aitaskmanager.py`.
+3. Install dependencies (above). First run seeds an `admin` user and trains the model.
 
 ### Write the code
-1. Add the following code to your `aitaskmanager.py` file.
-<FileCode file="projects/intermediate/aitaskmanager.py" lang="python" title="AI-Powered Task Management System" />
-2. Save the file.
-3. Run the following command to start the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\aiTaskManager> python aitaskmanager.py
-🤖 AI-Powered Task Management System
-==================================================
-
-Choose interface:
-1. Web Application (Recommended)
-2. CLI Demo
-Enter choice (1-2): 1
-
-🤖 AI Task Manager - CLI Demo
-Creating sample tasks with AI analysis...
-✅ Created task 1: Fix critical bug in login system
-✅ Created task 2: Write documentation for new API
-✅ Created task 3: Plan team meeting
-✅ Created task 4: Optimize database queries
-✅ Created task 5: Emergency server maintenance
-
-🚀 Starting web application...
-🌐 Access the dashboard at: http://localhost:5000
-🔑 Default login: admin / admin123
+<FileCode file="projects/intermediate/aitaskmanager.py" lang="python" title="aitaskmanager.py" />
 
-🤖 AI Features:
-   - Smart priority prediction
-   - Sentiment analysis
-   - Workload insights
-   - Productivity recommendations
-   - Real-time notifications
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ai-task-manager> python aitaskmanager.py
+# Default login: admin / admin123
+# On boot it trains the priority model (synthetic data if you have none yet).
 ```
 
-## Explanation
-
-1. The `AITaskManager` class integrates machine learning models for intelligent task analysis.
-2. The `train_ai_models()` method uses scikit-learn to train priority prediction models.
-3. Natural language processing analyzes task sentiment and complexity using NLTK and TextBlob.
-4. The `predict_task_priority()` function uses TF-IDF vectorization and logistic regression.
-5. Real-time collaboration is enabled through Flask-SocketIO for instant updates.
-6. User authentication system with password hashing using bcrypt for security.
-7. Intelligent suggestions engine provides personalized productivity recommendations.
-8. The web interface offers modern dashboard with interactive charts and real-time updates.
-9. Comprehensive analytics track user productivity patterns and task completion rates.
-10. Notification system keeps users informed of important updates and deadlines.
-11. The system learns from user behavior to improve AI predictions over time.
-12. Advanced features include time tracking, project management, and team collaboration.
-
-## Next Steps
+## Step-by-Step Explanation
 
-Congratulations! You have successfully created an AI-Powered Task Management System in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add calendar integration with Google Calendar or Outlook
-- Implement advanced machine learning models for better predictions
-- Create mobile app with push notifications
-- Add voice commands and speech recognition
-- Implement team collaboration features with role-based permissions
-- Add integration with project management tools like Jira or Trello
-- Create automated task scheduling based on deadlines and priorities
-- Implement advanced analytics with predictive insights
-
-## Conclusion
-
-In this project, you learned how to create an AI-Powered Task Management System in Python. You also learned about machine learning integration, natural language processing, real-time web applications, user authentication, and building intelligent productivity tools. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/aitaskmanager.py)
-
-## Code Explanation
-
-### Machine Learning Integration
-```python title="aitaskmanager.py" showLineNumbers{1}
-def train_ai_models(self):
-    # Prepare text data
-    df['full_text'] = df['task_title'].fillna('') + ' ' + df['task_description'].fillna('')
-    
-    # Vectorize text using TF-IDF
-    X_text = self.vectorizer.fit_transform(df['full_text'])
-    
-    # Extract additional features
-    additional_features = []
-    for _, row in df.iterrows():
-        analysis = self.analyze_task_text(row['task_title'], row['task_description'])
-        additional_features.append([
-            analysis['sentiment_score'],
-            analysis['urgency_score'],
-            analysis['complexity_score']
-        ])
-    
-    # Combine features and train model
-    X = np.hstack([X_text.toarray(), X_additional])
-    self.priority_model.fit(X_train, y_train)
+### 1. Turning text into features (the heart of the AI)
+Two feature sources are combined. First, **TF-IDF** converts the task text into a numeric vector that weights words by how distinctive they are:
+```python title="aitaskmanager.py"
+self.vectorizer = TfidfVectorizer(max_features=1000, stop_words='english')
+X_text = self.vectorizer.fit_transform(df['full_text'])
 ```
-
-Implements comprehensive machine learning pipeline with feature extraction and model training.
-
-### Natural Language Processing
-```python title="aitaskmanager.py" showLineNumbers{1}
-def analyze_task_text(self, title, description=""):
-    full_text = f"{title} {description}".lower()
-    
-    # Sentiment analysis using VADER
-    sentiment = self.sentiment_analyzer.polarity_scores(full_text)
-    sentiment_score = sentiment['compound']
-    
-    # Urgency keyword detection
-    urgency_keywords = ['urgent', 'asap', 'critical', 'emergency', 'deadline']
-    urgency_score = sum(1 for keyword in urgency_keywords if keyword in full_text)
-    
-    # Complexity analysis
-    complexity_keywords = ['complex', 'research', 'analysis', 'design', 'architecture']
-    complexity_score = sum(1 for keyword in complexity_keywords if keyword in full_text)
-    
-    return {
-        'sentiment_score': sentiment_score,
-        'urgency_score': urgency_score,
-        'complexity_score': complexity_score
-    }
+Second, **hand-engineered features** capture signal TF-IDF misses — mood, urgency, complexity:
+```python title="aitaskmanager.py"
+sentiment_score = self.sentiment_analyzer.polarity_scores(full_text)['compound']  # VADER
+urgency_score    = sum(1 for k in urgency_keywords    if k in full_text)
+complexity_score = sum(1 for k in complexity_keywords if k in full_text)
 ```
-
-Analyzes task text using advanced NLP techniques for sentiment and complexity detection.
-
-### AI Priority Prediction
-```python title="aitaskmanager.py" showLineNumbers{1}
-def predict_task_priority(self, title, description=""):
-    # Analyze text features
-    analysis = self.analyze_task_text(title, description)
-    full_text = f"{title} {description}"
-    
-    # Vectorize text
-    text_features = self.vectorizer.transform([full_text])
-    
-    # Create feature vector
-    additional_features = np.array([[
-        analysis['sentiment_score'],
-        analysis['urgency_score'],
-        analysis['complexity_score']
-    ]])
-    
-    # Combine features and predict
-    combined_features = np.hstack([text_features.toarray(), additional_features])
-    predicted_priority = self.priority_model.predict(combined_features)[0]
-    probability = self.priority_model.predict_proba(combined_features)[0]
-    
-    return {
-        'priority': int(predicted_priority),
-        'confidence': float(max(probability))
-    }
+Then the two are stacked into one matrix:
+```python title="aitaskmanager.py"
+X = np.hstack([X_text.toarray(), X_additional])   # words + engineered signals
 ```
+This **hybrid feature** approach — learned text features plus domain knowledge — is exactly how practical text classifiers are built.
 
-Uses trained ML model to intelligently predict task priorities with confidence scores.
+### 2. Pulling structured data out of prose
+A regex extracts time estimates straight from the description:
+```python title="aitaskmanager.py"
+time_pattern = r'(\d+)\s*(hour|hr|minute|min|day)'
+# "spend 2 hours" -> 2.0h ; "30 min" -> 0.5h ; "1 day" -> 8h
+```
+"Information extraction" sounds fancy; often it's a well-chosen regex.
 
-### Real-Time Web Interface
-```python title="aitaskmanager.py" showLineNumbers{1}
-def setup_socket_events(self):
-    @self.socketio.on('connect')
-    def handle_connect():
-        if 'user_id' in session:
-            join_room(f"user_{session['user_id']}")
-            emit('connected', {'message': 'Connected to real-time updates'})
-    
-    @self.socketio.on('task_update')
-    def handle_task_update(data):
-        if 'user_id' in session:
-            self.socketio.emit('task_updated', data, room=f"user_{session['user_id']}")
+### 3. Training a priority classifier
+```python title="aitaskmanager.py"
+if len(set(y)) > 1:                                   # need ≥2 classes to classify
+    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+    self.priority_model.fit(X_train, y_train)
+    accuracy = accuracy_score(y_test, self.priority_model.predict(X_test))
 ```
+`LogisticRegression` maps the combined features to a 1–5 priority. Simple, fast, interpretable — the right first model before reaching for anything heavier. It reports test accuracy so you know if it's learning.
 
-Implements real-time collaboration using WebSockets for instant updates across clients.
+### 4. The cold-start problem — solved with synthetic data
+A fresh install has no completed tasks to learn from. The fix:
+```python title="aitaskmanager.py"
+if len(df) < 10:
+    self.generate_training_data()    # seed with labeled example tasks
+```
+Hand-labeled examples ("Fix critical bug" → 5, "Fix typo" → 1) bootstrap the model so it's useful on day one, then it retrains on *your* real completed tasks as they accumulate. This cold-start bootstrap is a genuinely important ML-engineering pattern.
 
-### Smart Recommendations Engine
-```python title="aitaskmanager.py" showLineNumbers{1}
-def get_smart_suggestions(self, user_id):
-    suggestions = {
-        'overdue_tasks': [],
-        'high_priority_due_soon': [],
-        'workload_insights': {},
-        'productivity_tips': []
-    }
-    
-    # Analyze overdue tasks
-    for _, task in df.iterrows():
-        if task['due_date'] and task['status'] != 'done':
-            due_date = datetime.datetime.fromisoformat(task['due_date'])
-            if due_date < now:
-                suggestions['overdue_tasks'].append({
-                    'id': task['id'],
-                    'title': task['title'],
-                    'days_overdue': (now - due_date).days
-                })
-    
-    # Generate productivity insights
-    if len(suggestions['overdue_tasks']) > 3:
-        suggestions['productivity_tips'].append(
-            "Consider setting more realistic deadlines"
-        )
+### 5. Prediction with confidence
+```python title="aitaskmanager.py"
+predicted_priority = self.priority_model.predict(combined_features)[0]
+probability = self.priority_model.predict_proba(combined_features)[0]
+return {'priority': int(predicted_priority), 'confidence': float(max(probability)), ...}
+```
+Returning the model's confidence (`predict_proba`) — not just the label — lets the UI show how sure the AI is. Always surface confidence with predictions.
+
+### 6. Authentication done right
+Unlike some demos in this track, this one hashes passwords properly:
+```python title="aitaskmanager.py"
+password_hash = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
+# verify:
+bcrypt.checkpw(password.encode('utf-8'), stored_hash.encode('utf-8'))
 ```
+**bcrypt** is deliberately slow and salts automatically — the correct choice for passwords (SHA-256 is not). This is the standard to copy.
 
-Provides AI-powered insights and recommendations based on user behavior analysis.
+### 7. Real-time collaboration
+`flask-socketio` pushes updates over WebSockets, so task changes appear live for every connected user (rooms scope updates per project) — the same tech behind the [Real-time Chat Application](./real-time-chat-application).
 
-### Secure Authentication System
-```python title="aitaskmanager.py" showLineNumbers{1}
-def create_user(self, username, email, password, full_name=""):
-    # Check if user already exists
-    cursor.execute("SELECT id FROM users WHERE username = ? OR email = ?", (username, email))
-    if cursor.fetchone():
-        return None, "User already exists"
-    
-    # Hash password using bcrypt
-    password_hash = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
-    
-    cursor.execute('''
-        INSERT INTO users (username, email, password_hash, full_name)
-        VALUES (?, ?, ?, ?)
-    ''', (username, email, password_hash, full_name))
-```
+## Reality Check: "AI" Here Is Classical ML
 
-Implements secure user authentication with password hashing and session management.
+No neural networks, no LLM — and that's the lesson. Smart features + logistic regression delivers a useful, explainable, *fast* priority predictor that trains in milliseconds on a laptop. Reach for deep learning only when simple models plateau. Most shipped "AI features" look exactly like this.
 
-## Features
+## Common Mistakes
 
-- **AI Priority Prediction**: Machine learning-powered task priority suggestions
-- **Sentiment Analysis**: Natural language processing for task emotion detection
-- **Real-Time Collaboration**: WebSocket-based instant updates and notifications
-- **Smart Recommendations**: Personalized productivity insights and tips
-- **Advanced Analytics**: Comprehensive task completion and productivity tracking
-- **Secure Authentication**: User management with encrypted password storage
-- **Modern Web Interface**: Responsive dashboard with interactive charts
-- **Time Tracking**: Detailed time logging and productivity analysis
-- **Project Management**: Organize tasks into projects with team collaboration
-- **Notification System**: Smart alerts for deadlines and important updates
+| Problem | Cause | Fix |
+|---|---|---|
+| `NLTK ... vader_lexicon not found` | Corpora not downloaded | The code auto-downloads; ensure network on first run |
+| Model predicts one class for everything | Training labels all identical | Need ≥2 priority classes (the `len(set(y)) > 1` guard) |
+| Feature-count mismatch at predict time | Re-`fit` vs `transform` confusion | `fit_transform` in training, `transform` only at predict |
+| Predictions never improve | Not retraining on real tasks | Retrain periodically as tasks complete |
+| Auth feels slow | bcrypt is *intentionally* slow | That's the point — don't swap for a fast hash |
+| SocketIO clients don't update | Wrong room / no emit | Emit to the right room after each change |
 
-## Next Steps
+## Variations to Try
 
-### Enhancements
-- Add calendar integration with Google Calendar or Outlook
-- Implement advanced machine learning models for better predictions
-- Create mobile app with push notifications
-- Add voice commands and speech recognition
-- Implement team collaboration features with role-based permissions
-- Add integration with project management tools like Jira or Trello
-- Create automated task scheduling based on deadlines and priorities
-- Implement advanced analytics with predictive insights
+1. **Smarter model** — try `RandomForest`/`GradientBoosting`; compare accuracy.
+2. **Effort prediction** — predict `estimated_hours`, not just priority (regression).
+3. **Auto-assignment** — suggest the best assignee from history.
+4. **Deadline risk** — flag tasks likely to slip.
+5. **Better NLP** — spaCy entities, or embeddings instead of TF-IDF.
+6. **Feedback loop** — let users correct predictions; feed corrections back as labels.
+7. **Email/Slack alerts** — the SMTP scaffolding is already imported.
+8. **Explainability** — show which words drove a priority score.
 
-### Learning Extensions
-- Study advanced machine learning algorithms for task prediction
-- Explore deep learning for natural language understanding
-- Learn about real-time system architecture and scaling
-- Practice with advanced web development frameworks
-- Understand user experience design for productivity applications
-- Explore cloud deployment and microservices architecture
+## Real-World Applications
+- **Project management** — Jira/Asana-style auto-prioritization.
+- **Support triage** — routing and ranking incoming tickets.
+- **Personal productivity** — smart to-do ordering.
+- **Team collaboration** — real-time shared task boards.
 
 ## Educational Value
+- **Applied NLP** — TF-IDF, VADER sentiment, regex extraction.
+- **Feature engineering** — combining learned and hand-crafted features.
+- **ML lifecycle** — cold-start bootstrap, train/test, confidence, retraining.
+- **Secure auth** — bcrypt done correctly, plus real-time WebSockets.
 
-This project teaches:
-- **Machine Learning**: Implementing ML models for practical business applications
-- **Natural Language Processing**: Text analysis and sentiment detection
-- **Real-Time Systems**: WebSocket programming and instant collaboration
-- **Web Development**: Modern full-stack development with Flask and JavaScript
-- **Database Design**: Designing schemas for complex business logic
-- **User Authentication**: Secure login systems and session management
-- **AI Integration**: Combining multiple AI techniques for intelligent applications
-- **Software Architecture**: Building scalable and maintainable systems
+## Next Steps
+- Swap in a **stronger model** and compare accuracy.
+- Add a **feedback loop** so user corrections become training labels.
+- Predict **effort** and **deadline risk**, not just priority.
+- Add **explainability** for each prediction.
 
-Perfect for understanding AI application development, real-time web systems, and building intelligent productivity tools for modern businesses.
+## Conclusion
+You built a task manager whose priorities are *predicted* — by combining TF-IDF text features with engineered sentiment/urgency/complexity signals, training a logistic-regression classifier, and bootstrapping it with synthetic data until real tasks take over. Wrapped in bcrypt-secured, real-time collaboration, it shows what shipping an "AI feature" actually involves: thoughtful features and a simple model beat complexity almost every time. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/aitaskmanager.py). Explore more ML and web projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/anagram-game.mdx b/src/content/docs/projects/intermediate/anagram-game.mdx
index 8bf4e927..ee55cb36 100644
--- a/src/content/docs/projects/intermediate/anagram-game.mdx
+++ b/src/content/docs/projects/intermediate/anagram-game.mdx
@@ -1,5 +1,6 @@
 ---
 title: Anagram Game
+description: Build a Tkinter anagram game in Python — scramble words, validate guesses, track score, then level it up with a real dictionary, hints, a countdown timer, difficulty tiers, and persistent high scores.
 sidebar:
   order: 91
 hero:
@@ -12,57 +13,171 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+An anagram game is a deceptively rich little project. On the surface it just scrambles a word and asks you to unscramble it — but underneath it touches randomization, string manipulation, input validation, event-driven GUI programming, and game state. In this tutorial you build a Tkinter anagram game on a short word list, then grow it into something you'd actually want to play: a real dictionary, hints, a per-round countdown timer, difficulty levels, and a high-score table saved to disk.
 
-Create an Anagram Game that challenges users to form words from a scrambled set of letters. The app generates random anagrams, validates user input, and keeps track of the score. This project demonstrates string manipulation, randomization, and GUI development in Python.
+You will leave understanding:
+- How `random.sample` produces a scramble and why it can occasionally return the original word.
+- The Entry + Button + Label event loop that drives almost every small Tkinter app.
+- Why you normalize input (`strip().lower()`) before comparing strings.
+- How to separate game **state** (score, current word) from game **view** (the widgets).
+- How to add a non-blocking timer with `after` instead of `sleep`.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of string operations
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (ships with Python; on Linux: `sudo apt install python3-tk`).
+- Comfort with functions, classes, and basic string methods. If GUIs are new, start with [Calculator GUI](../../beginners/calculatorgui).
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `anagram_game`.
-2. Create a new file inside the folder and name it `anagram_game.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `anagram_game.py` file.
+
+### Create the project
+1. Create a folder named `anagram-game`.
+2. Inside it, create `anagram_game.py`.
+3. Open the folder in your editor.
 
 ### Write the code
 <FileCode file="projects/intermediate/anagram_game.py" lang="python" title="anagram_game.py" showLineNumbers={1} />
 
-## Key Features
-- Generate random anagrams from a word list
-- Validate user input against the original word
-- Keep track of the score
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\anagram-game> python anagram_game.py
+# A window opens showing a scrambled word, an answer box,
+# and Submit / Next buttons. Type the unscrambled word and Submit.
+```
+
+## Step-by-Step Explanation
 
-## Explanation
+### 1. The word bank
+```python title="anagram_game.py"
+WORDS = ["python", "anagram", "challenge", "programming", "developer", "algorithm"]
+```
+A plain list is fine to start. Later you'll swap this for a dictionary file so the game never runs out of words.
 
-### Generating Anagrams
-The app randomly selects a word and scrambles its letters:
-```python title="anagram_game.py" showLineNumbers={1}
+### 2. Scrambling a word
+```python title="anagram_game.py"
 self.current_word = random.choice(WORDS)
 self.scrambled_word = "".join(random.sample(self.current_word, len(self.current_word)))
 ```
+`random.choice` picks the answer; `random.sample(word, len(word))` returns the letters in a new random order. `sample` draws *without replacement*, so every letter is used exactly once — that's what makes it a true anagram rather than a random jumble. **Catch:** `sample` can occasionally return the letters in their original order, handing the player the answer for free. The fix is below.
 
-### Checking Answers
-User input is validated against the original word, and the score is updated:
-```python title="anagram_game.py" showLineNumbers={1}
+### 3. Validating the guess
+```python title="anagram_game.py"
+user_answer = self.answer_entry.get().strip().lower()
 if user_answer == self.current_word:
     self.score += 1
     messagebox.showinfo("Correct!", f"Well done! Your score: {self.score}")
 else:
     messagebox.showerror("Incorrect", f"The correct word was: {self.current_word}")
 ```
+`.strip()` kills stray spaces, `.lower()` makes the check case-insensitive — both essential when comparing free-text input. Skip them and "Python " (with a trailing space) reads as wrong.
 
-## Running the Application
-1. Save the file.
-2. Run the application:
-```bash
-python anagram_game.py
+### 4. State vs. view
+The `AnagramGame` class holds **state** (`score`, `current_word`, `scrambled_word`) as attributes and **view** (the `Label`, `Entry`, `Button`) as widgets. `next_word()` mutates state then pushes it into the view with `self.word_label.config(...)`. Keeping these two ideas separate is the single most useful habit you'll carry into bigger GUI apps.
+
+## Fix: Never Hand Out the Answer
+
+Re-scramble until the result differs from the original:
+```python title="fix.py"
+def scramble(word):
+    if len(word) < 2:
+        return word
+    while True:
+        letters = random.sample(word, len(word))
+        candidate = "".join(letters)
+        if candidate != word:
+            return candidate
 ```
+For a word with repeated letters (e.g. "letter") some scrambles look identical even when the underlying order changed — comparing strings is still the right check for the player's experience.
+
+## Use a Real Dictionary
+
+Hard-coded lists get stale. Load thousands of words from a file:
+```python title="dictionary.py"
+from pathlib import Path
+import random
+
+# One word per line. On Linux/Mac, /usr/share/dict/words exists.
+WORDS = [
+    w.strip().lower()
+    for w in Path("words.txt").read_text().splitlines()
+    if 4 <= len(w.strip()) <= 8 and w.strip().isalpha()
+]
+
+def new_word():
+    return random.choice(WORDS)
+```
+Filtering by length (`4 <= len <= 8`) keeps rounds fair — 2-letter words are trivial, 15-letter words are cruel.
+
+## Add a Hint Button
+
+Reveal the first letter, at the cost of points:
+```python title="hint.py"
+def show_hint(self):
+    self.hint_used = True
+    first = self.current_word[0]
+    self.hint_label.config(text=f"Starts with: {first.upper()}")
+```
+Award only half points (or zero) when `self.hint_used` is `True`. Hints turn a frustrating round into a learnable one.
+
+## Add a Per-Round Timer
+
+Use Tkinter's `after` — never `time.sleep`, which freezes the whole window:
+```python title="timer.py"
+def start_timer(self, seconds=20):
+    self.time_left = seconds
+    self.tick()
+
+def tick(self):
+    self.timer_label.config(text=f"Time: {self.time_left}s")
+    if self.time_left <= 0:
+        messagebox.showinfo("Time!", f"The word was: {self.current_word}")
+        self.next_word()
+        return
+    self.time_left -= 1
+    self._timer_id = self.root.after(1000, self.tick)   # schedule next tick
+```
+Cancel the pending tick whenever the player submits early: `self.root.after_cancel(self._timer_id)`. Otherwise an old timer fires on the next word.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Scramble shows the real word | `random.sample` returned original order | Loop until `candidate != word` |
+| "Correct" answer marked wrong | Trailing space or capital letters | Normalize with `.strip().lower()` on both sides |
+| Window freezes during countdown | Used `time.sleep` on the main thread | Use `root.after(1000, ...)` instead |
+| Timer fires on the wrong word | Old `after` callback still pending | Track the id and `after_cancel` it on submit |
+| Game crashes at end of list | Indexed past the word bank | Pick randomly, or guard `index < len(words)` |
+| Same word repeats constantly | Tiny word list | Load from a dictionary file |
+
+## Variations to Try
+
+1. **Multiplayer** — two players alternate; track separate scores.
+2. **Categories** — animals, countries, programming terms; pick a bank per round.
+3. **Streak bonus** — extra points for consecutive correct answers.
+4. **Definitions** — pull a definition from a dictionary API and show it as a hint.
+5. **Daily challenge** — seed `random` with today's date so everyone gets the same word.
+6. **Difficulty tiers** — short words = easy, long words = hard, shorter timer = harder.
+7. **Leaderboard** — persist `(name, score, date)` to JSON; show top 10 at launch.
+8. **Web version** — rebuild in Flask (see [Simple Blog with Flask](./simple-blog-with-flask)).
+
+## Real-World Applications
+- **Language learning** — vocabulary drills and spelling practice.
+- **Brain-training apps** — word games like those in Lumosity or NYT Games.
+- **Classroom tools** — teachers generating spelling exercises.
+- **Onboarding mini-games** — lightweight engagement in larger apps.
+
+## Educational Value
+- **Randomization** — `choice`, `sample`, and seeding.
+- **String hygiene** — normalizing user input before comparison.
+- **Event-driven GUIs** — the button-callback model.
+- **Non-blocking timing** — `after` vs. `sleep`, a lesson that scales to every GUI/async app.
+- **State/view separation** — the foundation of maintainable UI code.
+
+## Next Steps
+- Add the **re-scramble fix** so the answer is never given away.
+- Swap the list for a **dictionary file** and filter by length.
+- Add a **hint button** and a **per-round timer**.
+- Introduce **difficulty tiers** and a **JSON high-score table**.
 
 ## Conclusion
-This Anagram Game project is a fun way to practice string manipulation and GUI development in Python. You can extend it by adding a larger word list, hints, or a timer feature.
+You built a working anagram game, hardened its weak spots (free answers, sloppy input matching, blocking timers), and sketched a path to a polished word game with dictionaries, hints, timers, and leaderboards. The same Entry → validate → update-state → refresh-view loop powers most small interactive apps you'll write. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/anagram_game.py). Explore more games and tools on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/anagram_game.mdx b/src/content/docs/projects/intermediate/anagram_game.mdx
deleted file mode 100644
index 2cf4fc58..00000000
--- a/src/content/docs/projects/intermediate/anagram_game.mdx
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: Anagram Game
-sidebar:
-    order: 4
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/anagram_game.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Anagram Game is a Python project that challenges users to unscramble words. It demonstrates string manipulation, randomization, and GUI development. This project is ideal for learning about word games, event handling, and user interaction in Python.
-
-## Prerequisites
-- Python 3.6 or above
-- random (built-in)
-- tkinter (for GUI, usually pre-installed)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available.
-
-## Getting Started
-1. Create a folder named `anagram-game`.
-2. Create a file named `anagram_game.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/anagram_game.py" lang="python" title="Anagram Game" />
-4. Run the script: `python anagram_game.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import random
-import tkinter as tk
-```
-2. **Word selection and scrambling**
-```python
-words = ['python', 'algorithm', 'function', 'variable']
-word = random.choice(words)
-anagram = ''.join(random.sample(word, len(word)))
-```
-3. **GUI for game**
-```python
-root = tk.Tk()
-root.title('Anagram Game')
-# ...setup widgets for display and input...
-root.mainloop()
-```
-
-## Features
-- Random word selection
-- Scrambled word display
-- User input for guesses
-- Score tracking
-
-## How It Works
-- Selects a word and scrambles it
-- Displays anagram in GUI
-- User enters guess
-- Checks correctness and updates score
-
-## GUI Components
-- **Label:** Shows scrambled word
-- **Entry box:** For user guess
-- **Button:** Submits guess
-- **Score display:** Tracks correct answers
-
-## Use Cases
-- Improve vocabulary
-- Practice spelling
-- Learn string manipulation
-
-## Next Steps
-You can enhance this project by:
-- Adding more words
-- Implementing difficulty levels
-- Adding timer for each round
-- Keeping high scores
-- Giving hints
-
-## Enhanced Version Ideas
-```python
-def add_timer():
-    # Limit time for each guess
-    pass
-
-def show_hint():
-    # Display a hint for the word
-    pass
-```
-
-## Troubleshooting Tips
-- **GUI not showing:** Ensure Tkinter is installed
-- **No words displayed:** Check word list
-
-## Conclusion
-This project teaches string manipulation, randomization, and GUI basics. Extend it for more features and challenge levels.
diff --git a/src/content/docs/projects/intermediate/basic-chatroom-app.mdx b/src/content/docs/projects/intermediate/basic-chatroom-app.mdx
index 6ab73ba6..ae289a00 100644
--- a/src/content/docs/projects/intermediate/basic-chatroom-app.mdx
+++ b/src/content/docs/projects/intermediate/basic-chatroom-app.mdx
@@ -1,5 +1,6 @@
 ---
 title: Basic Chatroom App
+description: Build a multi-client chatroom in Python with sockets and threads — a server that broadcasts messages to every connected client — then harden it with usernames, clean disconnects, message framing, and a path to a GUI.
 sidebar:
   order: 90
 hero:
@@ -12,69 +13,168 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A chatroom is the "hello world" of network programming — the moment sockets stop being abstract and start feeling like magic. In this tutorial you build a TCP server that accepts many clients at once and **broadcasts** each message to everyone else, plus a client that sends and receives at the same time. You'll meet the two ideas that power almost all networked apps: **sockets** (the pipe between machines) and **threads** (so one slow client doesn't block the rest). Then you'll harden the naive version with usernames, graceful disconnects, and proper message framing.
 
-Build a Basic Chatroom App that allows multiple users to communicate in real-time. The app includes both server and client implementations using sockets and threading. This project demonstrates network programming, concurrency, and user interaction in Python.
+You will leave understanding:
+- The TCP server lifecycle: `socket` → `bind` → `listen` → `accept`.
+- Why each client needs its own thread, and what `broadcast` does.
+- How `encode`/`decode` move strings across the wire as bytes.
+- Why bare `except:` and unframed `recv` are the two classic chat bugs.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with socket programming
-- Knowledge of threading for concurrency
+- Python 3.6 or above.
+- A text editor or IDE.
+- Standard library only — `socket` and `threading` are built in.
+- A basic mental model of client/server networking.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `basic_chatroom_app`.
-2. Create a new file inside the folder and name it `basic_chatroom_app.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `basic_chatroom_app.py` file.
+
+### Create the project
+1. Create a folder named `chatroom`.
+2. Inside it, create `basic_chatroom_app.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/basic_chatroom_app.py" lang="python" title="basic_chatroom_app.py" showLineNumbers={1} />
 
-## Key Features
-- Server-side implementation to manage multiple clients
-- Client-side implementation for sending and receiving messages
-- Real-time communication using sockets
-- Threading for handling multiple clients concurrently
+### Run it
+```cmd title="command"
+# Terminal 1 — start the server
+C:\Users\Your Name\chatroom> python basic_chatroom_app.py
+Do you want to start the server or client? (server/client): server
+
+# Terminal 2 and 3 — start clients
+C:\Users\Your Name\chatroom> python basic_chatroom_app.py
+Do you want to start the server or client? (server/client): client
+```
+Type in one client; the message appears in the others.
 
-## Explanation
+## Step-by-Step Explanation
 
-### Server Implementation
-The server listens for incoming connections and starts a new thread for each client:
-```python title="basic_chatroom_app.py" showLineNumbers={1}
+### 1. The server socket
+```python title="basic_chatroom_app.py"
 self.server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 self.server.bind((host, port))
 self.server.listen(5)
-threading.Thread(target=self.handle_client, args=(client_socket,)).start()
 ```
+`AF_INET` = IPv4, `SOCK_STREAM` = TCP (reliable, ordered). `bind` claims the address/port, `listen(5)` opens the door with a backlog of 5 pending connections.
 
-### Client Implementation
-The client connects to the server and starts a thread to receive messages:
-```python title="basic_chatroom_app.py" showLineNumbers={1}
-self.client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-self.client.connect((host, port))
-threading.Thread(target=self.receive_messages).start()
+### 2. Accepting clients, one thread each
+```python title="basic_chatroom_app.py"
+while True:
+    client_socket, client_address = self.server.accept()   # blocks until someone connects
+    self.clients.append(client_socket)
+    threading.Thread(target=self.handle_client, args=(client_socket,)).start()
 ```
+`accept()` blocks until a client connects, then returns a dedicated socket for that client. Spinning up a **thread per client** means the server can talk to everyone concurrently — without threads, the second client would wait for the first to finish.
 
-### Message Broadcasting
-The server broadcasts messages to all connected clients except the sender:
-```python title="basic_chatroom_app.py" showLineNumbers={1}
-for client in self.clients:
-    if client != client_socket:
-        client.send(message)
+### 3. Broadcasting
+```python title="basic_chatroom_app.py"
+def broadcast(self, message, client_socket):
+    for client in self.clients:
+        if client != client_socket:       # don't echo back to the sender
+            try:
+                client.send(message)
+            except:
+                self.clients.remove(client)
 ```
+The server is a relay: a message from one client goes out to every *other* client. That `if client != client_socket` is what stops you from seeing your own messages twice.
 
-## Running the Application
-1. Save the file.
-2. Run the server:
-```bash
-python basic_chatroom_app.py
+### 4. Bytes on the wire
+```python title="basic_chatroom_app.py"
+self.client.send(message.encode("utf-8"))      # str -> bytes to send
+message = self.client.recv(1024).decode("utf-8")  # bytes -> str on receive
 ```
-3. Run the client in a separate terminal:
-```bash
-python basic_chatroom_app.py
+Sockets move **bytes**, not strings. `encode`/`decode` translate. `recv(1024)` reads up to 1024 bytes at a time.
+
+## Fix #1: Stop Swallowing Errors
+
+Bare `except:` hides bugs (it even catches Ctrl-C). Catch what you mean and modifying a list while iterating it is unsafe:
+```python title="safe_broadcast.py"
+def broadcast(self, message, sender):
+    dead = []
+    for client in self.clients:
+        if client is sender:
+            continue
+        try:
+            client.send(message)
+        except OSError:           # socket actually broken
+            dead.append(client)
+    for client in dead:           # remove AFTER the loop
+        self.clients.remove(client)
 ```
 
+## Fix #2: Add Usernames
+
+Right now everyone's anonymous. Have each client send a name on join, store it, and prefix messages:
+```python title="usernames.py"
+# client, right after connect:
+self.client.send(self.username.encode("utf-8"))
+
+# server, first recv in handle_client:
+name = client_socket.recv(1024).decode("utf-8")
+self.names[client_socket] = name
+self.broadcast(f"*** {name} joined ***".encode(), client_socket)
+```
+
+## Fix #3: Frame Your Messages
+
+TCP is a *stream*, not a series of messages — two fast sends can arrive glued together, or one send can arrive split. For real apps, prefix each message with its length:
+```python title="framing.py"
+import struct
+
+def send_msg(sock, text):
+    data = text.encode("utf-8")
+    sock.sendall(struct.pack(">I", len(data)) + data)   # 4-byte length header
+
+def recv_exact(sock, n):
+    buf = b""
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            return None
+        buf += chunk
+    return buf
+```
+Read the 4-byte length, then read exactly that many bytes. This is how you avoid the "messages mash together" bug.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `Address already in use` | Previous server didn't release the port | `setsockopt(SO_REUSEADDR)` before bind |
+| Messages glue together / split | TCP is a stream, not messages | Length-prefix framing |
+| Server crashes when a client quits | Bare `except` + list mutation in loop | Catch `OSError`, remove after the loop |
+| Client can't type and receive | Receive loop on main thread | Run `recv` on its own thread (the code does) |
+| Garbled non-ASCII text | Wrong/missing encoding | Always `encode/decode("utf-8")` |
+| Everyone is "anonymous" | No handshake | Send a username on connect |
+
+## Variations to Try
+
+1. **Private messages** — `/msg alice hello` routed to one user.
+2. **Chat rooms** — multiple named channels; clients join/leave.
+3. **Tkinter GUI** — replace `input()`/`print()` with a window (see [Chat Application with Sockets](./chat-application-socket)).
+4. **Message history** — persist the last N messages and replay on join.
+5. **Nicknames & colors** — per-user display styling.
+6. **`asyncio` rewrite** — swap threads for `async`/`await`.
+7. **Encryption** — wrap the socket in TLS with `ssl`.
+
+## Real-World Applications
+- **Messaging apps** — the conceptual core of Slack, Discord, IRC.
+- **Live support widgets** — customer chat on websites.
+- **Multiplayer games** — real-time state sync between players.
+- **IoT command channels** — devices reporting to a hub.
+
+## Educational Value
+- **Socket programming** — the server lifecycle and TCP basics.
+- **Concurrency** — thread-per-client and shared state.
+- **Serialization** — encoding text to bytes and message framing.
+- **Robustness** — handling the disconnect/error paths that demos ignore.
+
+## Next Steps
+- Replace bare `except` with **targeted error handling**.
+- Add **usernames** and join/leave notices.
+- Implement **length-prefixed framing**.
+- Build a **Tkinter GUI** client.
+
 ## Conclusion
-This Basic Chatroom App is a great introduction to network programming and concurrency in Python. You can extend it by adding user authentication, message history, or a GUI interface.
+You built a multi-client chatroom and met the two pillars of network programming — sockets and threads — then fixed the three bugs every first chat app has: swallowed errors, anonymous users, and unframed streams. From here, a GUI or `asyncio` rewrite is a natural next step, and the relay-server pattern you learned underpins every messaging system you've ever used. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/basic_chatroom_app.py). Explore more networking projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/basic-file-version-control-system.mdx b/src/content/docs/projects/intermediate/basic-file-version-control-system.mdx
index cc372aaa..f8af3f8d 100644
--- a/src/content/docs/projects/intermediate/basic-file-version-control-system.mdx
+++ b/src/content/docs/projects/intermediate/basic-file-version-control-system.mdx
@@ -1,5 +1,6 @@
 ---
 title: Basic File Version Control System
+description: Build a mini Git in Python — hash files with SHA-256, commit snapshots with messages, and revert to earlier versions — then grow it into a real multi-version history with diffs, and learn why pickle is the wrong store.
 sidebar:
   order: 95
 hero:
@@ -12,45 +13,59 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Ever wondered what Git actually *does*? Strip away the branches and remotes and you're left with a simple idea: hash a file's contents, store a snapshot, and let the user roll back. This project builds exactly that — a command-line version control system that commits files with messages, skips commits when nothing changed (by comparing hashes), and reverts to the last saved version. Then you'll grow it from "remembers one version" into a real multi-version history with timestamps, a full log, and diffs — and learn why `pickle` is a poor storage choice for anything you'll keep.
 
-Build a Basic File Version Control System that tracks changes to files, allows committing changes with messages, and reverting to previous versions. This project demonstrates file hashing, serialization, and command-line interaction in Python.
+You will leave understanding:
+- Why content **hashing** (SHA-256) is the heart of every VCS.
+- How "no changes detected" works by comparing the new hash to the stored one.
+- The commit → store-snapshot → revert cycle.
+- The limits of the starter design (one version, pickle) and how to fix them.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of file handling and hashing
-- Familiarity with serialization (pickle)
+- Python 3.8 or above (uses the `:=` walrus operator).
+- A text editor or IDE.
+- Standard library only — `os`, `hashlib`, `pickle`, `datetime`.
+- Comfort with classes, dictionaries, and file I/O.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `basic_file_version_control_system`.
-2. Create a new file inside the folder and name it `basic_file_version_control_system.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `basic_file_version_control_system.py` file.
+
+### Create the project
+1. Create a folder named `mini-vcs`.
+2. Inside it, create `basic_file_version_control_system.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/basic_file_version_control_system.py" lang="python" title="basic_file_version_control_system.py" showLineNumbers={1} />
 
-## Key Features
-- Track changes to files
-- Commit changes with messages
-- Revert to previous versions
-- Command-line interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\mini-vcs> python basic_file_version_control_system.py
+# Menu: 1) Commit  2) Revert  3) View Log  4) Exit
+# Commit a file, edit it, commit again, then revert to undo your edits.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### File Hashing
-The app uses SHA-256 to hash file contents for change detection:
-```python title="basic_file_version_control_system.py" showLineNumbers={1}
-hasher = hashlib.sha256()
-with open(file_path, "rb") as f:
-    hasher.update(f.read())
+### 1. Hashing a file
+```python title="basic_file_version_control_system.py"
+def hash_file(self, file_path):
+    hasher = hashlib.sha256()
+    with open(file_path, "rb") as f:
+        while chunk := f.read(8192):
+            hasher.update(chunk)
+    return hasher.hexdigest()
 ```
+This is the core idea. A SHA-256 hash is a fixed-length fingerprint of the file's bytes — change a single character and the hash changes completely. Reading in 8 KB chunks (the `:=` walrus loop) means even a huge file never loads fully into memory. Git uses the same trick (with SHA-1/SHA-256) to identify content.
 
-### Committing Changes
-Changes are committed with a message and stored in a serialized file:
-```python title="basic_file_version_control_system.py" showLineNumbers={1}
+### 2. Skipping unchanged commits
+```python title="basic_file_version_control_system.py"
+if file_name in self.versions and self.versions[file_name]["hash"] == file_hash:
+    print("No changes detected.")
+    return
+```
+Before saving, compare the new hash to the stored one. Identical hashes mean identical content — so there's nothing to commit. That's how Git knows "nothing to commit, working tree clean".
+
+### 3. Storing a snapshot
+```python title="basic_file_version_control_system.py"
 version_data = {
     "hash": file_hash,
     "timestamp": timestamp,
@@ -61,23 +76,96 @@ self.versions[file_name] = version_data
 with open(self.version_file, "wb") as f:
     pickle.dump(self.versions, f)
 ```
+Each commit stores the hash, time, message, and the **full file contents**, then pickles the whole `versions` dict to `.versions.pkl`. **Notice the limitation:** `self.versions[file_name] = ...` *overwrites* — so only the latest version per file is kept. The upgrade below fixes that.
+
+### 4. Reverting
+```python title="basic_file_version_control_system.py"
+with open(os.path.join(self.repo_path, file_name), "wb") as f:
+    f.write(self.versions[file_name]["content"])
+```
+Revert just writes the stored bytes back to disk. Because we kept the raw content, restoring is trivial.
+
+## Fix #1: Keep Every Version
+
+A real VCS keeps history. Store a *list* of versions per file:
+```python title="history.py"
+# versions[file_name] becomes a list of snapshots
+entry = {"hash": file_hash, "timestamp": timestamp,
+         "message": message, "content": data}
+self.versions.setdefault(file_name, []).append(entry)
 
-### Reverting and Logging
-Users can revert files to previous versions and view commit logs:
-```python title="basic_file_version_control_system.py" showLineNumbers={1}
-def revert(self, file_name):
-    # Restore file from self.versions
+def revert(self, file_name, index=-1):      # -1 = latest, 0 = first, etc.
+    snapshot = self.versions[file_name][index]
+    Path(self.repo_path, file_name).write_bytes(snapshot["content"])
 
 def log(self, file_name):
-    # Print commit history
+    for i, v in enumerate(self.versions[file_name]):
+        print(f"[{i}] {v['timestamp']}  {v['hash'][:8]}  {v['message']}")
+```
+Now you can revert to *any* past commit by index — much closer to real version control.
+
+## Fix #2: Store Diffs, Not Full Copies
+
+Saving the whole file every commit wastes space. Store the *difference* between versions:
+```python title="diffs.py"
+import difflib
+
+def make_diff(old_text, new_text):
+    return list(difflib.unified_diff(old_text.splitlines(), new_text.splitlines(), lineterm=""))
 ```
+Git does a sophisticated version of this (delta compression). For a learning project, `difflib` is enough to show how diffs shrink storage.
+
+## Fix #3: Drop Pickle
 
-## Running the Application
-1. Save the file.
-2. Run the application:
-```bash
-python basic_file_version_control_system.py
+`pickle` is convenient but **unsafe** (unpickling untrusted data can execute code) and not human-readable. For text snapshots, prefer storing content files in a folder plus a JSON index:
+```python title="store.py"
+import json, hashlib
+# Save each unique blob by its hash, like Git's object store
+blob_path = Path(self.repo_path, ".objects", file_hash)
+blob_path.write_bytes(data)
+# Index maps filename -> list of {hash, timestamp, message}
+Path(self.repo_path, "index.json").write_text(json.dumps(index, indent=2))
 ```
+This is literally a simplified version of Git's `.git/objects` content-addressable store.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Only one version is kept | `versions[name] = ...` overwrites | Append to a **list** per file |
+| `SyntaxError` on `:=` | Python < 3.8 | Upgrade, or use a normal `while` loop |
+| Reverting wipes recent work | Revert with no confirmation | Confirm; commit current state first |
+| Repo file grows huge | Storing full content every commit | Store **diffs** or dedupe blobs by hash |
+| `pickle` load fails / unsafe | Format change or untrusted data | Switch to JSON index + blob store |
+| Binary files break diffs | `difflib` is line-based | Keep full copies for binaries |
+
+## Variations to Try
+
+1. **Multi-version history** — revert to any commit by index or hash.
+2. **`status` command** — show which tracked files changed since last commit.
+3. **Whole-directory tracking** — commit a folder, not one file.
+4. **Diff viewer** — print a colored unified diff between two versions.
+5. **Tags** — name important commits ("v1.0").
+6. **Branches** — keep parallel histories (the real leap toward Git).
+7. **Compression** — gzip stored blobs to save space.
+
+## Real-World Applications
+- **Understanding Git** — this *is* Git's core, minus the plumbing.
+- **Document versioning** — wikis, CMSs, and editors that track edits.
+- **Config backups** — snapshot a config before changing it.
+- **Undo systems** — the same snapshot/restore idea powers app undo.
+
+## Educational Value
+- **Hashing** — content fingerprints and change detection.
+- **Serialization** — pickle vs. JSON vs. a blob store, and their trade-offs.
+- **Data modeling** — why a list beats a single slot for history.
+- **Demystifying tools** — seeing the simple idea inside a complex tool.
+
+## Next Steps
+- Store **every version** in a list and revert by index.
+- Replace full copies with **diffs**.
+- Swap `pickle` for a **JSON index + hashed blob store**.
+- Add **status**, **tags**, and eventually **branches**.
 
 ## Conclusion
-This Basic File Version Control System project is a great way to learn about file tracking and serialization in Python. You can extend it by adding branching, remote repositories, or a GUI interface.
+You built a miniature version control system and saw that the magic behind Git is really just *hash the content, store a snapshot, restore on request*. By keeping full history, storing diffs, and dropping pickle for a content-addressable store, you walk the same path Git's designers did. Next time you `git commit`, you'll know exactly what's happening underneath. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/basic_file_version_control_system.py). Explore more systems projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/basic_chatroom_app.mdx b/src/content/docs/projects/intermediate/basic_chatroom_app.mdx
deleted file mode 100644
index 18c75841..00000000
--- a/src/content/docs/projects/intermediate/basic_chatroom_app.mdx
+++ /dev/null
@@ -1,108 +0,0 @@
----
-title: Basic Chatroom App
-sidebar:
-    order: 3
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/basic_chatroom_app.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Basic Chatroom App is a Python project that enables real-time text communication between multiple users over a network. It demonstrates socket programming, threading, and basic GUI development. This project is ideal for learning about client-server architecture, concurrency, and event-driven programming.
-
-## Prerequisites
-- Python 3.6 or above
-- socket, threading (built-in)
-- tkinter (for GUI, usually pre-installed)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available.
-
-## Getting Started
-1. Create a folder named `chatroom-app`.
-2. Create a file named `basic_chatroom_app.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/basic_chatroom_app.py" lang="python" title="Basic Chatroom App" />
-4. Run the server and client scripts as described in the code comments.
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import socket
-import threading
-import tkinter as tk
-```
-2. **Server setup**
-```python
-def start_server():
-    # Accepts connections and relays messages
-    pass
-```
-3. **Client setup**
-```python
-def start_client():
-    # Connects to server and sends/receives messages
-    pass
-```
-4. **GUI for chat**
-```python
-root = tk.Tk()
-root.title('Chatroom')
-# ...setup widgets for chat display and input...
-root.mainloop()
-```
-
-## Features
-- Real-time text chat
-- Multiple users
-- Simple GUI
-- Demonstrates sockets and threading
-
-## How It Works
-- Server listens for connections
-- Clients connect and send messages
-- Messages are broadcast to all clients
-- GUI displays chat and allows input
-
-## GUI Components
-- **Text area:** Shows chat history
-- **Entry box:** For message input
-- **Send button:** Sends message
-
-## Use Cases
-- Learn networking basics
-- Build simple chat apps
-- Experiment with concurrency
-
-## Next Steps
-You can enhance this project by:
-- Adding user authentication
-- Supporting private messages
-- Improving GUI design
-- Adding emojis or file sharing
-- Implementing message history
-
-## Enhanced Version Ideas
-```python
-def add_authentication():
-    # Require login for chat
-    pass
-
-def save_chat_history():
-    # Store messages in a file
-    pass
-```
-
-## Troubleshooting Tips
-- **Connection errors:** Check IP and port
-- **GUI not showing:** Ensure Tkinter is installed
-- **Messages not sent:** Check server/client status
-
-## Conclusion
-This project teaches networking, threading, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/basic_file_version_control_system.mdx b/src/content/docs/projects/intermediate/basic_file_version_control_system.mdx
deleted file mode 100644
index 12e4a502..00000000
--- a/src/content/docs/projects/intermediate/basic_file_version_control_system.mdx
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Basic File Version Control System
-sidebar:
-    order: 8
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/basic_file_version_control_system.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Basic File Version Control System is a Python project that tracks changes to files and allows users to revert to previous versions. It demonstrates file management, hashing, and simple CLI interaction. This project is ideal for learning about versioning, backups, and automation in Python.
-
-## Prerequisites
-- Python 3.6 or above
-- os, shutil, hashlib (built-in)
-- datetime (built-in)
-
-## Before you Start
-Ensure Python is installed. No external packages are required.
-
-## Getting Started
-1. Create a folder named `file-version-control`.
-2. Create a file named `basic_file_version_control_system.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/basic_file_version_control_system.py" lang="python" title="Basic File Version Control System" />
-4. Run the script: `python basic_file_version_control_system.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import os
-import shutil
-import hashlib
-import datetime
-```
-2. **Save file versions**
-```python
-def save_version(file_path):
-    # Save copy with timestamp
-    pass
-```
-3. **List and restore versions**
-```python
-def list_versions():
-    # Show available versions
-    pass
-
-def restore_version(version):
-    # Restore selected version
-    pass
-```
-
-## Features
-- Tracks file changes
-- Saves versions with timestamps
-- Allows restoring previous versions
-- Simple CLI usage
-
-## How It Works
-- Copies file to versioned folder on change
-- Lists available versions
-- Restores selected version
-
-## Use Cases
-- Backup important files
-- Track document changes
-- Learn version control basics
-
-## Next Steps
-You can enhance this project by:
-- Adding logging
-- Supporting multiple files
-- Adding a GUI
-- Integrating with cloud storage
-- Conflict resolution
-
-## Enhanced Version Ideas
-```python
-def add_logging():
-    # Log all version actions
-    pass
-
-def cloud_backup():
-    # Sync versions to cloud
-    pass
-```
-
-## Troubleshooting Tips
-- **File not saved:** Check file path
-- **Restore not working:** Check version folder
-- **Permission errors:** Check file access
-
-## Conclusion
-This project teaches file management, versioning, and automation. Extend it for more robust version control and features.
diff --git a/src/content/docs/projects/intermediate/basic_ocr_with_tesseract.mdx b/src/content/docs/projects/intermediate/basic_ocr_with_tesseract.mdx
index 00ed23f9..e5af14b7 100644
--- a/src/content/docs/projects/intermediate/basic_ocr_with_tesseract.mdx
+++ b/src/content/docs/projects/intermediate/basic_ocr_with_tesseract.mdx
@@ -1,5 +1,6 @@
 ---
 title: Basic OCR with Tesseract
+description: Build an OCR app in Python with Tesseract and Tkinter — upload an image and extract its text — then boost accuracy with OpenCV preprocessing, learn page-segmentation modes, batch processing, and PDF/searchable output.
 sidebar:
     order: 10
 hero:
@@ -12,76 +13,172 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Basic OCR with Tesseract is a Python project that extracts text from images using Tesseract OCR. It demonstrates image processing, external tool integration, and automation. This project is ideal for learning about OCR, file handling, and real-world automation.
+Optical Character Recognition turns a *picture* of text into *editable* text — the tech behind scanning receipts, digitizing books, and reading license plates. This project wraps Google's open-source **Tesseract** engine in a Tkinter GUI: upload an image, and the extracted text appears in a scrollable box. It's only a few lines, because `pytesseract` does the heavy lifting. The real lesson is everything *around* the OCR call — because raw scans rarely read cleanly, you'll learn the image preprocessing (grayscale, threshold, denoise) that turns garbage output into accurate text, plus page-segmentation modes, batch processing, and searchable-PDF export.
 
-## Prerequisites
-- Python 3.6 or above
-- pytesseract (`pip install pytesseract`)
-- Pillow (`pip install pillow`)
-- Tesseract installed on your system
+You will leave understanding:
+- How `pytesseract` bridges Python and the Tesseract engine.
+- Why **preprocessing** is 80% of real-world OCR accuracy.
+- What page-segmentation modes (`--psm`) do and when to change them.
+- How to scale from one image to a batch pipeline.
 
-## Before you Start
-Install Python, Tesseract, pytesseract, and Pillow. Ensure Tesseract is in your system PATH.
+## Prerequisites
+- Python 3.6 or above.
+- **The Tesseract engine itself** (separate from the Python package): install via [the Tesseract installer](https://github.com/UB-Mannheim/tesseract/wiki) on Windows, `brew install tesseract` on Mac, or `apt install tesseract-ocr` on Linux.
+- `pip install pytesseract pillow opencv-python`.
+- Tkinter (bundled with Python).
 
 ## Getting Started
-1. Create a folder named `ocr-tesseract`.
-2. Create a file named `basic_ocr_with_tesseract.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/basic_ocr_with_tesseract.py" lang="python" title="Basic OCR with Tesseract" />
-4. Run the script: `python basic_ocr_with_tesseract.py`
 
-## Explanation
+### Point Python at Tesseract (Windows)
+If `pytesseract` can't find the engine, set the path explicitly:
+```python title="setup.py"
+import pytesseract
+pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"
+```
+
+### Create the project
+1. Create a folder named `ocr-app`.
+2. Inside it, create `basic_ocr_with_tesseract.py`.
+3. Install the Python packages and the Tesseract engine.
+
+### Write the code
+<FileCode file="projects/intermediate/basic_ocr_with_tesseract.py" lang="python" title="basic_ocr_with_tesseract.py" showLineNumbers={1} />
+
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ocr-app> python basic_ocr_with_tesseract.py
+# Upload Image -> pick a clear photo/scan of text -> text appears in the box.
+```
+
+## Step-by-Step Explanation
 
-### Code Breakdown
-1. **Import modules**
-```python
+### 1. The OCR call
+```python title="basic_ocr_with_tesseract.py"
 from PIL import Image
 import pytesseract
+
+image = Image.open(file_path)
+extracted_text = pytesseract.image_to_string(image)
+```
+That's the entire recognition step. `Image.open` loads the file with Pillow; `image_to_string` hands it to Tesseract and returns the recognized text. Everything else is UI and error handling.
+
+### 2. The file dialog
+```python title="basic_ocr_with_tesseract.py"
+file_path = filedialog.askopenfilename(
+    filetypes=[("Image Files", "*.png;*.jpg;*.jpeg;*.bmp;*.tiff")])
+if file_path:
+    self.extract_text(file_path)
 ```
-2. **Load image and extract text**
-```python
-img = Image.open('sample.png')
-text = pytesseract.image_to_string(img)
-print(text)
+Restricting `filetypes` keeps users from selecting files Tesseract can't read. The `if file_path` guard handles the user pressing Cancel.
+
+### 3. Showing the result safely
+```python title="basic_ocr_with_tesseract.py"
+try:
+    ...
+    self.text_area.delete(1.0, END)
+    self.text_area.insert(END, extracted_text)
+except Exception as e:
+    self.text_area.delete(1.0, END)
+    self.text_area.insert(END, f"Error: {e}")
 ```
+Clearing before inserting prevents results from stacking. Wrapping in `try/except` turns a missing-engine or corrupt-file error into a visible message instead of a crash.
 
-## Features
-- Extracts text from images
-- Uses Tesseract OCR engine
-- Simple CLI usage
-- Easy to extend for more features
+## The Secret to Good OCR: Preprocessing
 
-## How It Works
-- Loads image file
-- Passes to Tesseract for OCR
-- Prints extracted text
+Tesseract is only as good as the image you feed it. Clean it up with OpenCV first — this single step often doubles accuracy:
+```python title="preprocess.py"
+import cv2
 
-## Use Cases
-- Digitize documents
-- Automate data entry
-- Learn OCR basics
+def clean(path):
+    img = cv2.imread(path)
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)          # 1. drop color
+    gray = cv2.medianBlur(gray, 3)                        # 2. remove speckle noise
+    # 3. binarize: pure black text on white, adaptive to lighting
+    thresh = cv2.adaptiveThreshold(
+        gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+        cv2.THRESH_BINARY, 31, 2)
+    return thresh
 
-## Next Steps
-You can enhance this project by:
-- Processing multiple images
-- Saving text to files
-- Adding a GUI
-- Supporting different languages
-
-## Enhanced Version Ideas
-```python
-def process_folder():
-    # OCR all images in a folder
-    pass
-
-def add_language_support():
-    # Use Tesseract for other languages
-    pass
+text = pytesseract.image_to_string(clean("scan.jpg"))
 ```
+Grayscale → denoise → threshold (black/white) is the standard recipe. For skewed scans, add deskewing; for tiny text, upscale the image first.
 
-## Troubleshooting Tips
-- **Tesseract not found:** Check installation and PATH
-- **No text extracted:** Try different images
+## Page-Segmentation Modes
+
+Tesseract assumes a full page by default. Tell it the layout for better results:
+```python title="psm.py"
+# --psm 6: assume a single uniform block of text (great for paragraphs)
+pytesseract.image_to_string(img, config="--psm 6")
+# --psm 7: treat the image as a single line (receipts, labels)
+pytesseract.image_to_string(img, config="--psm 7")
+# --psm 10: a single character
+```
+Picking the right `--psm` for the content is one of the biggest accuracy levers.
+
+## Get Word Positions (Bounding Boxes)
+
+Beyond plain text, Tesseract can tell you *where* each word is — useful for highlighting or forms:
+```python title="boxes.py"
+data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)
+for i, word in enumerate(data["text"]):
+    if word.strip():
+        x, y, w, h = (data[k][i] for k in ("left", "top", "width", "height"))
+        print(word, (x, y, w, h), "conf:", data["conf"][i])
+```
+
+## Batch Mode and Searchable PDFs
+
+Process a folder, or produce a PDF with an invisible text layer (so it's searchable):
+```python title="batch.py"
+from pathlib import Path
+for img in Path("scans").glob("*.png"):
+    Path(img.with_suffix(".txt")).write_text(
+        pytesseract.image_to_string(Image.open(img)))
+
+# Searchable PDF:
+pdf = pytesseract.image_to_pdf_or_hocr("scan.png", extension="pdf")
+Path("scan.pdf").write_bytes(pdf)
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `TesseractNotFoundError` | Engine not installed / not on PATH | Install Tesseract; set `tesseract_cmd` |
+| Gibberish output | Noisy, low-contrast, or skewed image | Preprocess: grayscale + threshold + denoise |
+| Misses a single line / receipt | Wrong layout assumption | Set `--psm 7` (single line) or `6` (block) |
+| Wrong language | Default is English | Install language data; pass `lang="deu"` etc. |
+| Tiny text unread | Resolution too low | Upscale the image before OCR |
+| Results stack in the box | Didn't clear the Text widget | `delete(1.0, END)` before inserting |
+
+## Variations to Try
+
+1. **Preprocessing pipeline** — grayscale, threshold, deskew (the big win).
+2. **Multi-language** — add `lang=` and the language packs.
+3. **Batch folder** — OCR every image in a directory.
+4. **Searchable PDF** — image → PDF with a hidden text layer.
+5. **Receipt parser** — extract totals/dates with regex on the output.
+6. **Live capture** — OCR from a webcam frame.
+7. **Translate** — pipe extracted text into a translation API.
+8. **Confidence highlighting** — color words by Tesseract's confidence score.
+
+## Real-World Applications
+- **Document digitization** — turning paper archives into searchable text.
+- **Data entry automation** — invoices, receipts, forms.
+- **Accessibility** — reading text aloud for the visually impaired.
+- **License-plate / sign reading** — logistics and automotive.
+
+## Educational Value
+- **OCR fundamentals** — what the engine does and its inputs.
+- **Image preprocessing** — the unglamorous step that drives accuracy.
+- **Configuration** — page-segmentation modes and languages.
+- **Pipelines** — single image → batch → structured output.
+
+## Next Steps
+- Add an **OpenCV preprocessing** step before OCR.
+- Experiment with **`--psm` modes** and **languages**.
+- Build **batch processing** and **searchable-PDF** export.
+- Parse structured docs (receipts/forms) with regex on the output.
 
 ## Conclusion
-This project teaches OCR, image processing, and automation. Extend it for more robust text extraction and features.
+You built an OCR app that extracts text from images in a few lines — and learned that the real skill isn't the `image_to_string` call, it's the preprocessing and configuration that make it *accurate*. Grayscale, threshold, the right `--psm`, and batch pipelines are what separate a demo from the engine behind every scanner app. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/basic_ocr_with_tesseract.py). Explore more vision projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/cryptocurrency-portfolio-tracker.mdx b/src/content/docs/projects/intermediate/cryptocurrency-portfolio-tracker.mdx
index ef0edf88..7f9f7ef2 100644
--- a/src/content/docs/projects/intermediate/cryptocurrency-portfolio-tracker.mdx
+++ b/src/content/docs/projects/intermediate/cryptocurrency-portfolio-tracker.mdx
@@ -1,6 +1,6 @@
 ---
 title: Cryptocurrency Portfolio Tracker
-description: Advanced cryptocurrency portfolio management system with real-time tracking, technical analysis, automated alerts, and comprehensive performance analytics.
+description: Build a full crypto portfolio platform in Python — live prices via CoinGecko, a SQLite schema for holdings and transactions, technical analysis (RSI/MACD/Bollinger), risk metrics (Sharpe, drawdown), automated alerts, and a Flask dashboard.
 sidebar:
     order: 61
 hero:
@@ -13,70 +13,219 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This is the most ambitious project in the intermediate track — a full cryptocurrency portfolio platform that pulls live prices, stores your holdings and transactions in a relational database, computes professional risk and performance metrics, runs technical-analysis indicators, fires automated price alerts on a schedule, and serves it all through a Flask web dashboard. Rather than walk every line of 1,200+, this guide teaches it the way you'd actually understand a real codebase: **by its architecture**. Five focused classes, each with one job, wired together by a Flask app. Learn how they collaborate and you can extend any of them.
 
-Build a professional cryptocurrency portfolio management system that provides real-time portfolio tracking, advanced technical analysis, automated alerts, and comprehensive performance analytics for serious crypto investors.
+You will leave understanding:
+- How to separate concerns across **API**, **database**, **analytics**, **technical-analysis**, and **alerting** layers.
+- How a normalized SQLite schema models portfolios, holdings, and transactions.
+- How financial metrics (P/L, allocation, Sharpe ratio, max drawdown, HHI diversification) are computed.
+- How background scheduling powers live alerts and periodic snapshots.
 
 ## Prerequisites
-
-- Python 3.8 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of financial analysis and trading concepts
-- Familiarity with REST APIs and WebSocket connections
-- Understanding of portfolio management and risk metrics
-- Experience with data visualization and analytics
+- Python 3.8 or above.
+- A text editor or IDE.
+- Comfort with **classes/OOP**, SQL, and REST APIs.
+- `pip install requests pandas numpy flask schedule` (full feature set also uses `ccxt`, `websocket-client`, `plotly`, `ta-lib`, `cryptography`).
+- Basic familiarity with investing concepts (cost basis, P/L, volatility) helps.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `cryptoPortfolioTracker`.
-2. Create a new file and name it `cryptoportfoliotracker.py`.
-3. Install required dependencies: `pip install ccxt requests websockets pandas matplotlib numpy`.
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `cryptoportfoliotracker.py` file.
+### Create the project
+1. Create a folder named `crypto-portfolio-tracker`.
+2. Inside it, create `cryptoportfoliotracker.py`.
+3. Install dependencies (start with the core set above).
 
 ### Write the code
-1. Add the following code to your `cryptoportfoliotracker.py` file.
-<FileCode file="projects/intermediate/cryptoportfoliotracker.py" lang="python" title="Cryptocurrency Portfolio Tracker" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\cryptoPortfolioTracker> python cryptoportfoliotracker.py
-💰 Cryptocurrency Portfolio Tracker
-==================================================
-🚀 Starting portfolio tracker...
-🌐 Real-time price updates enabled
-📈 Access analytics dashboard at: http://localhost:5000
-🔔 Automated alerts active
+<FileCode file="projects/intermediate/cryptoportfoliotracker.py" lang="python" title="cryptoportfoliotracker.py" />
+
+### Run it
+```cmd title="command"
+C:\Users\Your Name\crypto-portfolio-tracker> python cryptoportfoliotracker.py
+# Choose: 1) Web Interface  2) CLI Demo
+# Web dashboard: http://localhost:5000  (demo login: demo / demo)
 ```
 
-## Explanation
-
-1. The system uses CCXT and CoinGecko APIs for real-time and historical market data.
-2. Portfolio management supports multiple portfolios, transaction history, and asset allocation analysis.
-3. Advanced analytics include performance metrics, risk analysis, and historical trend tracking.
-4. Technical analysis engine provides indicators, trading signals, and price targets.
-5. Real-time features use WebSocket connections for live price feeds and automated alerts.
-6. Data visualization is handled with matplotlib and pandas for charts and analytics.
-7. The dashboard provides comprehensive performance, diversification, and risk metrics.
-8. Automated alerts notify users of price changes, milestones, and trading signals.
-9. Portfolio snapshots track historical performance and enable trend analysis.
-10. Database design supports complex financial data with proper relationships.
-11. Risk management includes volatility calculations, Sharpe ratios, and drawdown analysis.
-12. The web interface provides intuitive portfolio management and analytics tools.
+## The Architecture
 
-## Next Steps
+The app is five classes plus a Flask front end. Each layer depends only on the ones below it:
 
-Congratulations! You have successfully created a Cryptocurrency Portfolio Tracker in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add support for more exchanges and data sources
-- Implement advanced charting and visualization features
-- Integrate trading automation and order management
-- Add mobile notifications and email alerts
-- Create multi-user support and authentication
-- Implement tax reporting and export features
-- Add custom technical indicators and strategies
-- Integrate with DeFi protocols and wallets
+```
+┌─────────────────────────────────────────┐
+│ CryptoPortfolioApp (Flask routes + UI)   │
+├───────────────┬───────────────┬──────────┤
+│ PortfolioAnalyzer │ TechnicalAnalyzer │ AlertManager │
+├───────────────┴───────────────┴──────────┤
+│ CryptoDatabase (SQLite)   CryptoAPI (HTTP)│
+└─────────────────────────────────────────┘
+```
+This separation is the real lesson: each class is independently testable and replaceable. Swap CoinGecko for Binance and only `CryptoAPI` changes.
 
-## Conclusion
+## Layer 1: `CryptoAPI` — Data with Caching and Rate Limits
+
+Talking to a public API responsibly means caching results and respecting rate limits:
+```python title="cryptoportfoliotracker.py"
+def _rate_limit_check(self):
+    now = time.time()
+    while self.api_calls and self.api_calls[0] <= now - 60:
+        self.api_calls.popleft()                 # drop calls older than 60s
+    if len(self.api_calls) >= self.max_calls_per_minute:
+        time.sleep(60 - (now - self.api_calls[0]))
+    self.api_calls.append(now)
+```
+A `deque` of timestamps enforces "max N calls per minute" — the sliding-window rate limiter every API client needs. Prices are also cached for 60 seconds, so repeated dashboard loads don't hammer CoinGecko:
+```python title="cryptoportfoliotracker.py"
+if symbol in self.price_cache:
+    cache_time, price = self.price_cache[symbol]
+    if time.time() - cache_time < self.cache_duration:
+        cached_prices[symbol] = price            # serve from cache
+```
+
+## Layer 2: `CryptoDatabase` — A Real Schema
+
+Eight related tables model the whole domain. The key relationships:
+```python title="cryptoportfoliotracker.py"
+# portfolios belong to users; holdings & transactions belong to portfolios
+CREATE TABLE holdings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    portfolio_id INTEGER NOT NULL,
+    symbol TEXT NOT NULL,
+    amount REAL NOT NULL,
+    average_cost REAL NOT NULL,
+    ...
+    FOREIGN KEY (portfolio_id) REFERENCES portfolios (id)
+)
+```
+Note the design choices: `FOREIGN KEY` constraints enforce relationships, a `CHECK(transaction_type IN ('buy','sell',...))` validates enums at the DB level, and `portfolio_snapshots` stores point-in-time JSON so historical performance can be replayed. This is how you model financial data that has to stay consistent.
+
+## Layer 3: `PortfolioAnalyzer` — The Money Math
+
+This is where holdings become insight. For each holding it computes current value and profit/loss:
+```python title="cryptoportfoliotracker.py"
+current_value = amount * current_price
+profit_loss = current_value - (amount * avg_cost)
+profit_loss_pct = (profit_loss / (amount * avg_cost)) * 100 if avg_cost > 0 else 0
+```
+Then portfolio-level risk metrics from the snapshot history:
+```python title="cryptoportfoliotracker.py"
+# Annualized volatility from daily returns
+snapshots_df['daily_return'] = snapshots_df['total_value'].pct_change()
+volatility = snapshots_df['daily_return'].std() * np.sqrt(365) * 100
+
+# Sharpe ratio (risk-adjusted return, 0% risk-free assumed)
+sharpe_ratio = (snapshots_df['daily_return'].mean() * 365) / (volatility / 100)
 
-In this project, you learned how to build a professional cryptocurrency portfolio management system in Python. You explored real-time data integration, technical analysis, automated alerts, and advanced analytics. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/cryptoportfoliotracker.py)
+# Maximum drawdown — worst peak-to-trough drop
+running_max = snapshots_df['total_value'].expanding().max()
+max_drawdown = ((snapshots_df['total_value'] - running_max) / running_max).min() * 100
+```
+And a **diversification score** using the Herfindahl-Hirschman Index — a real concentration metric from economics:
+```python title="cryptoportfoliotracker.py"
+allocations = holdings_df['allocation_percentage'].values / 100
+hhi = np.sum(allocations ** 2)               # 1.0 = everything in one coin
+diversification_score = (1 - hhi) * 100      # higher = better diversified
+```
+
+## Layer 4: `TechnicalAnalyzer` — Indicators and Signals
+
+Standard trading indicators, computed with pandas:
+```python title="cryptoportfoliotracker.py"
+def _calculate_rsi(self, prices, period=14):
+    delta = prices.diff()
+    gain = (delta.where(delta > 0, 0)).rolling(period).mean()
+    loss = (-delta.where(delta < 0, 0)).rolling(period).mean()
+    rs = gain / loss
+    return (100 - (100 / (1 + rs))).iloc[-1]   # <30 oversold, >70 overbought
+```
+RSI, MACD, Bollinger Bands, and moving averages each cast a vote; the majority becomes a buy/sell/hold **signal**:
+```python title="cryptoportfoliotracker.py"
+buy_signals = signals.count('buy')
+sell_signals = signals.count('sell')
+return 'buy' if buy_signals > sell_signals else 'sell' if sell_signals > buy_signals else 'hold'
+```
+This ensemble-of-indicators approach is exactly how simple trading bots make decisions.
+
+## Layer 5: `AlertManager` — Background Scheduling
+
+Alerts run on a timer in a daemon thread, so the web app stays responsive:
+```python title="cryptoportfoliotracker.py"
+schedule.every(1).minutes.do(self._check_alerts)
+monitor_thread = threading.Thread(target=self._run_monitor, daemon=True)
+monitor_thread.start()
+```
+Each check fetches current prices, tests every active alert's condition (`price_above`, `change_below`, …), and — crucially — **debounces** so you aren't spammed:
+```python title="cryptoportfoliotracker.py"
+if last_triggered and datetime.now() - last_trigger_time < timedelta(hours=1):
+    continue            # already alerted within the last hour
+```
+
+## The Flask Layer Ties It Together
+
+Routes are thin — they delegate to the classes above and render templates:
+```python title="cryptoportfoliotracker.py"
+@self.app.route('/portfolio/<int:portfolio_id>')
+def portfolio_detail(portfolio_id):
+    metrics = self.analyzer.calculate_portfolio_metrics(portfolio_id)
+    performance = self.analyzer.generate_performance_report(portfolio_id)
+    return render_template('portfolio_detail.html', metrics=metrics, performance=performance)
+```
+Adding a transaction recomputes holdings with proper **average-cost** accounting:
+```python title="cryptoportfoliotracker.py"
+new_amount = old_amount + amount
+new_total_cost = old_total_cost + (amount * price)
+new_avg_cost = new_total_cost / new_amount     # weighted average cost basis
+```
+
+## Security Notes (Important)
+
+The starter code makes choices fine for a demo but **not** for production:
+
+| Demo code | Production fix |
+|---|---|
+| `app.secret_key = 'crypto_portfolio_secret_2024'` | Load from an environment variable; make it random |
+| `hashlib.sha256(password)` for passwords | Use `bcrypt`/`argon2` with a salt — SHA-256 is too fast |
+| `debug=True` | Never in production (exposes a code-execution console) |
+| API keys in the DB | Encrypt with the included `Fernet` setup; never log them |
+| `ssl.CERT_NONE` on WebSocket | Verify certificates |
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `429 Too Many Requests` | Ignoring API limits | Use the rate limiter + price cache (built in) |
+| Wrong P/L after selling | Cost basis not recalculated | Use weighted average-cost accounting |
+| Volatility/Sharpe are `0` | No snapshot history yet | Let the snapshot scheduler run first |
+| Alerts fire repeatedly | No debounce | Skip if `last_triggered` within an hour |
+| App hangs on startup | Blocking work on the main thread | Run monitoring/snapshots in daemon threads |
+| `ta-lib` won't install | Needs a system C library | Use the pandas-based indicators (no `ta-lib`) |
+
+## Variations to Try
+
+1. **More data sources** — add Binance/Kraken via `ccxt`.
+2. **Live charts** — Plotly candlesticks with indicator overlays.
+3. **Real email/SMS alerts** — wire up the SMTP stub or Twilio.
+4. **Tax reporting** — FIFO/LIFO realized-gain calculations.
+5. **DeFi/wallet integration** — read on-chain balances.
+6. **Backtesting** — replay history to test a signal strategy.
+7. **Multi-currency** — track value in EUR/GBP, not just USD.
+8. **Proper auth** — sessions, hashed passwords, CSRF protection.
+
+## Real-World Applications
+- **Portfolio trackers** — CoinStats, Delta, Kubera.
+- **Trading dashboards** — analytics for active traders.
+- **Robo-advisors** — automated allocation and rebalancing.
+- **Risk management** — institutional exposure monitoring.
+
+## Educational Value
+- **Layered architecture** — separating API, data, analytics, and UI.
+- **Database design** — normalized schemas with constraints and relationships.
+- **Quantitative finance** — Sharpe, drawdown, HHI, technical indicators in code.
+- **Production concerns** — rate limiting, caching, scheduling, and security trade-offs.
+
+## Next Steps
+- Run the **CLI demo** first to see prices and analysis without the web layer.
+- Read each class in isolation — start with `CryptoAPI`, end with the Flask routes.
+- Harden the **security** issues above before deploying anywhere.
+- Add **live charts** and a real **alert channel**.
+
+## Conclusion
+You studied a production-shaped crypto platform not line by line but **layer by layer** — API, database, analytics, technical analysis, alerts, and a Flask UI, each doing one job and collaborating cleanly. That separation of concerns, plus real techniques like rate limiting, average-cost accounting, and risk metrics, is what turns a script into software. Treat each layer as a project of its own and extend it. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/cryptoportfoliotracker.py). Explore more finance and data projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/ecommerce-analytics.mdx b/src/content/docs/projects/intermediate/ecommerce-analytics.mdx
index 47bf7bb8..02e6a06c 100644
--- a/src/content/docs/projects/intermediate/ecommerce-analytics.mdx
+++ b/src/content/docs/projects/intermediate/ecommerce-analytics.mdx
@@ -1,6 +1,6 @@
 ---
 title: E-commerce Analytics Platform
-description: A comprehensive analytics platform for e-commerce businesses featuring sales tracking, customer segmentation, product performance analysis, marketing effectiveness measurement, AI-powered forecasting, and cohort retention analysis.
+description: Build an e-commerce analytics platform in Python — SQLite warehouse with sample data, RFM customer segmentation, product/marketing analysis, a RandomForest sales forecast, cohort retention, and a Plotly Flask dashboard. CLI included.
 sidebar: 
     order: 62
 hero:
@@ -13,265 +13,149 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This is a data-science capstone disguised as a business app. You'll build the analytics brain behind an online store: an 8-table SQLite warehouse (customers, products, orders, sessions, campaigns…), a synthetic-data generator so there's something to analyze, and a suite of real analytics — period-over-period sales growth, **RFM customer segmentation**, product profitability, marketing-channel attribution, a **machine-learning sales forecast**, and **cohort retention** analysis — all surfaced through a Plotly-powered Flask dashboard (plus a CLI). It's the project that connects SQL, pandas, scikit-learn, and web dashboards into one pipeline.
 
-This comprehensive analytics platform provides powerful business intelligence tools for e-commerce businesses. It features sales tracking, customer segmentation, product performance analysis, marketing effectiveness measurement, AI-powered sales forecasting, and cohort retention analysis with an interactive web dashboard.
+You will leave understanding:
+- How a star-schema-style warehouse models an e-commerce business.
+- **RFM** (Recency, Frequency, Monetary) segmentation with pandas `qcut`.
+- How to engineer time-series features (lags, moving averages) and train a `RandomForestRegressor` to forecast sales.
+- What cohort analysis reveals about retention — and the pandas idioms behind it.
 
 ## Prerequisites
-
-- Python 3.8 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of data analysis and business intelligence
-- Familiarity with machine learning concepts
-- Understanding of web development with Flask
-- Experience with data visualization and analytics
-- Basic knowledge of e-commerce metrics and KPIs
+- Python 3.8 or above.
+- A text editor or IDE.
+- `pip install pandas numpy scikit-learn plotly flask` (the code also imports `matplotlib`/`seaborn`).
+- Solid SQL (`JOIN`, `GROUP BY`, window-ish aggregates) and pandas comfort.
+- Basic ML literacy (train/test split, regression, R²). See [ML Model Trainer](./ml-model-trainer).
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `ecommerceAnalytics`.
-2. Create a new file and name it `ecommerceanalytics.py`.
-3. Install required dependencies: `pip install flask pandas numpy matplotlib seaborn plotly scikit-learn sqlite3`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `ecommerceanalytics.py` file.
+### Create the project
+1. Create a folder named `ecommerce-analytics`.
+2. Inside it, create `ecommerceanalytics.py`.
+3. Install dependencies (above). First run seeds ~1,000 customers, 500 products, 2,000 orders, 5,000 sessions.
 
 ### Write the code
-1. Add the following code to your `ecommerceanalytics.py` file.
-<FileCode file="projects/intermediate/ecommerceanalytics.py" lang="python" title="E-commerce Analytics Platform" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\ecommerceAnalytics> python ecommerceanalytics.py
-� E-commerce Analytics Platform
-==================================================
-🚀 Starting analytics platform...
-📊 Dashboard available at: http://localhost:5000
-🤖 AI forecasting models loaded
-� Analytics engine ready
-```
-
-### 🏗️ Project Structure
+<FileCode file="projects/intermediate/ecommerceanalytics.py" lang="python" title="ecommerceanalytics.py" />
 
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ecommerce-analytics> python ecommerceanalytics.py
+# Choose: 1) Web Dashboard (http://localhost:5000)  2) CLI Analytics Demo
 ```
-ecommerce_analytics/
-├── ecommerceanalytics.py          # Main analytics platform
-├── templates/
-│   └── ecommerce_dashboard.html   # Web dashboard template
-├── ecommerce_analytics.db         # SQLite database (auto-generated)
-└── requirements.txt               # Project dependencies
-```
-
-### 🚀 How to Run
-
-1. **Install Dependencies**:
-   ```bash title="terminal" showLineNumbers{1}
-   pip install flask pandas numpy matplotlib seaborn plotly scikit-learn
-   ```
-
-2. **Run the Platform**:
-   ```bash title="terminal" showLineNumbers{1}
-   python ecommerceanalytics.py
-   ```
-
-3. **Choose Interface**:
-   - **Option 1**: Web Dashboard (Interactive GUI)
-   - **Option 2**: CLI Analytics Demo
-
-4. **Access Dashboard**:
-   - Open browser to `http://localhost:5000`
-   - Explore interactive analytics and charts
-
-### 📊 Analytics Features
-
-#### Sales Analytics
-- **Revenue Tracking**: Daily, weekly, monthly revenue analysis
-- **Order Analysis**: Order volume, average order value trends
-- **Growth Metrics**: Period-over-period growth calculations
-- **Performance KPIs**: Key performance indicators and benchmarks
-
-#### Customer Segmentation
-- **RFM Analysis**: Recency, Frequency, Monetary value segmentation
-- **Customer Lifetime Value**: CLV calculation and analysis
-- **Segment Classification**: Champions, loyal customers, at-risk identification
-- **Retention Analysis**: Customer behavior and churn prediction
-
-#### Product Intelligence
-- **Performance Metrics**: Revenue, units sold, profit margins
-- **Inventory Management**: Stock alerts and turnover analysis
-- **Category Analysis**: Product category performance comparison
-- **Slow-Moving Inventory**: Identification of underperforming products
-
-#### Marketing Effectiveness
-- **Channel Analysis**: Customer acquisition channel performance
-- **Conversion Tracking**: Session analysis and conversion rates
-- **Campaign ROI**: Marketing campaign effectiveness measurement
-- **Traffic Analysis**: Source attribution and device performance
-
-#### Predictive Analytics
-- **Sales Forecasting**: AI-powered revenue and order predictions
-- **Trend Analysis**: Historical pattern recognition
-- **Seasonal Adjustments**: Time-based forecasting models
-- **Model Validation**: Accuracy metrics and performance tracking
-
-### 🎨 Example Usage
-
-```python title="ecommerceanalytics.py" showLineNumbers{1}
-# Initialize analytics platform
-analytics = EcommerceAnalytics()
-
-# Get sales overview for last 30 days
-sales_data = analytics.get_sales_overview(30)
-print(f"Revenue: ${sales_data['current_metrics']['total_revenue']:,.2f}")
-
-# Analyze customer segments
-segments = analytics.analyze_customer_segments()
-for segment, count in segments['segment_distribution'].items():
-    print(f"{segment}: {count} customers")
 
-# Product performance analysis
-products = analytics.analyze_product_performance(30)
-for product in products['top_products'][:3]:
-    print(f"{product['name']}: ${product['revenue']:,.2f}")
+## Step-by-Step Explanation
 
-# Sales forecasting
-forecast = analytics.predict_sales_forecast(30)
-print(f"30-day forecast: ${forecast['summary']['total_predicted_revenue']:,.2f}")
+### 1. A warehouse, not just tables
+Eight related tables model the whole funnel: `customers → sessions → product_views → orders → order_items`, plus `products`, `campaigns`, and `inventory_movements`. This is how analytics systems are structured — separate facts (orders, sessions) from dimensions (customers, products) so you can slice any way. `generate_sample_data()` then fabricates a realistic dataset so every analysis has something to chew on.
 
-# Marketing effectiveness
-marketing = analytics.analyze_marketing_effectiveness()
-print(f"Best channel: {marketing['summary_metrics']['best_channel']}")
+### 2. Sales overview with growth
+```python title="ecommerceanalytics.py"
+# current period vs the immediately preceding period of equal length
+for metric in ['total_orders', 'total_revenue', 'avg_order_value', 'unique_customers']:
+    if previous[metric] > 0:
+        growth_rates[f"{metric}_growth"] = ((current[metric] - previous[metric]) / previous[metric]) * 100
 ```
+Every metric is reported *with its growth rate* — comparing this 30 days to the previous 30. A number without a trend is almost useless in business analytics.
+
+### 3. RFM customer segmentation
+The crown jewel. RFM scores each customer on **Recency** (how recently they bought), **Frequency** (how often), and **Monetary** (how much), then labels them:
+```python title="ecommerceanalytics.py"
+df['recency_score']   = pd.qcut(df['recency_days'], 5, labels=[5,4,3,2,1])   # recent = high
+df['frequency_score'] = pd.qcut(df['frequency'].rank(method='first'), 5, labels=[1,2,3,4,5])
+df['monetary_score']  = pd.qcut(df['total_spent'], 5, labels=[1,2,3,4,5])
+
+def segment_customers(row):
+    if row['recency_score'] >= 4 and row['frequency_score'] >= 4: return 'Champions'
+    elif row['recency_score'] <= 2 and row['frequency_score'] >= 4: return 'At Risk'
+    ...
+```
+`pd.qcut` splits a column into 5 equal-sized buckets (quintiles) — note recency is reversed (recent buyers score *high*). The result is actionable: "Champions" get loyalty perks, "At Risk" get win-back emails. This is real CRM analytics in ~40 lines.
+
+### 4. Product performance with a single query
+```python title="ecommerceanalytics.py"
+COALESCE(SUM(oi.total_price - (p.cost * oi.quantity)), 0) as profit
+...
+df['profit_margin'] = np.where(df['revenue'] > 0, (df['profit'] / df['revenue']) * 100, 0)
+df['inventory_turnover'] = np.where(df['stock_quantity'] > 0, df['units_sold'] / df['stock_quantity'], 0)
+```
+One `LEFT JOIN` across products→order_items→orders yields units sold, revenue, and profit per product; pandas then derives margin and turnover. `np.where` is the vectorized guard against divide-by-zero — far faster than a Python loop.
+
+### 5. Machine-learning sales forecast
+This is where it gets serious. The forecaster engineers time-series features and trains a random forest:
+```python title="ecommerceanalytics.py"
+df['revenue_lag_1'] = df['revenue'].shift(1)      # yesterday
+df['revenue_lag_7'] = df['revenue'].shift(7)      # same day last week
+df['revenue_ma_7']  = df['revenue'].rolling(7).mean()   # weekly trend
+...
+revenue_model = RandomForestRegressor(n_estimators=100, random_state=42)
+revenue_model.fit(X_train, y_train)
+revenue_r2 = r2_score(y_test, revenue_model.predict(X_test))
+```
+**Lag features** (yesterday, last week) and **moving averages** let a regressor learn seasonality and momentum. It reports R² so you know how much to trust it, then rolls forward day-by-day to predict the next 30. This is the standard recipe for tabular time-series forecasting.
+
+### 6. Cohort retention
+Group customers by signup month, then track what fraction return in each later month:
+```python title="ecommerceanalytics.py"
+df['registration_month'] = df['registration_date'].dt.to_period('M')
+cohort_table = cohort_data.pivot(index='registration_month', columns='period_number', values='customer_id')
+cohort_table_pct = cohort_table.divide(cohort_sizes, axis=0)    # retention rates
+```
+The pivot turns a flat event log into the classic triangular cohort grid — the single most revealing view of whether a business actually retains customers.
 
-### 📈 Key Analytics Insights
-
-#### Business Metrics
-- **Revenue Trends**: Track daily, weekly, and monthly revenue patterns
-- **Customer Acquisition**: Monitor new customer acquisition and channels
-- **Order Patterns**: Analyze order frequency and seasonality
-- **Profit Analysis**: Calculate margins and profitability by product/category
-
-#### Customer Intelligence
-- **Segmentation**: Identify high-value customers and at-risk segments
-- **Lifetime Value**: Calculate and predict customer lifetime value
-- **Retention Rates**: Track customer retention and churn patterns
-- **Purchase Behavior**: Analyze buying patterns and preferences
-
-#### Operational Insights
-- **Inventory Optimization**: Identify fast-moving and slow-moving inventory
-- **Demand Forecasting**: Predict future demand for better planning
-- **Supply Chain**: Optimize stock levels and reorder points
-- **Performance Monitoring**: Track KPIs and operational efficiency
-
-### 🎯 Advanced Features
-
-#### Machine Learning Models
-- **Random Forest**: Sales forecasting and trend prediction
-- **K-Means Clustering**: Customer segmentation automation
-- **Time Series Analysis**: Seasonal pattern recognition
-- **Predictive Modeling**: Revenue and order volume forecasting
-
-#### Dashboard Components
-- **Interactive Charts**: Plotly-powered visualizations
-- **Real-time Updates**: Live data refresh and monitoring
-- **Export Capabilities**: Data export and report generation
-- **Mobile Responsive**: Cross-device dashboard access
-
-#### Data Analysis
-- **Cohort Analysis**: Customer retention tracking over time
-- **Funnel Analysis**: Conversion funnel optimization
-- **A/B Testing**: Campaign and feature performance comparison
-- **Statistical Analysis**: Advanced statistical calculations
-
-### 📊 Database Schema
-
-The platform uses a comprehensive SQLite database with tables for:
-
-- **Customers**: Customer information and metrics
-- **Products**: Product catalog and inventory
-- **Orders**: Order transactions and status
-- **Order Items**: Detailed order line items
-- **Sessions**: Website analytics and behavior
-- **Product Views**: Product interaction tracking
-- **Campaigns**: Marketing campaign data
-- **Inventory Movements**: Stock tracking
-
-### 🎨 Customization Options
-
-1. **Add New Metrics**: Extend analytics with custom KPIs
-2. **Custom Segments**: Create specialized customer segments
-3. **Advanced Forecasting**: Implement additional ML models
-4. **Integration APIs**: Connect to external data sources
-5. **Custom Reports**: Build specialized business reports
-6. **Alert Systems**: Set up automated business alerts
-
-### 🔧 Technical Architecture
+### 7. Dashboard: Python computes, JS renders
+The Flask app exposes each analysis as a JSON API; the browser fetches and renders with Plotly + jQuery. Charts are serialized server-side with `PlotlyJSONEncoder` and re-hydrated client-side — clean separation of compute and presentation.
 
-#### Backend Components
-- **Flask Application**: Web server and API endpoints
-- **SQLite Database**: Data storage and persistence
-- **Pandas/Numpy**: Data processing and analysis
-- **Scikit-learn**: Machine learning models
-- **Plotly**: Chart generation and visualization
+## Two Bugs to Fix in the Source
 
-#### Frontend Features
-- **Bootstrap**: Responsive UI framework
-- **jQuery**: Interactive functionality
-- **Plotly.js**: Client-side chart rendering
-- **Font Awesome**: Professional icons
-- **Responsive Design**: Mobile-friendly interface
+This code targets older library versions. On a current stack it breaks in two spots:
 
-### 🎯 Business Applications
+| Line | Bug | Fix |
+|---|---|---|
+| `df['week_of_year'] = df['date'].dt.week` | `.dt.week` was **removed** in pandas ≥1.1 | `df['date'].dt.isocalendar().week` |
+| `(df['order_month'] - df['registration_month']).apply(attrgetter('n'))` | `attrgetter` is **never imported** → `NameError` | `from operator import attrgetter`, or `.apply(lambda x: x.n)` |
 
-#### Retail Analytics
-- **E-commerce Stores**: Online retail performance tracking
-- **Inventory Management**: Stock optimization and planning
-- **Customer Experience**: Shopping behavior analysis
-- **Revenue Optimization**: Pricing and promotion strategies
+Spotting version-rot like this is a real maintenance skill — the fix is small but the app won't run without it.
 
-#### Marketing Intelligence
-- **Campaign Analysis**: Marketing ROI measurement
-- **Customer Acquisition**: Channel effectiveness tracking
-- **Conversion Optimization**: Funnel improvement strategies
-- **Retention Marketing**: Customer loyalty programs
+## Common Mistakes
 
-#### Strategic Planning
-- **Business Forecasting**: Revenue and growth predictions
-- **Market Analysis**: Competitive positioning insights
-- **Resource Planning**: Inventory and capacity optimization
-- **Performance Monitoring**: KPI tracking and reporting
+| Problem | Cause | Fix |
+|---|---|---|
+| `AttributeError: 'dt' ... week` | Removed pandas accessor | Use `.dt.isocalendar().week` |
+| `NameError: attrgetter` | Missing import | `from operator import attrgetter` |
+| `qcut` "bin edges not unique" | Too many tied values for 5 bins | `rank(method='first')` first (the code does for frequency) |
+| Forecast returns an error | < ~20 clean daily rows | Need more history; widen the date range |
+| Misleading R² | Random forest overfits small data | More data; cross-validate; try simpler models |
+| Dashboard charts blank | API error or empty data | Check the `/api/...` endpoints return JSON |
 
-### 📚 Educational Value
+## Variations to Try
 
-This project demonstrates:
+1. **Fix the two bugs** and get it running on a modern stack.
+2. **K-Means segments** — the code imports `KMeans`; cluster on RFM instead of rules.
+3. **Cohort heatmap** — visualize the retention grid with a Plotly heatmap.
+4. **Real data** — load an actual orders CSV instead of the generator.
+5. **Better forecasting** — try Prophet or XGBoost; add holiday features.
+6. **Churn prediction** — classify which customers will lapse.
+7. **Market-basket analysis** — "customers who bought X also bought Y".
+8. **Export reports** — scheduled PDF/email summaries.
 
-## Explanation
+## Real-World Applications
+- **BI dashboards** — the analytics layer of any e-commerce stack.
+- **CRM & retention** — RFM drives loyalty and win-back campaigns.
+- **Demand planning** — forecasts feed inventory and staffing.
+- **Marketing attribution** — channel ROI and conversion analysis.
 
-1. The `EcommerceAnalytics` class manages the complete analytics platform with Flask web framework.
-2. The `SalesAnalyzer` provides comprehensive sales tracking and performance metrics.
-3. The `CustomerSegmentationEngine` implements RFM analysis and customer lifetime value calculations.
-4. The `ProductPerformanceAnalyzer` tracks inventory, profitability, and product insights.
-5. The `MarketingAnalyzer` measures channel effectiveness and conversion rates.
-6. The `SalesForecastingEngine` uses Random Forest models for AI-powered predictions.
-7. The `CohortAnalysisEngine` provides customer retention and behavior analysis.
-8. Interactive dashboard uses Plotly for professional data visualizations.
-9. Database design supports complex e-commerce analytics with proper relationships.
-10. Machine learning models provide predictive insights for business planning.
-11. Comprehensive KPIs and metrics support data-driven decision making.
-12. Export capabilities allow sharing insights and generating reports.
+## Educational Value
+- **Data warehousing** — fact/dimension modeling in SQLite.
+- **Analytics in pandas** — `groupby`, `qcut`, pivots, vectorized math.
+- **Applied ML** — feature engineering and forecasting with scikit-learn.
+- **Full pipeline** — SQL → pandas → ML → API → interactive charts.
 
 ## Next Steps
-
-Congratulations! You have successfully created an E-commerce Analytics Platform in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add real-time data streaming capabilities
-- Implement advanced ML models for better predictions
-- Create API integrations with e-commerce platforms
-- Add mobile responsive dashboard features
-- Implement advanced reporting with PDF generation
-- Create multi-tenant support for multiple businesses
-- Add cloud deployment and scalability features
-- Integrate with payment processing analytics
+- Patch the **`.dt.week`** and **`attrgetter`** bugs.
+- Swap rule-based segments for **K-Means**; add a **cohort heatmap**.
+- Upgrade the forecast (**Prophet/XGBoost**, holiday features).
+- Add **churn prediction** and **scheduled reports**.
 
 ## Conclusion
-
-In this project, you learned how to create a comprehensive E-commerce Analytics Platform in Python using machine learning, data analysis, and web development. You explored business intelligence, predictive analytics, customer segmentation, and building professional dashboards for data-driven decision making. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/ecommerceanalytics.py)
+You built the analytics engine of an online store — a warehouse, RFM segmentation, profitability analysis, an ML sales forecast, and cohort retention — wired into a Plotly dashboard and a CLI. Along the way you saw the full data-science pipeline (SQL → pandas → scikit-learn → web) and practiced a genuine maintenance skill: diagnosing the library version-rot that keeps the code from running. Fix those two bugs and it's a portfolio centerpiece. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/ecommerceanalytics.py). Explore more data and ML projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/ecommerce-website.mdx b/src/content/docs/projects/intermediate/ecommerce-website.mdx
index 60f6e62f..769fcea8 100644
--- a/src/content/docs/projects/intermediate/ecommerce-website.mdx
+++ b/src/content/docs/projects/intermediate/ecommerce-website.mdx
@@ -1,5 +1,6 @@
 ---
 title: E-commerce Website (Basic)
+description: Build a basic e-commerce site in Python with Flask — product listing, add-to-cart, and total calculation — then fix the global-cart bug with sessions and add quantities, checkout, a database, and templates.
 sidebar:
   order: 104
 hero:
@@ -12,68 +13,185 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Every online store boils down to three moves: show products, let people add them to a cart, and total it up. This project builds exactly that in Flask — a routes-and-templates web app with a product list, an add-to-cart action, and a cart page that sums the prices. It's the perfect introduction to server-side web development: routing, URL parameters, template rendering, and redirects. Then you'll fix the one bug that makes the starter version unusable as a real site — a *global* cart shared by every visitor — and add quantities, checkout, and a database.
 
-Build a Basic E-commerce Website that displays products, allows adding to a shopping cart, and calculates the total price. The app uses Flask for web development and provides a simple web interface. This project demonstrates web development, routing, and template rendering in Python.
+You will leave understanding:
+- How Flask maps URLs to functions with `@app.route`.
+- The request → process → redirect pattern (POST/Redirect/GET).
+- How `render_template` passes data into Jinja HTML.
+- Why a module-level `cart` list is a serious bug, and how **sessions** fix it.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Flask for web development
-- Knowledge of HTML templates
+- Python 3.6 or above.
+- A text editor or IDE.
+- Flask: `pip install flask`.
+- Basic HTML.
+- Comfort with functions and lists/dicts.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `ecommerce_website`.
-2. Create a new file inside the folder and name it `ecommerce_website.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `ecommerce_website.py` file.
+
+### Create the project
+1. Create a folder named `ecommerce`.
+2. Inside it, create `ecommerce_website.py` and a `templates/` folder.
+3. Install Flask: `pip install flask`.
+
+### Templates
+Flask looks for HTML in `templates/`. You'll need `index.html` and `cart.html`:
+```html title="templates/index.html"
+<h1>Products</h1>
+<ul>
+{% for p in products %}
+  <li>{{ p.name }} — ${{ p.price }}
+      <a href="{{ url_for('add_to_cart', product_id=p.id) }}">Add to cart</a></li>
+{% endfor %}
+</ul>
+<a href="{{ url_for('view_cart') }}">View cart</a>
+```
+```html title="templates/cart.html"
+<h1>Your Cart</h1>
+<ul>{% for item in cart %}<li>{{ item.name }} — ${{ item.price }}</li>{% endfor %}</ul>
+<p>Total: ${{ total_price }}</p>
+<a href="{{ url_for('index') }}">Keep shopping</a>
+```
 
 ### Write the code
 <FileCode file="projects/intermediate/ecommerce_website.py" lang="python" title="ecommerce_website.py" showLineNumbers={1} />
 
-## Key Features
-- Display a list of products
-- Add products to a shopping cart
-- Calculate total price
-- Web interface using Flask and HTML templates
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ecommerce> python ecommerce_website.py
+# Visit http://127.0.0.1:5000 in your browser.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Displaying Products
-Products are stored in a list of dictionaries and rendered using Flask templates:
-```python title="ecommerce_website.py" showLineNumbers={1}
+### 1. The app and data
+```python title="ecommerce_website.py"
+app = Flask(__name__)
 products = [
     {"id": 1, "name": "Laptop", "price": 800},
     {"id": 2, "name": "Smartphone", "price": 500},
-    {"id": 3, "name": "Headphones", "price": 100},
-    {"id": 4, "name": "Keyboard", "price": 50},
+    ...
 ]
+cart = []
+```
+`Flask(__name__)` creates the app. Products are a hard-coded list of dicts (a database stand-in). `cart` is — for now — a single global list. (Hold that thought.)
+
+### 2. Routes map URLs to functions
+```python title="ecommerce_website.py"
+@app.route('/')
+def index():
+    return render_template('index.html', products=products)
+```
+The decorator binds the URL `/` to `index()`. `render_template` loads `index.html` and injects `products` so Jinja can loop over them.
+
+### 3. URL parameters and redirect
+```python title="ecommerce_website.py"
+@app.route('/add_to_cart/<int:product_id>')
+def add_to_cart(product_id):
+    product = next((p for p in products if p['id'] == product_id), None)
+    if product:
+        cart.append(product)
+    return redirect(url_for('view_cart'))
 ```
+`<int:product_id>` captures a number from the URL and passes it as an argument. After adding, the route **redirects** to the cart — the Post/Redirect/Get pattern, which stops a page refresh from re-adding the item.
+
+### 4. Computing the total
+```python title="ecommerce_website.py"
+@app.route('/cart')
+def view_cart():
+    total_price = sum(item['price'] for item in cart)
+    return render_template('cart.html', cart=cart, total_price=total_price)
+```
+A generator expression sums the prices — clean and lazy.
+
+## The Critical Bug: One Cart for the Whole Internet
 
-### Adding to Cart
-Users can add products to the cart, which is stored in a list:
-```python title="ecommerce_website.py" showLineNumbers={1}
-cart.append(product)
+`cart = []` lives at module level, so **every visitor shares the same cart**. Two users shopping at once would see each other's items. The fix is Flask **sessions** — per-user storage backed by a signed cookie:
+```python title="sessions.py"
+from flask import session
+app.secret_key = "change-me"     # required to sign the session cookie
+
+@app.route('/add_to_cart/<int:product_id>')
+def add_to_cart(product_id):
+    cart = session.get("cart", [])
+    cart.append(product_id)          # store IDs, not whole objects
+    session["cart"] = cart
+    return redirect(url_for('view_cart'))
 ```
+Now each browser gets its own cart. This is the single most important upgrade in the project.
+
+## Add Quantities
 
-### Viewing Cart and Total Price
-The cart and total price are displayed using Flask templates:
-```python title="ecommerce_website.py" showLineNumbers={1}
-total_price = sum(item['price'] for item in cart)
-return render_template('cart.html', cart=cart, total_price=total_price)
+Storing duplicate IDs is clumsy. Use a `{product_id: quantity}` map:
+```python title="quantities.py"
+cart = session.get("cart", {})
+cart[str(pid)] = cart.get(str(pid), 0) + 1     # JSON keys must be strings
+session["cart"] = cart
 ```
+On the cart page, multiply price × quantity per line.
+
+## Add a Checkout
 
-## Running the Application
-1. Save the file.
-2. Install Flask:
-```bash
-pip install flask
+A form that captures the order and clears the cart:
+```python title="checkout.py"
+@app.route('/checkout', methods=['POST'])
+def checkout():
+    order = session.pop("cart", {})
+    # save the order to a database here...
+    return render_template('thanks.html', order=order)
 ```
-3. Run the application:
-```bash
-python ecommerce_website.py
+
+## Move Products to a Database
+
+Hard-coded products don't scale. SQLite is the natural next step:
+```python title="db.py"
+import sqlite3
+def get_products():
+    conn = sqlite3.connect("shop.db")
+    rows = conn.execute("SELECT id, name, price FROM products").fetchall()
+    conn.close()
+    return [{"id": r[0], "name": r[1], "price": r[2]} for r in rows]
 ```
 
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Everyone shares one cart | Global `cart` list | Use `session` (per-user) |
+| `RuntimeError: secret key` | Sessions without a key | Set `app.secret_key` |
+| `TemplateNotFound` | HTML not in `templates/` | Put templates in the `templates/` folder |
+| Refresh re-adds the item | Action returned HTML directly | Redirect after the POST (PRG) |
+| Prices wrong with duplicates | Counting items, not quantities | Store `{id: qty}` and multiply |
+| Data lost on restart | Everything in memory | Persist products/orders to a DB |
+
+## Variations to Try
+
+1. **Sessions cart** — the must-do fix above.
+2. **Quantities & remove** — increment, decrement, delete lines.
+3. **Product detail pages** — `/product/<id>` with description and image.
+4. **Search & categories** — filter the catalog.
+5. **User accounts** — login, order history (see [REST API with Authentication](./rest-api-auth)).
+6. **Payment stub** — integrate a sandbox Stripe checkout.
+7. **Admin panel** — add/edit products through a form.
+
+## Real-World Applications
+- **Online stores** — the skeleton of any Shopify-style shop.
+- **Booking systems** — carts generalize to reservations and tickets.
+- **SaaS billing** — plan selection and checkout flows.
+- **Learning Flask** — the canonical "real app" beyond hello-world.
+
+## Educational Value
+- **Web routing** — URLs to handlers, URL parameters.
+- **Templating** — Jinja loops and `url_for`.
+- **State & sessions** — the difference between global and per-user state.
+- **App architecture** — the path from in-memory demo to DB-backed app.
+
+## Next Steps
+- Replace the global cart with **sessions**.
+- Add **quantities**, **remove**, and a **checkout**.
+- Move products and orders into a **database**.
+- Add **accounts** and a **payment** integration.
+
 ## Conclusion
-This Basic E-commerce Website project is a great way to learn about web development and routing in Python. You can extend it by adding user authentication, product search, or payment integration.
+You built a working e-commerce site — products, cart, totals — and learned the routing/templating/redirect loop at the heart of every Flask app. More importantly, you found and fixed the bug that separates a demo from a real store: shared global state versus per-user sessions. With quantities, checkout, and a database, this scales into a genuine shop. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/ecommerce_website.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/ecommerce_website.mdx b/src/content/docs/projects/intermediate/ecommerce_website.mdx
deleted file mode 100644
index 22caddb4..00000000
--- a/src/content/docs/projects/intermediate/ecommerce_website.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: E-commerce Website
-sidebar:
-  order: 18
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/ecommerce_website.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-E-commerce Website is a Python project that simulates an online store with product listings, shopping cart, and checkout functionality. It demonstrates web development, backend logic, and user interaction. This project is ideal for learning about web apps, databases, and business logic.
-
-## Prerequisites
-- Python 3.6 or above
-- Flask (`pip install flask`)
-- SQLite (built-in)
-
-## Before you Start
-Install Python and Flask. Prepare a sample product database for testing.
-
-## Getting Started
-1. Create a folder named `ecommerce-website`.
-2. Create a file named `ecommerce_website.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/ecommerce_website.py" lang="python" title="E-commerce Website" />
-4. Run the script: `python ecommerce_website.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-from flask import Flask, render_template, request, redirect, url_for
-import sqlite3
-```
-2. **Set up Flask app and database.**
-```python
-app = Flask(__name__)
-conn = sqlite3.connect('products.db')
-cursor = conn.cursor()
-```
-3. **Define routes and logic.**
-```python
-@app.route('/')
-def home():
-    # Show product listings
-    pass
-
-@app.route('/cart')
-def cart():
-    # Show shopping cart
-    pass
-
-@app.route('/checkout')
-def checkout():
-    # Handle checkout
-    pass
-```
-4. **Run the app.**
-```python
-if __name__ == '__main__':
-    app.run(debug=True)
-```
-
-## Features
-- Product listings
-- Shopping cart
-- Checkout functionality
-- Simple web interface
-- Easy to extend for more features
-
-## How It Works
-- Handles HTTP requests
-- Renders templates for pages
-- Stores products and cart in database
-
-## GUI Components
-- **Home page:** Lists products
-- **Cart page:** Shows selected items
-- **Checkout page:** Handles payment
-
-## Use Cases
-- Simulate online shopping
-- Learn web development
-- Build portfolio projects
-
-## Next Steps
-You can enhance this project by:
-- Adding user authentication
-- Supporting payment gateways
-- Improving UI with CSS
-- Adding product search/filter
-- Deploying online
-
-## Enhanced Version Ideas
-```python
-def add_payment_gateway():
-    # Integrate with Stripe or PayPal
-    pass
-
-def add_user_login():
-    # Require login for checkout
-    pass
-```
-
-## Troubleshooting Tips
-- **Flask errors:** Check installation
-- **App not running:** Check port and debug mode
-- **Database errors:** Check database setup
-
-## Conclusion
-This project teaches Flask basics, database usage, and web app structure. Extend it for more features and production use.
diff --git a/src/content/docs/projects/intermediate/file-synchronization-tool.mdx b/src/content/docs/projects/intermediate/file-synchronization-tool.mdx
index 53e742c4..13a48466 100644
--- a/src/content/docs/projects/intermediate/file-synchronization-tool.mdx
+++ b/src/content/docs/projects/intermediate/file-synchronization-tool.mdx
@@ -1,5 +1,6 @@
 ---
 title: File Synchronization Tool
+description: Build a Tkinter file sync tool in Python that mirrors one directory into another — copying new and changed files, deleting stragglers — then add a dry-run preview, hash-based change detection, two-way sync, and a progress log.
 sidebar:
   order: 89
 hero:
@@ -12,60 +13,155 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A sync tool is your introduction to serious filesystem work: walking directory trees, comparing modification times, copying with metadata intact, and — the scary part — deleting files. In this tutorial you build a Tkinter app that mirrors a source directory into a target, copying anything new or updated and removing anything that no longer exists at the source. Then you make it trustworthy: a **dry-run preview** before any destructive action, hash-based change detection, optional two-way sync, and a scrollable action log.
 
-Create a File Synchronization Tool that synchronizes files between two directories. The app detects new or updated files, copies them, and provides a summary of actions. This project demonstrates file handling, directory traversal, and GUI development in Python.
+You will leave understanding:
+- How `os.walk` traverses a directory tree, and `os.path.relpath` preserves structure.
+- Why `getmtime` comparison decides what's "newer".
+- Why `shutil.copy2` (not `copy`) keeps timestamps and permissions.
+- How to make destructive tools safe with a preview-before-commit pattern.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of file and directory operations
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (bundled with Python).
+- Comfort with `os` and `shutil` from the standard library.
+- **Two test folders with throwaway files** — never debug a sync tool on real data.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `file_synchronization_tool`.
-2. Create a new file inside the folder and name it `file_synchronization_tool.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `file_synchronization_tool.py` file.
+
+### Create the project
+1. Create a folder named `file-sync-tool`.
+2. Inside it, create `file_synchronization_tool.py`.
+3. Make two test folders (e.g. `src_test`, `dst_test`) with a few dummy files.
 
 ### Write the code
 <FileCode file="projects/intermediate/file_synchronization_tool.py" lang="python" title="file_synchronization_tool.py" showLineNumbers={1} />
 
-## Key Features
-- Detect and copy new or updated files
-- Delete files that no longer exist in the source directory
-- Provide a summary of synchronization actions
-- GUI interface for easy selection of directories
+### Run it
+```cmd title="command"
+C:\Users\Your Name\file-sync-tool> python file_synchronization_tool.py
+# Browse for a source and target folder, then click Synchronize.
+# A summary dialog lists every file copied or deleted.
+```
+
+## Step-by-Step Explanation
+
+### 1. Walk the source tree
+```python title="file_synchronization_tool.py"
+for root, dirs, files in os.walk(self.source_dir):
+    relative_path = os.path.relpath(root, self.source_dir)
+    target_root = os.path.join(self.target_dir, relative_path)
+    if not os.path.exists(target_root):
+        os.makedirs(target_root)
+```
+`os.walk` yields every subdirectory and its files. `relpath` turns an absolute source path into a path *relative* to the source root, which you then re-root onto the target — that's how nested folder structure is preserved on the other side.
 
-## Explanation
+### 2. Copy new or changed files
+```python title="file_synchronization_tool.py"
+if not os.path.exists(target_file) or os.path.getmtime(source_file) > os.path.getmtime(target_file):
+    shutil.copy2(source_file, target_file)
+    actions.append(f"Copied: {source_file} -> {target_file}")
+```
+Two conditions trigger a copy: the file is **missing** at the target, or the source is **newer** (`getmtime` is the last-modified timestamp). `shutil.copy2` copies the *contents and metadata* (timestamps, permissions) — plain `copy` would reset the modification time and break the next comparison.
 
-### Directory Selection
-The app uses Tkinter's file dialog to let users select source and target directories:
-```python title="file_synchronization_tool.py" showLineNumbers={1}
-self.source_dir = filedialog.askdirectory()
-self.target_dir = filedialog.askdirectory()
+### 3. Delete stragglers
+```python title="file_synchronization_tool.py"
+for root, dirs, files in os.walk(self.target_dir):
+    ...
+    if not os.path.exists(source_file):
+        os.remove(target_file)
+        actions.append(f"Deleted: {target_file}")
 ```
+This second walk — over the *target* — removes anything that no longer exists at the source, making the target a true mirror. **This is the dangerous part:** a wrong source folder will wipe the target. The dry-run below is your seatbelt.
 
-### Synchronization Logic
-The tool compares files in both directories and copies new or updated files:
-```python title="file_synchronization_tool.py" showLineNumbers={1}
-if not os.path.exists(destination_file) or os.path.getmtime(source_file) > os.path.getmtime(destination_file):
-    shutil.copy2(source_file, destination_file)
+### 4. Report what happened
+```python title="file_synchronization_tool.py"
+if actions:
+    messagebox.showinfo("Synchronization Complete", "\n".join(actions))
+else:
+    messagebox.showinfo("Synchronization Complete", "No changes were made.")
 ```
+Always tell the user exactly what changed. Silent file operations destroy trust (and data).
+
+## Add a Dry-Run Preview
+
+The single most important upgrade for any destructive tool — compute the actions, show them, act only on confirmation:
+```python title="dryrun.py"
+def plan(self):
+    """Return the list of actions WITHOUT performing them."""
+    actions = []
+    # ...same comparison logic, but append strings instead of copying/deleting...
+    return actions
 
-### User Interface
-The GUI provides buttons for browsing directories and starting synchronization:
-```python title="file_synchronization_tool.py" showLineNumbers={1}
-Button(self.root, text="Synchronize", command=self.synchronize).grid(row=2, column=0, columnspan=3, pady=20)
+def synchronize(self):
+    actions = self.plan()
+    preview = "\n".join(actions) or "No changes."
+    if messagebox.askyesno("Confirm Sync", f"{preview}\n\nApply these changes?"):
+        self.apply(actions)
 ```
+Now the user sees "Delete: report.docx" *before* it's gone.
+
+## Detect Changes by Content, Not Just Time
+
+`getmtime` can lie — a restored backup may have an old timestamp but new content. Hash the files instead:
+```python title="hashing.py"
+import hashlib
 
-## Running the Application
-1. Save the file.
-2. Run the application:
-```bash
-python file_synchronization_tool.py
+def file_hash(path, chunk=65536):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(chunk), b""):
+            h.update(block)
+    return h.hexdigest()
+
+def changed(src, dst):
+    return not os.path.exists(dst) or file_hash(src) != file_hash(dst)
 ```
+Slower, but it never misses an edit and never copies an unchanged file. Read in chunks so large files don't blow up memory.
+
+## Two-Way Sync (Carefully)
+
+True two-way sync keeps the *newest* version of each file on both sides and is genuinely hard — you need to track deletions vs. creations, usually with a stored snapshot of the last sync. Start one-way; only attempt two-way once you've added a manifest of known files.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Target files wiped unexpectedly | Wrong source folder + delete pass | Always run a **dry-run** and confirm first |
+| Unchanged files keep re-copying | Used `copy` (resets mtime) | Use `shutil.copy2` to preserve timestamps |
+| Edits not detected | Same mtime, different content | Compare with a **content hash** |
+| App freezes on big folders | Sync on the main thread | Run on a background thread; show progress |
+| `PermissionError` mid-sync | File open/locked, or no rights | Catch per-file and log; continue the rest |
+| Empty subfolders not mirrored | Only files were handled | Create dirs during the walk (as the code does) |
+
+## Variations to Try
+
+1. **Dry-run by default** — make preview mandatory, apply on confirm.
+2. **Exclude patterns** — skip `.git`, `node_modules`, `*.tmp` via globs.
+3. **Progress bar** — show files-done / total during long syncs.
+4. **Scheduling** — run sync every N minutes with `after` or a cron job.
+5. **Conflict handling** — when both sides changed, keep both with a suffix.
+6. **Cloud target** — sync to S3 or Google Drive via their SDKs.
+7. **Versioned backups** — move deleted files to a `.trash` folder instead of removing.
+
+## Real-World Applications
+- **Backup software** — the core of every incremental backup tool.
+- **Deployment** — pushing build artifacts to a server directory.
+- **Photo/media management** — mirroring a camera card to a library.
+- **Dev environments** — keeping a working copy in sync with a share.
+
+## Educational Value
+- **Filesystem traversal** — `os.walk`, `relpath`, `makedirs`.
+- **Change detection** — mtime vs. content hashing trade-offs.
+- **Safe destructive operations** — the preview-then-commit pattern.
+- **Metadata-aware copying** — why `copy2` matters.
+
+## Next Steps
+- Make the **dry-run preview** mandatory before any delete.
+- Switch to **hash-based** change detection.
+- Add **exclude patterns** and a **progress bar**.
+- Move deletions to a **`.trash` folder** for recoverability.
 
 ## Conclusion
-This File Synchronization Tool is a practical project for learning about file operations, directory traversal, and GUI development in Python. You can extend it by adding logging, conflict resolution, or scheduling features.
+You built a directory mirror that copies new and changed files and prunes the rest, then made it safe with a dry-run preview and accurate with content hashing. Handling files — especially *deleting* them — demands the caution you practiced here: show the plan, confirm, preserve metadata, log everything. That discipline is what turns a risky script into a tool you'd trust with real data. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/file_synchronization_tool.py). Explore more file-handling projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/file_synchronization_tool.mdx b/src/content/docs/projects/intermediate/file_synchronization_tool.mdx
deleted file mode 100644
index 89db896d..00000000
--- a/src/content/docs/projects/intermediate/file_synchronization_tool.mdx
+++ /dev/null
@@ -1,99 +0,0 @@
----
-title: File Synchronization Tool
-sidebar:
-    order: 2
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/file_synchronization_tool.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-File Synchronization Tool is a Python utility that keeps files in two directories synchronized. It demonstrates file system operations, hashing, and automation. This project is great for learning about file management, automation, and error handling in Python.
-
-## Prerequisites
-- Python 3.6 or above
-- os, shutil, hashlib (built-in)
-
-## Before you Start
-Make sure you have Python installed. No external packages are required; all modules used are built-in.
-
-## Getting Started
-1. Create a folder named `file-sync-tool`.
-2. Create a file named `file_synchronization_tool.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/file_synchronization_tool.py" lang="python" title="File Synchronization Tool" />
-4. Run the script: `python file_synchronization_tool.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import os
-import shutil
-import hashlib
-```
-2. **Compare and sync files**
-```python
-def sync_dirs(src, dest):
-    for filename in os.listdir(src):
-        src_file = os.path.join(src, filename)
-        dest_file = os.path.join(dest, filename)
-        if not os.path.exists(dest_file) or hash_file(src_file) != hash_file(dest_file):
-            shutil.copy2(src_file, dest_file)
-```
-3. **Hashing function**
-```python
-def hash_file(path):
-    with open(path, 'rb') as f:
-        return hashlib.md5(f.read()).hexdigest()
-```
-
-## Features
-- Syncs files between folders
-- Uses hashing for change detection
-- Automates backup tasks
-- Simple CLI usage
-
-## How It Works
-- Compares files by hash
-- Copies changed/new files
-- Ensures destination matches source
-
-## Use Cases
-- Backup important files
-- Mirror folders
-- Automate file management
-- Keep USB drives synced
-
-## Next Steps
-You can enhance this project by:
-- Adding logging
-- Supporting subdirectories
-- Scheduling syncs
-- Adding a GUI
-- Handling file deletions
-- Conflict resolution
-
-## Enhanced Version Ideas
-```python
-def sync_with_logging(src, dest):
-    # Log all sync actions
-    pass
-
-def sync_subdirs(src, dest):
-    # Recursively sync folders
-    pass
-```
-
-## Troubleshooting Tips
-- **Permission errors:** Check file access
-- **Hash mismatch:** Re-run sync
-- **File not copied:** Check source/destination paths
-
-## Conclusion
-This project teaches file operations, hashing, and automation. Expand it for more robust syncing and scheduling. Useful for backups and file management.
diff --git a/src/content/docs/projects/intermediate/github-profile-viewer.mdx b/src/content/docs/projects/intermediate/github-profile-viewer.mdx
index cecb3526..60fa849a 100644
--- a/src/content/docs/projects/intermediate/github-profile-viewer.mdx
+++ b/src/content/docs/projects/intermediate/github-profile-viewer.mdx
@@ -1,5 +1,6 @@
 ---
 title: GitHub Profile Viewer
+description: Build a Tkinter app in Python that fetches and displays any GitHub user's profile via the GitHub REST API — then add avatars, repo lists, rate-limit handling, authentication, and a side-by-side profile comparison.
 sidebar:
   order: 103
 hero:
@@ -12,60 +13,150 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+The GitHub REST API is a fantastic teaching API — no key required for basic reads, clean JSON, and data everyone recognizes. In this tutorial you build a Tkinter app that takes a username and shows the user's name, bio, repo count, and followers. Then you grow it into a real profile dashboard: avatar images, a scrollable repository list sorted by stars, authenticated requests for higher rate limits, and a side-by-side comparison of two developers.
 
-Build a GitHub Profile Viewer that fetches and displays GitHub user profile information using the GitHub API. The app provides a GUI for entering usernames and viewing profile details. This project demonstrates API integration, data parsing, and GUI development in Python.
+You will leave understanding:
+- How to call a public REST API and read its JSON response.
+- Why `data.get("name", "N/A")` is safer than `data["name"]`.
+- How API rate limits work and how authentication raises them.
+- The fetch → display pattern that scales to any JSON API.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of HTTP requests and JSON parsing
+- Python 3.6 or above.
+- A text editor or IDE.
+- The `requests` library: `pip install requests`.
+- Tkinter (bundled with Python).
+- Optional: a GitHub Personal Access Token for higher rate limits.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `github_profile_viewer`.
-2. Create a new file inside the folder and name it `github_profile_viewer.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `github_profile_viewer.py` file.
+
+### Create the project
+1. Create a folder named `github-profile-viewer`.
+2. Inside it, create `github_profile_viewer.py`.
+3. Install the dependency: `pip install requests`.
 
 ### Write the code
 <FileCode file="projects/intermediate/github_profile_viewer.py" lang="python" title="github_profile_viewer.py" showLineNumbers={1} />
 
-## Key Features
-- Fetch GitHub user profile information
-- Display details like name, bio, repositories, followers, etc.
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\github-profile-viewer> python github_profile_viewer.py
+# Type a username (e.g. "torvalds") and click "Fetch Profile".
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Fetching Profile Data
-The app uses the GitHub API to fetch user profile information:
-```python title="github_profile_viewer.py" showLineNumbers={1}
+### 1. The endpoint
+```python title="github_profile_viewer.py"
 url = f"https://api.github.com/users/{username}"
 response = requests.get(url)
+```
+GitHub's user endpoint needs no key for basic data. The username goes straight into the path. (In production you'd URL-encode it, but GitHub usernames are already restricted to safe characters.)
+
+### 2. Check the status code
+```python title="github_profile_viewer.py"
 if response.status_code == 200:
     data = response.json()
+    self.display_profile(data)
+else:
+    messagebox.showerror("Error", f"Failed to fetch profile. Status code: {response.status_code}")
 ```
+`404` means no such user, `403` usually means you hit the rate limit. Reporting the code turns a silent failure into a debuggable one.
 
-### Displaying Profile Information
-Profile details are shown in a Tkinter Text widget:
-```python title="github_profile_viewer.py" showLineNumbers={1}
+### 3. Safe field access
+```python title="github_profile_viewer.py"
 self.result_text.insert(END, f"Name: {data.get('name', 'N/A')}\n")
 self.result_text.insert(END, f"Bio: {data.get('bio', 'N/A')}\n")
-self.result_text.insert(END, f"Public Repos: {data.get('public_repos', 'N/A')}\n")
 ```
+Many profiles leave `name` or `bio` empty, returning `null`. `data.get('name', 'N/A')` substitutes a default instead of printing `None` or raising `KeyError`. Use `.get()` for every optional field.
+
+### 4. The Text widget
+```python title="github_profile_viewer.py"
+self.result_text.delete(1.0, END)     # clear previous result
+self.result_text.insert(END, ...)     # append lines
+```
+`1.0` means "line 1, character 0". Clearing before each fetch prevents profiles from stacking on top of each other.
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install requests
+## Beat the Rate Limit with Authentication
+
+Unauthenticated requests are capped at **60/hour**; authenticated ones get **5,000/hour**. Add a token:
+```python title="auth.py"
+import os, requests
+
+headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
+r = requests.get("https://api.github.com/users/torvalds", headers=headers, timeout=10)
 ```
-3. Run the application:
-```bash
-python github_profile_viewer.py
+Create a token at GitHub → Settings → Developer settings → Personal access tokens. Store it in an environment variable, never in the code.
+
+## Show the Avatar
+
+The JSON includes `avatar_url`:
+```python title="avatar.py"
+from io import BytesIO
+import requests
+from PIL import Image, ImageTk     # pip install pillow
+
+def load_avatar(url):
+    raw = requests.get(url, timeout=10).content
+    img = Image.open(BytesIO(raw)).resize((96, 96))
+    return ImageTk.PhotoImage(img)
 ```
+Display it in a `Label(image=...)` — remember to keep a reference or Tkinter garbage-collects the image.
+
+## List the User's Repositories
+
+A second endpoint returns repos; sort them by stars:
+```python title="repos.py"
+def top_repos(username, n=5):
+    r = requests.get(f"https://api.github.com/users/{username}/repos",
+                     params={"sort": "updated", "per_page": 100}, timeout=10)
+    repos = r.json()
+    repos.sort(key=lambda x: x["stargazers_count"], reverse=True)
+    return [(x["name"], x["stargazers_count"], x["language"]) for x in repos[:n]]
+```
+
+## Compare Two Developers
+
+Fetch two profiles and lay them out side by side — followers, repos, and total stars. A great use of the API for "who's more active" debates and a clean way to practice reusing your fetch function.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `403 Forbidden` after a few calls | Hit the 60/hour anonymous limit | Authenticate with a token (5,000/hour) |
+| Prints `None` for name/bio | Field was `null` | Use `data.get(field, "N/A")` |
+| Profiles stack up in the box | Didn't clear the `Text` widget | `delete(1.0, END)` before inserting |
+| Avatar doesn't show | Image garbage-collected | Keep a reference: `self.photo = ...` |
+| App hangs on slow network | No `timeout` | Add `timeout=10` to every request |
+| Crash on empty username | No input guard | Check `if not username` and return early |
+
+## Variations to Try
+
+1. **Repo dashboard** — table of repos with stars, forks, and language.
+2. **Contribution stats** — total stars across all repos, most-used language.
+3. **Org viewer** — switch the endpoint to `/orgs/{name}`.
+4. **Follower explorer** — list followers and click through to their profiles.
+5. **Export** — save a profile summary to JSON or a PDF card.
+6. **Search** — use `/search/users` to find profiles by query.
+7. **Dark mode** — theme the UI; show language colors like GitHub does.
+
+## Real-World Applications
+- **Recruiting tools** — quick candidate snapshots from a username.
+- **Developer dashboards** — track your own or your team's activity.
+- **OSS analytics** — measure project reach and contributor influence.
+- **Portfolio sites** — auto-populate a "my GitHub" section.
+
+## Educational Value
+- **REST APIs** — endpoints, paths, JSON, status codes.
+- **Rate limits & auth** — tokens, headers, and being a good API citizen.
+- **Defensive coding** — `.get()` defaults and status checks.
+- **Working with images** — fetching and rendering remote bytes in a GUI.
+
+## Next Steps
+- Add **token authentication** to lift the rate limit.
+- Render the **avatar** and a **top-repos** list.
+- Build the **side-by-side comparison** view.
+- **Export** profiles to JSON.
 
 ## Conclusion
-This GitHub Profile Viewer project is a great way to learn about API integration and data parsing in Python. You can extend it by adding repository lists, contribution graphs, or user authentication.
+You built a GitHub profile viewer from one `requests.get`, then grew it into a dashboard with avatars, repo rankings, authenticated requests, and comparisons. The fetch → check status → safe-parse → display loop you practiced here is the exact shape of every API client you'll write — only the endpoint changes. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/github_profile_viewer.py). Find more API projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/github_profile_viewer.mdx b/src/content/docs/projects/intermediate/github_profile_viewer.mdx
deleted file mode 100644
index 01228401..00000000
--- a/src/content/docs/projects/intermediate/github_profile_viewer.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: GitHub Profile Viewer
-sidebar:
-  order: 16
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/github_profile_viewer.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-GitHub Profile Viewer is a Python project that fetches and displays GitHub user profiles using the GitHub API. It demonstrates API integration, data parsing, and GUI development. This project is ideal for learning about REST APIs, JSON handling, and interactive desktop apps.
-
-## Prerequisites
-- Python 3.6 or above
-- requests (`pip install requests`)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Install Python and requests. Obtain a GitHub username for testing.
-
-## Getting Started
-1. Create a folder named `github-profile-viewer`.
-2. Create a file named `github_profile_viewer.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/github_profile_viewer.py" lang="python" title="GitHub Profile Viewer" />
-4. Run the script: `python github_profile_viewer.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import requests
-import tkinter as tk
-```
-2. **Fetch GitHub profile data.**
-```python
-url = f'https://api.github.com/users/{username}'
-response = requests.get(url)
-data = response.json()
-```
-3. **Display profile in GUI.**
-```python
-root = tk.Tk()
-root.title('GitHub Profile Viewer')
-# ...setup widgets for profile display...
-root.mainloop()
-```
-
-## Features
-- Fetches GitHub user profiles
-- Displays profile info in GUI
-- Easy to extend for more features
-
-## How It Works
-- User enters GitHub username
-- App fetches and displays profile info
-
-## GUI Components
-- **Label:** Shows profile info
-- **Entry box:** For username input
-- **Button:** Fetches profile
-
-## Use Cases
-- View GitHub profiles
-- Learn API integration
-- Build custom dashboards
-
-## Next Steps
-You can enhance this project by:
-- Displaying repositories
-- Showing followers/following
-- Improving GUI design
-- Adding charts or graphs
-
-## Enhanced Version Ideas
-```python
-def show_repositories():
-    # Display user's repositories
-    pass
-
-def show_followers():
-    # Display user's followers
-    pass
-```
-
-## Troubleshooting Tips
-- **API errors:** Check username and internet connection
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches API usage, JSON parsing, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/gui-sql-database-viewer.mdx b/src/content/docs/projects/intermediate/gui-sql-database-viewer.mdx
index 8c4a60d3..352a5218 100644
--- a/src/content/docs/projects/intermediate/gui-sql-database-viewer.mdx
+++ b/src/content/docs/projects/intermediate/gui-sql-database-viewer.mdx
@@ -1,5 +1,6 @@
 ---
 title: GUI-based SQL Database Viewer
+description: Build a Tkinter SQL database viewer in Python — connect to SQLite, run queries, and show results in a Treeview table — then add safety guards, parameterized queries, schema browsing, and CSV export.
 sidebar:
   order: 101
 hero:
@@ -12,69 +13,172 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A database GUI is the kind of tool you reach for constantly — a mini DB Browser or phpMyAdmin you built yourself. This project connects to a SQLite database, runs whatever SQL you type, and renders the results in a proper table using Tkinter's `Treeview` widget. You'll learn cursors, dynamic columns from `cursor.description`, and result rendering. Then you'll make it safe and useful: guard destructive statements, support parameterized queries, browse the schema, and export results to CSV.
 
-Build a GUI-based SQL Database Viewer that allows users to connect to a database, execute SQL queries, and view results in a table format. This project demonstrates database interaction, SQL query execution, and GUI development in Python.
+You will leave understanding:
+- The SQLite workflow: `connect` → `cursor` → `execute` → `fetchall`.
+- How `cursor.description` gives you column names for any query.
+- How `Treeview` displays tabular data with sortable headings.
+- Why running arbitrary SQL is powerful *and* dangerous — and how to fence it.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of SQL and database operations
+- Python 3.6 or above.
+- A text editor or IDE.
+- Standard library only — `sqlite3` and `tkinter` are built in.
+- Basic SQL (`SELECT`, `INSERT`, `CREATE TABLE`).
+- A SQLite `.db` file to open (or create one — see below).
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `gui_sql_database_viewer`.
-2. Create a new file inside the folder and name it `gui_sql_database_viewer.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `gui_sql_database_viewer.py` file.
+
+### Make a test database (optional)
+```python title="make_db.py"
+import sqlite3
+conn = sqlite3.connect("test.db")
+conn.execute("CREATE TABLE users (id INTEGER, name TEXT, age INTEGER)")
+conn.executemany("INSERT INTO users VALUES (?, ?, ?)",
+                 [(1, "Alice", 30), (2, "Bob", 25), (3, "Carol", 41)])
+conn.commit(); conn.close()
+```
+
+### Create the project
+1. Create a folder named `sql-viewer`.
+2. Inside it, create `gui_sql_database_viewer.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/gui_sql_database_viewer.py" lang="python" title="gui_sql_database_viewer.py" showLineNumbers={1} />
 
-## Key Features
-- Connect to a database
-- Execute SQL queries
-- Display query results in a table format
-- GUI interface for user interaction
-
-## Explanation
-
-### Connecting to Database
-The app allows users to enter a database path and connect:
-```python title="gui_sql_database_viewer.py" showLineNumbers={1}
-Label(root, text="Database Path:").grid(row=0, column=0, padx=10, pady=10)
-self.db_entry = Entry(root, width=50)
-self.db_entry.grid(row=0, column=1, padx=10, pady=10)
-Button(root, text="Connect", command=self.connect_to_db).grid(row=0, column=2, padx=10, pady=10)
+### Run it
+```cmd title="command"
+C:\Users\Your Name\sql-viewer> python gui_sql_database_viewer.py
+# Enter the path to a .db file, click Connect.
+# Type "SELECT * FROM users" and click Execute.
+```
+
+## Step-by-Step Explanation
+
+### 1. Connecting
+```python title="gui_sql_database_viewer.py"
+self.connection = sqlite3.connect(db_path)
+```
+`sqlite3.connect` opens (or creates) a database file and returns a connection. Everything else flows through it. Wrapping it in `try/except sqlite3.Error` turns a bad path into a friendly dialog instead of a crash.
+
+### 2. Executing a query
+```python title="gui_sql_database_viewer.py"
+cursor = self.connection.cursor()
+cursor.execute(query)
+self.connection.commit()
 ```
+A **cursor** runs SQL and holds the result set. `commit()` saves changes for write statements (`INSERT`/`UPDATE`/`DELETE`); it's harmless for `SELECT`.
 
-### Executing SQL Queries
-Users can enter SQL queries and execute them:
-```python title="gui_sql_database_viewer.py" showLineNumbers={1}
-Label(root, text="Enter SQL Query:").grid(row=1, column=0, padx=10, pady=10)
-self.query_text = Text(root, height=5, width=60)
-self.query_text.grid(row=1, column=1, columnspan=2, padx=10, pady=10)
-Button(root, text="Execute", command=self.execute_query).grid(row=2, column=1, pady=10)
+### 3. Dynamic columns
+```python title="gui_sql_database_viewer.py"
+columns = [description[0] for description in cursor.description] if cursor.description else []
+self.result_tree["columns"] = columns
+for col in columns:
+    self.result_tree.heading(col, text=col)
 ```
+This is the clever bit. `cursor.description` lists metadata about each result column — its `[0]` is the name. Because you read it *after* every query, the table adapts to *any* SQL automatically. For non-`SELECT` statements `description` is `None`, hence the guard.
 
-### Displaying Results
-Query results are shown in a table using Tkinter's Treeview widget:
-```python title="gui_sql_database_viewer.py" showLineNumbers={1}
-self.result_tree = Treeview(root, columns=("#1", "#2", "#3"), show="headings")
-self.result_tree.grid(row=3, column=0, columnspan=3, padx=10, pady=10)
+### 4. Filling the table
+```python title="gui_sql_database_viewer.py"
+for item in self.result_tree.get_children():   # clear old rows
+    self.result_tree.delete(item)
+for row in cursor.fetchall():                   # add new rows
+    self.result_tree.insert("", END, values=row)
 ```
+Clear, then insert. `fetchall()` pulls every result row as a tuple; each becomes a Treeview row.
+
+## Safety: Fence Off Destructive SQL
+
+Running *any* SQL means a typo'd `DROP TABLE` is one click away. Add a confirmation for write/DDL statements:
+```python title="guard.py"
+DESTRUCTIVE = ("drop", "delete", "update", "alter", "truncate")
+
+def is_destructive(query):
+    return query.strip().lower().split()[0] in DESTRUCTIVE
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install sqlite3
+# before executing:
+if is_destructive(query):
+    if not messagebox.askyesno("Confirm", "This modifies data. Continue?"):
+        return
 ```
-3. Run the application:
-```bash
-python gui_sql_database_viewer.py
+For a pure *viewer*, consider opening read-only: `sqlite3.connect("file:db.sqlite?mode=ro", uri=True)`.
+
+## Parameterized Queries
+
+Typed queries are fine for exploration, but if you add input fields (e.g. "find user by name"), **never** f-string values into SQL:
+```python title="params.py"
+# WRONG — SQL injection
+cursor.execute(f"SELECT * FROM users WHERE name = '{name}'")
+# RIGHT — parameterized
+cursor.execute("SELECT * FROM users WHERE name = ?", (name,))
 ```
+The `?` placeholder lets SQLite handle escaping safely.
+
+## Browse the Schema
+
+List tables and columns so users don't have to guess:
+```python title="schema.py"
+def tables(conn):
+    return [r[0] for r in conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table'")]
+
+def columns(conn, table):
+    return [r[1] for r in conn.execute(f"PRAGMA table_info({table})")]
+```
+Show these in a side panel; double-click a table to auto-fill `SELECT * FROM <table>`.
+
+## Export Results to CSV
+
+```python title="export.py"
+import csv
+def export(tree, path="results.csv"):
+    cols = tree["columns"]
+    with open(path, "w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(cols)
+        for item in tree.get_children():
+            w.writerow(tree.item(item)["values"])
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Accidental data loss | Ran `DROP`/`DELETE` by mistake | Confirm destructive SQL; open read-only |
+| Old + new rows mixed | Didn't clear the Treeview | `delete` all children before inserting |
+| Crash on `INSERT`/`CREATE` | `cursor.description` is `None` | Guard before reading column names |
+| SQL injection risk | f-stringing inputs into SQL | Use `?` parameterized queries |
+| Changes don't persist | Forgot `commit()` | Commit after write statements |
+| UI freezes on big result | Fetching huge tables at once | Page results / `fetchmany`, or add `LIMIT` |
+
+## Variations to Try
+
+1. **Read-only mode** — open the DB so no query can modify it.
+2. **Schema browser** — clickable tree of tables and columns.
+3. **Query history** — recall and re-run past queries.
+4. **Sortable columns** — click a heading to sort by that column.
+5. **Multiple DB engines** — add MySQL/PostgreSQL via their drivers.
+6. **Export/import** — CSV and JSON round-trips.
+7. **Pagination** — `LIMIT`/`OFFSET` for large tables.
+
+## Real-World Applications
+- **Database administration** — lightweight DB Browser / TablePlus clone.
+- **Internal admin tools** — quick data inspection for support teams.
+- **Data exploration** — ad-hoc querying during development.
+- **Teaching SQL** — a safe sandbox for learners.
+
+## Educational Value
+- **Database programming** — connections, cursors, transactions.
+- **Dynamic UIs** — building tables from query metadata.
+- **Security** — injection, parameterization, read-only access.
+- **`Treeview` mastery** — Tkinter's most capable data widget.
+
+## Next Steps
+- Add a **destructive-SQL confirmation** or open **read-only**.
+- Support **parameterized** input fields.
+- Build a **schema browser** and **CSV export**.
+- Add **query history** and **column sorting**.
 
 ## Conclusion
-This GUI-based SQL Database Viewer project is a great way to learn about database interaction and GUI development in Python. You can extend it by adding support for more database types, query history, or export features.
+You built a SQL database viewer that runs arbitrary queries and renders them in a self-adapting table — then made it safe with confirmations, parameterization, and read-only access. The `connect → cursor → execute → describe → render` pipeline is the backbone of every database tool, and the `cursor.description` trick is how real viewers handle queries they've never seen. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/gui_sql_database_viewer.py). Explore more database projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/gui_sql_database_viewer.mdx b/src/content/docs/projects/intermediate/gui_sql_database_viewer.mdx
deleted file mode 100644
index 5c46c256..00000000
--- a/src/content/docs/projects/intermediate/gui_sql_database_viewer.mdx
+++ /dev/null
@@ -1,104 +0,0 @@
----
-title: GUI SQL Database Viewer
-sidebar:
-  order: 14
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/gui_sql_database_viewer.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-GUI SQL Database Viewer is a Python project that allows users to view and query SQL databases through a graphical interface. It demonstrates database connectivity, SQL querying, and GUI development. This project is ideal for learning about database management, user interaction, and data visualization.
-
-## Prerequisites
-- Python 3.6 or above
-- sqlite3 (built-in)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available. Prepare a sample SQLite database for testing.
-
-## Getting Started
-1. Create a folder named `sql-database-viewer`.
-2. Create a file named `gui_sql_database_viewer.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/gui_sql_database_viewer.py" lang="python" title="GUI SQL Database Viewer" />
-4. Run the script: `python gui_sql_database_viewer.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import sqlite3
-import tkinter as tk
-```
-2. **Connect to database.**
-```python
-conn = sqlite3.connect('sample.db')
-cursor = conn.cursor()
-```
-3. **Query and display results.**
-```python
-cursor.execute('SELECT * FROM tablename')
-rows = cursor.fetchall()
-# Display rows in GUI
-```
-4. **GUI for database viewer.**
-```python
-root = tk.Tk()
-root.title('SQL Database Viewer')
-# ...setup widgets for table display and query input...
-root.mainloop()
-```
-
-## Features
-- Connects to SQLite databases
-- Displays tables and query results
-- GUI for user interaction
-- Easy to extend for more features
-
-## How It Works
-- Connects to database
-- Executes SQL queries
-- Displays results in GUI
-
-## GUI Components
-- **Table display:** Shows query results
-- **Entry box:** For SQL queries
-- **Button:** Executes query
-
-## Use Cases
-- Explore database contents
-- Learn SQL querying
-- Build database management tools
-
-## Next Steps
-You can enhance this project by:
-- Supporting other database engines
-- Adding data editing features
-- Improving GUI design
-- Exporting results to CSV
-
-## Enhanced Version Ideas
-```python
-def export_to_csv():
-    # Save query results to CSV file
-    pass
-
-def add_data_editing():
-    # Allow editing database records
-    pass
-```
-
-## Troubleshooting Tips
-- **Database not found:** Check file path
-- **Query errors:** Check SQL syntax
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches database connectivity, SQL querying, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/image-recognition-with-opencv.mdx b/src/content/docs/projects/intermediate/image-recognition-with-opencv.mdx
index 434ba921..00ab0c1a 100644
--- a/src/content/docs/projects/intermediate/image-recognition-with-opencv.mdx
+++ b/src/content/docs/projects/intermediate/image-recognition-with-opencv.mdx
@@ -1,5 +1,6 @@
 ---
 title: Image Recognition with OpenCV
+description: Build a face-detection app in Python with OpenCV and Tkinter — load an image, find faces with a Haar cascade, draw boxes — then tune detection, add eyes/smile cascades, webcam mode, and learn where deep-learning detectors win.
 sidebar:
   order: 5
 hero:
@@ -12,135 +13,161 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
-Image Recognition with OpenCV is a Python project that detects and classifies objects in images using computer vision techniques. It demonstrates image processing, OpenCV usage, and basic machine learning concepts. This project is ideal for learning about image analysis, feature extraction, and real-world AI applications.
+Computer vision sounds intimidating until you draw your first green box around a face — then it clicks. This project uses OpenCV's classic **Haar cascade** classifier to detect faces in a photo and outline them, wrapped in a small Tkinter loader. You'll learn the grayscale-then-detect pipeline, what the `scaleFactor`/`minNeighbors` knobs actually do, and how to draw on an image. Then you'll extend it to detect eyes and smiles, run live on a webcam, and understand when to graduate from Haar cascades to modern deep-learning detectors.
 
-## Prerequisites
-- Python 3.6 or above
-- OpenCV (`pip install opencv-python`)
-- numpy (`pip install numpy`)
-- Sample images for testing
+You will leave understanding:
+- Why detection runs on a **grayscale** copy, not the color image.
+- How a Haar cascade scans an image at multiple scales.
+- What `scaleFactor`, `minNeighbors`, and `minSize` control (and how they trade speed for accuracy).
+- The limits of Haar cascades and what replaced them.
 
-## Before you Start
-Before starting, ensure you have Python installed. Install OpenCV and numpy using pip. Download or prepare sample images for testing. You may also want to install an IDE or code editor like Visual Studio Code.
+## Prerequisites
+- Python 3.6 or above.
+- A text editor or IDE.
+- OpenCV: `pip install opencv-python`.
+- Tkinter (bundled with Python).
+- A photo with a clear, front-facing face to test on.
 
 ## Getting Started
+
+### Create the project
 1. Create a folder named `image-recognition`.
-2. Create a file named `image_recognition_with_opencv.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/image_recognition_with_opencv.py" lang="python" title="Image Recognition with OpenCV" />
-4. Save the file and run: `python image_recognition_with_opencv.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import cv2
-import numpy as np
+2. Inside it, create `image_recognition_with_opencv.py`.
+3. Install OpenCV: `pip install opencv-python`.
+
+### Write the code
+<FileCode file="projects/intermediate/image_recognition_with_opencv.py" lang="python" title="image_recognition_with_opencv.py" showLineNumbers={1} />
+
+### Run it
+```cmd title="command"
+C:\Users\Your Name\image-recognition> python image_recognition_with_opencv.py
+# Load Image -> pick a photo -> Detect Faces -> a window shows boxed faces.
+# Press any key to close the image window.
+```
+
+## Step-by-Step Explanation
+
+### 1. Loading the cascade
+```python title="image_recognition_with_opencv.py"
+self.cascade = cv2.CascadeClassifier(
+    cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
 ```
-2. **Load and process image.**
-```python
-img = cv2.imread('sample.jpg')
-gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+A Haar cascade is a pre-trained classifier shipped *with* OpenCV — `cv2.data.haarcascades` is the folder path. The XML encodes thousands of simple "is this region light-then-dark?" features that, in sequence, recognize face-like patterns. No training required.
+
+### 2. Grayscale first
+```python title="image_recognition_with_opencv.py"
+image = cv2.imread(self.image_path)
+gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
 ```
-3. **Detect objects/features.**
-```python
-face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
-faces = face_cascade.detectMultiScale(gray, 1.3, 5)
-for (x, y, w, h) in faces:
-    cv2.rectangle(img, (x, y), (x+w, y+h), (255, 0, 0), 2)
+Detection uses brightness patterns, not color — so you convert to grayscale. (Note OpenCV loads images as **BGR**, not RGB; that bites everyone once.) You detect on `gray` but draw on the original color `image`.
+
+### 3. The detection call
+```python title="image_recognition_with_opencv.py"
+faces = self.cascade.detectMultiScale(
+    gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
 ```
-4. **Display results.**
-```python
-cv2.imshow('Image', img)
+`detectMultiScale` slides a window across the image at many sizes and returns a list of `(x, y, w, h)` boxes. The knobs:
+- **`scaleFactor=1.1`** — shrink the image 10% each pass to catch faces of different sizes. Smaller = more thorough but slower.
+- **`minNeighbors=5`** — how many overlapping detections confirm a real face. Higher = fewer false positives, but may miss faces.
+- **`minSize=(30,30)`** — ignore anything smaller than 30×30 pixels.
+
+### 4. Drawing the boxes
+```python title="image_recognition_with_opencv.py"
+for (x, y, w, h) in faces:
+    cv2.rectangle(image, (x, y), (x+w, y+h), (255, 0, 0), 2)
+cv2.imshow("Detected Faces", image)
 cv2.waitKey(0)
 cv2.destroyAllWindows()
 ```
+Each box is drawn with `rectangle` (color is BGR, so `(255,0,0)` is blue). `waitKey(0)` holds the window open until a key press; always `destroyAllWindows()` after.
 
-## Features
-- Detects objects (e.g., faces) in images
-- Uses OpenCV for image processing
-- Real-time or static image analysis
-- Easy to extend for more features
-- Visual feedback with bounding boxes
-
-## How It Works
-- Loads image and converts to grayscale
-- Uses Haar cascade classifiers to detect objects
-- Draws rectangles around detected features
-- Displays result in a window
-
-## GUI Components
-- **Image window:** Shows processed image
-- **Rectangles:** Highlight detected objects
-- **Status bar:** Can show number of objects detected
-
-## Use Cases
-- Face detection for security systems
-- Object recognition in photos
-- Educational demos for computer vision
-- Preprocessing for machine learning
+## Tune the Detector
 
-## Next Steps
-You can enhance this project by:
-- Adding more classifiers (eyes, smiles, etc.)
-- Processing video streams from webcam
-- Saving results to files
-- Integrating with web apps or APIs
-- Training custom models for specific objects
-- Adding a GUI for user interaction
-
-## Enhanced Version Ideas
-```python
-def detect_objects_in_video():
-    # Use webcam for real-time detection
-    pass
-
-def train_custom_classifier():
-    # Train on your own dataset
-    pass
+Detection quality lives in the parameters:
+```python title="tuning.py"
+# Catch more faces (slower, more false positives):
+cascade.detectMultiScale(gray, scaleFactor=1.05, minNeighbors=3)
+# Be strict (faster, fewer false positives, may miss some):
+cascade.detectMultiScale(gray, scaleFactor=1.3, minNeighbors=8)
 ```
+There's no universal setting — tune for your images. Too many false boxes? Raise `minNeighbors`. Missing small faces? Lower `scaleFactor`.
 
-## Advanced Features Ideas
-- **Multiple Object Detection:** Detect more than just faces (cars, animals, etc.)
-- **Live Video Processing:** Use OpenCV to process frames from a webcam
-- **Integration with ML Models:** Use TensorFlow or PyTorch for advanced recognition
-- **Export Results:** Save annotated images to disk
-- **Performance Optimization:** Use GPU acceleration for faster processing
+## Detect Eyes and Smiles Too
 
-## Performance Considerations
-- **Memory Usage:** Depends on image size and number of objects
-- **CPU Usage:** Real-time video can be CPU intensive
-- **Accuracy:** Depends on classifier and image quality
-- **Responsiveness:** OpenCV windows are fast and interactive
+OpenCV ships more cascades. Detect eyes *within* each face for accuracy:
+```python title="features.py"
+eye_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_eye.xml")
+for (x, y, w, h) in faces:
+    roi_gray = gray[y:y+h, x:x+w]          # region of interest: just the face
+    for (ex, ey, ew, eh) in eye_cascade.detectMultiScale(roi_gray):
+        cv2.rectangle(image, (x+ex, y+ey), (x+ex+ew, y+ey+eh), (0, 255, 0), 1)
+```
+Searching only inside each face box is both faster and more reliable than scanning the whole image.
+
+## Go Live: Webcam Detection
+
+Run detection on every frame from the camera:
+```python title="webcam.py"
+cap = cv2.VideoCapture(0)
+while True:
+    ok, frame = cap.read()
+    if not ok: break
+    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    for (x, y, w, h) in cascade.detectMultiScale(gray, 1.1, 5):
+        cv2.rectangle(frame, (x, y), (x+w, y+h), (255, 0, 0), 2)
+    cv2.imshow("Live", frame)
+    if cv2.waitKey(1) & 0xFF == ord("q"): break
+cap.release(); cv2.destroyAllWindows()
+```
 
-## Educational Value
-This project teaches:
-- **Computer Vision:** Basics of image analysis
-- **OpenCV Usage:** Practical application of a popular library
-- **Event Handling:** Responding to user actions (e.g., closing window)
-- **Feature Extraction:** Detecting and highlighting objects
-- **Visualization:** Drawing on images for feedback
-
-## Common Improvements
-- **Precision:** Use deep learning models for better accuracy
-- **Visual Feedback:** Add color changes for different object types
-- **User Experience:** Add confirmation dialogs for saving results
-- **Accessibility:** Support keyboard navigation in GUI
-- **Persistence:** Save detection logs to files
+## When to Outgrow Haar Cascades
+
+Haar cascades are fast and dependency-free but struggle with tilted faces, profiles, and poor lighting. For production accuracy, modern detectors win:
+- **DNN face detector** (`cv2.dnn`, an SSD/ResNet model) — far more robust, still in OpenCV.
+- **`face_recognition`** / dlib — adds *identity* recognition, not just detection.
+- **YOLO / MediaPipe** — real-time multi-object and face-mesh detection.
+
+Start with Haar to learn the concepts; reach for these when accuracy matters.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| No faces detected | Wrong params / tilted face / low light | Lower `scaleFactor`, lower `minNeighbors`, better light |
+| Too many false boxes | `minNeighbors` too low | Raise it (e.g. 6-8) |
+| Colors look swapped | OpenCV uses **BGR**, not RGB | Convert with `cvtColor` when needed |
+| `NoneType` from `imread` | Bad path / unsupported file | Check the path; verify the image loads |
+| Window won't close | Missing `waitKey`/`destroyAllWindows` | Always call both after `imshow` |
+| Slow on webcam | Detecting full-res every frame | Downscale the frame before detecting |
+
+## Variations to Try
+
+1. **Multi-feature** — boxes for face + eyes + smile.
+2. **Live webcam** — real-time detection (above).
+3. **Blur faces** — anonymize detected regions.
+4. **Count people** — tally faces in a crowd photo.
+5. **Save crops** — export each detected face as its own file.
+6. **DNN upgrade** — swap in OpenCV's deep-learning detector.
+7. **Face recognition** — identify *who* with the `face_recognition` library.
+8. **Display in Tkinter** — show the boxed result inside the GUI (with Pillow) instead of an OpenCV window.
 
 ## Real-World Applications
-- **Security:** Face detection for access control
-- **Productivity:** Automate image sorting and tagging
-- **Education:** Teach computer vision concepts
-- **Professional:** Preprocess images for ML pipelines
-- **Entertainment:** Build fun apps (e.g., filters, games)
-
-## Troubleshooting Tips
-- **No image loaded:** Check file path and image format
-- **No objects detected:** Try different images or adjust classifier parameters
-- **OpenCV errors:** Check installation and version compatibility
-- **Window issues:** Ensure display drivers are working
+- **Security & surveillance** — detecting people in feeds.
+- **Photography** — autofocus and face-aware cropping.
+- **Access control** — face-based attendance and unlock.
+- **AR filters** — the face tracking behind Snapchat-style effects.
+
+## Educational Value
+- **Computer vision basics** — grayscale, scanning, detection.
+- **Classical ML** — what a pre-trained cascade is and its limits.
+- **Parameter tuning** — the speed/accuracy trade-off, made concrete.
+- **Image manipulation** — regions of interest and drawing.
+
+## Next Steps
+- **Tune** the detector for your own images.
+- Add **eye/smile** cascades and **webcam** mode.
+- **Anonymize** faces or **save crops**.
+- Graduate to a **DNN detector** or **face recognition**.
 
 ## Conclusion
-In this project, we learned how to create an Image Recognition app using Python's OpenCV library. We explored image processing, object detection, and visualization techniques. This project serves as a foundation for more advanced computer vision applications and can be extended with deep learning, video processing, and custom models. For more projects like this, visit Python Central Hub.
+You built a face detector with OpenCV's Haar cascades, learned the grayscale-detect-draw pipeline, and saw exactly what the tuning knobs do. Extended to eyes, smiles, and live webcam, it's a real vision app — and you now know when to trade cascades for modern deep-learning detectors. Computer vision just stopped being a black box. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/image_recognition_with_opencv.py). Explore more vision projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/image_recognition_with_opencv.mdx b/src/content/docs/projects/intermediate/image_recognition_with_opencv.mdx
deleted file mode 100644
index 24762ce3..00000000
--- a/src/content/docs/projects/intermediate/image_recognition_with_opencv.mdx
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Image Recognition with OpenCV
-sidebar:
-    order: 5
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/image_recognition_with_opencv.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Image Recognition with OpenCV is a Python project that detects and classifies objects in images using computer vision techniques. It demonstrates image processing, OpenCV usage, and basic machine learning concepts. This project is ideal for learning about image analysis, feature extraction, and real-world AI applications.
-
-## Prerequisites
-- Python 3.6 or above
-- OpenCV (`pip install opencv-python`)
-- numpy (`pip install numpy`)
-
-## Before you Start
-Install Python, OpenCV, and numpy. You may need sample images for testing.
-
-## Getting Started
-1. Create a folder named `image-recognition`.
-2. Create a file named `image_recognition_with_opencv.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/image_recognition_with_opencv.py" lang="python" title="Image Recognition with OpenCV" />
-4. Run the script: `python image_recognition_with_opencv.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import cv2
-import numpy as np
-```
-2. **Load and process image**
-```python
-img = cv2.imread('sample.jpg')
-gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-```
-3. **Detect objects/features**
-```python
-faces = face_cascade.detectMultiScale(gray, 1.3, 5)
-for (x, y, w, h) in faces:
-    cv2.rectangle(img, (x, y), (x+w, y+h), (255, 0, 0), 2)
-```
-4. **Display results**
-```python
-cv2.imshow('Image', img)
-cv2.waitKey(0)
-cv2.destroyAllWindows()
-```
-
-## Features
-- Detects objects (e.g., faces)
-- Uses OpenCV for image processing
-- Real-time or static image analysis
-- Easy to extend for more features
-
-## How It Works
-- Loads image and converts to grayscale
-- Uses classifiers to detect objects
-- Draws rectangles around detected features
-- Displays result in a window
-
-## GUI Components
-- **Image window:** Shows processed image
-- **Rectangles:** Highlight detected objects
-
-## Use Cases
-- Face detection
-- Object recognition
-- Security systems
-- Educational demos
-
-## Next Steps
-You can enhance this project by:
-- Adding more classifiers
-- Processing video streams
-- Saving results to files
-- Integrating with web apps
-- Training custom models
-
-## Enhanced Version Ideas
-```python
-def detect_objects_in_video():
-    # Use webcam for real-time detection
-    pass
-
-def train_custom_classifier():
-    # Train on your own dataset
-    pass
-```
-
-## Troubleshooting Tips
-- **No image loaded:** Check file path
-- **No objects detected:** Try different images/classifiers
-- **OpenCV errors:** Check installation
-
-## Conclusion
-This project teaches image processing, OpenCV basics, and object detection. Extend it for more advanced computer vision tasks.
diff --git a/src/content/docs/projects/intermediate/interactive-periodic-table.mdx b/src/content/docs/projects/intermediate/interactive-periodic-table.mdx
index 53d18386..596408a8 100644
--- a/src/content/docs/projects/intermediate/interactive-periodic-table.mdx
+++ b/src/content/docs/projects/intermediate/interactive-periodic-table.mdx
@@ -1,76 +1,167 @@
 ---
 title: Interactive Periodic Table
+description: Build a clickable periodic table in Python with Tkinter — show element details on click — then expand to all 118 elements, lay them out in the real periodic grid, color by category, and add search and filtering.
 sidebar:
   order: 96
 hero:
     actions:
         - text: View Source Code
-          link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/interactive_periodic_table.mdx
+          link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/interactive_periodic_table.py
           icon: external
           variant: primary
 ---
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+The periodic table is a beautiful data-visualization problem: 118 elements, each with a dozen properties, arranged in a grid that itself encodes meaning (rows = periods, columns = groups). In this tutorial you build a Tkinter app where each element is a clickable button that pops up its details. Then you scale it from 10 elements to all 118, lay them out in the *real* periodic-table shape, color them by category (metals, nonmetals, noble gases), and add live search and filtering.
 
-Build an Interactive Periodic Table application that displays element information and allows searching by name or symbol. The app uses a GUI for user interaction. This project demonstrates data organization, event handling, and GUI development in Python.
+You will leave understanding:
+- How to generate a grid of widgets from a data list with `grid(row=, column=)`.
+- The classic late-binding lambda bug in loops — and the `e=element` fix.
+- How to drive layout from data (atomic number → grid position).
+- How to color-code and filter a dataset in a GUI.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of data structures
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (bundled with Python).
+- Comfort with lists, dictionaries, and loops.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `interactive_periodic_table`.
-2. Create a new file inside the folder and name it `interactive_periodic_table.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `interactive_periodic_table.py` file.
+
+### Create the project
+1. Create a folder named `periodic-table`.
+2. Inside it, create `interactive_periodic_table.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/interactive_periodic_table.py" lang="python" title="interactive_periodic_table.py" showLineNumbers={1} />
 
-## Key Features
-- Display interactive periodic table
-- Show element details on click
-- Search elements by name or symbol
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\periodic-table> python interactive_periodic_table.py
+# A grid of element buttons appears. Click one to see its details.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Data Organization
-Elements are stored as dictionaries in a list for easy access:
-```python title="interactive_periodic_table.py" showLineNumbers={1}
+### 1. Elements as data
+```python title="interactive_periodic_table.py"
 elements = [
-    {"symbol": "H", "name": "Hydrogen", "atomic_number": 1, "atomic_mass": 1.008},
-    {"symbol": "He", "name": "Helium", "atomic_number": 2, "atomic_mass": 4.0026},
-    # ... more elements ...
+    {"symbol": "H",  "name": "Hydrogen", "atomic_number": 1, "atomic_mass": 1.008},
+    {"symbol": "He", "name": "Helium",   "atomic_number": 2, "atomic_mass": 4.0026},
+    ...
 ]
 ```
+Each element is a dict. The UI is *generated* from this list — add an element here and a button appears automatically. This data-drives-the-view idea is the heart of the project.
 
-### Creating the Table
-The app dynamically creates buttons for each element:
-```python title="interactive_periodic_table.py" showLineNumbers={1}
+### 2. Building the grid
+```python title="interactive_periodic_table.py"
 for i, element in enumerate(elements):
-    btn = Button(self.root, text=element["symbol"], command=lambda e=element: self.show_element_info(e))
-    btn.grid(row=..., column=...)
+    button = tk.Button(
+        self.root, text=element["symbol"], width=10, height=3,
+        command=lambda e=element: self.show_element_info(e),
+    )
+    button.grid(row=i // 5, column=i % 5, padx=5, pady=5)
 ```
+`grid` places widgets in rows and columns. The integer math is the trick: `i // 5` is the row, `i % 5` is the column — so elements flow left-to-right, wrapping every 5. Change the `5` to change the columns per row.
 
-### Showing Element Info
-Clicking an element displays its details:
-```python title="interactive_periodic_table.py" showLineNumbers={1}
+### 3. The lambda gotcha (critical)
+```python title="interactive_periodic_table.py"
+command=lambda e=element: self.show_element_info(e)
+```
+Why `e=element` and not just `lambda: self.show_element_info(element)`? Because of **late binding**: a bare lambda captures the *variable* `element`, not its current value. By the time you click, the loop has finished and `element` points at the *last* item — so every button would show Neon. Binding `e=element` as a default argument snapshots the value *now*. This is the single most common Tkinter-loop bug.
+
+### 4. Showing details
+```python title="interactive_periodic_table.py"
 def show_element_info(self, element):
-    messagebox.showinfo("Element Info", f"Name: {element['name']}\nSymbol: {element['symbol']}\nAtomic Number: {element['atomic_number']}\nAtomic Mass: {element['atomic_mass']}")
+    info = (
+        f"Name: {element['name']}\n"
+        f"Symbol: {element['symbol']}\n"
+        f"Atomic Number: {element['atomic_number']}\n"
+        f"Atomic Mass: {element['atomic_mass']}"
+    )
+    messagebox.showinfo("Element Information", info)
+```
+A popup is fine to start; a side panel that updates in place feels far more like a real app (below).
+
+## Scale to All 118 Elements — in the Real Layout
+
+The actual periodic table isn't a 5-wide wrap; it's an 18-column grid with gaps. Store each element's `group` (column) and `period` (row) and place it precisely:
+```python title="layout.py"
+# Each element gains "period" and "group" fields
+for el in elements:
+    tk.Button(self.root, text=el["symbol"], width=4, height=2,
+              command=lambda e=el: self.show(e)).grid(
+        row=el["period"], column=el["group"], padx=1, pady=1)
+```
+The lanthanides and actinides sit in two detached rows below — exactly as on a wall chart. Pull a full dataset from a JSON file rather than typing 118 dicts by hand.
+
+## Color by Category
+
+Chemistry uses color to group elements. Map categories to colors:
+```python title="colors.py"
+CATEGORY_COLORS = {
+    "alkali metal": "#ff6666", "noble gas": "#66ccff",
+    "nonmetal": "#99ff99", "metalloid": "#ffcc66", "transition metal": "#cccccc",
+}
+btn.config(bg=CATEGORY_COLORS.get(el["category"], "white"))
 ```
+Suddenly the table *teaches* — trends jump out visually.
 
-## Running the Application
-1. Save the file.
-2. Run the application:
-```bash
-python interactive_periodic_table.py
+## Add Search and Filtering
+
+An Entry that highlights matches as you type:
+```python title="search.py"
+def on_search(self, query):
+    q = query.lower()
+    for el, btn in self.buttons.items():
+        match = q in el["name"].lower() or q == el["symbol"].lower()
+        btn.config(relief="solid" if match and q else "raised")
 ```
+Filter by category with a dropdown to dim everything except, say, the noble gases.
+
+## Upgrade the Detail View
+
+Replace the popup with a persistent side panel showing electron configuration, melting/boiling points, discovery year, and a short description. Update it on click instead of spawning dialogs — it feels like a reference tool, not a quiz.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Every button shows the last element | Late-binding lambda | Bind the value: `lambda e=element: ...` |
+| Elements pile in one column | Wrong `row`/`column` math | Use `i // cols` and `i % cols`, or real group/period |
+| Layout looks nothing like the chart | Used a simple wrap | Place by `group`/`period` with gaps |
+| Window huge or buttons tiny | Fixed sizes vs. 118 cells | Smaller `width`/`height`; let the grid expand |
+| Typing 118 dicts by hand is error-prone | Hard-coded data | Load elements from a JSON dataset |
+| Search does nothing | Compared against symbol case-sensitively | Normalize with `.lower()` |
+
+## Variations to Try
+
+1. **Full dataset** — all 118 elements with 15+ properties from JSON.
+2. **Trend heatmaps** — color by electronegativity or atomic radius.
+3. **Element quiz** — "click the noble gases" timed challenge.
+4. **Compare mode** — select two elements and diff their properties.
+5. **3D Bohr model** — draw electron shells for the selected element.
+6. **Unit toggles** — switch mass/temperature units.
+7. **Export** — save the selected element as a flashcard image.
+
+## Real-World Applications
+- **Education** — chemistry teaching and revision tools.
+- **Reference apps** — quick element lookup for students and engineers.
+- **Data-viz practice** — encoding multiple dimensions (color, position) at once.
+- **Material selection** — filtering elements by property ranges.
+
+## Educational Value
+- **Data-driven UI** — generating widgets from a dataset.
+- **Grid layout math** — mapping an index (or group/period) to position.
+- **Closures & late binding** — the most-asked-about Python loop bug.
+- **Visual encoding** — color and position carrying meaning.
+
+## Next Steps
+- Load **all 118 elements** from a JSON dataset.
+- Lay them out in the **real group/period grid**.
+- **Color by category** and add **search + filtering**.
+- Swap the popup for a **live detail panel**.
 
 ## Conclusion
-This Interactive Periodic Table project is a great way to learn about data organization and event-driven programming in Python. You can extend it by adding more elements, search filters, or visual enhancements.
+You built an interactive periodic table, dodged the infamous late-binding lambda trap, and learned to drive a UI entirely from data. Scaled to 118 color-coded, searchable elements in their true layout, it becomes a genuine reference and teaching tool — and the data-drives-the-view pattern you practiced powers dashboards, seating charts, and any grid-of-things UI you'll build next. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/interactive_periodic_table.py). Explore more visualization projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/interactive_periodic_table.mdx b/src/content/docs/projects/intermediate/interactive_periodic_table.mdx
deleted file mode 100644
index f496a74a..00000000
--- a/src/content/docs/projects/intermediate/interactive_periodic_table.mdx
+++ /dev/null
@@ -1,98 +0,0 @@
----
-title: Interactive Periodic Table
-sidebar:
-    order: 9
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/interactive_periodic_table.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Interactive Periodic Table is a Python project that displays chemical elements and their properties in a GUI. It demonstrates data visualization, event handling, and Tkinter usage. This project is ideal for learning about educational tools, data display, and interactive interfaces.
-
-## Prerequisites
-- Python 3.6 or above
-- tkinter (usually pre-installed)
-- pandas (`pip install pandas`) for advanced features
-
-## Before you Start
-Ensure Python and Tkinter are installed. For advanced features, install pandas.
-
-## Getting Started
-1. Create a folder named `periodic-table`.
-2. Create a file named `interactive_periodic_table.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/interactive_periodic_table.py" lang="python" title="Interactive Periodic Table" />
-4. Run the script: `python interactive_periodic_table.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import tkinter as tk
-```
-2. **Set up element data**
-```python
-elements = [
-    {'symbol': 'H', 'name': 'Hydrogen', 'atomic_number': 1},
-    # ...more elements...
-]
-```
-3. **GUI for table**
-```python
-root = tk.Tk()
-root.title('Periodic Table')
-# ...setup grid of buttons for elements...
-root.mainloop()
-```
-
-## Features
-- Displays elements in a grid
-- Shows properties on click
-- Search/filter functionality
-- Educational and interactive
-
-## How It Works
-- Loads element data
-- Displays each as a button
-- Shows details when clicked
-
-## GUI Components
-- **Grid:** Buttons for each element
-- **Popup:** Shows element details
-- **Search box:** For filtering
-
-## Use Cases
-- Chemistry education
-- Quick reference tool
-- Interactive learning
-
-## Next Steps
-You can enhance this project by:
-- Adding more properties
-- Integrating with online databases
-- Improving UI design
-- Adding quizzes or games
-
-## Enhanced Version Ideas
-```python
-def add_quiz_mode():
-    # Quiz users on element facts
-    pass
-
-def fetch_online_data():
-    # Get element info from web
-    pass
-```
-
-## Troubleshooting Tips
-- **GUI not showing:** Ensure Tkinter is installed
-- **Element data missing:** Check data source
-
-## Conclusion
-This project teaches data visualization, event handling, and GUI basics. Extend it for more features and educational value.
diff --git a/src/content/docs/projects/intermediate/ml-model-trainer.mdx b/src/content/docs/projects/intermediate/ml-model-trainer.mdx
index 4f3e6097..5abc7f85 100644
--- a/src/content/docs/projects/intermediate/ml-model-trainer.mdx
+++ b/src/content/docs/projects/intermediate/ml-model-trainer.mdx
@@ -1,6 +1,6 @@
 ---
 title: Machine Learning Model Trainer
-description: Comprehensive ML platform for automated model training, evaluation, and deployment featuring multiple algorithms, hyperparameter tuning, performance tracking, model comparison, and a web-based interface for experiment management.
+description: Build an AutoML platform in Python with scikit-learn and XGBoost — load any CSV/Excel/JSON, auto-preprocess, train and compare 20 algorithms, tune hyperparameters with grid search, track experiments in SQLite, and serve it from a Flask UI.
 sidebar: 
     order: 63
 hero:
@@ -13,387 +13,152 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Most ML tutorials train *one* model on *one* dataset. This project builds the machine that does it for *any* dataset, *any* of 20 algorithms — a mini AutoML platform. Point it at a CSV (or Excel/JSON), tell it the target column, and it analyzes the data, preprocesses it (missing values, encoding, scaling, feature selection), trains and compares a fleet of classification or regression models, tunes the winner's hyperparameters with grid search, extracts feature importance, and logs every experiment to a database — all behind a Flask UI. Building this teaches you the **end-to-end ML workflow** far better than memorizing one `model.fit()`.
 
-This comprehensive ML platform provides automated model training, evaluation, and deployment capabilities. It features multiple algorithms for classification and regression, hyperparameter tuning, performance tracking, model comparison, and a professional web interface for experiment management and monitoring.
+You will leave understanding:
+- The full ML pipeline: load → analyze → preprocess → train → evaluate → tune → persist.
+- Why preprocessing (scaling, encoding, missing values) usually matters more than model choice.
+- How to treat **models as interchangeable** via a dictionary of algorithms.
+- Hyperparameter tuning with `GridSearchCV` and honest evaluation with cross-validation.
 
 ## Prerequisites
-
-- Python 3.8 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of machine learning concepts and algorithms
-- Familiarity with data preprocessing and feature engineering
-- Understanding of model evaluation and validation techniques
-- Experience with web development frameworks
-- Basic knowledge of statistical analysis and data science
+- Python 3.8 or above.
+- A text editor or IDE.
+- `pip install scikit-learn xgboost pandas numpy flask matplotlib plotly joblib`.
+- ML fundamentals (train/test split, over/underfitting, metrics).
+- A dataset to play with (the classic Titanic/Iris/housing CSVs work great).
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `mlModelTrainer`.
-2. Create a new file and name it `mlmodeltrainer.py`.
-3. Install required dependencies: `pip install scikit-learn pandas numpy matplotlib seaborn plotly flask xgboost joblib`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `mlmodeltrainer.py` file.
+### Create the project
+1. Create a folder named `ml-trainer`.
+2. Inside it, create `mlmodeltrainer.py`.
+3. Install dependencies (above).
 
 ### Write the code
-1. Add the following code to your `mlmodeltrainer.py` file.
-<FileCode file="projects/intermediate/mlmodeltrainer.py" lang="python" title="Machine Learning Model Trainer" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\mlModelTrainer> python mlmodeltrainer.py
-🤖 Machine Learning Model Trainer
-==================================================
-🚀 Starting ML platform...
-📊 Dashboard available at: http://localhost:5000
-🔬 Experiment tracking ready
-📈 Model comparison tools loaded
-```
-- **Web Development**: Build ML platforms with Flask
-
-### 🔧 Features
-
-- **Multiple Algorithms**: 15+ classification and regression algorithms
-- **Automated Training**: One-click model training and comparison
-- **Hyperparameter Tuning**: Grid Search and Random Search optimization
-- **Performance Metrics**: Comprehensive evaluation with multiple metrics
-- **Feature Analysis**: Feature importance and selection tools
-- **Experiment Management**: Track and compare ML experiments
-- **Model Export**: Download trained models for deployment
-- **Web Interface**: Professional dashboard for ML workflows
-- **Data Preprocessing**: Automated data cleaning and preparation
-- **Visualization**: Performance charts and model insights
+<FileCode file="projects/intermediate/mlmodeltrainer.py" lang="python" title="mlmodeltrainer.py" />
 
-### 📋 Requirements
-
-```bash title="terminal" showLineNumbers{1}
-pip install scikit-learn pandas numpy matplotlib seaborn plotly flask xgboost joblib
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ml-trainer> python mlmodeltrainer.py
+# Upload a dataset, pick the target column + problem type, train and compare models.
 ```
 
-
-### 🏗️ Project Structure
+## The ML Workflow This Project Teaches
 
 ```
-ml_model_trainer/
-├── mlmodeltrainer.py           # Main ML training platform
-├── templates/
-│   ├── ml_dashboard.html       # Dashboard interface
-│   ├── upload.html             # Dataset upload page
-│   ├── create_experiment.html  # Experiment creation
-│   ├── experiments.html        # Experiments list
-│   └── experiment_detail.html  # Detailed experiment view
-├── datasets/                   # Uploaded datasets (auto-created)
-├── trained_models/             # Saved models (auto-created)
-├── ml_trainer.db              # SQLite database (auto-generated)
-└── requirements.txt           # Project dependencies
+Load data → Analyze → Preprocess → Train many models → Evaluate/compare → Tune best → Persist
 ```
+Every step is a class method you can read in isolation. Internalize this loop and you can tackle any tabular ML problem.
 
-### 🚀 How to Run
-
-1. **Install Dependencies**:
-   ```bash title="terminal" showLineNumbers{1}
-   pip install scikit-learn pandas numpy matplotlib seaborn plotly flask xgboost joblib
-   ```
-
-2. **Run the Platform**:
-   ```bash title="terminal" showLineNumbers{1}
-   python mlmodeltrainer.py
-   ```
-
-3. **Choose Interface**:
-   - **Option 1**: Web Interface (Recommended)
-   - **Option 2**: CLI Demo
-
-4. **Access Dashboard**:
-   - Open browser to `http://localhost:5000`
-   - Upload dataset and create experiments
-   - Train models and compare performance
-
-### 🤖 Supported Algorithms
-
-#### Classification Algorithms
-- **Random Forest**: Ensemble learning with decision trees
-- **Logistic Regression**: Linear classification with probabilistic output
-- **Support Vector Machine**: Maximum margin classification
-- **Decision Tree**: Tree-based classification rules
-- **K-Nearest Neighbors**: Instance-based learning
-- **Naive Bayes**: Probabilistic classification
-- **Gradient Boosting**: Sequential ensemble learning
-- **Neural Network**: Multi-layer perceptron
-- **XGBoost**: Optimized gradient boosting
-
-#### Regression Algorithms
-- **Random Forest**: Ensemble regression with trees
-- **Linear Regression**: Linear relationship modeling
-- **Ridge Regression**: L2 regularized linear regression
-- **Lasso Regression**: L1 regularized linear regression
-- **Elastic Net**: Combined L1/L2 regularization
-- **Support Vector Regression**: Maximum margin regression
-- **Decision Tree**: Tree-based regression
-- **K-Nearest Neighbors**: Instance-based regression
-- **Gradient Boosting**: Sequential ensemble regression
-- **Neural Network**: Multi-layer perceptron regression
-- **XGBoost**: Optimized gradient boosting regression
-
-### 📊 Performance Metrics
-
-#### Classification Metrics
-- **Accuracy**: Overall classification accuracy
-- **Precision**: Positive prediction accuracy
-- **Recall**: True positive detection rate
-- **F1-Score**: Harmonic mean of precision and recall
-- **ROC AUC**: Area under ROC curve (binary classification)
-- **Confusion Matrix**: Classification error analysis
-- **Cross-Validation**: K-fold validation scores
-
-#### Regression Metrics
-- **Mean Squared Error (MSE)**: Average squared prediction errors
-- **Root Mean Squared Error (RMSE)**: Square root of MSE
-- **Mean Absolute Error (MAE)**: Average absolute prediction errors
-- **R-squared (R²)**: Coefficient of determination
-- **Cross-Validation**: K-fold validation scores
+## Step-by-Step Explanation
 
-### 🎨 Example Usage
-
-```python title="mlmodeltrainer.py" showLineNumbers{1}
-# Initialize ML experiment manager
-manager = MLExperimentManager()
-
-# Create a new experiment
-experiment = manager.create_experiment(
-    name="Customer Churn Prediction",
-    description="Predict customer churn using ML",
-    dataset_path="customer_data.csv",
-    target_column="churn",
-    problem_type="classification",
-    test_size=0.2
-)
-
-# Run experiment with multiple algorithms
-results = manager.run_experiment(
-    experiment['experiment_id'],
-    algorithms=['random_forest', 'gradient_boosting', 'xgboost'],
-    hyperparameter_tuning=True
-)
-
-# Compare model performance
-for algorithm, result in results.items():
-    accuracy = result['metrics']['test_accuracy']
-    print(f"{algorithm}: {accuracy:.3f} accuracy")
-
-# Train individual model
-trainer = ModelTrainer()
-X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
-
-model_result = trainer.train_model(
-    X_train, X_test, y_train, y_test,
-    algorithm='random_forest',
-    problem_type='classification'
-)
-
-print(f"Training time: {model_result['training_time']:.2f} seconds")
-print(f"Test accuracy: {model_result['metrics']['test_accuracy']:.3f}")
+### 1. Load anything
+```python title="mlmodeltrainer.py"
+if file_ext == '.csv':      df = pd.read_csv(file_path)
+elif file_ext in ['.xlsx','.xls']: df = pd.read_excel(file_path)
+elif file_ext == '.json':   df = pd.read_json(file_path)
 ```
-
-### 🔧 Data Preprocessing Features
-
-#### Data Loading
-- **Multiple Formats**: CSV, Excel, JSON support
-- **Automatic Detection**: File format and encoding detection
-- **Large Files**: Efficient handling of large datasets
-- **Error Handling**: Robust file loading with validation
-
-#### Data Cleaning
-- **Missing Values**: Multiple strategies (drop, fill, interpolate)
-- **Outlier Detection**: Statistical outlier identification
-- **Data Types**: Automatic type inference and conversion
-- **Duplicate Removal**: Automatic duplicate detection
-
-#### Feature Engineering
-- **Categorical Encoding**: Label encoding for categorical variables
-- **Feature Scaling**: Standard, MinMax, and Robust scaling
-- **Feature Selection**: K-best and RFE feature selection
-- **Dimensionality Reduction**: PCA and feature importance
-
-### 📈 Hyperparameter Tuning
-
-#### Grid Search
-- **Exhaustive Search**: Test all parameter combinations
-- **Cross-Validation**: K-fold validation for each combination
-- **Parallel Processing**: Multi-core optimization
-- **Custom Grids**: Algorithm-specific parameter grids
-
-#### Random Search
-- **Efficient Sampling**: Random parameter sampling
-- **Faster Results**: Quicker than exhaustive search
-- **Good Coverage**: Effective parameter space exploration
-- **Resource Control**: Configurable iteration limits
-
-#### Parameter Grids
-```python title="mlmodeltrainer.py" showLineNumbers{1}
-hyperparameter_grids = {
-    'random_forest': {
-        'n_estimators': [50, 100, 200],
-        'max_depth': [3, 5, 10, None],
-        'min_samples_split': [2, 5, 10],
-        'min_samples_leaf': [1, 2, 4]
-    },
-    'xgboost': {
-        'n_estimators': [50, 100, 200],
-        'learning_rate': [0.01, 0.1, 0.2],
-        'max_depth': [3, 5, 7],
-        'subsample': [0.8, 0.9, 1.0]
-    }
+One loader, three formats. Pandas normalizes them all to a `DataFrame` — the universal currency of tabular ML.
+
+### 2. Analyze before you model
+```python title="mlmodeltrainer.py"
+analysis = {
+    'shape': df.shape, 'missing_values': df.isnull().sum().to_dict(),
+    'numeric_columns': df.select_dtypes(include=[np.number]).columns.tolist(),
+    'categorical_columns': df.select_dtypes(include=['object']).columns.tolist(), ...
 }
 ```
+Know your data first: shape, dtypes, missing values, numeric vs. categorical. Skipping this is the #1 cause of garbage models.
+
+### 3. Preprocess (where models are won or lost)
+```python title="mlmodeltrainer.py"
+# missing values: drop or fill (mean for numeric, mode for categorical)
+# categorical -> numbers with LabelEncoder
+# scaling: StandardScaler / MinMaxScaler / RobustScaler
+# optional feature selection: SelectKBest(f_classif | f_regression, k)
+```
+Most algorithms need **numeric, scaled** input, can't handle NaNs, and benefit from dropping noise features. The crucial subtlety: encoders and scalers are **fit on training data and reused** — the code keeps `self.label_encoders` so prediction-time data is transformed identically. Re-fitting on test data leaks information and inflates scores.
+
+### 4. Models as a dictionary (the key design idea)
+```python title="mlmodeltrainer.py"
+self.classification_models = {
+    'random_forest': RandomForestClassifier(random_state=42),
+    'logistic_regression': LogisticRegression(random_state=42),
+    'svc': SVC(random_state=42), 'xgboost': XGBClassifier(...), ...   # 9 total
+}
+self.regression_models = { ... }   # 11 total
+```
+Because every scikit-learn model shares the same `fit`/`predict` interface, you can store them in a dict and train them in a loop. Adding an algorithm is one line. This **uniform API** is scikit-learn's superpower — lean on it.
 
-### 🎯 Web Interface Features
-
-#### Dashboard
-- **Experiment Overview**: Summary of all ML experiments
-- **Performance Metrics**: Visual performance comparisons
-- **Model Status**: Training progress and completion status
-- **Quick Actions**: Create new experiments and upload datasets
-
-#### Experiment Management
-- **Create Experiments**: Simple experiment setup wizard
-- **Track Progress**: Real-time training progress monitoring
-- **Compare Models**: Side-by-side model comparison
-- **Export Models**: Download trained models for deployment
-
-#### Data Upload
-- **Drag & Drop**: Easy dataset upload interface
-- **Format Validation**: Automatic format detection and validation
-- **Data Preview**: Sample data display and column analysis
-- **Target Selection**: Interactive target column selection
-
-### 📊 Database Schema
-
-#### Core Tables
-- **Experiments**: Experiment metadata and configuration
-- **Datasets**: Dataset information and file paths
-- **Models**: Trained model information and paths
-- **Model Metrics**: Performance metrics for all models
-- **Feature Importance**: Feature importance scores
-- **Hyperparameter Results**: Tuning results and rankings
-
-### 🎨 Advanced Features
-
-#### Model Comparison
-- **Multiple Metrics**: Compare models across various metrics
-- **Statistical Testing**: Significance testing for comparisons
-- **Visualization**: Charts and graphs for performance
-- **Ranking System**: Automatic best model identification
-
-#### Feature Analysis
-- **Importance Scoring**: Feature importance from tree-based models
-- **Correlation Analysis**: Feature correlation matrices
-- **Selection Tools**: Automated feature selection methods
-- **Visualization**: Feature importance charts
-
-#### Experiment Tracking
-- **Version Control**: Track experiment versions
-- **Reproducibility**: Consistent random seeds and parameters
-- **Metadata Storage**: Complete experiment configuration
-- **Performance History**: Historical performance tracking
-
-### 🔧 Technical Architecture
-
-#### Backend Components
-- **Flask Application**: Web server and API endpoints
-- **SQLite Database**: Experiment and model storage
-- **Scikit-learn**: Core ML algorithms and utilities
-- **XGBoost**: Advanced gradient boosting
-- **Joblib**: Model serialization and persistence
-
-#### Data Processing
-- **Pandas**: Data manipulation and analysis
-- **NumPy**: Numerical computing and arrays
-- **Preprocessing**: Comprehensive data preparation
-- **Validation**: Cross-validation and performance assessment
-
-### 🎯 Use Cases
-
-#### Business Applications
-- **Customer Analytics**: Churn prediction, segmentation, lifetime value
-- **Financial Modeling**: Credit scoring, fraud detection, risk assessment
-- **Marketing Optimization**: Campaign effectiveness, recommendation systems
-- **Operations Research**: Demand forecasting, inventory optimization
-
-#### Research and Development
-- **Academic Research**: Reproducible ML experiments
-- **Model Prototyping**: Rapid model development and testing
-- **Algorithm Comparison**: Systematic algorithm evaluation
-- **Performance Benchmarking**: Standardized performance assessment
-
-#### Data Science Workflows
-- **Automated ML**: Streamlined model development
-- **Experiment Management**: Organized research processes
-- **Model Selection**: Data-driven algorithm choice
-- **Deployment Preparation**: Production-ready model export
-
-### 📚 Educational Value
-
-This project demonstrates:
-
-- **Machine Learning**: Comprehensive ML algorithm implementation
-- **Automated Systems**: Building automated ML workflows
-- **Data Science**: Complete data science project lifecycle
-- **Web Development**: Professional ML platform development
-- **Database Design**: Experiment tracking and model storage
-- **Performance Optimization**: Efficient model training and evaluation
-- **Software Engineering**: Production-quality code organization
-
-## Explanation
+### 5. Train and score by problem type
+```python title="mlmodeltrainer.py"
+model.fit(X_train, y_train)
+# classification -> accuracy, precision, recall, F1
+# regression     -> MSE, MAE, R²
+```
+The trainer computes **train and test** metrics. The gap between them is your overfitting detector: high train + low test = memorizing, not learning.
+
+### 6. Feature importance — two ways
+```python title="mlmodeltrainer.py"
+if hasattr(model, 'feature_importances_'):      # trees / boosting
+    feature_importance = model.feature_importances_
+elif hasattr(model, 'coef_'):                    # linear models
+    feature_importance = np.abs(model.coef_).flatten()
+```
+Different model families expose importance differently; `hasattr` lets one code path handle both. Knowing *which features matter* is often more valuable than the prediction itself.
 
-1. The `MLExperimentManager` class orchestrates the complete machine learning workflow.
-2. The `ModelTrainer` handles individual model training with multiple algorithms.
-3. The `DataPreprocessor` provides automated data cleaning and feature engineering.
-4. The `HyperparameterTuner` implements grid search and random search optimization.
-5. The `ModelEvaluator` calculates comprehensive performance metrics for classification and regression.
-6. The `FeatureAnalyzer` provides feature importance and selection capabilities.
-7. The `ExperimentTracker` maintains detailed logs of all experiments and results.
-8. Web interface provides intuitive model training and comparison tools.
-9. Database design supports experiment management and model versioning.
-10. Automated preprocessing handles missing values, encoding, and scaling.
-11. Export functionality enables model deployment and sharing.
-12. Visualization tools provide insights into model performance and feature importance.
+### 7. Hyperparameter tuning
+```python title="mlmodeltrainer.py"
+'random_forest': {'n_estimators': [50,100,200], 'max_depth': [3,5,10,None],
+                  'min_samples_split': [2,5,10], 'min_samples_leaf': [1,2,4]}
+# fed to GridSearchCV / RandomizedSearchCV with cross-validation
+```
+Default hyperparameters are rarely optimal. Grid search tries combinations with **cross-validation** (train on k-1 folds, validate on the rest) so the chosen settings generalize rather than fit one lucky split.
+
+### 8. Track every experiment
+Datasets, models, metrics, feature importances, and tuning results all persist to SQLite. **Reproducibility and comparison** are what separate real ML work from one-off notebook runs — you can answer "which model/params won, and why" later.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Test score ≫ realistic | Scaler/encoder fit on all data | Fit on **train only**, `transform` test |
+| `ValueError: could not convert string` | Categorical left unencoded | Encode before fitting |
+| Model can't handle NaN | Missing values not treated | Drop or impute first |
+| Great train, poor test | Overfitting | Simpler model, regularize, more data, CV |
+| Grid search takes forever | Huge grid × big data | `RandomizedSearchCV`; shrink the grid |
+| Misleading accuracy | Imbalanced classes | Use F1/precision/recall, not just accuracy |
+| `xgboost` import fails | Library/build missing | `pip install xgboost`, or drop it from the dict |
+
+## Variations to Try
+
+1. **Pipelines** — wrap preprocessing + model in `sklearn.pipeline.Pipeline` to kill leakage.
+2. **More metrics** — ROC-AUC curves, confusion matrices (imports are already there).
+3. **Stacking/voting** — ensemble the top models.
+4. **SHAP explanations** — richer feature attribution than `feature_importances_`.
+5. **Imbalance handling** — SMOTE / class weights.
+6. **AutoML compare-all** — train every algorithm and rank automatically.
+7. **Model serving** — expose the saved model as a `/predict` API.
+8. **Time-series split** — proper CV for temporal data.
+
+## Real-World Applications
+- **Rapid prototyping** — baseline many models fast on a new problem.
+- **AutoML tooling** — the engine behind no-code ML platforms.
+- **Education** — see how preprocessing and algorithm choice move metrics.
+- **Model governance** — experiment tracking and reproducibility.
+
+## Educational Value
+- **End-to-end ML** — the whole pipeline, not just `fit`.
+- **scikit-learn mastery** — the uniform estimator API, preprocessing, tuning.
+- **Honest evaluation** — train/test gap, cross-validation, the right metric.
+- **MLOps basics** — persistence, experiment tracking, comparison.
 
 ## Next Steps
-
-Congratulations! You have successfully created a Machine Learning Model Trainer in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add deep learning models with TensorFlow/PyTorch
-- Implement automated feature selection techniques
-- Create model deployment pipelines for production
-- Add advanced visualization and model interpretability
-- Integrate with cloud platforms for scalable training
-- Implement real-time prediction APIs
-- Add collaborative features for team experiments
-- Create automated model monitoring and retraining
+- Refactor preprocessing + model into a **`Pipeline`** (no leakage).
+- Add **ROC/confusion-matrix** visuals and **SHAP** explanations.
+- Build an **auto-compare-all** mode and a **/predict** serving endpoint.
+- Handle **class imbalance** and **time-series** splits.
 
 ## Conclusion
-
-In this project, you learned how to create a comprehensive Machine Learning Model Trainer in Python. You explored automated model training, hyperparameter tuning, experiment management, and building professional ML platforms. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/mlmodeltrainer.py)
-
-Experiment Workflow:
-1. 📊 Upload Dataset: customer_churn.csv (10,000 rows × 20 features)
-2. 🎯 Set Target: 'churn' column (classification problem)
-3. 🤖 Train Models: Random Forest, XGBoost, Gradient Boosting
-4. 📈 Hyperparameter Tuning: Grid Search optimization
-5. 📊 Compare Results:
-   - Random Forest: 0.892 accuracy
-   - XGBoost: 0.905 accuracy (Best)
-   - Gradient Boosting: 0.887 accuracy
-6. 💾 Export Model: Download best XGBoost model
-7. 📋 Generate Report: Complete experiment documentation
-
-Performance Metrics:
-✅ Model Training: 3 algorithms trained successfully
-✅ Hyperparameter Tuning: 150 combinations tested
-✅ Cross-Validation: 5-fold CV completed
-✅ Feature Importance: Top 10 features identified
-✅ Model Export: Production-ready model saved
-```
-
-This Machine Learning Model Trainer provides a comprehensive platform for automated ML workflows, enabling data scientists and researchers to efficiently train, evaluate, and deploy machine learning models with professional-grade tools and interfaces!
+You built an AutoML platform that turns any dataset into trained, tuned, compared, and tracked models — and in doing so learned the workflow that underlies *all* applied ML: analyze, preprocess (the part that really matters), train interchangeable models via scikit-learn's uniform API, evaluate honestly with cross-validation, tune, and persist. That loop, not any single algorithm, is the transferable skill. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/mlmodeltrainer.py). Explore more ML projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/multiplayer-tic-tac-toe.mdx b/src/content/docs/projects/intermediate/multiplayer-tic-tac-toe.mdx
index 7dba8bf2..76234d67 100644
--- a/src/content/docs/projects/intermediate/multiplayer-tic-tac-toe.mdx
+++ b/src/content/docs/projects/intermediate/multiplayer-tic-tac-toe.mdx
@@ -1,5 +1,6 @@
 ---
 title: Multiplayer Tic-Tac-Toe (Socket Programming)
+description: Build a networked two-player Tic-Tac-Toe in Python with sockets and threads — shared board, win detection, turn locking — then fix the turn-enforcement and broadcast gaps and add reconnection and a GUI.
 sidebar:
   order: 98
 hero:
@@ -12,72 +13,157 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Tic-Tac-Toe is simple enough that the *game* never gets in the way of the real lesson: how do two programs on different machines share one consistent state? In this project you build a socket server that hosts a game board, assigns players X and O, validates moves, detects a winner, and uses a **lock** to keep the shared board from being corrupted by two threads at once. Along the way you'll see exactly why naive multiplayer code lets both players move at once — and how to enforce turns and broadcast the board to everyone.
 
-Build a Multiplayer Tic-Tac-Toe game using socket programming. Two players can play over a network with real-time updates of the game board. This project demonstrates network programming, concurrency, and game logic in Python.
+You will leave understanding:
+- How a server holds authoritative game state two clients connect to.
+- Why shared mutable state across threads needs a `threading.Lock`.
+- The win/draw detection algorithm over a flat 9-cell board.
+- The difference between *having* a lock and actually *enforcing turns*.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with socket programming
-- Knowledge of threading for concurrency
+- Python 3.6 or above.
+- A text editor or IDE.
+- Standard library only — `socket` and `threading`.
+- Comfort with lists, loops, and basic threading.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `multiplayer_tic_tac_toe`.
-2. Create a new file inside the folder and name it `multiplayer_tic_tac_toe.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `multiplayer_tic_tac_toe.py` file.
+
+### Create the project
+1. Create a folder named `tic-tac-toe-net`.
+2. Inside it, create `multiplayer_tic_tac_toe.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/multiplayer_tic_tac_toe.py" lang="python" title="multiplayer_tic_tac_toe.py" showLineNumbers={1} />
 
-## Key Features
-- Two-player networked Tic-Tac-Toe
-- Real-time game board updates
-- Server-client architecture
-- Threading for handling multiple players
+### Run it
+```cmd title="command"
+# Start the server
+C:\Users\Your Name\tic-tac-toe-net> python multiplayer_tic_tac_toe.py
+Server started. Waiting for players...
+
+# Connect two clients (e.g. with `telnet 127.0.0.1 65432` or a small client script)
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Server Implementation
-The server manages connections and game state:
-```python title="multiplayer_tic_tac_toe.py" showLineNumbers={1}
-server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-server.bind((HOST, PORT))
-server.listen(2)
+### 1. Shared state + a lock
+```python title="multiplayer_tic_tac_toe.py"
+board = [" " for _ in range(9)]
+current_player = "X"
+lock = threading.Lock()
 ```
+The board is a flat list of 9 cells (index 0-8). Because two client threads can touch `board` and `current_player` at the same time, every change is guarded by `lock` to prevent a **race condition** — two writes interleaving and leaving the board inconsistent.
 
-### Game Logic
-The board is updated and checked for winners after each move:
-```python title="multiplayer_tic_tac_toe.py" showLineNumbers={1}
-def check_winner():
-    winning_combinations = [ ... ]
-    for combo in winning_combinations:
-        if board[combo[0]] == board[combo[1]] == board[combo[2]] != " ":
-            return board[combo[0]]
-    if " " not in board:
-        return "Draw"
-    return None
+### 2. Assigning players
+```python title="multiplayer_tic_tac_toe.py"
+player = current_player
+with lock:
+    current_player = "O" if current_player == "X" else "X"
 ```
+The first client becomes X, the second O. `with lock:` ensures the swap is atomic — without it, two simultaneous connections could both grab "X".
 
-### Client Handling
-Each client is handled in a separate thread:
-```python title="multiplayer_tic_tac_toe.py" showLineNumbers={1}
-def handle_client(conn, addr):
-    # Communicate with player, update board
+### 3. Win detection
+```python title="multiplayer_tic_tac_toe.py"
+winning_combinations = [
+    [0, 1, 2], [3, 4, 5], [6, 7, 8],   # rows
+    [0, 3, 6], [1, 4, 7], [2, 5, 8],   # columns
+    [0, 4, 8], [2, 4, 6]               # diagonals
+]
+for combo in winning_combinations:
+    if board[combo[0]] == board[combo[1]] == board[combo[2]] != " ":
+        return board[combo[0]]
+if " " not in board:
+    return "Draw"
 ```
+All 8 winning lines are hard-coded as index triples. The chained comparison checks "all three equal *and* not empty" in one line. No empty cells and no winner means a draw.
 
-## Running the Application
-1. Save the file.
-2. Run the server:
-```bash
-python multiplayer_tic_tac_toe.py
+### 4. Validating a move
+```python title="multiplayer_tic_tac_toe.py"
+if not move.isdigit() or int(move) not in range(9):
+    conn.sendall("Invalid move. Try again.\n".encode())
+    continue
+...
+with lock:
+    if board[move] == " ":
+        board[move] = player
+    else:
+        conn.sendall("Spot already taken. Try again.\n".encode())
 ```
-3. Run the client in a separate terminal:
-```bash
-python multiplayer_tic_tac_toe.py
+Input is validated twice: it must be a digit 0-8, and the target cell must be empty. Both checks happen before mutating the board.
+
+## The Big Gap: Turns Aren't Actually Enforced
+
+Look closely — the server swaps `current_player` *once at connect*, but the move loop never checks **whose turn it is**. Both players can hammer moves whenever they like. Real turn enforcement:
+```python title="turns.py"
+turn = "X"   # global, lock-protected
+
+# inside the move handler:
+with lock:
+    if player != turn:
+        conn.sendall("Not your turn. Wait.\n".encode())
+        continue
+    if board[move] == " ":
+        board[move] = player
+        winner = check_winner()
+        turn = "O" if turn == "X" else "X"   # hand off the turn
 ```
+A multiplayer server is the **referee** — clients propose moves, the server decides if they're legal.
+
+## The Other Gap: Broadcast the Board to Both
+
+The current code sends the board only to the player who just moved. The opponent never sees it. Track both connections and push updates to both:
+```python title="broadcast.py"
+clients = []   # filled as players connect
+
+def send_board():
+    rendered = render(board).encode()
+    for c in list(clients):
+        try:
+            c.sendall(rendered)
+        except OSError:
+            clients.remove(c)
+```
+Call `send_board()` after every accepted move so both screens stay in sync.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Both players move freely | Turn never checked in the loop | Enforce `player == turn` under the lock |
+| Opponent's screen never updates | Board sent only to the mover | Broadcast to all connected clients |
+| Board occasionally corrupts | Unlocked access from two threads | Guard every read/write with `lock` |
+| `Address already in use` | Port not released | `setsockopt(SO_REUSEADDR)` before bind |
+| Server hangs after a win | Socket not closed / loop not broken | `break` and `conn.close()` on game over |
+| Move index off by one | Used 1-9 instead of 0-8 | Keep cells 0-8, or subtract 1 on input |
+
+## Variations to Try
+
+1. **Proper turn engine** — enforce alternation and reject out-of-turn moves.
+2. **Spectators** — extra connections that receive the board read-only.
+3. **Rematch** — reset the board and swap who goes first.
+4. **Tkinter client** — a clickable 3×3 grid instead of typing indices.
+5. **Lobby / multiple games** — pair players into separate boards.
+6. **AI opponent** — single-player vs. a minimax bot.
+7. **`N×N` board** — generalize win detection to k-in-a-row.
+
+## Real-World Applications
+- **Turn-based multiplayer games** — chess, checkers, board games.
+- **Authoritative servers** — the anti-cheat pattern in online games.
+- **Collaborative state** — shared whiteboards, live documents.
+- **State synchronization** — keeping multiple clients consistent.
+
+## Educational Value
+- **Authoritative server design** — the server as referee.
+- **Thread safety** — locks and race conditions on shared state.
+- **Protocol design** — how clients and server agree on messages.
+- **Game logic** — win/draw detection over a flat array.
+
+## Next Steps
+- Add a **real turn engine** that rejects out-of-turn moves.
+- **Broadcast** the board to both players after each move.
+- Build a **Tkinter client** with a clickable grid.
+- Add **rematch** and a simple **lobby**.
 
 ## Conclusion
-This Multiplayer Tic-Tac-Toe project is a great way to learn about networked games and concurrency in Python. You can extend it by adding a GUI, chat feature, or player statistics.
+You built networked Tic-Tac-Toe and learned the defining idea of online multiplayer: the server owns the truth, clients only propose. You also saw why "has a lock" isn't the same as "enforces the rules" — turn logic and broadcasting are what make it a real game. Those patterns scale straight up to chess servers and collaborative editors. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/multiplayer_tic_tac_toe.py). Explore more networking and game projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/multiplayer_tic_tac_toe.mdx b/src/content/docs/projects/intermediate/multiplayer_tic_tac_toe.mdx
deleted file mode 100644
index 06236259..00000000
--- a/src/content/docs/projects/intermediate/multiplayer_tic_tac_toe.mdx
+++ /dev/null
@@ -1,103 +0,0 @@
----
-title: Multiplayer Tic Tac Toe
-sidebar:
-    order: 11
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/multiplayer_tic_tac_toe.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Multiplayer Tic Tac Toe is a Python project that allows two players to play Tic Tac Toe over a network. It demonstrates socket programming, game logic, and GUI development. This project is ideal for learning about multiplayer games, networking, and event-driven programming.
-
-## Prerequisites
-- Python 3.6 or above
-- socket, threading (built-in)
-- tkinter (for GUI, usually pre-installed)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available.
-
-## Getting Started
-1. Create a folder named `tic-tac-toe`.
-2. Create a file named `multiplayer_tic_tac_toe.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/multiplayer_tic_tac_toe.py" lang="python" title="Multiplayer Tic Tac Toe" />
-4. Run the server and client scripts as described in the code comments.
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import socket
-import threading
-import tkinter as tk
-```
-2. **Server and client setup**
-```python
-def start_server():
-    # Accepts connections and relays moves
-    pass
-
-def start_client():
-    # Connects to server and sends/receives moves
-    pass
-```
-3. **Game logic and GUI**
-```python
-root = tk.Tk()
-root.title('Multiplayer Tic Tac Toe')
-# ...setup grid for game board...
-root.mainloop()
-```
-
-## Features
-- Two-player networked game
-- Real-time move updates
-- GUI for game board
-- Demonstrates sockets and threading
-
-## How It Works
-- Server relays moves between clients
-- Clients send/receive moves
-- GUI displays board and handles input
-
-## GUI Components
-- **Grid:** Buttons for each cell
-- **Status display:** Shows turn and winner
-
-## Use Cases
-- Learn networking basics
-- Build multiplayer games
-- Practice game logic
-
-## Next Steps
-You can enhance this project by:
-- Adding chat feature
-- Supporting AI opponent
-- Improving GUI design
-- Keeping score history
-
-## Enhanced Version Ideas
-```python
-def add_chat():
-    # Allow players to chat
-    pass
-
-def add_ai_opponent():
-    # Play against computer
-    pass
-```
-
-## Troubleshooting Tips
-- **Connection errors:** Check IP and port
-- **GUI not showing:** Ensure Tkinter is installed
-- **Moves not sent:** Check server/client status
-
-## Conclusion
-This project teaches networking, game logic, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/news-aggregator.mdx b/src/content/docs/projects/intermediate/news-aggregator.mdx
index 9bfdd334..ee647524 100644
--- a/src/content/docs/projects/intermediate/news-aggregator.mdx
+++ b/src/content/docs/projects/intermediate/news-aggregator.mdx
@@ -1,5 +1,6 @@
 ---
 title: News Aggregator
+description: Build a Tkinter news aggregator in Python that pulls headlines from multiple RSS feeds, browse and read summaries, and save favorites — then add threaded fetching, search, deduplication, and persistent storage.
 sidebar:
   order: 88
 hero:
@@ -12,69 +13,169 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+RSS is the quiet backbone of the web — nearly every news site, blog, and podcast publishes a machine-readable feed. A news aggregator turns those feeds into one personal front page. In this tutorial you build a Tkinter app that fetches articles from several RSS categories with `feedparser`, lists the headlines, shows summaries on click, and saves favorites to a file. Then you make it feel professional: background fetching so the UI never freezes, full-text search, duplicate removal across feeds, and persistent JSON storage.
 
-Build a News Aggregator application that fetches and displays news articles from multiple sources using RSS feeds. The app categorizes news by topic, allows searching for articles, and lets users save favorites for later reading. This project demonstrates working with external APIs, parsing XML, and building a GUI in Python.
+You will leave understanding:
+- What RSS/Atom feeds are and how `feedparser` normalizes them.
+- The fetch → list → detail → save flow common to every reader app.
+- Why network calls must move off the main thread in a GUI.
+- How to dedupe and search across multiple sources.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Knowledge of HTTP requests and RSS/XML parsing
-- Familiarity with Tkinter for GUI development
+- Python 3.6 or above.
+- A text editor or IDE.
+- `feedparser`: `pip install feedparser`.
+- Tkinter (bundled with Python).
+- Basic understanding of dictionaries and lists.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `news_aggregator`.
-2. Create a new file inside the folder and name it `news_aggregator.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `news_aggregator.py` file.
+
+### Create the project
+1. Create a folder named `news-aggregator`.
+2. Inside it, create `news_aggregator.py`.
+3. Install the dependency: `pip install feedparser`.
 
 ### Write the code
 <FileCode file="projects/intermediate/news_aggregator.py" lang="python" title="news_aggregator.py" showLineNumbers={1} />
 
-## Key Features
-- Fetch news articles from multiple RSS feeds
-- Categorize news by topic (Technology, Sports, World)
-- Search for articles by keyword
-- Save favorite articles for later reading
-- GUI interface for easy navigation
+### Run it
+```cmd title="command"
+C:\Users\Your Name\news-aggregator> python news_aggregator.py
+# Click a category (Technology / Sports / World) to load its headlines.
+# Select one and View Article, or Save to Favorites.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Fetching RSS Feeds
-The application uses a dictionary to store RSS feed URLs for different categories. When a category is selected, the corresponding feed is fetched and parsed:
-```python title="news_aggregator.py" showLineNumbers={1}
+### 1. Feeds as a dictionary
+```python title="news_aggregator.py"
 self.feeds = {
     "Technology": "https://rss.nytimes.com/services/xml/rss/nyt/Technology.xml",
-    "Sports": "https://rss.nytimes.com/services/xml/rss/nyt/Sports.xml",
-    "World": "https://rss.nytimes.com/services/xml/rss/nyt/World.xml",
+    "Sports":     "https://rss.nytimes.com/services/xml/rss/nyt/Sports.xml",
+    "World":      "https://rss.nytimes.com/services/xml/rss/nyt/World.xml",
 }
 ```
+Category → feed URL. Adding a source is a one-line edit. A button is generated per category in `setup_ui`.
+
+### 2. Parsing a feed
+```python title="news_aggregator.py"
+feed = feedparser.parse(feed_url)
+self.articles = feed.entries
+for article in self.articles:
+    self.article_list.insert("end", article.title)
+```
+`feedparser.parse` handles the messy reality of RSS *and* Atom, returning a uniform object. `feed.entries` is the list of articles; each has `.title`, `.summary`, `.link`, and usually `.published`. This normalization is the whole reason to use the library.
+
+### 3. The list → detail pattern
+```python title="news_aggregator.py"
+selected_index = self.article_list.curselection()
+article = self.articles[selected_index[0]]
+messagebox.showinfo("Article", f"Title: {article.title}\n\n{article.summary}")
+```
+`curselection()` returns the highlighted row's index; you use it to look up the matching article object. This list-then-detail flow is how every email client and reader works.
 
-### Displaying Articles
-Articles are displayed in a Tkinter Listbox. Users can select an article to view details or save it to favorites:
-```python title="news_aggregator.py" showLineNumbers={1}
-self.article_list = Listbox(self.root, width=80, height=20)
-self.article_list.pack(pady=5)
+### 4. Saving favorites
+```python title="news_aggregator.py"
+with open("favorites.txt", "a") as file:
+    file.write(f"{article.title}\n{article.link}\n\n")
 ```
+Appending to a text file is the simplest possible persistence. You'll upgrade this to structured JSON below.
 
-### Viewing and Saving Articles
-The app provides buttons to view the selected article or save it for later:
-```python title="news_aggregator.py" showLineNumbers={1}
-Button(self.root, text="View Article", command=self.view_article).pack(pady=5)
-Button(self.root, text="Save to Favorites", command=self.save_to_favorites).pack(pady=5)
+## Fix: Don't Freeze the UI
+
+`feedparser.parse` makes a network call — on the main thread it freezes the whole window until the feed loads. Fetch in a background thread and update the UI safely:
+```python title="threaded.py"
+import threading
+
+def fetch_articles(self, category):
+    threading.Thread(target=self._fetch, args=(category,), daemon=True).start()
+
+def _fetch(self, category):
+    feed = feedparser.parse(self.feeds[category])
+    # schedule the UI update back on the main thread
+    self.root.after(0, lambda: self._populate(feed.entries))
 ```
+Network work off-thread, widget updates via `root.after` — the same rule as every Tkinter app.
 
-## Running the Application
-1. Save the file.
-2. Install any required dependencies (e.g., `feedparser` for RSS parsing):
-```bash
-pip install feedparser
+## Deduplicate Across Feeds
+
+The same wire story shows up under multiple sources. Dedupe by link:
+```python title="dedupe.py"
+def merge(entry_lists):
+    seen, merged = set(), []
+    for entries in entry_lists:
+        for e in entries:
+            if e.link not in seen:
+                seen.add(e.link)
+                merged.append(e)
+    return merged
 ```
-3. Run the application:
-```bash
-python news_aggregator.py
+
+## Add Search
+
+Filter the visible list as the user types:
+```python title="search.py"
+def on_search(self, query):
+    q = query.lower()
+    self.article_list.delete(0, "end")
+    for a in self.articles:
+        if q in a.title.lower() or q in a.summary.lower():
+            self.article_list.insert("end", a.title)
 ```
 
+## Upgrade Favorites to JSON
+
+Text files can't store structure. Save full records:
+```python title="favorites.py"
+import json
+from pathlib import Path
+
+def save_favorite(article):
+    path = Path("favorites.json")
+    favs = json.loads(path.read_text()) if path.exists() else []
+    favs.append({"title": article.title, "link": article.link,
+                 "summary": article.summary})
+    path.write_text(json.dumps(favs, indent=2))
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Window freezes on fetch | Network call on the main thread | Fetch on a background thread + `root.after` |
+| `IndexError` on View Article | No row selected | Check `curselection()` before indexing |
+| Same story listed twice | Multiple feeds, same article | Dedupe by `link` |
+| Garbled HTML in summary | RSS summaries contain HTML | Strip tags with `html.parser` or `BeautifulSoup` |
+| Favorites lost on restart | Only kept in memory | Persist to JSON |
+| Feed silently empty | Bad URL or feed offline | Check `feed.bozo` / `feed.status` and report it |
+
+## Variations to Try
+
+1. **Add your own feeds** — let users paste any RSS URL.
+2. **Auto-refresh** — re-fetch every N minutes with `after`.
+3. **Open in browser** — `webbrowser.open(article.link)` on double-click.
+4. **Unread tracking** — bold unread items, mark read on view.
+5. **Offline reading** — cache article text locally.
+6. **Keyword alerts** — notify when a story matches a watchlist.
+7. **Sentiment tags** — score headlines positive/negative with NLP.
+
+## Real-World Applications
+- **News readers** — Feedly, Inoreader, NetNewsWire.
+- **Media monitoring** — tracking mentions of a brand or topic.
+- **Research dashboards** — aggregating sources by subject.
+- **Podcast clients** — RSS is also how podcasts are distributed.
+
+## Educational Value
+- **Working with feeds** — RSS/Atom parsing and normalization.
+- **GUI responsiveness** — threading network I/O.
+- **Data hygiene** — deduplication and search.
+- **Persistence** — moving from flat text to structured JSON.
+
+## Next Steps
+- Move fetching to a **background thread**.
+- **Dedupe** across feeds and add **search**.
+- Upgrade favorites to **JSON** with full records.
+- Add **auto-refresh** and **open-in-browser**.
+
 ## Conclusion
-This News Aggregator project is a great way to learn about working with external data sources, parsing XML, and building user interfaces in Python. You can extend it by adding more categories, integrating APIs, or improving the search and favorites features.
+You built a news aggregator that unifies multiple RSS feeds into one browsable, searchable, savable front page — then fixed the freeze, the duplicates, and the fragile storage that hold back the naive version. The fetch → list → detail → persist loop you practiced is the skeleton of every reader, inbox, and feed app. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/news_aggregator.py). Explore more data and API projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/news_aggregator.mdx b/src/content/docs/projects/intermediate/news_aggregator.mdx
deleted file mode 100644
index 742eb65e..00000000
--- a/src/content/docs/projects/intermediate/news_aggregator.mdx
+++ /dev/null
@@ -1,107 +0,0 @@
----
-title: News Aggregator
-sidebar:
-    order: 1
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/news_aggregator.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-News Aggregator is a Python application that fetches and displays the latest news headlines from multiple sources using public APIs. It demonstrates API integration, data parsing, and GUI development with Tkinter. This project is ideal for learning about REST APIs, JSON handling, and building interactive desktop apps.
-
-## Prerequisites
-- Python 3.6 or above
-- requests module (`pip install requests`)
-- tkinter (usually pre-installed)
-- Internet connection
-
-## Before you Start
-Before starting, ensure you have Python and a code editor installed. Install the `requests` library using `pip install requests`. Obtain a free API key from [NewsAPI](https://newsapi.org/).
-
-## Getting Started
-1. Create a folder named `news-aggregator`.
-2. Create a file named `news_aggregator.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/news_aggregator.py" lang="python" title="News Aggregator" />
-4. Run the script: `python news_aggregator.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import requests
-import tkinter as tk
-```
-2. **Fetch news from API**
-```python
-def fetch_news():
-    url = 'https://newsapi.org/v2/top-headlines?country=us&apiKey=YOUR_API_KEY'
-    response = requests.get(url)
-    data = response.json()
-    return [article['title'] for article in data['articles']]
-```
-3. **Display headlines in GUI**
-```python
-root = tk.Tk()
-root.title('News Aggregator')
-listbox = tk.Listbox(root, width=80)
-listbox.pack(pady=20)
-for headline in fetch_news():
-    listbox.insert(tk.END, headline)
-root.mainloop()
-```
-
-## Features
-- Fetches latest headlines from multiple sources
-- Simple Tkinter GUI for display
-- Easy to extend for more sources
-- Demonstrates API and JSON usage
-
-## How It Works
-- Uses requests to call news API
-- Parses JSON response
-- Displays headlines in a listbox
-
-## GUI Components
-- **Listbox:** Shows headlines
-- **Window Title:** News Aggregator
-- **Padding:** For readability
-
-## Use Cases
-- Stay updated with news
-- Learn API integration
-- Build custom news dashboards
-
-## Next Steps
-You can enhance this project by:
-- Adding more news sources
-- Displaying summaries and images
-- Implementing search/filter
-- Saving favorite articles
-- Adding refresh button
-- Supporting multiple countries/languages
-
-## Enhanced Version Ideas
-```python
-def fetch_news_with_images():
-    # Fetch headlines and images
-    pass
-
-def search_news(query):
-    # Search for news by keyword
-    pass
-```
-
-## Troubleshooting Tips
-- **API key errors:** Check your key
-- **No headlines:** Check internet connection
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches API usage, JSON parsing, and GUI basics. Extend it for more features and sources. Great for learning real-world Python and desktop app development.
diff --git a/src/content/docs/projects/intermediate/personal-finance-tracker.mdx b/src/content/docs/projects/intermediate/personal-finance-tracker.mdx
index 7713b78e..65fbd569 100644
--- a/src/content/docs/projects/intermediate/personal-finance-tracker.mdx
+++ b/src/content/docs/projects/intermediate/personal-finance-tracker.mdx
@@ -1,6 +1,6 @@
 ---
 title: Personal Finance Tracker
-description: Build a comprehensive personal finance management system with transaction tracking, budgeting, goal setting, analytics, and both GUI and CLI interfaces
+description: Build a full personal finance app in Python — SQLite-backed transactions, categories, budgets and goals; a tabbed Tkinter dashboard with embedded matplotlib charts; CSV/JSON import-export; budget alerts; and auto-generated insights. CLI included.
 sidebar:
   order: 63
 hero:
@@ -13,251 +13,162 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This is the project where the standard library finally feels like an *application platform*. You'll build a personal finance manager that records income and expenses in SQLite, organizes them by category, tracks budgets and savings goals, and surfaces everything in a tabbed Tkinter dashboard with **live matplotlib charts embedded right in the window**. It exports and imports CSV/JSON, fires budget alerts, and generates plain-language insights about your spending. One engine (`PersonalFinanceTracker`) drives two front ends (GUI and CLI) — a clean separation worth studying.
 
-Create a comprehensive personal finance management system that tracks income and expenses, manages budgets, sets financial goals, generates detailed reports, and provides actionable insights. Features both a modern GUI interface and command-line functionality for complete financial management.
+You will leave understanding:
+- How to model a real domain with related SQLite tables and SQL aggregation.
+- How to embed a matplotlib figure inside Tkinter with `FigureCanvasTkAgg`.
+- The "data class + view class" split that keeps logic out of the UI.
+- How `GROUP BY` + `CASE` turn raw transactions into budgets, reports, and insights.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of GUI development with Tkinter
-- Familiarity with databases and SQL operations
-- Understanding of data visualization with matplotlib
-- Basic knowledge of financial planning concepts
+- Python 3.7 or above.
+- A text editor or IDE.
+- `pip install matplotlib pandas` (`sqlite3`, `tkinter`, `csv`, `json` are built in).
+- SQL basics (`JOIN`, `GROUP BY`, `SUM`) and Tkinter familiarity.
+- The [GUI SQL Database Viewer](./gui-sql-database-viewer) is good warm-up for `Treeview`.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `personalFinanceTracker`.
-2. Create a new file and name it `personalfinancetracker.py`.
-3. Install required dependencies: `pip install matplotlib pandas tkinter`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `personalfinancetracker.py` file.
+### Create the project
+1. Create a folder named `finance-tracker`.
+2. Inside it, create `personalfinancetracker.py`.
+3. Install dependencies: `pip install matplotlib pandas`.
 
 ### Write the code
-1. Add the following code to your `personalfinancetracker.py` file.
-<FileCode file="projects/intermediate/personalfinancetracker.py" lang="python" title="Personal Finance Tracker" />
-2. Save the file.
-3. Run the following command to start the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\personalFinanceTracker> python personalfinancetracker.py
-💰 Personal Finance Tracker
-==================================================
-
-Choose interface:
-1. Command Line
-2. GUI
-Enter choice (1-2): 2
-
-[GUI opens with tabs for Dashboard, Transactions, Budgets, Goals, Reports]
-
-Dashboard shows:
-- Monthly Income: $5,200.00
-- Monthly Expenses: $3,800.00
-- Monthly Savings: $1,400.00
-- Net Worth: $15,600.00
+<FileCode file="projects/intermediate/personalfinancetracker.py" lang="python" title="personalfinancetracker.py" />
 
-Financial Insights:
-- 🎉 Excellent! You're saving 26.9% of your income
-- 🛒 Your biggest expense category is Food & Dining ($450.00)
+### Run it
+```cmd title="command"
+C:\Users\Your Name\finance-tracker> python personalfinancetracker.py
+# Choose: 1) Command Line  2) GUI
+# The GUI opens a tabbed dashboard; the CLI gives a menu-driven version.
 ```
 
-## Explanation
-
-1. The `PersonalFinanceTracker` class manages the core financial data and database operations.
-2. The `init_database()` method creates comprehensive tables for transactions, categories, budgets, goals, and accounts.
-3. Transaction management includes detailed tracking with categories, payment methods, locations, and tags.
-4. Budget functionality allows setting limits with alert thresholds and period-based tracking.
-5. Goal setting includes progress tracking with automatic achievement detection.
-6. The `FinanceTrackerGUI` class provides a modern Tkinter interface with tabbed navigation.
-7. Dashboard analytics include real-time charts using matplotlib integration.
-8. Financial insights provide AI-like recommendations based on spending patterns.
-9. Data export/import functionality supports CSV and JSON formats for backup and migration.
-10. Comprehensive reporting includes monthly summaries with category breakdowns and trends.
-11. The system supports both GUI and command-line interfaces for different user preferences.
-12. Advanced features include recurring transactions, account balancing, and savings rate analysis.
-
-## Next Steps
-
-Congratulations! You have successfully created a Personal Finance Tracker in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add investment portfolio tracking with real-time stock prices
-- Implement bill reminder notifications and recurring payments
-- Create mobile app integration with receipt scanning
-- Add multi-currency support for international transactions
-- Implement machine learning for expense categorization
-- Add collaborative features for family budget management
-- Create scheduled backup and cloud synchronization
-- Implement advanced analytics with predictive forecasting
+## Architecture: One Engine, Two Front Ends
 
-## Conclusion
-
-In this project, you learned how to create a Personal Finance Tracker in Python. You also learned about database design, GUI development, data visualization, financial analytics, and building comprehensive desktop applications. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/personalfinancetracker.py)
-
-## Code Explanation
-
-### Database Schema Design
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def init_database(self):
-    cursor.execute('''
-        CREATE TABLE IF NOT EXISTS transactions (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            amount REAL NOT NULL,
-            description TEXT NOT NULL,
-            category_id INTEGER NOT NULL,
-            date DATE NOT NULL,
-            payment_method TEXT DEFAULT 'cash',
-            location TEXT,
-            tags TEXT,
-            recurring BOOLEAN DEFAULT 0,
-            FOREIGN KEY (category_id) REFERENCES categories (id)
-        )
-    ''')
 ```
-
-Creates normalized database schema with proper foreign key relationships for financial data integrity.
-
-### Transaction Management
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def add_transaction(self, amount: float, description: str, category_id: int, 
-                   date: str = None, payment_method: str = 'cash', 
-                   location: str = '', tags: str = '') -> int:
-    if date is None:
-        date = datetime.date.today().isoformat()
-        
-    cursor.execute('''
-        INSERT INTO transactions (amount, description, category_id, date, 
-                                payment_method, location, tags)
-        VALUES (?, ?, ?, ?, ?, ?, ?)
-    ''', (amount, description, category_id, date, payment_method, location, tags))
+PersonalFinanceTracker   ← all logic + SQLite (no UI code)
+        ▲           ▲
+        │           │
+FinanceTrackerGUI   CLI menu (in main)
 ```
-
-Handles transaction creation with automatic date assignment and comprehensive metadata tracking.
-
-### Budget Monitoring
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def check_budget_status(self) -> List[Dict]:
-    budgets = cursor.fetchall()
-    budget_status = []
-    
-    for budget in budgets:
-        spent = cursor.fetchone()[0]
-        percentage = (spent / amount) * 100 if amount > 0 else 0
-        
-        status = {
-            'category': category,
-            'budget': amount,
-            'spent': spent,
-            'remaining': amount - spent,
-            'percentage': percentage,
-            'alert': percentage >= (threshold * 100)
-        }
-        budget_status.append(status)
+`PersonalFinanceTracker` knows nothing about Tkinter or `print` — it just exposes methods like `add_transaction`, `get_balance_summary`, `check_budget_status`. Both the GUI and the CLI call those same methods. This is the lesson: **keep business logic out of the UI** so you can put any face on it.
+
+## Step-by-Step Explanation
+
+### 1. The schema models the domain
+Five tables — `categories`, `transactions`, `budgets`, `goals`, `accounts` — with `CHECK` constraints enforcing valid values at the database level:
+```python title="personalfinancetracker.py"
+CREATE TABLE categories (
+    ...
+    type TEXT CHECK(type IN ('income', 'expense')) NOT NULL,
+    ...
+)
 ```
-
-Implements intelligent budget tracking with percentage calculations and automatic alert triggers.
-
-### Financial Insights Engine
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def get_financial_insights(self) -> Dict:
-    insights = {
-        'spending_habits': [],
-        'recommendations': [],
-        'warnings': [],
-        'achievements': []
-    }
-    
-    if summary['monthly_expenses'] > summary['monthly_income']:
-        insights['warnings'].append("⚠️ You're spending more than you earn!")
-        
-    savings_rate = (summary['monthly_savings'] / summary['monthly_income']) * 100
-    if savings_rate >= 20:
-        insights['achievements'].append(f"🎉 Excellent! You're saving {savings_rate:.1f}%")
+A category is either income or expense, full stop — the database refuses anything else. Transactions reference categories via a `FOREIGN KEY`. Defaults are seeded once on first run (`populate_default_categories`).
+
+### 2. Summaries via SQL aggregation
+The balance summary is pure SQL — let the database do the math:
+```python title="personalfinancetracker.py"
+SELECT COALESCE(SUM(t.amount), 0)
+FROM transactions t
+JOIN categories c ON t.category_id = c.id
+WHERE c.type = 'income'
 ```
-
-Provides AI-like financial analysis with personalized recommendations and achievement recognition.
-
-### GUI Dashboard Integration
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def update_charts(self):
-    # Category spending pie chart
-    if expenses:
-        labels = [cat[0] for cat in expenses]
-        amounts = [cat[2] for cat in expenses]
-        colors = [cat[1] for cat in expenses]
-        
-        self.ax1.pie(amounts, labels=labels, colors=colors, autopct='%1.1f%%')
-        self.ax1.set_title('Monthly Expenses by Category')
-    
-    # Monthly trend line chart
-    self.ax2.plot(x, expenses, label='Expenses', marker='o', color='red')
-    self.ax2.plot(x, income, label='Income', marker='o', color='green')
+`COALESCE(SUM(...), 0)` is the key detail: `SUM` of zero rows is `NULL`, which would break arithmetic — `COALESCE` turns it into `0`. The same query with `type = 'expense'` gives expenses; net worth is the difference.
+
+### 3. Charts inside the window
+This is the standout technique. A matplotlib figure lives *inside* Tkinter:
+```python title="personalfinancetracker.py"
+from matplotlib.backends.backend_tkagg import FigureCanvasTkAgg
+self.fig, (self.ax1, self.ax2) = plt.subplots(1, 2, figsize=(12, 6))
+self.canvas = FigureCanvasTkAgg(self.fig, charts_frame)
+self.canvas.get_tk_widget().pack(fill='both', expand=True)
 ```
+To update, you `clear()` the axes, redraw, and call `self.canvas.draw()`. No saving PNGs, no separate windows — the chart is a native widget. This pattern powers most Python desktop dashboards.
 
-Creates interactive charts with matplotlib integration for visual financial analytics.
-
-### Goal Progress Tracking
-```python title="personalfinancetracker.py" showLineNumbers{1}
-def update_goal_progress(self, goal_id: int, amount: float):
-    cursor.execute('''
-        UPDATE goals 
-        SET current_amount = current_amount + ?
-        WHERE id = ?
-    ''', (amount, goal_id))
-    
-    # Check if goal is achieved
-    cursor.execute('''
-        UPDATE goals 
-        SET achieved = 1 
-        WHERE id = ? AND current_amount >= target_amount
-    ''', (goal_id,))
+### 4. Tabs with `ttk.Notebook`
+```python title="personalfinancetracker.py"
+self.notebook = ttk.Notebook(self.root)
+self.notebook.add(dashboard_frame, text="Dashboard")
+self.notebook.add(transactions_frame, text="Transactions")
 ```
+Each feature gets its own tab (Dashboard, Transactions, Budgets, Goals, Reports). `Notebook` is Tkinter's tabbed-container widget — the cleanest way to organize a multi-feature app.
 
-Automatically tracks goal progress with achievement detection and status updates.
-
-## Features
+### 5. Budget tracking with alerts
+```python title="personalfinancetracker.py"
+spent = ...   # SUM of transactions in the budget's category and date range
+percentage = (spent / amount) * 100 if amount > 0 else 0
+status = {..., 'alert': percentage >= (threshold * 100)}
+```
+Each budget compares spending against its limit and flags an alert past the threshold (default 80%). That `if amount > 0` guard avoids a division-by-zero crash on a zero budget.
 
-- **Transaction Management**: Complete income and expense tracking with categories and metadata
-- **Budget Planning**: Set category-specific budgets with automatic alert notifications
-- **Goal Setting**: Define and track financial goals with progress monitoring
-- **Visual Analytics**: Interactive charts and graphs for spending patterns and trends
-- **Financial Insights**: AI-like recommendations based on spending behavior analysis
-- **Dual Interface**: Modern GUI with Tkinter and efficient command-line interface
-- **Data Export/Import**: Backup and migration support with CSV and JSON formats
-- **Monthly Reports**: Comprehensive financial summaries with category breakdowns
-- **Account Tracking**: Multiple account support with balance management
-- **Payment Methods**: Track various payment methods and locations
+### 6. Insights from the data
+```python title="personalfinancetracker.py"
+if summary['monthly_expenses'] > summary['monthly_income']:
+    insights['warnings'].append("⚠️ You're spending more than you earn this month!")
+savings_rate = (summary['monthly_savings'] / summary['monthly_income']) * 100
+```
+No AI needed — a few rules over the aggregated numbers produce genuinely useful guidance (overspending warnings, savings-rate praise, biggest-category callouts). Rules-over-data is often all "insights" requires.
 
-## Next Steps
+### 7. Export / import
+CSV for spreadsheets, JSON for programs:
+```python title="personalfinancetracker.py"
+writer.writerow(['ID','Amount','Description','Category','Type','Date',...])
+writer.writerows(transactions)
+```
+Import is the reverse, auto-creating any missing category. Round-tripping your data is what makes the tool trustworthy.
 
-### Enhancements
-- Add investment portfolio tracking with real-time stock prices
-- Implement bill reminder notifications and recurring payments
-- Create mobile app integration with receipt scanning
-- Add multi-currency support for international transactions
-- Implement machine learning for expense categorization
-- Add collaborative features for family budget management
-- Create scheduled backup and cloud synchronization
-- Implement advanced analytics with predictive forecasting
+## A Correctness Note: Use Cents, Not Floats
 
-### Learning Extensions
-- Study personal finance best practices and investment strategies
-- Explore advanced GUI frameworks like PyQt or Kivy
-- Learn about financial APIs and real-time data integration
-- Practice with machine learning for financial prediction
-- Understand security best practices for financial applications
-- Explore cloud storage and synchronization technologies
+Money in `REAL`/`float` columns invites rounding errors (`0.1 + 0.2 != 0.3`). For real finance code:
+```python title="money.py"
+# Store integer cents, format on display
+amount_cents = round(dollars * 100)
+display = f"${amount_cents / 100:.2f}"
+```
+The starter uses floats for simplicity; switching to integer cents (or `Decimal`) is the right move for anything beyond a demo.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Totals show `None` | `SUM` over zero rows is `NULL` | Wrap in `COALESCE(SUM(...), 0)` |
+| Chart doesn't refresh | Forgot `canvas.draw()` | `clear()` axes, redraw, then `draw()` |
+| Rounding drift in balances | Floats for money | Store integer cents or use `Decimal` |
+| Crash on zero budget | Division by zero | Guard `if amount > 0` |
+| DB locked errors | One shared connection across threads | One connection per thread, or serialize access |
+| Import fails on new category | Category didn't exist | Auto-create it (the code does) |
+
+## Variations to Try
+
+1. **Integer-cents money** — eliminate float rounding.
+2. **Recurring transactions** — auto-post salary/rent (schema has the fields).
+3. **Multi-account transfers** — move money between accounts.
+4. **Forecasting** — project month-end balance from spending pace.
+5. **Receipt OCR** — auto-fill transactions (see [Basic OCR with Tesseract](./basic_ocr_with_tesseract)).
+6. **Bank CSV import** — map common bank export formats.
+7. **Cloud sync** — back the DB with Postgres for multi-device.
+8. **Web version** — reuse the engine behind a Flask UI.
+
+## Real-World Applications
+- **Budgeting apps** — Mint, YNAB, Monarch in concept.
+- **Expense management** — small-business bookkeeping.
+- **Financial dashboards** — net-worth and cash-flow tracking.
+- **Desktop analytics** — any app needing embedded charts.
 
 ## Educational Value
+- **Relational modeling** — tables, foreign keys, `CHECK` constraints.
+- **SQL aggregation** — `JOIN`, `GROUP BY`, `SUM`, `CASE`, `COALESCE`.
+- **Embedded plotting** — matplotlib inside Tkinter via `FigureCanvasTkAgg`.
+- **Architecture** — logic/UI separation enabling GUI + CLI from one core.
 
-This project teaches:
-- **Financial Management**: Personal finance principles and budgeting strategies
-- **Database Design**: Normalized schemas with foreign key relationships
-- **GUI Development**: Creating professional desktop applications with Tkinter
-- **Data Visualization**: Building interactive charts and analytics dashboards
-- **Financial Analytics**: Calculating savings rates, budget tracking, and insights
-- **Software Architecture**: Designing modular, maintainable financial systems
-- **Data Import/Export**: Implementing backup and migration functionality
-- **User Experience**: Creating intuitive interfaces for complex financial data
+## Next Steps
+- Switch money to **integer cents** or `Decimal`.
+- Implement **recurring transactions** and **forecasting**.
+- Add **bank-CSV import** and **multi-account transfers**.
+- Reuse the engine behind a **web UI**.
 
-Perfect for understanding personal finance management, desktop application development, and building production-ready financial tracking systems.
+## Conclusion
+You built a finance manager that stores, aggregates, budgets, charts, and advises — with the business logic cleanly separated from a tabbed Tkinter dashboard that renders matplotlib charts inline, plus a CLI sharing the same engine. The `FigureCanvasTkAgg` embedding and the logic/UI split are techniques you'll reuse in every desktop data app. (Just remember: real money lives in integer cents, not floats.) Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/personalfinancetracker.py). Explore more data and finance projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/portfolio-website.mdx b/src/content/docs/projects/intermediate/portfolio-website.mdx
index d50cbe1e..a1d21108 100644
--- a/src/content/docs/projects/intermediate/portfolio-website.mdx
+++ b/src/content/docs/projects/intermediate/portfolio-website.mdx
@@ -1,6 +1,6 @@
 ---
 title: Dynamic Portfolio Website with Flask
-description: Build a dynamic portfolio website with Flask featuring content management, project galleries, contact forms, and responsive design
+description: Build a data-driven portfolio site in Python with Flask — content from a JSON file, self-generating Bootstrap templates, Jinja inheritance, a working contact form, and an admin inbox — then harden the real security gaps.
 sidebar: 
     order: 58
 hero:
@@ -13,178 +13,172 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A portfolio site is the project that pays for itself — you learn Flask *and* end up with something to show employers. This one is smarter than a pile of hard-coded HTML: all your content (bio, skills, projects, experience) lives in a single **JSON file**, the app **generates its own** Bootstrap templates and CSS on first run, and a contact form saves messages you can read in a tiny admin inbox. You'll learn the data-driven page pattern, Jinja template inheritance, form handling, and — importantly — spot the security mistakes the starter code makes so you don't ship them.
 
-Create a dynamic portfolio website using Flask that showcases projects, skills, and experience with a professional responsive design. This project demonstrates web development with Flask, template rendering, form handling, and creating dynamic content management for personal branding.
+You will leave understanding:
+- Why separating **content (JSON)** from **presentation (templates)** beats hard-coded HTML.
+- How Jinja `{% extends %}`/`{% block %}` inheritance avoids repeating layout.
+- The contact-form flow: POST → validate → persist → flash → redirect.
+- The concrete security holes here (`debug=True`, f-string HTML, open admin) and their fixes.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and web development
-- Knowledge of Flask framework and Jinja2 templating
-- Familiarity with HTML, CSS, and basic JavaScript
-- Understanding of responsive web design principles
-- Basic knowledge of form handling and data validation
+- Python 3.7 or above.
+- A text editor or IDE.
+- Flask: `pip install flask`.
+- Comfort with Flask routing and Jinja basics (see [Simple Blog with Flask](./simple-blog-with-flask)).
+- Basic HTML/CSS to customize the look.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `portfolioWebsite`.
-2. Create a new file and name it `portfoliowebsite.py`.
-3. Create folders: `templates`, `static/css`, `static/js`, `static/images`
-4. Install required dependencies: `pip install flask flask-wtf flask-sqlalchemy`
-5. Open the project folder in your favorite text editor or IDE.
-6. Copy the code below and paste it into your `portfoliowebsite.py` file.
-
-### Write the code
-1. Add the following code to your `portfoliowebsite.py` file.
-<FileCode file="projects/intermediate/portfoliowebsite.py" lang="python" title="Dynamic Portfolio Website with Flask" />
-2. Save the file.
-3. Run the following command to start the website.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\portfolioWebsite> python portfoliowebsite.py
- * Running on http://127.0.0.1:5000
-Portfolio Website Server
-========================
-✓ Database initialized
-✓ Templates loaded
-✓ Static files ready
-✓ Server running on http://localhost:5000
-Visit your portfolio: http://localhost:5000
-Admin panel: http://localhost:5000/admin
-```
-
-## Explanation
-
-1. The `from flask import Flask, render_template, request` imports Flask components for web development.
-2. The `flask_wtf` provides form handling and validation capabilities for contact forms.
-3. The `PortfolioSite` class manages the website structure and content organization.
-4. Template rendering displays dynamic content using Jinja2 templating engine.
-5. Responsive design ensures the website works on all devices and screen sizes.
-6. Project gallery showcases work samples with images, descriptions, and links.
-7. Contact form enables visitors to send messages with validation and feedback.
-8. Skills section displays technical competencies and experience levels.
-9. About page provides personal information and professional background.
-10. Navigation system creates smooth user experience across website sections.
-11. Static file serving handles CSS, JavaScript, and image resources.
-12. Database integration stores contact messages and portfolio data.
-
-## Next Steps
+### Create the project
+1. Create a folder named `portfolio-website`.
+2. Inside it, create `portfoliowebsite.py`.
+3. Install Flask: `pip install flask`.
 
-Congratulations! You have successfully created a Dynamic Portfolio Website in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add blog functionality with post creation and management
-- Implement user authentication for admin features
-- Create dynamic theme switching capabilities
-- Add social media integration and sharing
-- Implement SEO optimization features
-- Create mobile app companion
-- Add real-time chat for client communication
-- Implement analytics and visitor tracking
-- Create automated deployment workflows
+The app creates the `templates/` and `static/` folders and their files for you on first run — no manual setup.
 
-## Conclusion
-
-In this project, you learned how to create a Dynamic Portfolio Website in Python using Flask. You also learned about web development, template rendering, responsive design, and creating professional online presence. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/portfoliowebsite.py)
-
-## Code Explanation
-
-### Flask Application Structure
-```python title="portfoliowebsite.py" showLineNumbers{1}
-from flask import Flask, render_template, request, redirect, url_for
-from flask_wtf import FlaskForm
-from wtforms import StringField, TextAreaField, SubmitField
-from wtforms.validators import DataRequired, Email
+### Write the code
+<FileCode file="projects/intermediate/portfoliowebsite.py" lang="python" title="portfoliowebsite.py" />
 
-app = Flask(__name__)
-app.config['SECRET_KEY'] = 'your-secret-key'
+### Run it
+```cmd title="command"
+C:\Users\Your Name\portfolio-website> python portfoliowebsite.py
+# Visit http://localhost:5000   (portfolio)
+#       http://localhost:5000/admin   (contact messages)
 ```
 
-Sets up the Flask application with form handling and security configuration.
+## Step-by-Step Explanation
 
-### Template Rendering
-```python title="portfoliowebsite.py" showLineNumbers{1}
-@app.route('/')
-def home():
-    projects = get_featured_projects()
-    skills = get_skills_data()
-    return render_template('index.html', projects=projects, skills=skills)
+### 1. Content lives in JSON, not in code
+```python title="portfoliowebsite.py"
+class PortfolioData:
+    def __init__(self):
+        self.data_file = 'portfolio_data.json'
+        self.load_data()
 ```
+`PortfolioData` loads everything — personal info, skills, projects, experience — from `portfolio_data.json`, falling back to sensible defaults on first run and saving them out. The win: **you edit one JSON file to update your site**, never the Python or HTML. This separation of content from presentation is the core idea behind every CMS.
+
+### 2. Self-generating templates
+```python title="portfoliowebsite.py"
+def create_templates():
+    base_template = '''<!DOCTYPE html> ... '''
+    with open('templates/base.html', 'w') as f:
+        f.write(base_template)
+```
+Rather than ship loose files, the app writes `base.html`, `index.html`, `projects.html`, the CSS, and the JS at startup. Handy for a single-file demo — though in a real project you'd keep templates as actual files under version control.
+
+### 3. Jinja template inheritance
+```html title="templates/index.html"
+{% extends "base.html" %}
+{% block content %}
+  <!-- hero, about, skills, projects, contact sections -->
+{% endblock %}
+```
+`base.html` defines the shared shell (nav, footer, Bootstrap links) with `{% block content %}` holes; each page `{% extends %}` it and fills the blocks. Write the layout once, reuse everywhere — change the navbar in `base.html` and every page updates.
+
+### 4. Data drives the markup
+```html title="templates/index.html"
+{% for skill in skills %}
+  <span>{{ skill.name }}</span>
+  <div class="progress-bar" style="width: {{ skill.level }}%"></div>
+{% endfor %}
+```
+The templates loop over the JSON data. Add a skill or project to the JSON and a new card/bar appears automatically — no template edits.
 
-Renders dynamic content by passing data from Python to HTML templates.
-
-### Contact Form Handling
-```python title="portfoliowebsite.py" showLineNumbers{1}
-class ContactForm(FlaskForm):
-    name = StringField('Name', validators=[DataRequired()])
-    email = StringField('Email', validators=[DataRequired(), Email()])
-    message = TextAreaField('Message', validators=[DataRequired()])
-    submit = SubmitField('Send Message')
-
-@app.route('/contact', methods=['GET', 'POST'])
+### 5. The contact form
+```python title="portfoliowebsite.py"
+@app.route('/contact', methods=['POST'])
 def contact():
-    form = ContactForm()
-    if form.validate_on_submit():
-        save_contact_message(form.data)
-        return redirect(url_for('contact', success=True))
-    return render_template('contact.html', form=form)
+    contact_data = {'name': name, 'email': email, 'subject': subject,
+                    'message': message, 'timestamp': datetime.now().isoformat()}
+    contacts.append(contact_data)
+    with open('contacts.json', 'w') as f:
+        json.dump(contacts, f, indent=2)
+    flash('Thank you for your message!', 'success')
+    return redirect(url_for('index') + '#contact')
 ```
-
-Implements form validation, data processing, and user feedback for contact functionality.
-
-### Responsive Design Integration
-```python title="portfoliowebsite.py" showLineNumbers{1}
-@app.route('/projects')
-def projects():
-    project_list = get_all_projects()
-    return render_template('projects.html', 
-                         projects=project_list,
-                         page_title='My Projects')
+Messages append to `contacts.json`, the user gets a `flash` confirmation, and the route **redirects** (Post/Redirect/Get) so a refresh won't resend. Classic Flask form handling.
+
+## Fix the Security Holes (Important)
+
+The starter code is fine for localhost but unsafe to deploy as-is:
+
+| Starter code | Problem | Fix |
+|---|---|---|
+| `app.run(debug=True, host='0.0.0.0')` | Debug console = remote code execution, exposed to the network | `debug=False`; bind `127.0.0.1` unless you mean to expose it |
+| `app.secret_key = 'your-secret-key-here'` | Predictable key forges sessions/flash | Load a random key from an env var |
+| `/admin` has no auth | Anyone can read your contacts | Require login (Flask-Login / basic auth) |
+| Admin HTML built with f-strings | `{contact['message']}` injected raw → **stored XSS** | Render via a Jinja template (auto-escapes) |
+| `email` never validated | Junk/spoofed submissions | Validate with WTForms `Email()` |
+
+The XSS one is the sneakiest:
+```python title="admin_fix.py"
+# WRONG — visitor's message injected into HTML unescaped
+html += f"<p>{contact['message']}</p>"
+# RIGHT — Jinja escapes it
+return render_template('admin.html', contacts=contacts)
 ```
 
-Creates project showcase with responsive grid layout and detailed project information.
+## Add an Admin Login
+
+Gate `/admin` behind a password:
+```python title="auth.py"
+from functools import wraps
+from flask import session, request, redirect, url_for
+
+def login_required(view):
+    @wraps(view)
+    def wrapped(*args, **kwargs):
+        if not session.get('admin'):
+            return redirect(url_for('login'))
+        return view(*args, **kwargs)
+    return wrapped
+
+@app.route('/admin')
+@login_required
+def admin():
+    ...
+```
 
-## Features
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Edits to JSON don't show | Server caches in memory | Reload data per request, or restart |
+| `TemplateNotFound` | `create_templates()` not run | Ensure setup runs before serving |
+| Images 404 | Files missing from `static/images` | Add images or guard with defaults |
+| Contact form resubmits on refresh | No redirect after POST | Use the PRG pattern (built in) |
+| Admin shows raw HTML tags from a message | f-string injection (XSS) | Render through Jinja |
+| Site reachable from other machines unexpectedly | `host='0.0.0.0'` | Bind `127.0.0.1` for local-only |
+
+## Variations to Try
+
+1. **Render the admin page** via a Jinja template (fixes XSS).
+2. **Real email** — send contact messages via SMTP instead of a file.
+3. **Blog section** — reuse the [Simple Blog](./simple-blog-with-flask) pattern.
+4. **Project detail pages** — `/project/<id>` with full write-ups.
+5. **Dark/light theme** — toggle with a CSS variable + localStorage.
+6. **Resume download** — serve a PDF; track downloads.
+7. **Visitor analytics** — log page views.
+8. **Deploy it** — ship to Render/Railway/Fly with `debug=False`.
+
+## Real-World Applications
+- **Personal branding** — the developer portfolio itself.
+- **Small business sites** — content-managed brochure sites.
+- **Agency templates** — one codebase, many clients via JSON.
+- **Learning full-stack Flask** — templating, forms, static assets together.
 
-- **Responsive Design**: Mobile-first approach with cross-device compatibility
-- **Project Gallery**: Showcase work samples with detailed descriptions
-- **Contact System**: Functional contact form with validation and feedback
-- **Skills Display**: Visual representation of technical competencies
-- **About Section**: Professional background and personal information
-- **Navigation Menu**: Smooth scrolling and intuitive site navigation
-- **Modern UI**: Clean, professional design with CSS animations
-- **SEO Friendly**: Optimized for search engines and social sharing
+## Educational Value
+- **Separation of concerns** — content (JSON) vs. presentation (templates).
+- **Template inheritance** — DRY layouts with Jinja blocks.
+- **Form handling** — validation, flashing, PRG.
+- **Web security** — debug mode, secret keys, XSS, and auth — the things tutorials skip.
 
 ## Next Steps
+- Fix the **security issues** above before deploying.
+- Render the **admin page through Jinja**; add a **login**.
+- Wire up **real email** for the contact form.
+- **Deploy** with `debug=False` and a real secret key.
 
-### Enhancements
-- Add blog functionality with post creation and management
-- Implement user authentication for admin features
-- Create dynamic theme switching capabilities
-- Add social media integration and sharing
-- Implement SEO optimization features
-- Create mobile app companion
-- Add real-time chat for client communication
-- Implement analytics and visitor tracking
-
-### Learning Extensions
-- Study modern web design trends and UI/UX principles
-- Explore advanced CSS frameworks like Bootstrap or Tailwind
-- Learn about content management systems (CMS)
-- Practice with JavaScript frameworks for enhanced interactivity
-- Understand web accessibility standards and best practices
-- Explore deployment strategies and hosting options
-
-## Educational Value
-
-This project teaches:
-- **Web Development**: Building dynamic websites with Flask framework
-- **Template Rendering**: Creating reusable HTML templates with Jinja2
-- **Responsive Design**: Implementing mobile-friendly layouts and designs
-- **Form Handling**: Processing user input and validation
-- **Professional Branding**: Creating effective online presence and portfolios
-- **User Experience**: Designing intuitive navigation and user interactions
-- **Content Management**: Organizing and presenting portfolio content effectively
-- **Web Standards**: Following best practices for modern web development
-
-Perfect for understanding web development, personal branding, and creating professional online portfolios with Python.
-````
+## Conclusion
+You built a portfolio site that's content-driven (one JSON file), DRY (template inheritance), and interactive (a working contact form + admin inbox) — and, just as valuable, you learned to spot the security mistakes (`debug=True`, f-string HTML, an open admin route) that turn a nice demo into a liability. Fix those and it's genuinely deployable. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/portfoliowebsite.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/qr-code-attendance-system.mdx b/src/content/docs/projects/intermediate/qr-code-attendance-system.mdx
index 5d0c3e3c..afadf30a 100644
--- a/src/content/docs/projects/intermediate/qr-code-attendance-system.mdx
+++ b/src/content/docs/projects/intermediate/qr-code-attendance-system.mdx
@@ -1,5 +1,6 @@
 ---
 title: QR Code Attendance System
+description: Build a QR-based attendance system in Python — generate per-user QR codes with qrcode and scan them via webcam with OpenCV to log attendance — then add a database, duplicate prevention, live overlays, and CSV export.
 sidebar:
   order: 102
 hero:
@@ -12,65 +13,167 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+QR codes turn any phone or printout into a scannable ID — which is why they run everything from event check-ins to classroom attendance. This project wires together two libraries: `qrcode` to **generate** a code for each user, and OpenCV to **scan** it through a webcam and stamp the time. You'll build the generate-and-scan core, then turn the toy into a usable system: a database of records, duplicate-scan prevention, a live camera overlay that shows the decoded ID, and CSV export for reports.
 
-Build a QR Code Attendance System that generates QR codes for users and scans them to mark attendance. The app provides a GUI for generating and scanning codes. This project demonstrates QR code generation, image processing, and GUI development in Python.
+You will leave understanding:
+- How QR codes encode arbitrary text and how `qrcode` renders them.
+- The OpenCV capture loop: open camera → read frame → detect → release.
+- Why the naive version can't tell who's already checked in (and how to fix it).
+- How to move from "popup says scanned" to a real attendance log.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of QR code generation and OpenCV
+- Python 3.6 or above.
+- A text editor or IDE.
+- `pip install qrcode[pil] opencv-python`.
+- A working webcam.
+- Tkinter (bundled with Python).
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `qr_code_attendance_system`.
-2. Create a new file inside the folder and name it `qr_code_attendance_system.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `qr_code_attendance_system.py` file.
+
+### Create the project
+1. Create a folder named `qr-attendance`.
+2. Inside it, create `qr_code_attendance_system.py`.
+3. Install dependencies: `pip install qrcode[pil] opencv-python`.
 
 ### Write the code
 <FileCode file="projects/intermediate/qr_code_attendance_system.py" lang="python" title="qr_code_attendance_system.py" showLineNumbers={1} />
 
-## Key Features
-- Generate QR codes for user identification
-- Scan QR codes to mark attendance
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\qr-attendance> python qr_code_attendance_system.py
+# Enter a User ID and "Generate QR Code" -> saves <id>_qr.png
+# "Scan QR Code" opens the webcam; show the code to mark attendance.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Generating QR Codes
-The app uses the `qrcode` library to generate QR codes:
-```python title="qr_code_attendance_system.py" showLineNumbers={1}
+### 1. Generating a QR code
+```python title="qr_code_attendance_system.py"
 qr = qrcode.QRCode(version=1, box_size=10, border=5)
 qr.add_data(user_id)
 qr.make(fit=True)
 img = qr.make_image(fill="black", back_color="white")
-img.save(img_path)
+img.save(f"{user_id}_qr.png")
 ```
+A QR code is just text encoded as a grid. `version` sets capacity (1 = smallest), `box_size` is pixels per module, `border` is the quiet zone around it. `fit=True` auto-grows the version if the data doesn't fit. Here the encoded data is simply the user ID.
 
-### Scanning QR Codes
-OpenCV is used to scan QR codes and mark attendance:
-```python title="qr_code_attendance_system.py" showLineNumbers={1}
-cap = cv2.VideoCapture(0)
+### 2. Opening the camera
+```python title="qr_code_attendance_system.py"
+cap = cv2.VideoCapture(0)          # 0 = default webcam
 detector = cv2.QRCodeDetector()
+```
+`VideoCapture(0)` grabs the first camera. `QRCodeDetector` is OpenCV's built-in QR reader — no extra library needed.
+
+### 3. The scan loop
+```python title="qr_code_attendance_system.py"
 while True:
     ret, frame = cap.read()
+    if not ret:
+        break
     data, bbox, _ = detector.detectAndDecode(frame)
     if data:
-        # Mark attendance
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        messagebox.showinfo("Attendance Marked", f"User ID: {data}\nTime: {timestamp}")
+        break
+    cv2.imshow("QR Code Scanner", frame)
+    if cv2.waitKey(1) & 0xFF == ord("q"):
+        break
+cap.release()
+cv2.destroyAllWindows()
+```
+Each loop reads a frame, tries to decode a QR code, and on success stamps the time and stops. `cv2.imshow` shows the live feed; `waitKey(1)` keeps it responsive and lets `q` quit. **Always** `release()` the camera and `destroyAllWindows()` — skip it and the webcam stays locked.
+
+## The Core Problem: Nothing Is Actually Stored
+
+The naive version pops a message and forgets. A real system needs a record. Add SQLite:
+```python title="db.py"
+import sqlite3
+
+conn = sqlite3.connect("attendance.db")
+conn.execute("""CREATE TABLE IF NOT EXISTS attendance (
+    user_id TEXT, timestamp TEXT
+)""")
+
+def mark(user_id):
+    ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    conn.execute("INSERT INTO attendance VALUES (?, ?)", (user_id, ts))
+    conn.commit()
+```
+Note `?` placeholders — never f-string user input into SQL (injection risk).
+
+## Prevent Duplicate Scans
+
+A code lingering in view marks attendance dozens of times. Check today's log first:
+```python title="dedupe.py"
+def already_marked_today(user_id):
+    today = datetime.now().strftime("%Y-%m-%d")
+    row = conn.execute(
+        "SELECT 1 FROM attendance WHERE user_id=? AND timestamp LIKE ?",
+        (user_id, f"{today}%")).fetchone()
+    return row is not None
 ```
+Mark only if `not already_marked_today(data)`.
+
+## Draw a Live Overlay
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install qrcode opencv-python
+Show the detected box and ID on the video so the user knows it worked:
+```python title="overlay.py"
+if data and bbox is not None:
+    pts = bbox.astype(int).reshape(-1, 2)
+    for i in range(len(pts)):
+        cv2.line(frame, tuple(pts[i]), tuple(pts[(i + 1) % len(pts)]), (0, 255, 0), 2)
+    cv2.putText(frame, data, tuple(pts[0]), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)
 ```
-3. Run the application:
-```bash
-python qr_code_attendance_system.py
+
+## Export to CSV
+
+For reports, dump the table:
+```python title="export.py"
+import csv
+def export():
+    rows = conn.execute("SELECT user_id, timestamp FROM attendance").fetchall()
+    with open("attendance.csv", "w", newline="") as f:
+        csv.writer(f).writerows([("User ID", "Time"), *rows])
 ```
 
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Camera stays on / locked | Forgot `release()` | Always `cap.release()` + `destroyAllWindows()` |
+| Same person marked many times | No duplicate check | Skip if already marked today |
+| Attendance vanishes on exit | Nothing persisted | Store in SQLite/CSV |
+| Black window, no feed | Wrong camera index or in-use | Try `VideoCapture(1)`; close other apps |
+| QR won't scan | Too small / poor lighting / glare | Larger `box_size`, better light, hold steady |
+| SQL breaks on odd IDs | String-formatted query | Use `?` parameterized queries |
+
+## Variations to Try
+
+1. **User registry** — generate codes for a whole roster from a CSV.
+2. **Check-in / check-out** — track both, compute hours present.
+3. **Web dashboard** — live attendance via Flask (see [Simple Blog with Flask](./simple-blog-with-flask)).
+4. **Encrypted payloads** — sign the QR data so codes can't be forged.
+5. **Email/SMS confirmation** — notify on successful check-in.
+6. **Photo capture** — save a webcam snapshot with each scan.
+7. **Mobile scanning** — a companion phone app posting to your API.
+
+## Real-World Applications
+- **Events & conferences** — ticketed entry and session check-in.
+- **Schools & offices** — class and workplace attendance.
+- **Gyms & memberships** — access logging.
+- **Inventory & logistics** — scanning items in and out.
+
+## Educational Value
+- **QR generation & decoding** — encoding data, the `qrcode` and OpenCV APIs.
+- **Computer vision basics** — the capture/detect/release loop.
+- **Database design** — records, queries, and safe parameterization.
+- **Data integrity** — duplicate prevention and exports.
+
+## Next Steps
+- Persist scans to **SQLite** with **duplicate prevention**.
+- Add a **live overlay** showing the decoded ID.
+- Support **check-in/check-out** and **CSV export**.
+- Generate codes for a **whole roster** at once.
+
 ## Conclusion
-This QR Code Attendance System project is a great way to learn about QR code generation and image processing in Python. You can extend it by adding a database, attendance history, or email notifications.
+You combined `qrcode` and OpenCV into a scan-to-log attendance system, then closed the gap that makes the naive version a toy: it now *remembers*, refuses duplicates, and exports reports. Generate-then-scan plus a database is the exact recipe behind ticketing, access control, and inventory systems everywhere. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/qr_code_attendance_system.py). Explore more computer-vision projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/qr_code_attendance_system.mdx b/src/content/docs/projects/intermediate/qr_code_attendance_system.mdx
deleted file mode 100644
index a8fdebfa..00000000
--- a/src/content/docs/projects/intermediate/qr_code_attendance_system.mdx
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: QR Code Attendance System
-sidebar:
-  order: 15
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/qr_code_attendance_system.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-QR Code Attendance System is a Python project that records attendance using QR codes. It demonstrates QR code generation/scanning, file handling, and GUI development. This project is ideal for learning about automation, data management, and real-world applications.
-
-## Prerequisites
-- Python 3.6 or above
-- qrcode (`pip install qrcode`)
-- opencv-python (`pip install opencv-python`)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Install Python, qrcode, and OpenCV. Prepare a sample list of users for QR code generation.
-
-## Getting Started
-1. Create a folder named `qr-attendance-system`.
-2. Create a file named `qr_code_attendance_system.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/qr_code_attendance_system.py" lang="python" title="QR Code Attendance System" />
-4. Run the script: `python qr_code_attendance_system.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import qrcode
-import cv2
-import tkinter as tk
-```
-2. **Generate QR codes.**
-```python
-img = qrcode.make('UserID123')
-img.save('user_qr.png')
-```
-3. **Scan QR codes.**
-```python
-cap = cv2.VideoCapture(0)
-# ...scan and decode QR codes...
-```
-4. **GUI for attendance.**
-```python
-root = tk.Tk()
-root.title('QR Code Attendance System')
-# ...setup widgets for scanning and logging attendance...
-root.mainloop()
-```
-
-## Features
-- Generates and scans QR codes
-- Records attendance automatically
-- GUI for user interaction
-- Easy to extend for more features
-
-## How It Works
-- Generates QR codes for users
-- Scans QR codes to record attendance
-- Logs attendance in a file or database
-
-## GUI Components
-- **Scan button:** Starts QR scanning
-- **Status display:** Shows attendance status
-- **Log file:** Records attendance
-
-## Use Cases
-- School or office attendance
-- Event check-in
-- Automate record keeping
-
-## Next Steps
-You can enhance this project by:
-- Adding user authentication
-- Exporting attendance logs
-- Improving GUI design
-- Integrating with cloud storage
-
-## Enhanced Version Ideas
-```python
-def export_logs():
-    # Save attendance logs to CSV
-    pass
-
-def add_cloud_sync():
-    # Sync logs to cloud
-    pass
-```
-
-## Troubleshooting Tips
-- **QR code not recognized:** Check camera and lighting
-- **Log file errors:** Check file permissions
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches QR code handling, automation, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/quiz-game-with-timer.mdx b/src/content/docs/projects/intermediate/quiz-game-with-timer.mdx
index 6c7f2e23..bfd794ca 100644
--- a/src/content/docs/projects/intermediate/quiz-game-with-timer.mdx
+++ b/src/content/docs/projects/intermediate/quiz-game-with-timer.mdx
@@ -1,5 +1,6 @@
 ---
 title: Quiz Game with Timer
+description: Build a timed multiple-choice quiz in Python with Tkinter — countdown per question, auto-advance on timeout, and scoring — then fix the threading pitfalls and add a JSON question bank, progress bar, and results screen.
 sidebar:
   order: 94
 hero:
@@ -12,62 +13,174 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Adding a timer to a quiz sounds trivial — until you discover that `time.sleep` freezes the entire window, and that updating widgets from a background thread is officially unsafe in Tkinter. This project is the perfect vehicle for learning **non-blocking timing** and **GUI thread safety**. You'll build a multiple-choice quiz where each question has a 10-second countdown that auto-advances when it expires, then refactor the timing to the idiomatic, bug-free approach and grow the game with a JSON question bank, a progress bar, and a proper results screen.
 
-Build a Quiz Game with Timer that challenges users to answer multiple-choice questions within a time limit. The app tracks the score and provides instant feedback. This project demonstrates event-driven programming, threading, and GUI development in Python.
+You will leave understanding:
+- Why `time.sleep` on the main thread freezes a GUI, and two correct alternatives.
+- The thread-safety rule for Tkinter and how `root.after` sidesteps it.
+- How to manage per-question state (index, score, time left).
+- How to cancel a pending timer when the player answers early.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of threading for timers
+- Python 3.6 or above.
+- A text editor or IDE.
+- Tkinter (bundled with Python).
+- Basic understanding of functions, classes, and (helpful) threads.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `quiz_game_with_timer`.
-2. Create a new file inside the folder and name it `quiz_game_with_timer.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `quiz_game_with_timer.py` file.
+
+### Create the project
+1. Create a folder named `quiz-timer`.
+2. Inside it, create `quiz_game_with_timer.py`.
 
 ### Write the code
 <FileCode file="projects/intermediate/quiz_game_with_timer.py" lang="python" title="quiz_game_with_timer.py" showLineNumbers={1} />
 
-## Key Features
-- Multiple-choice questions
-- Timer for each question
-- Score tracking and instant feedback
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\quiz-timer> python quiz_game_with_timer.py
+# Each question shows four options and a countdown. Answer before time runs out.
+```
+
+## Step-by-Step Explanation
 
-## Explanation
+### 1. Questions as a list of dicts
+```python title="quiz_game_with_timer.py"
+self.questions = [
+    {"question": "What is the capital of France?",
+     "options": ["Paris", "London", "Berlin", "Madrid"], "answer": "Paris"},
+    ...
+]
+```
+Each question is a self-contained dict — far cleaner than parallel lists. Later you'll load this same shape from a JSON file.
 
-### Timer Implementation
-The app uses threading to implement a countdown timer for each question:
-```python title="quiz_game_with_timer.py" showLineNumbers={1}
+### 2. Per-question state
+```python title="quiz_game_with_timer.py"
+self.current_question_index = 0
+self.score = 0
 self.time_left = 10
-threading.Thread(target=self.start_timer).start()
 ```
+Three variables track the whole game: which question, the running score, and the countdown.
+
+### 3. The timer (as written — note the caveat)
+```python title="quiz_game_with_timer.py"
+def start_timer(self):
+    self.timer_running = True
+    self.timer_thread = threading.Thread(target=self.countdown)
+    self.timer_thread.start()
+
+def countdown(self):
+    while self.time_left > 0 and self.timer_running:
+        time.sleep(1)
+        self.time_left -= 1
+        self.timer_label.config(text=f"Time left: {self.time_left} seconds")
+    if self.time_left == 0:
+        self.timer_running = False
+        self.root.after(0, self.time_up)
+```
+This runs the countdown on a **background thread** so `time.sleep` doesn't freeze the window. It works, but it breaks a Tkinter rule: `self.timer_label.config(...)` is called *from the background thread*. Tkinter widgets should only be touched from the main thread. It usually works on CPython but can crash or corrupt the display. The fix is below — and it's simpler.
+
+### 4. Checking the answer cancels the timer
+```python title="quiz_game_with_timer.py"
+def check_answer(self, index):
+    if not self.timer_running:
+        return
+    self.timer_running = False    # stop the countdown loop
+    ...
+```
+Setting `timer_running = False` is how the answer button tells the countdown loop to stop. Without it, an expired timer could advance the question a second time.
+
+## The Idiomatic Fix: `root.after` Instead of Threads
+
+Tkinter has a built-in scheduler. `root.after(ms, fn)` runs `fn` later, **on the main thread** — no threads, no sleep, no safety violation:
+```python title="after_timer.py"
+def start_timer(self, seconds=10):
+    self.time_left = seconds
+    self.tick()
+
+def tick(self):
+    self.timer_label.config(text=f"Time left: {self.time_left} seconds")
+    if self.time_left <= 0:
+        self.time_up()
+        return
+    self.time_left -= 1
+    self._after_id = self.root.after(1000, self.tick)   # schedule the next tick
 
-### Checking Answers
-User answers are checked and the score is updated:
-```python title="quiz_game_with_timer.py" showLineNumbers={1}
-if selected_option == question_data["answer"]:
-    self.score += 1
+def check_answer(self, index):
+    self.root.after_cancel(self._after_id)              # stop the pending tick
+    ...
 ```
+This is shorter, thread-safe, and trivially cancelable. **Rule:** for periodic UI work in Tkinter, reach for `after`, not `threading` + `sleep`.
 
-### Displaying Questions
-Questions and options are displayed using Tkinter widgets:
-```python title="quiz_game_with_timer.py" showLineNumbers={1}
-self.question_label.config(text=question_data["question"])
-for i, option in enumerate(question_data["options"]):
-    self.options[i].config(text=option)
+## Load Questions from JSON
+
+Hard-coded questions don't scale. Move them to a file:
+```python title="questions.json"
+[
+  {"question": "Capital of France?", "options": ["Paris","London","Berlin","Madrid"], "answer": "Paris"},
+  {"question": "5 + 7?", "options": ["10","12","14","16"], "answer": "12"}
+]
+```
+```python title="load.py"
+import json
+from pathlib import Path
+self.questions = json.loads(Path("questions.json").read_text())
 ```
+Now non-programmers can author quizzes, and you can ship multiple categories as separate files.
+
+## Add a Progress Bar
 
-## Running the Application
-1. Save the file.
-2. Run the application:
-```bash
-python quiz_game_with_timer.py
+Show how much time remains visually:
+```python title="progress.py"
+from tkinter import ttk
+self.bar = ttk.Progressbar(self.root, maximum=10, length=300)
+self.bar.pack(pady=5)
+# in tick():
+self.bar["value"] = self.time_left
 ```
 
+## Build a Results Screen
+
+Instead of a popup, end on a summary with per-question feedback — which you got right, which timed out, and the correct answers. Educational quizzes live on feedback, not just a final number.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Window freezes during countdown | `time.sleep` on the main thread | Use `root.after(1000, ...)` |
+| Random crashes / display glitches | Updating widgets from a thread | Do all UI work on the main thread |
+| Question advances twice | Expired timer + manual answer both fire | Cancel the timer on answer (`after_cancel`) |
+| Timer keeps running after game over | Loop/`after` not stopped | Cancel pending callbacks in `end_game` |
+| Score off by one | Checked answer after incrementing index | Compare before advancing |
+| Same answer position every time | Options not shuffled | `random.shuffle` the options per question |
+
+## Variations to Try
+
+1. **Difficulty-based timing** — less time for harder questions.
+2. **Streak bonus** — extra points for fast consecutive correct answers.
+3. **Categories** — load different JSON banks for science, history, etc.
+4. **Lifelines** — 50/50 (remove two wrong options), skip, or extra time.
+5. **Sound effects** — a tick near the deadline, a chime for correct answers.
+6. **Leaderboard** — persist scores to JSON and show top players.
+7. **Online questions** — pull from the Open Trivia DB API for endless content.
+
+## Real-World Applications
+- **E-learning** — timed assessments and certification practice.
+- **Corporate training** — compliance quizzes with time pressure.
+- **Game shows / trivia apps** — the timer *is* the format.
+- **Cognitive testing** — reaction-time and recall measurement.
+
+## Educational Value
+- **Non-blocking timing** — `after` vs. `sleep`, a lesson that scales to all async UI.
+- **GUI thread safety** — the single-thread rule and why it matters.
+- **State machines** — advancing through questions cleanly.
+- **Data-driven design** — questions as data, loaded from JSON.
+
+## Next Steps
+- Refactor the timer to **`root.after`** and delete the thread.
+- Move questions to a **JSON bank** with multiple categories.
+- Add a **progress bar** and a **results screen**.
+- Persist a **leaderboard** to disk.
+
 ## Conclusion
-This Quiz Game with Timer project is a fun way to learn about event-driven programming and threading in Python. You can extend it by adding more questions, difficulty levels, or a high score leaderboard.
+You built a timed quiz, then learned the most important Tkinter lesson hiding inside it: never block or touch widgets off the main thread — `root.after` does timing the right way. With a JSON question bank and a results screen, the same code becomes a real assessment engine. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/quiz_game_with_timer.py). Find more games on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/quiz_game_with_timer.mdx b/src/content/docs/projects/intermediate/quiz_game_with_timer.mdx
deleted file mode 100644
index 16aff462..00000000
--- a/src/content/docs/projects/intermediate/quiz_game_with_timer.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Quiz Game with Timer
-sidebar:
-    order: 7
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/quiz_game_with_timer.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Quiz Game with Timer is a Python project that challenges users with timed questions. It demonstrates event-driven programming, GUI development, and time management. This project is ideal for learning about interactive games, user input, and countdown timers in Python.
-
-## Prerequisites
-- Python 3.6 or above
-- tkinter (usually pre-installed)
-- random (built-in)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available.
-
-## Getting Started
-1. Create a folder named `quiz-game-timer`.
-2. Create a file named `quiz_game_with_timer.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/quiz_game_with_timer.py" lang="python" title="Quiz Game with Timer" />
-4. Run the script: `python quiz_game_with_timer.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import tkinter as tk
-import random
-```
-2. **Set up questions and timer**
-```python
-questions = [
-    {'q': 'What is 2+2?', 'a': '4'},
-    {'q': 'Capital of France?', 'a': 'Paris'}
-]
-```
-3. **Timer mechanism**
-```python
-def start_timer():
-    # Countdown logic
-    pass
-```
-4. **GUI for quiz**
-```python
-root = tk.Tk()
-root.title('Quiz Game with Timer')
-# ...setup widgets for questions, input, timer...
-root.mainloop()
-```
-
-## Features
-- Timed questions
-- Score tracking
-- Randomized questions
-- GUI for interaction
-
-## How It Works
-- Displays questions one by one
-- Starts timer for each question
-- User enters answer before time runs out
-- Updates score and moves to next question
-
-## GUI Components
-- **Label:** Shows question
-- **Entry box:** For answer
-- **Timer display:** Shows remaining time
-- **Score display:** Tracks correct answers
-
-## Use Cases
-- Practice quick thinking
-- Educational quizzes
-- Game nights
-
-## Next Steps
-You can enhance this project by:
-- Adding more questions
-- Implementing difficulty levels
-- Adding sound alerts
-- Keeping high scores
-- Supporting multiplayer
-
-## Enhanced Version Ideas
-```python
-def add_sound_alert():
-    # Play sound when time is up
-    pass
-
-def multiplayer_mode():
-    # Allow multiple players
-    pass
-```
-
-## Troubleshooting Tips
-- **Timer not working:** Check countdown logic
-- **GUI not showing:** Ensure Tkinter is installed
-- **Questions not loading:** Check question list
-
-## Conclusion
-This project teaches event-driven programming, timers, and GUI basics. Extend it for more features and challenge levels.
diff --git a/src/content/docs/projects/intermediate/real-time-chat-application.mdx b/src/content/docs/projects/intermediate/real-time-chat-application.mdx
index bef262ed..b36359df 100644
--- a/src/content/docs/projects/intermediate/real-time-chat-application.mdx
+++ b/src/content/docs/projects/intermediate/real-time-chat-application.mdx
@@ -1,5 +1,6 @@
 ---
 title: Real-time Chat Application (WebSocket)
+description: Build a real-time chat server in Python with asyncio and websockets — broadcast messages to every connected client over a persistent connection — then fix the deprecated broadcast call and add usernames, rooms, and a browser client.
 sidebar:
   order: 104
 hero:
@@ -12,60 +13,181 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+WebSockets are how the modern web does *real-time* — a persistent, two-way connection that lets a server push messages to clients the instant they arrive, with none of the polling overhead of plain HTTP. This project builds a WebSocket chat server in pure `asyncio`: clients connect, and every message is broadcast to all of them, live. It's your introduction to **asynchronous** Python — `async`/`await`, coroutines, and an event loop handling many connections on a single thread. You'll also fix a real deprecation in the starter code and add usernames, rooms, and a browser client.
 
-Build a Real-time Chat Application using WebSocket for real-time communication between clients. The app includes server and client implementations for sending and receiving messages. This project demonstrates WebSocket programming, concurrency, and network communication in Python.
+You will leave understanding:
+- What a WebSocket is and how it differs from request/response HTTP.
+- How `async`/`await` lets one thread juggle thousands of connections.
+- The `async for message in websocket` pattern for receiving.
+- Why the starter's `asyncio.wait([...])` broadcast is deprecated, and the modern replacement.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with WebSocket programming
-- Knowledge of asyncio for concurrency
+- Python 3.7 or above (for `asyncio.run`).
+- A text editor or IDE.
+- The websockets library: `pip install websockets`.
+- Basic understanding of functions; async is explained here.
+- Helpful: the thread-based [Basic Chatroom App](./basic-chatroom-app) for contrast.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `real_time_chat_application`.
-2. Create a new file inside the folder and name it `real_time_chat_application.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `real_time_chat_application.py` file.
+
+### Create the project
+1. Create a folder named `ws-chat`.
+2. Inside it, create `real_time_chat_application.py`.
+3. Install the dependency: `pip install websockets`.
 
 ### Write the code
 <FileCode file="projects/intermediate/real_time_chat_application.py" lang="python" title="real_time_chat_application.py" showLineNumbers={1} />
 
-## Key Features
-- Real-time messaging between multiple clients
-- Server-side implementation using `websockets` library
-- Client-side implementation for sending and receiving messages
-- Concurrency using asyncio
+### Run it
+```cmd title="command"
+C:\Users\Your Name\ws-chat> python real_time_chat_application.py
+Server started on ws://localhost:8765
+# Connect with a browser console or a small client (see below).
+```
+
+## Step-by-Step Explanation
 
-## Explanation
+### 1. Tracking connected clients
+```python title="real_time_chat_application.py"
+connected_clients = set()
+```
+A `set` of active WebSocket connections. Sets make add/remove O(1) and prevent duplicates — perfect for a connection registry.
 
-### Server Implementation
-The server handles incoming messages and broadcasts them to all clients:
-```python title="real_time_chat_application.py" showLineNumbers={1}
+### 2. Handling a client (a coroutine)
+```python title="real_time_chat_application.py"
 async def handle_client(websocket, path):
     connected_clients.add(websocket)
-    async for message in websocket:
-        await broadcast(message)
+    try:
+        async for message in websocket:
+            print(f"Received message: {message}")
+            await broadcast(message)
+    except websockets.ConnectionClosed:
+        print("Client disconnected")
+    finally:
+        connected_clients.remove(websocket)
+```
+`async def` makes this a **coroutine** — a function that can pause at `await` and let other connections run. `async for message in websocket` yields each incoming message as it arrives, *without blocking* the other clients. The `finally` guarantees the client is removed from the registry even if it disconnects abruptly — critical for not broadcasting to dead sockets.
+
+### 3. Broadcasting
+```python title="real_time_chat_application.py"
+async def broadcast(message):
+    if connected_clients:
+        await asyncio.wait([client.send(message) for client in connected_clients])
 ```
+Send the message to everyone. **Heads-up:** this line is deprecated in modern `websockets`/`asyncio` — see the fix below.
 
-### Broadcasting Messages
-Messages are sent to all connected clients:
-```python title="real_time_chat_application.py" showLineNumbers={1}
+### 4. Starting the server
+```python title="real_time_chat_application.py"
+async def main():
+    server = await websockets.serve(handle_client, "localhost", 8765)
+    print("Server started on ws://localhost:8765")
+    await server.wait_closed()
+
+asyncio.run(main())
+```
+`websockets.serve` binds the port and runs `handle_client` for each connection. `asyncio.run(main())` creates the event loop, runs the coroutine, and cleans up — the standard async entry point.
+
+## Fix: Modernize the Broadcast
+
+`asyncio.wait([coro, ...])` with bare coroutines is **deprecated** (and broadcasting to a client that just disconnected raises). The clean, current approach:
+```python title="broadcast_fixed.py"
 async def broadcast(message):
-    await asyncio.wait([client.send(message) for client in connected_clients])
+    if not connected_clients:
+        return
+    # gather runs all sends concurrently; return_exceptions keeps one
+    # failed send from cancelling the rest
+    await asyncio.gather(
+        *(client.send(message) for client in connected_clients),
+        return_exceptions=True,
+    )
 ```
+Recent `websockets` versions also offer a built-in `websockets.broadcast(connected_clients, message)` helper that handles dead connections for you.
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install websockets
+## Add Usernames
+
+Have each client send a name as its first message, then prefix broadcasts:
+```python title="usernames.py"
+names = {}   # websocket -> name
+
+async def handle_client(websocket):
+    name = await websocket.recv()          # first message is the name
+    names[websocket] = name
+    connected_clients.add(websocket)
+    await broadcast(f"*** {name} joined ***")
+    try:
+        async for msg in websocket:
+            await broadcast(f"{name}: {msg}")
+    finally:
+        connected_clients.discard(websocket)
+        await broadcast(f"*** {name} left ***")
 ```
-3. Run the server:
-```bash
-python real_time_chat_application.py
+(Modern `websockets` passes only `websocket` to the handler — `path` is no longer required.)
+
+## Add Rooms
+
+Group clients into channels by keeping a `dict[str, set]` of rooms and broadcasting only within the sender's room — the same pattern Slack and Discord channels use.
+
+## A Browser Client
+
+WebSockets are native to browsers — no library needed:
+```html title="client.html"
+<script>
+  const ws = new WebSocket("ws://localhost:8765");
+  ws.onopen = () => ws.send("Alice");                 // send username first
+  ws.onmessage = (e) => console.log(e.data);          // print incoming
+  function send(text) { ws.send(text); }
+</script>
 ```
 
+## WebSockets vs. Threads (vs. HTTP)
+
+| Approach | Model | Scales to many clients? |
+|---|---|---|
+| HTTP polling | Repeated request/response | Poorly — wasteful, laggy |
+| Thread per client | One OS thread each | Hundreds (threads are heavy) |
+| **asyncio + WebSocket** | One loop, many coroutines | Thousands (cheap to suspend) |
+
+This is *why* async exists: I/O-bound work (waiting on the network) suspends cheaply, so one thread serves enormous numbers of idle-but-connected clients.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `DeprecationWarning` on broadcast | `asyncio.wait` with coroutines | Use `asyncio.gather(..., return_exceptions=True)` |
+| Server crashes when one client drops | `send` to a closed socket | `return_exceptions=True`, or `websockets.broadcast` |
+| `handler() takes 1 arg` error | Newer `websockets` drops `path` | Define `handle_client(websocket)` |
+| Messages never arrive | Mixed `ws://` and `wss://`, or wrong port | Match scheme/port; `wss` needs TLS |
+| Dead clients still in the set | Removed only on clean close | Remove in a `finally` block |
+| Blocking call freezes everyone | Using sync I/O in a coroutine | Use async equivalents; never `time.sleep` |
+
+## Variations to Try
+
+1. **Modern broadcast** — the `gather`/`websockets.broadcast` fix (do this first).
+2. **Usernames & system messages** — join/leave notices.
+3. **Chat rooms** — multiple channels.
+4. **Browser UI** — an HTML/JS front end (above).
+5. **Message history** — replay the last N messages on join.
+6. **Typing indicators / presence** — show who's online and typing.
+7. **Authentication** — validate a token on connect.
+8. **Persistence** — log messages to a database.
+
+## Real-World Applications
+- **Live chat & messaging** — Slack, Discord, support widgets.
+- **Collaborative apps** — Google Docs-style live editing.
+- **Live dashboards** — real-time metrics, prices, scores.
+- **Multiplayer games** — low-latency state updates.
+
+## Educational Value
+- **Async Python** — `async`/`await`, coroutines, the event loop.
+- **WebSockets** — persistent, bidirectional connections.
+- **Concurrency models** — async vs. threads vs. polling.
+- **Keeping up with APIs** — recognizing and fixing deprecations.
+
+## Next Steps
+- Replace the deprecated broadcast with **`asyncio.gather`**.
+- Add **usernames**, **system messages**, and **rooms**.
+- Build a **browser client** and add **message history**.
+- Add **authentication** and **persistence**.
+
 ## Conclusion
-This Real-time Chat Application project is a great way to learn about WebSocket programming and concurrency in Python. You can extend it by adding a GUI, message history, or user authentication.
+You built a real-time chat server with `asyncio` and WebSockets, learned how one thread serves thousands of connections by suspending at `await`, and modernized a deprecated broadcast in the process. Persistent, push-based connections are the backbone of every live app you use — and async is how Python scales them. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/real_time_chat_application.py). Explore more networking projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/real_time_chat_application.mdx b/src/content/docs/projects/intermediate/real_time_chat_application.mdx
deleted file mode 100644
index f5a46762..00000000
--- a/src/content/docs/projects/intermediate/real_time_chat_application.mdx
+++ /dev/null
@@ -1,108 +0,0 @@
----
-title: Real-time Chat Application
-sidebar:
-  order: 17
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/real_time_chat_application.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Real-time Chat Application is a Python project that enables users to chat in real time over a network. It demonstrates socket programming, threading, and GUI development. This project is ideal for learning about client-server architecture, concurrency, and event-driven programming.
-
-## Prerequisites
-- Python 3.6 or above
-- socket, threading (built-in)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Ensure Python is installed. No external packages are required. For GUI, make sure Tkinter is available.
-
-## Getting Started
-1. Create a folder named `real-time-chat`.
-2. Create a file named `real_time_chat_application.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/real_time_chat_application.py" lang="python" title="Real-time Chat Application" />
-4. Run the server and client scripts as described in the code comments.
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import socket
-import threading
-import tkinter as tk
-```
-2. **Server setup.**
-```python
-def start_server():
-    # Accepts connections and relays messages
-    pass
-```
-3. **Client setup.**
-```python
-def start_client():
-    # Connects to server and sends/receives messages
-    pass
-```
-4. **GUI for chat.**
-```python
-root = tk.Tk()
-root.title('Real-time Chat Application')
-# ...setup widgets for chat display and input...
-root.mainloop()
-```
-
-## Features
-- Real-time text chat
-- Multiple users
-- Simple GUI
-- Demonstrates sockets and threading
-
-## How It Works
-- Server listens for connections
-- Clients connect and send messages
-- Messages are broadcast to all clients
-- GUI displays chat and allows input
-
-## GUI Components
-- **Text area:** Shows chat history
-- **Entry box:** For message input
-- **Send button:** Sends message
-
-## Use Cases
-- Learn networking basics
-- Build simple chat apps
-- Experiment with concurrency
-
-## Next Steps
-You can enhance this project by:
-- Adding user authentication
-- Supporting private messages
-- Improving GUI design
-- Adding emojis or file sharing
-- Implementing message history
-
-## Enhanced Version Ideas
-```python
-def add_authentication():
-    # Require login for chat
-    pass
-
-def save_chat_history():
-    # Store messages in a file
-    pass
-```
-
-## Troubleshooting Tips
-- **Connection errors:** Check IP and port
-- **GUI not showing:** Ensure Tkinter is installed
-- **Messages not sent:** Check server/client status
-
-## Conclusion
-This project teaches networking, threading, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/rest-api-server.mdx b/src/content/docs/projects/intermediate/rest-api-server.mdx
index ef477d4a..fbe2708c 100644
--- a/src/content/docs/projects/intermediate/rest-api-server.mdx
+++ b/src/content/docs/projects/intermediate/rest-api-server.mdx
@@ -1,6 +1,6 @@
 ---
 title: Flask REST API Server with Authentication
-description: Build a comprehensive REST API server with Flask featuring user authentication, database integration, and CRUD operations
+description: Build a production-shaped REST API in Python with Flask — API-key auth, SQLite-backed CRUD for tasks/products/users, pagination, filtering, request logging, usage stats, and JSON error handlers — then learn what to harden for production.
 sidebar: 
     order: 55
 hero:
@@ -13,191 +13,193 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Almost every app you'll build talks to an API — so learning to *build* one is a turning point. This project is a complete REST API in Flask: full CRUD for three resources (tasks, products, users), API-key authentication via a reusable decorator, pagination and filtering on list endpoints, automatic request logging, a usage-statistics endpoint, and consistent JSON error handlers. It's structured the way real APIs are, so the patterns transfer directly to FastAPI, Django REST Framework, or any framework you meet next.
 
-Create a comprehensive REST API server using Flask that provides user authentication, database integration, CRUD operations, and API key management. This project demonstrates backend development principles, HTTP methods, JSON handling, and secure API design patterns.
+You will leave understanding:
+- What makes an API **RESTful**: resources, HTTP verbs, and status codes.
+- How a **decorator** (`@require_api_key`) cleanly bolts auth onto any endpoint.
+- The CRUD-to-SQL mapping (GET→SELECT, POST→INSERT, PUT→UPDATE, DELETE→DELETE).
+- How pagination, filtering, logging, and error handling work in practice — and what to fix before production.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of HTTP protocols and REST principles
-- Familiarity with databases and SQL operations
-- Understanding of web development and API concepts
-- Basic knowledge of authentication and security practices
+- Python 3.7 or above.
+- A text editor or IDE.
+- `pip install flask flask-cors`.
+- Basic SQL and an understanding of HTTP methods/status codes.
+- A way to make requests: `curl`, Postman, or the `requests` library.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `flaskRESTAPI`.
-2. Create a new file and name it `flaskrestapi.py`.
-3. Install required dependencies: `pip install flask flask-cors`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `flaskrestapi.py` file.
+### Create the project
+1. Create a folder named `flask-rest-api`.
+2. Inside it, create `flaskrestapi.py`.
+3. Install dependencies: `pip install flask flask-cors`.
 
 ### Write the code
-1. Add the following code to your `flaskrestapi.py` file.
-<FileCode file="projects/intermediate/flaskrestapi.py" lang="python" title="Flask REST API Server with Authentication" />
-2. Save the file.
-3. Run the following command to start the API server.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\flaskRESTAPI> python flaskrestapi.py
- * Running on http://127.0.0.1:5000
- * Debug mode: on
-Flask REST API Server Started
-===============================
-Available Endpoints:
-POST /api/users/register - Register new user
-POST /api/users/login - User login
-GET /api/users - Get all users (requires auth)
-GET /api/data - Get data items
-POST /api/data - Create new data item
+<FileCode file="projects/intermediate/flaskrestapi.py" lang="python" title="flaskrestapi.py" />
+
+### Run it
+```cmd title="command"
+C:\Users\Your Name\flask-rest-api> python flaskrestapi.py
+# Docs:   http://localhost:5000/
+# Health: http://localhost:5000/health
+# Demo key: demo_key_123456789
+```
+Then exercise it:
+```bash title="terminal"
+# List tasks (authenticated)
+curl -H "X-API-Key: demo_key_123456789" http://localhost:5000/api/tasks
+
+# Create a task
+curl -X POST -H "X-API-Key: demo_key_123456789" -H "Content-Type: application/json" \
+     -d '{"title":"Write docs","priority":"high"}' http://localhost:5000/api/tasks
 ```
 
-## Explanation
-
-1. The `from flask import Flask, request, jsonify` imports the Flask framework for web development.
-2. The `flask_cors` enables Cross-Origin Resource Sharing for API accessibility.
-3. The `sqlite3` module provides database functionality for data persistence.
-4. The `DatabaseManager` class handles all database operations and table creation.
-5. User authentication uses password hashing and API key generation for security.
-6. CRUD operations (Create, Read, Update, Delete) manage data through HTTP methods.
-7. JSON responses ensure standardized data exchange between client and server.
-8. Error handling provides meaningful HTTP status codes and error messages.
-9. API key authentication secures endpoints and validates user permissions.
-10. Logging functionality tracks API usage and debugging information.
-11. Route decorators define URL endpoints and acceptable HTTP methods.
-12. Request validation ensures data integrity and prevents malformed requests.
-
-## Next Steps
-
-Congratulations! You have successfully created a Flask REST API Server in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add JWT token-based authentication
-- Implement rate limiting and API throttling
-- Create comprehensive API documentation with Swagger
-- Add data validation and serialization
-- Implement file upload and download endpoints
-- Create real-time features with WebSockets
-- Add caching mechanisms for improved performance
-- Implement API versioning strategies
-- Create automated testing suites for endpoints
+## REST in One Minute
 
-## Conclusion
+A REST API exposes **resources** (tasks, products) at URLs, and uses HTTP **verbs** to act on them:
 
-In this project, you learned how to create a Flask REST API Server in Python with authentication and database integration. You also learned about HTTP protocols, JSON handling, security practices, and building scalable backend services. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/flaskrestapi.py)
+| Verb | URL | Action | SQL | Success code |
+|---|---|---|---|---|
+| GET | `/api/tasks` | List | `SELECT` | 200 |
+| GET | `/api/tasks/<id>` | Read one | `SELECT … WHERE id` | 200 |
+| POST | `/api/tasks` | Create | `INSERT` | 201 |
+| PUT | `/api/tasks/<id>` | Update | `UPDATE` | 200 |
+| DELETE | `/api/tasks/<id>` | Delete | `DELETE` | 204 |
 
-## Code Explanation
+Learn this table and you've learned the shape of every CRUD API.
 
-### Flask Application Setup
-```python title="restapiserver.py" showLineNumbers{1}
-from flask import Flask, request, jsonify
-from flask_cors import CORS
+## Step-by-Step Explanation
 
+### 1. Setup and CORS
+```python title="flaskrestapi.py"
 app = Flask(__name__)
-CORS(app)  # Enable CORS for all routes
-app.config['SECRET_KEY'] = 'your-secret-key-here'
+CORS(app)   # let browser front-ends on other origins call this API
 ```
-
-Initializes the Flask application with CORS support and configuration settings.
-
-### Database Management
-```python title="restapiserver.py" showLineNumbers{1}
-class DatabaseManager:
-    def init_database(self):
-        with sqlite3.connect(self.db_path) as conn:
-            cursor = conn.cursor()
-            cursor.execute('''CREATE TABLE IF NOT EXISTS users...''')
-```
-
-Manages database connections, table creation, and data operations with SQLite integration.
-
-### User Authentication
-```python title="restapiserver.py" showLineNumbers{1}
-def hash_password(password):
-    salt = secrets.token_hex(16)
-    password_hash = hashlib.sha256((password + salt).encode()).hexdigest()
-    return f"{salt}:{password_hash}"
-
-def verify_password(password, stored_hash):
-    salt, hash_value = stored_hash.split(':')
-    return hashlib.sha256((password + salt).encode()).hexdigest() == hash_value
+`flask-cors` adds the headers a browser needs to call your API from a different origin (e.g. a React app on `localhost:3000`). Without it, the browser blocks the request.
+
+### 2. The database layer
+`DatabaseManager` creates five tables — `users`, `api_keys`, `tasks`, `products`, `api_logs` — and seeds sample data. Foreign keys link API keys and tasks to users. Note `conn.row_factory = sqlite3.Row`, which lets rows convert to dicts so they `jsonify` cleanly:
+```python title="flaskrestapi.py"
+def get_db_connection():
+    conn = sqlite3.connect(DATABASE)
+    conn.row_factory = sqlite3.Row     # rows behave like dicts -> dict(row)
+    return conn
 ```
 
-Implements secure password hashing and verification using salt and SHA-256.
-
-### API Key Authentication
-```python title="restapiserver.py" showLineNumbers{1}
+### 3. Authentication as a decorator
+This is the centerpiece. Instead of repeating auth in every endpoint, wrap it once:
+```python title="flaskrestapi.py"
 def require_api_key(f):
     @wraps(f)
     def decorated_function(*args, **kwargs):
-        api_key = request.headers.get('X-API-Key')
-        if not api_key or not db_manager.verify_api_key(api_key):
+        api_key = request.headers.get('X-API-Key') or request.args.get('api_key')
+        if not api_key:
+            return jsonify({'error': 'API key required'}), 401
+        # look the key up, join to its user, check both are active...
+        if not result:
             return jsonify({'error': 'Invalid API key'}), 401
+        request.current_user_id = result[1]      # stash user on the request
         return f(*args, **kwargs)
     return decorated_function
 ```
-
-Protects API endpoints with decorator-based authentication using API keys.
-
-### CRUD Operations
-```python title="restapiserver.py" showLineNumbers{1}
-@app.route('/api/data', methods=['GET'])
-def get_data():
-    data = db_manager.get_all_data()
-    return jsonify({'data': data, 'count': len(data)})
-
-@app.route('/api/data', methods=['POST'])
-@require_api_key
-def create_data():
-    data = request.get_json()
-    result = db_manager.create_data_item(data)
-    return jsonify(result), 201
+Slap `@require_api_key` on any route and it's protected. The decorator also records `last_used` and attaches the authenticated user to `request`, so handlers know who's calling. This is exactly how production APIs centralize auth.
+
+### 4. List endpoint with filtering + pagination
+```python title="flaskrestapi.py"
+query = "SELECT * FROM tasks WHERE 1=1"
+params = []
+if completed is not None:
+    query += " AND completed = ?"; params.append(completed)
+if priority:
+    query += " AND priority = ?"; params.append(priority)
+query += " ORDER BY created_at DESC LIMIT ? OFFSET ?"
+params.extend([per_page, (page - 1) * per_page])
 ```
+The `WHERE 1=1` trick lets you append `AND …` clauses conditionally without worrying about whether it's the first one. `LIMIT`/`OFFSET` implement pagination, and `per_page` is capped (`min(..., 100)`) so a client can't request a million rows. Every value goes through `?` placeholders — no SQL injection.
+
+### 5. Create with validation
+```python title="flaskrestapi.py"
+data = request.get_json()
+if not data or 'title' not in data:
+    return jsonify({'error': 'Title is required'}), 400
+if priority not in ['low', 'medium', 'high', 'critical']:
+    return jsonify({'error': 'Invalid priority...'}), 400
+# INSERT ... then return the created row with 201
+return jsonify(dict(task)), 201
+```
+Validate **before** touching the database, return `400` with a clear message on bad input, and `201 Created` (not 200) with the new resource on success. Returning the created object saves the client a follow-up GET.
+
+### 6. Partial update (PATCH-style PUT)
+```python title="flaskrestapi.py"
+for field in ['title', 'description', 'completed', 'priority', 'due_date']:
+    if field in data:
+        update_fields.append(f"{field} = ?")
+        params.append(data[field])
+query = f"UPDATE tasks SET {', '.join(update_fields)} WHERE id = ?"
+```
+Only the fields present in the request body get updated — send just `{"completed": true}` and nothing else changes. (The field *names* are hard-coded in code, not taken from input, so this dynamic SQL is safe.)
 
-Implements Create, Read, Update, Delete operations through HTTP methods and JSON responses.
-
-## Features
+### 7. Consistent error handling
+```python title="flaskrestapi.py"
+@app.errorhandler(404)
+def not_found(error):
+    return jsonify({'error': 'Resource not found'}), 404
+```
+Registering JSON error handlers means clients always get JSON — never an HTML error page that breaks their parser. An API that sometimes returns HTML is a debugging nightmare.
+
+## Before Production: What to Fix
+
+The code is a great teaching API but makes demo-grade choices:
+
+| Issue | Why it matters | Fix |
+|---|---|---|
+| `hashlib.sha256(password)` | Too fast → brute-forceable; no salt | Use `bcrypt`/`argon2` |
+| API keys stored in plaintext | DB leak exposes all keys | Store **hashes** of keys |
+| `debug=True, host='0.0.0.0'` | Debug RCE, exposed to network | `debug=False`; bind appropriately |
+| Hard-coded `SECRET_KEY` | Forgeable | Load from env var |
+| No rate limiting | Abuse / DoS | Add `flask-limiter` |
+| Logging stores the API key | Sensitive data in logs | Log a key *id*, not the key |
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `401` on every call | Missing/!active key, or wrong header | Send `X-API-Key`; use a seeded demo key |
+| `415 Unsupported Media Type` | No `Content-Type: application/json` | Set the header on POST/PUT |
+| `Object of type Row is not JSON serializable` | Forgot to `dict(row)` | Convert rows before `jsonify` |
+| Returns HTML on errors | No JSON error handlers | Register `@app.errorhandler` for 400/404/500 |
+| SQL injection risk | String-built queries with input | Use `?` placeholders (the code does) |
+| Browser front-end blocked | CORS not enabled | `CORS(app)` (the code does) |
+
+## Variations to Try
+
+1. **JWT auth** — swap API keys for token-based login with expiry.
+2. **OpenAPI/Swagger** — auto-generate interactive docs.
+3. **Rate limiting** — `flask-limiter` per key.
+4. **Soft deletes** — flag `is_active` instead of `DELETE`.
+5. **Search & sort** — `?q=` full-text and `?sort=` parameters.
+6. **Versioning** — `/api/v1/...` to evolve without breaking clients.
+7. **Tests** — pytest hitting each endpoint with the test client.
+8. **Port to FastAPI** — compare async + automatic docs.
+
+## Real-World Applications
+- **Backends for web/mobile apps** — the server half of any SPA.
+- **Microservices** — small, focused services behind a gateway.
+- **Public/partner APIs** — key-authenticated third-party access.
+- **Internal tooling** — data services for dashboards and automations.
 
-- **User Registration & Authentication**: Secure user account management with hashed passwords
-- **API Key Management**: Generate and validate API keys for endpoint access
-- **Database Integration**: SQLite database with automated table creation and management
-- **CRUD Operations**: Complete Create, Read, Update, Delete functionality
-- **JSON API Responses**: Standardized JSON responses with proper HTTP status codes
-- **Error Handling**: Comprehensive error management with meaningful error messages
-- **CORS Support**: Cross-Origin Resource Sharing for web application integration
-- **Request Validation**: Input validation and data sanitization for security
+## Educational Value
+- **REST design** — resources, verbs, status codes, idempotency.
+- **Decorators** — cross-cutting concerns (auth, logging) done right.
+- **Database-backed CRUD** — safe parameterized SQL end to end.
+- **API operability** — pagination, logging, stats, error contracts.
 
 ## Next Steps
+- Exercise every endpoint with `curl`/Postman.
+- Add **JWT auth** and **rate limiting**.
+- Generate **Swagger** docs and write **pytest** tests.
+- Harden the **production** issues above.
 
-### Enhancements
-- Add JWT token-based authentication
-- Implement rate limiting and API throttling
-- Create comprehensive API documentation with Swagger
-- Add data validation and serialization with Marshmallow
-- Implement file upload and download endpoints
-- Create real-time features with WebSockets
-- Add caching mechanisms for improved performance
-- Implement API versioning strategies
-
-### Learning Extensions
-- Study RESTful API design principles
-- Explore microservices architecture patterns
-- Learn about API security best practices
-- Practice with database optimization techniques
-- Understand containerization with Docker
-- Explore cloud deployment strategies
-
-## Educational Value
-
-This project teaches:
-- **Backend Development**: Building server-side applications with Flask framework
-- **REST API Design**: Understanding HTTP methods, status codes, and resource modeling
-- **Database Integration**: Working with SQLite and SQL operations
-- **Authentication & Security**: Implementing secure user authentication and API protection
-- **JSON Handling**: Processing and returning JSON data in web applications
-- **Error Handling**: Managing exceptions and providing meaningful error responses
-- **Web Protocols**: Understanding HTTP requests, responses, and headers
-- **API Documentation**: Creating clear documentation for API endpoints
-
-Perfect for understanding backend development, web API creation, and server-side programming with Python.
-````
+## Conclusion
+You built a real REST API — authenticated, paginated, filtered, logged, and consistently error-handled — and learned the resource/verb/status-code model that underlies every backend. The `@require_api_key` decorator and parameterized CRUD are patterns you'll reuse for the rest of your career; the production-hardening table is what separates a tutorial API from a shippable one. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/flaskrestapi.py). Explore more backend projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/simple-blog-with-flask.mdx b/src/content/docs/projects/intermediate/simple-blog-with-flask.mdx
index 9b3d22a5..be48c525 100644
--- a/src/content/docs/projects/intermediate/simple-blog-with-flask.mdx
+++ b/src/content/docs/projects/intermediate/simple-blog-with-flask.mdx
@@ -1,5 +1,6 @@
 ---
 title: Simple Blog with Flask
+description: Build a blog in Python with Flask — list posts, view individual posts, and add new ones via a form — then make it persistent with a SQLite database, add templates, edit/delete, and basic validation.
 sidebar:
   order: 93
 hero:
@@ -12,46 +13,85 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+A blog is the "to-do app" of web frameworks — small enough to finish, complete enough to teach everything. This Flask project does the full CRUD-lite loop: list posts, view a single post by ID, and submit new posts through an HTML form. You'll learn routing, dynamic URLs, form handling with GET vs. POST, and Jinja templating. Then you'll fix the elephant in the room — posts vanish on restart because they live in a list — by moving to a SQLite database, and round it out with edit, delete, and validation.
 
-Create a Simple Blog application using Flask. The app displays a list of blog posts, allows adding new posts, and viewing individual posts. This project demonstrates web development, routing, and template rendering in Python.
+You will leave understanding:
+- How Flask routes URLs to view functions, including dynamic `<int:post_id>`.
+- The GET-to-show-form, POST-to-submit pattern and why you redirect after POST.
+- How Jinja templates render data passed from views.
+- Why in-memory storage fails and how a database fixes it.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Flask for web development
-- Knowledge of HTML templates
+- Python 3.6 or above.
+- A text editor or IDE.
+- Flask: `pip install flask`.
+- Basic HTML.
+- Understanding of functions, lists, and dicts.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `simple_blog_with_flask`.
-2. Create a new file inside the folder and name it `simple_blog_with_flask.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `simple_blog_with_flask.py` file.
+
+### Create the project
+1. Create a folder named `flask-blog` with a `templates/` subfolder.
+2. Inside it, create `simple_blog_with_flask.py`.
+3. Install Flask: `pip install flask`.
+
+### Templates
+Flask renders HTML from the `templates/` folder:
+```html title="templates/index.html"
+<h1>Blog</h1>
+<a href="{{ url_for('new_post') }}">New Post</a>
+<ul>
+{% for post in posts %}
+  <li><a href="{{ url_for('view_post', post_id=post.id) }}">{{ post.title }}</a></li>
+{% endfor %}
+</ul>
+```
+```html title="templates/post.html"
+<h1>{{ post.title }}</h1>
+<p>{{ post.content }}</p>
+<a href="{{ url_for('index') }}">Back</a>
+```
+```html title="templates/new_post.html"
+<h1>New Post</h1>
+<form method="POST">
+  <input name="title" placeholder="Title" required><br>
+  <textarea name="content" placeholder="Write here..." required></textarea><br>
+  <button type="submit">Publish</button>
+</form>
+```
 
 ### Write the code
 <FileCode file="projects/intermediate/simple_blog_with_flask.py" lang="python" title="simple_blog_with_flask.py" showLineNumbers={1} />
 
-## Key Features
-- Display a list of blog posts
-- Add new blog posts
-- View individual blog posts
-- Web interface using Flask and HTML templates
-
-## Explanation
-
-### Displaying Blog Posts
-The app uses a list of dictionaries to store blog posts and renders them using Flask templates:
-```python title="simple_blog_with_flask.py" showLineNumbers={1}
-blog_posts = [
-    {"id": 1, "title": "First Post", "content": "This is the content of the first post."},
-    {"id": 2, "title": "Second Post", "content": "This is the content of the second post."},
-]
+### Run it
+```cmd title="command"
+C:\Users\Your Name\flask-blog> python simple_blog_with_flask.py
+# Open http://127.0.0.1:5000 — see posts, click one, or add a new one.
 ```
 
-### Adding New Posts
-Users can add new posts via a form. The new post is appended to the list and the user is redirected to the main page:
-```python title="simple_blog_with_flask.py" showLineNumbers={1}
+## Step-by-Step Explanation
+
+### 1. Listing posts
+```python title="simple_blog_with_flask.py"
+@app.route('/')
+def index():
+    return render_template('index.html', posts=blog_posts)
+```
+The home route passes the `blog_posts` list into `index.html`, where Jinja loops over it. Data flows from Python to HTML through `render_template` keyword arguments.
+
+### 2. Viewing one post (dynamic URL)
+```python title="simple_blog_with_flask.py"
+@app.route('/post/<int:post_id>')
+def view_post(post_id):
+    post = next((p for p in blog_posts if p['id'] == post_id), None)
+    if post:
+        return render_template('post.html', post=post)
+    return "Post not found", 404
+```
+`<int:post_id>` captures the number from `/post/2` and passes it in. The `next(...)` finds the matching post; if none, returning a string + `404` sends a proper Not Found status. Handling the missing case is what separates robust routes from fragile ones.
+
+### 3. Adding a post (GET vs POST)
+```python title="simple_blog_with_flask.py"
 @app.route('/new', methods=['GET', 'POST'])
 def new_post():
     if request.method == 'POST':
@@ -62,28 +102,94 @@ def new_post():
         return redirect(url_for('index'))
     return render_template('new_post.html')
 ```
+One route, two behaviors: a **GET** shows the empty form, a **POST** processes the submission. After saving, it **redirects** to the home page — the Post/Redirect/Get pattern that prevents a refresh from re-submitting the post. The `new_id` line generates the next ID.
 
-### Viewing Individual Posts
-Each post can be viewed by visiting its unique URL:
-```python title="simple_blog_with_flask.py" showLineNumbers={1}
-@app.route('/post/<int:post_id>')
-def view_post(post_id):
-    post = next((p for p in blog_posts if p['id'] == post_id), None)
-    if post:
-        return render_template('post.html', post=post)
-    return "Post not found", 404
-```
+## The Real Problem: Posts Don't Survive Restart
+
+`blog_posts` is a Python list in memory — restart the server and every post is gone. Move storage to SQLite:
+```python title="db.py"
+import sqlite3
+from flask import g
 
-## Running the Application
-1. Save the file.
-2. Install Flask:
-```bash
-pip install flask
+def get_db():
+    if "db" not in g:
+        g.db = sqlite3.connect("blog.db")
+        g.db.row_factory = sqlite3.Row     # rows behave like dicts
+    return g.db
+
+# one-time setup:
+# CREATE TABLE posts (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, content TEXT);
+
+def all_posts():
+    return get_db().execute("SELECT * FROM posts").fetchall()
+
+def add_post(title, content):
+    db = get_db()
+    db.execute("INSERT INTO posts (title, content) VALUES (?, ?)", (title, content))
+    db.commit()
 ```
-3. Run the application:
-```bash
-python simple_blog_with_flask.py
+`AUTOINCREMENT` replaces the manual `new_id`, and `?` placeholders keep you safe from SQL injection. Now posts persist.
+
+## Add Edit and Delete
+
+Complete the CRUD set:
+```python title="crud.py"
+@app.route('/edit/<int:post_id>', methods=['GET', 'POST'])
+def edit_post(post_id):
+    if request.method == 'POST':
+        get_db().execute("UPDATE posts SET title=?, content=? WHERE id=?",
+                         (request.form['title'], request.form['content'], post_id))
+        get_db().commit()
+        return redirect(url_for('view_post', post_id=post_id))
+    post = get_db().execute("SELECT * FROM posts WHERE id=?", (post_id,)).fetchone()
+    return render_template('edit_post.html', post=post)
+
+@app.route('/delete/<int:post_id>', methods=['POST'])
+def delete_post(post_id):
+    get_db().execute("DELETE FROM posts WHERE id=?", (post_id,))
+    get_db().commit()
+    return redirect(url_for('index'))
 ```
 
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Posts disappear on restart | Stored in a Python list | Persist to **SQLite** |
+| `TemplateNotFound` | HTML not in `templates/` | Use the `templates/` folder |
+| `400 Bad Request` on submit | `request.form['x']` missing key | Match form `name=` attributes; use `.get()` |
+| Refresh re-posts the entry | No redirect after POST | Redirect (PRG pattern) |
+| Crash on `/post/999` | Assumed the post exists | Handle `None` → return 404 |
+| HTML shows as raw tags | Auto-escaping confusion | Trust Jinja's escaping; don't disable it |
+
+## Variations to Try
+
+1. **SQLite persistence** — the essential upgrade above.
+2. **Edit & delete** — full CRUD.
+3. **Markdown posts** — render content with a Markdown library.
+4. **Comments** — a second table linked to posts.
+5. **Authentication** — login so only you can post (see [REST API with Authentication](./rest-api-auth)).
+6. **Pagination** — `LIMIT`/`OFFSET` for many posts.
+7. **Tags & search** — categorize and filter posts.
+8. **Base template** — extract a shared layout with Jinja `{% extends %}`.
+
+## Real-World Applications
+- **Blogs & CMSs** — WordPress and Ghost are this idea, scaled up.
+- **Documentation sites** — content lists + detail pages.
+- **Internal wikis** — team knowledge bases.
+- **Learning Flask** — the canonical first real web app.
+
+## Educational Value
+- **Routing** — static and dynamic URLs.
+- **Forms** — GET/POST, `request.form`, and the PRG pattern.
+- **Templating** — passing data to Jinja, loops, `url_for`.
+- **Persistence** — moving from memory to a real database.
+
+## Next Steps
+- Move posts into **SQLite** so they persist.
+- Add **edit** and **delete** routes.
+- Render content as **Markdown**; add **comments**.
+- Add **authentication** and **pagination**.
+
 ## Conclusion
-This Simple Blog with Flask project is a great way to learn about web development and routing in Python. You can extend it by adding user authentication, comments, or a database backend.
+You built a Flask blog that lists, displays, and creates posts — and learned routing, forms, templating, and the PRG pattern along the way. Fixing the memory-storage flaw with SQLite and adding edit/delete turns it into a genuine little CMS. This is the foundation every Flask developer builds on. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/simple_blog_with_flask.py). Explore more web projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/simple-weather-forecast-app.mdx b/src/content/docs/projects/intermediate/simple-weather-forecast-app.mdx
index f752692c..6a1e0448 100644
--- a/src/content/docs/projects/intermediate/simple-weather-forecast-app.mdx
+++ b/src/content/docs/projects/intermediate/simple-weather-forecast-app.mdx
@@ -1,5 +1,6 @@
 ---
 title: Simple Weather Forecast App
+description: Build a Tkinter weather app in Python using the OpenWeatherMap API — fetch current conditions for any city, then add a 5-day forecast, weather icons, unit toggles, geolocation, caching, and graceful error handling.
 sidebar:
   order: 100
 hero:
@@ -12,56 +13,168 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Consuming a real web API is a rite of passage, and weather is the perfect first API: free, well-documented, and instantly gratifying. In this tutorial you build a Tkinter app that queries the OpenWeatherMap API for a city's current conditions and displays temperature, "feels like", humidity, and a description. Then you grow it into something polished — a 5-day forecast, weather icons, °C/°F toggle, geolocation, response caching, and the kind of error handling that separates a demo from a tool.
 
-Build a Simple Weather Forecast App that fetches and displays weather forecast data from an API. The app provides a GUI for entering city names and viewing the forecast. This project demonstrates API integration and GUI development in Python.
+You will leave understanding:
+- How to register for and use an API key safely.
+- The request → JSON → parse → display pipeline behind every API client.
+- How to read nested JSON (`data["weather"][0]["description"]`) without crashing.
+- Why you check `status_code` and handle the unhappy paths first.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of API requests
+- Python 3.6 or above.
+- A text editor or IDE.
+- The `requests` library: `pip install requests`.
+- A **free** OpenWeatherMap API key from [openweathermap.org/api](https://openweathermap.org/api).
+- Tkinter (bundled with Python).
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `simple_weather_forecast_app`.
-2. Create a new file inside the folder and name it `simple_weather_forecast_app.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `simple_weather_forecast_app.py` file.
+
+### Get an API key
+1. Sign up at [openweathermap.org](https://openweathermap.org/api) (free tier is plenty).
+2. Copy your API key from the dashboard.
+3. New keys can take a few minutes to activate — don't panic if the first call 401s.
+
+### Create the project
+1. Create a folder named `weather-app`.
+2. Inside it, create `simple_weather_forecast_app.py`.
+3. Install the dependency: `pip install requests`.
 
 ### Write the code
 <FileCode file="projects/intermediate/simple_weather_forecast_app.py" lang="python" title="simple_weather_forecast_app.py" showLineNumbers={1} />
 
-## Key Features
-- Fetch weather data from an API
-- Display forecast in a user-friendly format
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\weather-app> python simple_weather_forecast_app.py
+# Enter a city name, click "Get Weather".
+# Make sure you replaced API_KEY with your real key first.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Fetching Weather Data
-Weather data is fetched from the OpenWeatherMap API:
-```python title="simple_weather_forecast_app.py" showLineNumbers={1}
+### 1. The endpoint and key
+```python title="simple_weather_forecast_app.py"
+API_KEY = "your_openweathermap_api_key"
+BASE_URL = "http://api.openweathermap.org/data/2.5/weather"
+```
+`BASE_URL` is the "current weather" endpoint. The key authenticates you and counts against your rate limit.
+
+### 2. Building the request
+```python title="simple_weather_forecast_app.py"
 params = {"q": city, "appid": API_KEY, "units": "metric"}
 response = requests.get(BASE_URL, params=params)
+data = response.json()
+```
+Passing a `params` dict lets `requests` build the query string for you (`?q=London&appid=...&units=metric`) and handles URL-encoding spaces and special characters. `units="metric"` gives Celsius; `"imperial"` gives Fahrenheit.
+
+### 3. Check status before parsing
+```python title="simple_weather_forecast_app.py"
+if response.status_code == 200:
+    weather = data["weather"][0]["description"].capitalize()
+    temp = data["main"]["temp"]
+    ...
+else:
+    messagebox.showerror("Error", data.get("message", "Failed to fetch weather data."))
 ```
+This is the most important habit in API work: **handle the failure path first**. A typo'd city returns `404` with a helpful `message` field — surface it instead of crashing on a missing key.
 
-### Displaying Results
-Weather information is shown in a Tkinter Label widget:
-```python title="simple_weather_forecast_app.py" showLineNumbers={1}
-self.result_label.config(text=f"Weather: {weather}\nTemperature: {temp}°C")
+### 4. Reading nested JSON
+```python title="simple_weather_forecast_app.py"
+data["weather"][0]["description"]   # list → first item → field
+data["main"]["temp"]                # nested dict
 ```
+OpenWeatherMap nests `weather` inside a *list* (a place can have several conditions) and groups numbers under `main`. Knowing the shape of the JSON is half the battle — print `data` once and study it.
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install requests
+## Protect Your API Key
+
+Never hard-code secrets. Use an environment variable:
+```python title="config.py"
+import os
+API_KEY = os.environ["OWM_API_KEY"]   # set OWM_API_KEY in your shell, not in code
 ```
-3. Run the application:
-```bash
-python simple_weather_forecast_app.py
+```cmd title="command"
+# PowerShell
+$env:OWM_API_KEY = "your_key_here"
 ```
+This keeps the key out of screenshots, git history, and shared code.
+
+## Add a 5-Day Forecast
+
+The forecast endpoint returns data in 3-hour steps:
+```python title="forecast.py"
+FORECAST_URL = "http://api.openweathermap.org/data/2.5/forecast"
+
+def five_day(city):
+    r = requests.get(FORECAST_URL,
+                     params={"q": city, "appid": API_KEY, "units": "metric"},
+                     timeout=10)
+    r.raise_for_status()
+    # Pick the midday (12:00) reading for each day
+    return [item for item in r.json()["list"] if "12:00:00" in item["dt_txt"]]
+```
+Loop the result into five labels or a small table.
+
+## Show Weather Icons
+
+Each condition carries an icon code:
+```python title="icons.py"
+from tkinter import PhotoImage
+import requests, io
+
+icon_code = data["weather"][0]["icon"]                       # e.g. "10d"
+url = f"http://openweathermap.org/img/wn/{icon_code}@2x.png"
+img_bytes = requests.get(url, timeout=10).content
+# Save then load, or use Pillow's ImageTk for in-memory display
+```
+
+## Add a °C / °F Toggle
+
+Store the raw value once, convert for display:
+```python title="units.py"
+def to_fahrenheit(celsius):
+    return celsius * 9 / 5 + 32
+
+label.config(text=f"{temp}°C" if self.metric else f"{to_fahrenheit(temp):.1f}°F")
+```
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `401 Unauthorized` | Key missing, wrong, or not yet active | Check the key; wait a few minutes after signup |
+| `KeyError: 'main'` | Parsed JSON before checking status | Guard with `if status_code == 200` first |
+| App freezes on slow network | No `timeout` | Add `timeout=10`; fetch on a background thread |
+| Spaces in city name break URL | Manual string concatenation | Use the `params=` dict — it encodes for you |
+| Wrong temperature scale | Forgot `units` | Set `units="metric"` or `"imperial"` |
+| Rate-limit errors | Polling too often | Cache responses for a few minutes |
+
+## Variations to Try
+
+1. **Geolocation** — detect the user's city via their IP and load it on launch.
+2. **Hourly chart** — plot the next 24 hours with `matplotlib`.
+3. **Favorites** — save a list of cities and refresh them all at once.
+4. **Severe-weather alerts** — use the One Call API's `alerts` field.
+5. **Background by condition** — change the window color for sunny/rainy/snow.
+6. **Caching layer** — store responses with a timestamp; skip the API within 10 minutes.
+7. **Voice output** — read the forecast aloud (see [Weather App with Voice Commands](./weather-app-with-voice-commands)).
+
+## Real-World Applications
+- **Travel apps** — destination weather at a glance.
+- **Agriculture & logistics** — planning around conditions.
+- **Dashboards** — a weather widget on a home-automation panel.
+- **Event planning** — outdoor-event go/no-go decisions.
+
+## Educational Value
+- **REST APIs** — keys, query parameters, JSON responses.
+- **Defensive parsing** — status checks and `.get()` with defaults.
+- **Secret management** — environment variables over hard-coding.
+- **Caching & rate limits** — being a good API citizen.
+
+## Next Steps
+- Move the key into an **environment variable**.
+- Add a **5-day forecast** and **weather icons**.
+- Implement a **°C/°F toggle** and **response caching**.
+- Detect the user's city with **geolocation**.
 
 ## Conclusion
-This Simple Weather Forecast App project is a great way to learn about API integration and GUI development in Python. You can extend it by adding more detailed forecasts, weather maps, or historical data.
+You built a weather app that turns a city name into live conditions, then layered on a forecast, icons, unit toggles, and caching — all on top of the same request → parse → display loop you'll reuse for every API you ever touch. The skill transfers directly: swap the endpoint and you have a stock ticker, a currency converter, or a news reader. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/simple_weather_forecast_app.py). Explore more API projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/simple_blog_with_flask.mdx b/src/content/docs/projects/intermediate/simple_blog_with_flask.mdx
deleted file mode 100644
index 6da4c44c..00000000
--- a/src/content/docs/projects/intermediate/simple_blog_with_flask.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: Simple Blog with Flask
-sidebar:
-    order: 6
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/simple_blog_with_flask.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Simple Blog with Flask is a Python web application that allows users to create, view, and manage blog posts. It demonstrates web development, routing, and template rendering with Flask. This project is ideal for learning about backend development, HTTP requests, and dynamic web pages.
-
-## Prerequisites
-- Python 3.6 or above
-- Flask (`pip install flask`)
-
-## Before you Start
-Install Python and Flask. Familiarize yourself with basic web concepts.
-
-## Getting Started
-1. Create a folder named `simple-blog`.
-2. Create a file named `simple_blog_with_flask.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/simple_blog_with_flask.py" lang="python" title="Simple Blog with Flask" />
-4. Run the script: `python simple_blog_with_flask.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-from flask import Flask, render_template, request, redirect
-```
-2. **Set up Flask app**
-```python
-app = Flask(__name__)
-```
-3. **Define routes**
-```python
-@app.route('/')
-def home():
-    # Show all posts
-    pass
-
-@app.route('/add', methods=['POST'])
-def add_post():
-    # Add new post
-    pass
-```
-4. **Run the app**
-```python
-if __name__ == '__main__':
-    app.run(debug=True)
-```
-
-## Features
-- Create and view blog posts
-- Simple web interface
-- Demonstrates Flask routing
-- Easy to extend for more features
-
-## How It Works
-- Handles HTTP requests
-- Renders templates for pages
-- Stores posts in memory or file
-
-## GUI Components
-- **Home page:** Lists posts
-- **Form:** For adding new posts
-- **Buttons:** For navigation
-
-## Use Cases
-- Personal blogging
-- Learning web development
-- Building portfolio sites
-
-## Next Steps
-You can enhance this project by:
-- Adding user authentication
-- Storing posts in a database
-- Supporting comments
-- Improving UI with CSS
-- Deploying online
-
-## Enhanced Version Ideas
-```python
-def add_database_support():
-    # Use SQLite or PostgreSQL
-    pass
-
-def add_user_login():
-    # Require login for posting
-    pass
-```
-
-## Troubleshooting Tips
-- **Flask errors:** Check installation
-- **App not running:** Check port and debug mode
-- **Posts not saving:** Check storage logic
-
-## Conclusion
-This project teaches Flask basics, routing, and web app structure. Extend it for more features and production use.
diff --git a/src/content/docs/projects/intermediate/simple_weather_forecast_app.mdx b/src/content/docs/projects/intermediate/simple_weather_forecast_app.mdx
deleted file mode 100644
index fe3c0e1e..00000000
--- a/src/content/docs/projects/intermediate/simple_weather_forecast_app.mdx
+++ /dev/null
@@ -1,97 +0,0 @@
----
-title: Simple Weather Forecast App
-sidebar:
-    order: 13
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/simple_weather_forecast_app.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Simple Weather Forecast App is a Python project that fetches and displays weather forecasts for a given city. It demonstrates API integration, data parsing, and GUI development. This project is ideal for learning about REST APIs, JSON handling, and interactive desktop apps.
-
-## Prerequisites
-- Python 3.6 or above
-- requests (`pip install requests`)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Install Python and requests. Obtain a free API key from a weather service (e.g., OpenWeatherMap).
-
-## Getting Started
-1. Create a folder named `weather-forecast-app`.
-2. Create a file named `simple_weather_forecast_app.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/simple_weather_forecast_app.py" lang="python" title="Simple Weather Forecast App" />
-4. Run the script: `python simple_weather_forecast_app.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import requests
-import tkinter as tk
-```
-2. **Fetch weather data**
-```python
-def get_forecast(city):
-    # Fetch weather data from API
-    pass
-```
-3. **GUI for forecast display**
-```python
-root = tk.Tk()
-root.title('Weather Forecast App')
-# ...setup widgets for city input and forecast display...
-root.mainloop()
-```
-
-## Features
-- Fetches weather forecast from API
-- GUI for display
-- Easy to extend for more features
-
-## How It Works
-- User enters city name
-- App fetches and displays forecast
-
-## GUI Components
-- **Label:** Shows forecast info
-- **Entry box:** For city input
-- **Button:** Fetches forecast
-
-## Use Cases
-- Daily weather updates
-- Learn API integration
-- Build custom weather dashboards
-
-## Next Steps
-You can enhance this project by:
-- Adding more weather details
-- Supporting multiple cities
-- Improving GUI design
-- Adding charts or graphs
-
-## Enhanced Version Ideas
-```python
-def add_graphs():
-    # Display weather trends
-    pass
-
-def support_multiple_cities():
-    # Show forecasts for several cities
-    pass
-```
-
-## Troubleshooting Tips
-- **API key errors:** Check your key
-- **No forecast displayed:** Check city name and internet connection
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches API usage, JSON parsing, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/social-media-analytics.mdx b/src/content/docs/projects/intermediate/social-media-analytics.mdx
index e2017905..225f1610 100644
--- a/src/content/docs/projects/intermediate/social-media-analytics.mdx
+++ b/src/content/docs/projects/intermediate/social-media-analytics.mdx
@@ -1,6 +1,6 @@
 ---
 title: Social Media Analytics Dashboard
-description: Build a comprehensive social media analytics platform with real-time data fetching, sentiment analysis, engagement tracking, hashtag performance analysis, and AI-powered recommendations
+description: Build a multi-platform social analytics tool in Python — pull posts from Twitter/Facebook/Instagram (with a mock-data fallback), run TextBlob sentiment analysis, track engagement and hashtags, generate word clouds, and serve a Plotly Flask dashboard.
 sidebar:
   order: 64
 hero:
@@ -13,276 +13,133 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This project turns the firehose of social media into insight. It pulls posts from **Twitter, Facebook, and Instagram**, scores each one's sentiment with NLP, computes engagement rates, ranks hashtags, builds word clouds, and presents everything in a Plotly dashboard. The cleverest design choice: if you don't have API keys (and you probably don't), it transparently **falls back to realistic mock data** — so the whole thing runs and teaches on day one, then upgrades to live data when you add credentials. That graceful-degradation pattern is worth the price of admission alone.
 
-Create a comprehensive social media analytics platform that aggregates data from Twitter, Facebook, and Instagram, performs sentiment analysis, tracks engagement patterns, analyzes hashtag performance, and provides AI-powered recommendations for social media strategy optimization. Features both a modern web dashboard and command-line interface.
+You will leave understanding:
+- How to wrap three different platform APIs behind one normalized schema.
+- The **real-or-mock fallback** pattern that makes a project runnable without secrets.
+- Sentiment analysis with TextBlob — polarity scores and labels.
+- Extracting hashtags/mentions with regex and ranking them by engagement.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Strong understanding of Python syntax and OOP concepts
-- Knowledge of web development with Flask
-- Familiarity with data analysis and visualization
-- Understanding of social media APIs and authentication
-- Basic knowledge of machine learning and sentiment analysis
-- Experience with SQL databases and pandas
+- Python 3.7 or above.
+- A text editor or IDE.
+- `pip install flask textblob pandas plotly wordcloud matplotlib` (live mode also needs `tweepy`, `facebook-sdk`, `instaloader`).
+- `python -m textblob.download_corpora` for sentiment data.
+- API keys are **optional** — without them the app uses mock data.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `socialMediaAnalytics`.
-2. Create a new file and name it `socialmediaanalytics.py`.
-3. Install required dependencies: `pip install flask pandas matplotlib seaborn plotly tweepy facebook-sdk instaloader textblob wordcloud`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `socialmediaanalytics.py` file.
+### Create the project
+1. Create a folder named `social-analytics`.
+2. Inside it, create `socialmediaanalytics.py`.
+3. Install dependencies; download the TextBlob corpora.
 
 ### Write the code
-1. Add the following code to your `socialmediaanalytics.py` file.
-<FileCode file="projects/intermediate/socialmediaanalytics.py" lang="python" title="Social Media Analytics Dashboard" />
-2. Save the file.
-3. Run the following command to start the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\socialMediaAnalytics> python socialmediaanalytics.py
-📱 Social Media Analytics Dashboard
-==================================================
-
-Choose interface:
-1. Web Dashboard (Recommended)
-2. Command Line Interface
-3. Generate Sample Data & Run Dashboard
-Enter choice (1-3): 3
+<FileCode file="projects/intermediate/socialmediaanalytics.py" lang="python" title="socialmediaanalytics.py" />
 
-📊 Generating sample data...
-✅ Sample data generated and saved to database
-🚀 Starting web dashboard...
-📊 Access the dashboard at: http://localhost:5000
-🔗 Features available:
-   - Real-time social media data fetching
-   - Engagement and sentiment analytics
-   - Hashtag performance analysis
-   - AI-powered recommendations
-   - Comprehensive reporting
+### Run it
+```cmd title="command"
+C:\Users\Your Name\social-analytics> python socialmediaanalytics.py
+# No API keys? It runs on mock data automatically.
+# Add keys in the config dicts to switch to live data.
 ```
 
-## Explanation
-
-1. The `SocialMediaAnalyticsAPI` class manages social media data collection and analysis.
-2. The `init_database()` method creates comprehensive tables for posts, analytics, hashtags, competitors, and campaigns.
-3. API integration supports Twitter, Facebook, and Instagram with proper authentication handling.
-4. Sentiment analysis uses TextBlob to analyze post content and classify emotions.
-5. Engagement pattern analysis tracks likes, shares, comments, and reach across platforms.
-6. Hashtag performance analysis identifies trending tags and their effectiveness.
-7. The `SocialMediaDashboard` class provides a Flask web interface with interactive charts.
-8. AI-powered recommendations engine suggests content strategies based on performance data.
-9. Real-time data fetching allows continuous monitoring and updates.
-10. Comprehensive reporting generates detailed analytics with export functionality.
-11. The system supports both web dashboard and command-line interfaces.
-12. Advanced features include competitor analysis, campaign tracking, and content insights.
-
-## Next Steps
-
-Congratulations! You have successfully created a Social Media Analytics Dashboard in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add LinkedIn and TikTok API integration for complete coverage
-- Implement machine learning models for engagement prediction
-- Create automated posting and scheduling features
-- Add real-time monitoring with alert notifications
-- Implement advanced NLP for topic modeling and trend detection
-- Create collaborative features for social media teams
-- Add A/B testing capabilities for content optimization
-- Implement brand mention tracking and crisis management
+## Step-by-Step Explanation
 
-## Conclusion
-
-In this project, you learned how to create a Social Media Analytics Dashboard in Python. You also learned about API integration, data analysis, sentiment analysis, web dashboard development, and building comprehensive social media monitoring systems. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/socialmediaanalytics.py)
-
-## Code Explanation
-
-### Database Schema Design
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-def init_database(self):
-    cursor.execute('''
-        CREATE TABLE IF NOT EXISTS posts (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            platform TEXT NOT NULL,
-            post_id TEXT UNIQUE NOT NULL,
-            content TEXT,
-            author TEXT,
-            timestamp DATETIME,
-            likes INTEGER DEFAULT 0,
-            shares INTEGER DEFAULT 0,
-            comments INTEGER DEFAULT 0,
-            engagement_rate REAL DEFAULT 0,
-            sentiment_score REAL DEFAULT 0,
-            sentiment_label TEXT,
-            hashtags TEXT,
-            mentions TEXT
-        )
-    ''')
-```
+### 1. One schema for three platforms
+Twitter, Facebook, and Instagram return wildly different JSON, but the `posts` table normalizes them all to the same columns — `platform`, `content`, `likes`, `shares`, `comments`, `sentiment_score`, `hashtags`, … Normalizing to a common shape on ingest is what lets you compare platforms later. Extra tables (`analytics`, `hashtags`, `competitors`, `campaigns`) round out the warehouse.
 
-Creates comprehensive database schema for multi-platform social media data with engagement metrics.
-
-### Social Media API Integration
-```python title="socialmediaanalytics.py" showLineNumbers{1}
+### 2. The real-or-mock fallback (the key pattern)
+```python title="socialmediaanalytics.py"
 def fetch_twitter_data(self, username, count=100):
-    tweets = tweepy.Cursor(
-        self.twitter_api.user_timeline,
-        screen_name=username,
-        include_rts=False,
-        tweet_mode='extended'
-    ).items(count)
-    
-    for tweet in tweets:
-        sentiment = TextBlob(tweet.full_text).sentiment
-        hashtags = [tag['text'] for tag in tweet.entities['hashtags']]
-        
-        post_data = {
-            'platform': 'twitter',
-            'content': tweet.full_text,
-            'likes': tweet.favorite_count,
-            'shares': tweet.retweet_count,
-            'sentiment_score': sentiment.polarity,
-            'hashtags': json.dumps(hashtags)
-        }
+    if not self.twitter_api:
+        return self.generate_mock_twitter_data(username, count)   # no keys → mock
+    try:
+        tweets = tweepy.Cursor(self.twitter_api.user_timeline, ...).items(count)
+        ...
+    except Exception as e:
+        print(f"Twitter API error: {e}")
+        return self.generate_mock_twitter_data(username, count)    # error → mock
 ```
-
-Integrates with Twitter API for real-time data collection with automatic sentiment analysis.
-
-### Sentiment Analysis Engine
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-def analyze_sentiment_trends(self, platform=None, days=30):
-    query = '''
-        SELECT 
-            platform,
-            DATE(timestamp) as date,
-            sentiment_label,
-            COUNT(*) as count,
-            AVG(sentiment_score) as avg_sentiment
-        FROM posts 
-        WHERE timestamp >= date('now', '-{} days')
-        GROUP BY platform, DATE(timestamp), sentiment_label
-    '''.format(days)
-    
-    df = pd.read_sql_query(query, conn)
-    return df
+Two safety nets: no credentials *or* an API failure both fall back to generated data. The app is **never** broken by a missing key or a rate limit. This is how you ship a demo that anyone can run while keeping a real integration one config edit away.
+
+### 3. Sentiment analysis with TextBlob
+```python title="socialmediaanalytics.py"
+sentiment = TextBlob(content).sentiment           # .polarity in [-1, 1]
+sentiment_label = ('positive' if sentiment.polarity > 0.1
+                   else 'negative' if sentiment.polarity < -0.1
+                   else 'neutral')
 ```
+`TextBlob` gives a **polarity** from -1 (negative) to +1 (positive). The ±0.1 dead zone around zero is deliberate — text near neutral shouldn't be forced into positive/negative. One line of NLP turns raw captions into a measurable mood signal.
 
-Analyzes sentiment trends over time with platform-specific insights and scoring.
-
-### Engagement Pattern Analysis
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-def analyze_engagement_patterns(self, platform=None, days=30):
-    query = '''
-        SELECT 
-            platform,
-            DATE(timestamp) as date,
-            AVG(engagement_rate) as avg_engagement,
-            SUM(likes) as total_likes,
-            SUM(shares) as total_shares,
-            SUM(comments) as total_comments,
-            COUNT(*) as post_count
-        FROM posts 
-        WHERE timestamp >= date('now', '-{} days')
-        GROUP BY platform, DATE(timestamp)
-    '''.format(days)
+### 4. Extracting hashtags and mentions
+```python title="socialmediaanalytics.py"
+hashtags = re.findall(r'#\w+', message)           # every #tag
 ```
+For platforms that don't hand you structured entities, a regex over the text pulls hashtags (`#\w+`). Twitter's API provides them structured (`tweet.entities['hashtags']`), so the code uses whichever is available — another normalization step.
 
-Tracks engagement patterns across platforms with comprehensive metrics and trends.
-
-### Hashtag Performance Analytics
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-def analyze_hashtag_performance(self, platform=None, limit=20):
-    for hashtags_json, engagement, likes, shares, comments in results:
-        hashtags = json.loads(hashtags_json)
-        for hashtag in hashtags:
-            hashtag_stats[hashtag]['usage_count'] += 1
-            hashtag_stats[hashtag]['total_engagement'] += engagement
-            hashtag_stats[hashtag]['avg_engagement'] = stats['total_engagement'] / stats['usage_count']
-    
-    sorted_hashtags = sorted(hashtag_stats.items(), 
-                           key=lambda x: (x[1]['avg_engagement'], x[1]['usage_count']), 
-                           reverse=True)
+### 5. Storing as JSON in a column
+```python title="socialmediaanalytics.py"
+'hashtags': json.dumps(hashtags),
+'mentions': json.dumps(mentions)
 ```
+Lists don't fit in a SQL cell, so they're serialized to JSON strings. Pragmatic for a small app (deserialize with `json.loads` on read); at scale you'd use a separate hashtags table with a join.
 
-Analyzes hashtag effectiveness with usage frequency and engagement correlation.
+### 6. Engagement, word clouds, and the dashboard
+Engagement rate combines likes/shares/comments against reach. A `WordCloud` visualizes dominant terms. The Flask app exposes each analysis as a JSON endpoint and renders interactive Plotly charts client-side — Python computes, the browser draws.
 
-### AI Recommendations Engine
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-def generate_recommendations(self):
-    recommendations = {
-        'content_strategy': [],
-        'posting_schedule': [],
-        'hashtag_strategy': [],
-        'engagement_tactics': []
-    }
-    
-    if insights.get('avg_engagement_by_sentiment'):
-        best_sentiment = max(insights['avg_engagement_by_sentiment'].items(), key=lambda x: x[1])
-        recommendations['content_strategy'].append(
-            f"Focus on {best_sentiment[0]} content - it has {best_sentiment[1]:.1f}% higher engagement"
-        )
-```
+## A Note on Live-API Reality
 
-Generates AI-powered recommendations based on performance data analysis and trends.
+The mock mode is honest about something tutorials gloss over: **these APIs are hard to use for real now.**
 
-### Interactive Web Dashboard
-```python title="socialmediaanalytics.py" showLineNumbers{1}
-@self.app.route('/api/engagement-chart')
-def api_engagement_chart():
-    df = self.analytics_api.analyze_engagement_patterns(days=30)
-    
-    fig = px.line(df, x='date', y='avg_engagement', color='platform',
-                 title='Engagement Rate Over Time')
-    
-    graphJSON = json.dumps(fig, cls=PlotlyJSONEncoder)
-    return graphJSON
-```
+| Platform | Reality in 2024+ |
+|---|---|
+| Twitter/X | `user_timeline` is largely paywalled; `tweepy` v4 uses a different client (`tweepy.Client`) |
+| Instagram | `instaloader` scraping risks rate-limits/bans; no official read API for this |
+| Facebook | Requires app review and page tokens with specific permissions |
 
-Creates interactive web dashboard with real-time charts using Plotly and Flask.
+The mock fallback isn't just a convenience — it's what keeps this project *teachable* despite platform lockdown. Treat live integration as an advanced, optional extension.
 
-## Features
+## Common Mistakes
 
-- **Multi-Platform Integration**: Support for Twitter, Facebook, and Instagram APIs
-- **Real-Time Data Fetching**: Continuous monitoring and data collection
-- **Sentiment Analysis**: Advanced emotion detection using natural language processing
-- **Engagement Tracking**: Comprehensive metrics including likes, shares, comments, and reach
-- **Hashtag Analytics**: Performance analysis and trending hashtag identification
-- **Interactive Dashboard**: Modern web interface with real-time charts and visualizations
-- **AI Recommendations**: Machine learning-powered strategy suggestions
-- **Competitor Analysis**: Track and compare competitor performance
-- **Campaign Tracking**: Monitor social media campaign effectiveness
-- **Comprehensive Reporting**: Detailed analytics with export functionality
+| Problem | Cause | Fix |
+|---|---|---|
+| `Missing corpora` from TextBlob | NLTK data not downloaded | `python -m textblob.download_corpora` |
+| Live Twitter calls 401/403 | v1.1 endpoints deprecated/paywalled | Use `tweepy.Client` (v2) or stay on mock |
+| Instagram login fails/bans | Scraping against ToS + rate limits | Prefer mock; don't automate logins |
+| All sentiment looks "neutral" | Short/emoji-only text | Expected; TextBlob is lexical, not deep |
+| `UNIQUE constraint` on post_id | Re-ingesting same posts | `INSERT OR IGNORE`, or upsert |
+| Word cloud import error | `wordcloud` needs build tools | Install a prebuilt wheel |
 
-## Next Steps
+## Variations to Try
 
-### Enhancements
-- Add LinkedIn and TikTok API integration for complete coverage
-- Implement machine learning models for engagement prediction
-- Create automated posting and scheduling features
-- Add real-time monitoring with alert notifications
-- Implement advanced NLP for topic modeling and trend detection
-- Create collaborative features for social media teams
-- Add A/B testing capabilities for content optimization
-- Implement brand mention tracking and crisis management
+1. **Run on mock first** — explore every feature with zero keys.
+2. **Upgrade to `tweepy.Client`** — the supported v2 Twitter API.
+3. **Better sentiment** — swap TextBlob for VADER (great on social text) or a transformer.
+4. **Emoji sentiment** — emojis carry mood TextBlob ignores.
+5. **Competitor tracking** — the `competitors` table is ready to use.
+6. **Posting-time analysis** — find when engagement peaks.
+7. **Scheduled collection** — the `schedule` import enables periodic pulls.
+8. **Export reports** — weekly PDF summaries per platform.
 
-### Learning Extensions
-- Study advanced natural language processing techniques
-- Explore machine learning for social media prediction
-- Learn about real-time data streaming and processing
-- Practice with advanced data visualization libraries
-- Understand social media marketing strategies and best practices
-- Explore cloud deployment for scalable analytics platforms
+## Real-World Applications
+- **Social media management** — Hootsuite/Buffer-style analytics.
+- **Brand monitoring** — sentiment and mention tracking.
+- **Influencer analysis** — engagement-rate vetting.
+- **Campaign measurement** — reach, conversions, ROI.
 
 ## Educational Value
+- **API integration** — multiple providers behind one interface.
+- **Resilient design** — the real-or-mock fallback pattern.
+- **NLP basics** — sentiment polarity and text feature extraction.
+- **Data viz** — word clouds and interactive Plotly dashboards.
 
-This project teaches:
-- **API Integration**: Working with multiple social media APIs and authentication
-- **Data Analysis**: Advanced analytics with pandas and statistical analysis
-- **Sentiment Analysis**: Natural language processing and emotion detection
-- **Web Development**: Creating interactive dashboards with Flask and Plotly
-- **Database Design**: Designing schemas for complex social media data
-- **Machine Learning**: Implementing recommendation systems and predictive analytics
-- **Data Visualization**: Creating compelling charts and interactive dashboards
-- **Social Media Strategy**: Understanding engagement metrics and optimization techniques
+## Next Steps
+- Explore everything in **mock mode**, then add one real API.
+- Replace TextBlob with **VADER** for social-tuned sentiment.
+- Enable **scheduled collection** and **competitor tracking**.
+- Add **best-time-to-post** analysis and **report export**.
 
-Perfect for understanding social media analytics, API integration, and building production-ready analytics platforms for digital marketing and social media management.
+## Conclusion
+You built a multi-platform social analytics tool that ingests posts, scores sentiment, ranks hashtags, and visualizes it all — and, crucially, runs with or without API keys thanks to a clean real-or-mock fallback. That resilience pattern, plus normalizing three messy APIs into one schema, is exactly how production integrations are built to survive missing credentials and flaky upstreams. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/socialmediaanalytics.py). Explore more data and NLP projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/url-expander.mdx b/src/content/docs/projects/intermediate/url-expander.mdx
index 77edd4a5..1719d841 100644
--- a/src/content/docs/projects/intermediate/url-expander.mdx
+++ b/src/content/docs/projects/intermediate/url-expander.mdx
@@ -1,5 +1,6 @@
 ---
 title: URL Expander
+description: Build a Tkinter URL expander in Python that follows HTTP redirects to reveal where a shortened link really points — then add a full redirect chain, safety checks, timeouts, batch processing, and clipboard integration.
 sidebar:
   order: 105
 hero:
@@ -12,56 +13,167 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Shortened links (`bit.ly`, `t.co`, `tinyurl`) hide their real destination — convenient for sharing, risky for clicking. A URL expander follows the chain of HTTP redirects and shows you where a short link *actually* lands before you visit it. In this tutorial you build a small Tkinter app around a single `requests` call, then turn it into a genuinely useful safety tool: it reveals the **full** redirect chain, flags suspicious hops, handles timeouts, expands links in bulk, and copies results to the clipboard.
 
-Build a URL Expander application that expands shortened URLs to their original form. The app provides a GUI for entering URLs and displaying the expanded result. This project demonstrates HTTP requests, URL handling, and GUI development in Python.
+You will leave understanding:
+- How HTTP redirects (301/302) work and how `requests` follows them.
+- The difference between a `HEAD` and a `GET` request, and why `HEAD` is cheaper here.
+- How to handle network errors without crashing the UI.
+- Why expanding a link is a security practice, not just a convenience.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of HTTP requests
+- Python 3.6 or above.
+- A text editor or IDE.
+- The `requests` library: `pip install requests`.
+- Tkinter (bundled with Python).
+- A basic grasp of HTTP requests and responses.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `url_expander`.
-2. Create a new file inside the folder and name it `url_expander.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `url_expander.py` file.
+
+### Create the project
+1. Create a folder named `url-expander`.
+2. Inside it, create `url_expander.py`.
+3. Install the dependency: `pip install requests`.
 
 ### Write the code
 <FileCode file="projects/intermediate/url_expander.py" lang="python" title="url_expander.py" showLineNumbers={1} />
 
-## Key Features
-- Accept shortened URLs as input
-- Display expanded URLs
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\url-expander> python url_expander.py
+# Paste a short URL (e.g. https://bit.ly/xyz) and click "Expand URL".
+# A dialog shows the final destination.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Expanding URLs
-The app uses the `requests` library to follow redirects and expand URLs:
-```python title="url_expander.py" showLineNumbers={1}
-response = requests.head(short_url, allow_redirects=True)
-return response.url
+### 1. The core: follow the redirects
+```python title="url_expander.py"
+def expand_url(short_url):
+    try:
+        response = requests.head(short_url, allow_redirects=True)
+        return response.url
+    except requests.RequestException as e:
+        return str(e)
 ```
+Two ideas do all the work:
+- **`requests.head`** asks only for the response *headers*, not the page body. Since we only care about the final URL, downloading the whole page would be wasteful.
+- **`allow_redirects=True`** tells `requests` to chase every `Location` header automatically. After the last hop, `response.url` holds the real destination.
 
-### Displaying Results
-Expanded URLs are shown in a Tkinter message box:
-```python title="url_expander.py" showLineNumbers={1}
+Catching `requests.RequestException` (the base class for all `requests` errors) means a dead link or DNS failure returns a message instead of crashing.
+
+### 2. Input guard
+```python title="url_expander.py"
+short_url = self.url_entry.get()
+if not short_url:
+    messagebox.showerror("Error", "Please enter a URL.")
+    return
+```
+Never trust an empty field. Bail early with a clear message.
+
+### 3. Show the result
+```python title="url_expander.py"
+expanded_url = expand_url(short_url)
 messagebox.showinfo("Expanded URL", f"Original URL: {expanded_url}")
 ```
+A popup is fine for one URL. For more, you'll want a results panel (below).
+
+## Upgrade: Show the Full Redirect Chain
+
+A single destination hides intermediate hops — and those hops are where shady redirectors live. `response.history` records every step:
+```python title="chain.py"
+import requests
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install requests
+def redirect_chain(short_url, timeout=10):
+    r = requests.get(short_url, allow_redirects=True, timeout=timeout)
+    hops = [resp.url for resp in r.history] + [r.url]
+    return hops
+
+for i, url in enumerate(redirect_chain("https://bit.ly/example")):
+    print(f"{i}: {url}")
 ```
-3. Run the application:
-```bash
-python url_expander.py
+Seeing `bit.ly → tracking.example → final.com` tells you far more than `final.com` alone.
+
+## Add a Timeout (Always)
+
+A request with no timeout can hang forever, freezing your app:
+```python title="timeout.py"
+requests.head(short_url, allow_redirects=True, timeout=10)
 ```
+**Rule of thumb:** every network call in production code gets a `timeout`. Catch `requests.Timeout` separately to tell the user "the server is slow" rather than "the URL is broken".
+
+## Flag Suspicious Links
+
+A lightweight safety check before the user clicks:
+```python title="safety.py"
+from urllib.parse import urlparse
+
+SUSPICIOUS_TLDS = {".zip", ".mov", ".tk", ".xyz"}
+
+def looks_risky(url):
+    host = urlparse(url).netloc.lower()
+    flags = []
+    if any(url.lower().endswith(t) for t in SUSPICIOUS_TLDS):
+        flags.append("unusual TLD")
+    if url.count("//") > 1:
+        flags.append("nested redirect")
+    if "@" in url:
+        flags.append("credentials in URL")
+    return flags
+```
+This is heuristic, not a malware scanner — but "credentials in URL" and "nested redirect" catch a surprising number of phishing tricks.
+
+## Batch Mode
+
+Expand a whole list at once and show results in a `Text` widget instead of popups:
+```python title="batch.py"
+def expand_many(self):
+    urls = self.input_text.get("1.0", "end").splitlines()
+    self.output_text.delete("1.0", "end")
+    for url in filter(str.strip, urls):
+        final = expand_url(url.strip())
+        self.output_text.insert("end", f"{url.strip()}  ->  {final}\n")
+```
+Now you can paste 50 links and audit them in one click.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| App hangs on a bad link | No `timeout` set | Pass `timeout=10` to every request |
+| Some shorteners don't expand | They block `HEAD` requests | Fall back to `requests.get` |
+| Only the final URL shown | Ignored `response.history` | Build the chain from `history + [r.url]` |
+| `SSLError` on valid sites | Outdated certificates | Update `certifi`; never disable verification in production |
+| UI freezes during batch | Network calls on the main thread | Run expansion in a background thread |
+| Crash on malformed input | No URL validation | Check scheme with `urlparse` before requesting |
+
+## Variations to Try
+
+1. **Clipboard integration** — auto-read the clipboard and expand on launch.
+2. **Browser extension companion** — expose the logic as a small Flask API.
+3. **QR support** — decode a QR image to a short URL, then expand it.
+4. **History log** — save every expansion to a JSON file with a timestamp.
+5. **Threaded UI** — keep the window responsive during slow lookups.
+6. **Reputation lookup** — query a URL-reputation API and show a verdict.
+7. **CLI mode** — accept a URL as a command-line argument for scripting.
+
+## Real-World Applications
+- **Security & anti-phishing** — verify links before clicking in email or chat.
+- **Social media tooling** — audit campaign links and tracking parameters.
+- **Link analytics** — uncover the tracking domains a redirect passes through.
+- **Content moderation** — inspect user-submitted short links at scale.
+
+## Educational Value
+- **HTTP fundamentals** — redirects, status codes, `HEAD` vs. `GET`.
+- **Robust networking** — timeouts, exception hierarchies, retries.
+- **Security thinking** — why obscured destinations are a risk.
+- **Responsive GUIs** — moving slow work off the main thread.
+
+## Next Steps
+- Print the **full redirect chain** instead of just the destination.
+- Add a **timeout** and `HEAD`→`GET` fallback.
+- Implement the **suspicious-link** heuristics.
+- Build **batch mode** with a results panel and a saved history log.
 
 ## Conclusion
-This URL Expander project is a great way to learn about HTTP requests and URL handling in Python. You can extend it by adding batch expansion, URL validation, or analytics features.
+You built a URL expander from a single `requests.head` call and grew it into a redirect auditor that reveals every hop, flags risky links, survives slow servers, and processes links in bulk. Underneath a tiny UI sits a genuinely useful security habit: know where a link goes before you go there. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/url_expander.py). Find more networking projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/url-shortener-analytics.mdx b/src/content/docs/projects/intermediate/url-shortener-analytics.mdx
index cfd78503..36e47dea 100644
--- a/src/content/docs/projects/intermediate/url-shortener-analytics.mdx
+++ b/src/content/docs/projects/intermediate/url-shortener-analytics.mdx
@@ -1,6 +1,6 @@
 ---
 title: URL Shortener with Analytics
-description: Build a comprehensive URL shortening service with click tracking, analytics dashboard, QR code generation, and web interface
+description: Build a Bitly-style URL shortener in Python with Flask and SQLite — short codes, custom aliases, QR codes, expiry, and a full click-analytics dashboard (devices, browsers, referrers, daily charts) — plus a REST API and CLI.
 sidebar:
   order: 62
 hero:
@@ -13,238 +13,159 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+This is Bitly in miniature — and it's a brilliant teaching project because a "simple" URL shortener quietly touches code generation, redirects, a database, QR codes, request inspection, data aggregation, and charting. You'll build a service that turns long URLs into short codes (or custom aliases), redirects visitors while **logging every click**, and renders an analytics dashboard with device/browser/referrer breakdowns and a daily-clicks chart. It ships three interfaces over one engine: a web UI, a REST API, and a CLI.
 
-Create a comprehensive URL shortening service with advanced analytics capabilities including click tracking, device/browser statistics, QR code generation, and a web dashboard. This project demonstrates database design, web development, data visualization, and analytics implementation.
+You will leave understanding:
+- How short codes are generated, kept unique, and resolved back to the original URL.
+- The redirect-and-track pattern that powers all link analytics.
+- How to mine the HTTP request (user-agent, referrer, IP) for analytics.
+- How `GROUP BY` turns a raw click log into dashboards and charts.
 
 ## Prerequisites
-
-- Python 3.7 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of web development concepts (HTML, HTTP)
-- Familiarity with databases and SQL operations
-- Understanding of data visualization principles
-- Basic knowledge of Flask web framework
+- Python 3.7 or above.
+- A text editor or IDE.
+- `pip install flask qrcode pillow matplotlib`.
+- SQL basics (`INSERT`, `SELECT`, `GROUP BY`) and Flask routing.
+- Familiarity with the [QR Code Attendance System](./qr-code-attendance-system) helps for the QR part.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `urlShortenerAnalytics`.
-2. Create a new file and name it `urlshorteneranalytics.py`.
-3. Install required dependencies: `pip install flask matplotlib qrcode pillow`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `urlshorteneranalytics.py` file.
+### Create the project
+1. Create a folder named `url-shortener`.
+2. Inside it, create `urlshorteneranalytics.py`.
+3. Install dependencies: `pip install flask qrcode pillow matplotlib`.
 
 ### Write the code
-1. Add the following code to your `urlshorteneranalytics.py` file.
-<FileCode file="projects/intermediate/urlshorteneranalytics.py" lang="python" title="URL Shortener with Analytics" />
-2. Save the file.
-3. Run the following command to start the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\urlShortenerAnalytics> python urlshorteneranalytics.py
-🔗 URL Shortener with Analytics
-========================================
-
-📋 Menu:
-1. Create Short URL
-2. View Analytics
-3. List All URLs
-4. Start Web Server
-5. Delete URL
-6. Exit
-
-Enter your choice (1-6): 1
-Enter the URL to shorten: https://github.com/user/repo
-Custom alias (optional): my-repo
-Title (optional): My GitHub Repository
-Description (optional): My awesome Python project
-
-✅ Short URL created!
-Short URL: http://localhost:5000/my-repo
-QR Code generated: Yes
-
-Enter your choice (1-6): 4
-🌐 Starting web server...
-Access the web interface at: http://localhost:5000
-```
-
-## Explanation
-
-1. The `sqlite3` module provides database functionality for storing URLs and analytics data.
-2. The `URLShortenerAnalytics` class manages the core functionality and database operations.
-3. The `init_database()` method creates tables for URLs and click tracking analytics.
-4. The `generate_short_code()` function creates unique random codes for shortened URLs.
-5. The `create_short_url()` method handles URL creation with optional custom aliases and expiration.
-6. The `track_click()` function records detailed analytics for each URL access.
-7. The `generate_qr_code()` method creates QR codes for easy mobile sharing.
-8. The `get_analytics()` function provides comprehensive statistics and visualizations.
-9. The Flask web interface offers a user-friendly dashboard for managing URLs.
-10. The `generate_analytics_chart()` method creates visual charts using matplotlib.
-11. Device and browser parsing extracts information from user agent strings.
-12. The web templates provide responsive HTML interfaces for all features.
-
-## Next Steps
-
-Congratulations! You have successfully created a URL Shortener with Analytics in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add user authentication and personal dashboards
-- Implement bulk URL shortening from CSV files
-- Create mobile app integration with API endpoints
-- Add social media sharing buttons and tracking
-- Implement A/B testing for different short URLs
-- Add geographic location tracking for clicks
-- Create scheduled reports and email notifications
-- Implement URL preview and safety checking
-- Add collaborative features for teams
+<FileCode file="projects/intermediate/urlshorteneranalytics.py" lang="python" title="urlshorteneranalytics.py" />
 
-## Conclusion
-
-In this project, you learned how to create a URL Shortener with Analytics in Python. You also learned about database design, web development, data visualization, and building comprehensive analytics systems. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/urlshorteneranalytics.py)
-
-## Code Explanation
-
-### Database Schema Design
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
-def init_database(self):
-    cursor.execute('''
-        CREATE TABLE IF NOT EXISTS urls (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            original_url TEXT NOT NULL,
-            short_code TEXT UNIQUE NOT NULL,
-            custom_alias TEXT UNIQUE,
-            title TEXT,
-            description TEXT,
-            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-            expires_at TIMESTAMP,
-            is_active BOOLEAN DEFAULT 1,
-            total_clicks INTEGER DEFAULT 0,
-            unique_clicks INTEGER DEFAULT 0
-        )
-    ''')
+### Run it
+```cmd title="command"
+C:\Users\Your Name\url-shortener> python urlshorteneranalytics.py
+# Menu appears. Choose 4 to start the web server, then open http://localhost:5000
 ```
 
-Creates comprehensive database schema for URLs with metadata and analytics tracking.
+## Step-by-Step Explanation
 
-### Short Code Generation
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
+### 1. Generating a unique short code
+```python title="urlshorteneranalytics.py"
 def generate_short_code(self, length=6):
     characters = string.ascii_letters + string.digits
     while True:
         short_code = ''.join(random.choice(characters) for _ in range(length))
-        if not self.get_url_by_code(short_code):
+        if not self.get_url_by_code(short_code):     # collision check
             return short_code
 ```
+Six characters from a 62-symbol alphabet gives 62⁶ ≈ 56 billion combinations. The `while True` loop regenerates on the rare collision and only returns a code that isn't already taken — the `UNIQUE` constraint on the column is the safety net.
 
-Generates unique short codes with collision detection and validation.
-
-### Click Analytics Tracking
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
-def track_click(self, url_id, ip_address=None, user_agent=None, referrer=None):
-    device_type = self.parse_device_type(user_agent)
-    browser = self.parse_browser(user_agent)
-    
-    cursor.execute('''
-        INSERT INTO clicks (url_id, ip_address, user_agent, referrer, device_type, browser)
-        VALUES (?, ?, ?, ?, ?, ?)
-    ''', (url_id, ip_address, user_agent, referrer, device_type, browser))
+### 2. Validating the input URL
+```python title="urlshorteneranalytics.py"
+def validate_url(self, url):
+    result = urlparse(url)
+    return all([result.scheme, result.netloc])   # needs http(s):// and a host
 ```
+A real URL needs both a scheme and a network location. Rejecting junk up front keeps the database clean and the redirects working.
 
-Records detailed click analytics including device type, browser, and referrer information.
-
-### QR Code Generation
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
-def generate_qr_code(self, url):
-    qr = qrcode.QRCode(version=1, box_size=10, border=5)
-    qr.add_data(url)
-    qr.make(fit=True)
-    
-    img = qr.make_image(fill_color="black", back_color="white")
-    img_str = base64.b64encode(buffer.getvalue()).decode()
-    return f"data:image/png;base64,{img_str}"
-```
-
-Creates QR codes for URLs and converts them to base64 for web display.
-
-### Analytics Dashboard
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
-def get_analytics(self, url_id):
-    # Daily clicks over time
-    cursor.execute('''
-        SELECT DATE(clicked_at) as date, COUNT(*) as clicks
-        FROM clicks WHERE url_id = ? 
-        GROUP BY DATE(clicked_at) ORDER BY date
-    ''', (url_id,))
-    
-    # Device and browser statistics
-    cursor.execute('''
-        SELECT device_type, COUNT(*) as count
-        FROM clicks WHERE url_id = ? GROUP BY device_type
-    ''', (url_id,))
-```
+### 3. Two tables: links and clicks
+The schema splits **what** (the `urls` table) from **events** (the `clicks` table). Every redirect writes a row to `clicks` with timestamp, IP, user-agent, referrer, device, and browser. This event-log design is the foundation of all analytics — store raw events, aggregate later.
 
-Provides comprehensive analytics including time series data and demographic breakdowns.
-
-### Web Interface Integration
-```python title="urlshorteneranalytics.py" showLineNumbers{1}
+### 4. The redirect that tracks
+```python title="urlshorteneranalytics.py"
 @app.route('/<short_code>')
 def redirect_url(short_code):
     url_data = shortener.get_url_by_code(short_code)
-    
-    # Track the click
-    shortener.track_click(
-        url_id=url_data[0],
-        ip_address=request.remote_addr,
-        user_agent=request.headers.get('User-Agent'),
-        referrer=request.headers.get('Referer')
-    )
-    
-    return redirect(url_data[1])
+    if not url_data:
+        return "URL not found", 404
+    if url_data[7] and datetime.datetime.now() > datetime.datetime.fromisoformat(url_data[7]):
+        return "URL has expired", 410          # 410 Gone for expired links
+    shortener.track_click(url_id=url_data[0],
+                          ip_address=request.remote_addr,
+                          user_agent=request.headers.get('User-Agent'),
+                          referrer=request.headers.get('Referer'))
+    return redirect(url_data[1])               # send the visitor on their way
 ```
+This is the heart of the app: look up the code, check expiry (note the correct `410 Gone` status), **log the click**, then redirect. The visitor barely notices the detour.
+
+### 5. Mining the request for analytics
+```python title="urlshorteneranalytics.py"
+def parse_device_type(self, user_agent):
+    ua = user_agent.lower()
+    if 'mobile' in ua or 'android' in ua or 'iphone' in ua: return "Mobile"
+    elif 'tablet' in ua or 'ipad' in ua: return "Tablet"
+    else: return "Desktop"
+```
+The `User-Agent` header and `Referer` are goldmines: parse them into device type and browser, and you can show *who* clicked and *where from* — with no extra tracking.
 
-Handles URL redirection while automatically tracking analytics data.
-
-## Features
+### 6. Aggregating with `GROUP BY`
+```python title="urlshorteneranalytics.py"
+SELECT DATE(clicked_at) as date, COUNT(*) as clicks
+FROM clicks WHERE url_id = ?
+GROUP BY DATE(clicked_at) ORDER BY date
+```
+The dashboard is just `GROUP BY` queries: clicks per day, per device, per browser, per referrer. Raw events in, summarized insight out — the universal analytics pattern.
 
-- **URL Shortening**: Create short, memorable URLs with optional custom aliases
-- **QR Code Generation**: Automatic QR code creation for mobile sharing
-- **Click Analytics**: Detailed tracking of clicks, devices, browsers, and referrers
-- **Expiration Dates**: Set automatic expiration for temporary links
-- **Web Dashboard**: Complete web interface for managing URLs and viewing analytics
-- **Data Visualization**: Charts and graphs for analytics insights
-- **REST API**: Programmatic access to all features via JSON API
-- **Device Detection**: Automatic detection of mobile, tablet, and desktop users
-- **Browser Analytics**: Track which browsers are used to access your links
-- **Referrer Tracking**: See where your traffic is coming from
+### 7. QR codes and charts as data URIs
+```python title="urlshorteneranalytics.py"
+img_str = base64.b64encode(buffer.getvalue()).decode()
+return f"data:image/png;base64,{img_str}"
+```
+Both the QR code and the matplotlib charts are rendered in memory and base64-encoded into `data:` URIs, so they embed directly in the HTML — no temp files to manage.
 
-## Next Steps
+## Caveat: Unique Clicks by IP
 
-### Enhancements
-- Add user authentication and personal dashboards
-- Implement bulk URL shortening from CSV files
-- Create mobile app integration with API endpoints
-- Add social media sharing buttons and tracking
-- Implement A/B testing for different short URLs
-- Add geographic location tracking for clicks
-- Create scheduled reports and email notifications
-- Implement URL preview and safety checking
-
-### Learning Extensions
-- Study web analytics and tracking technologies
-- Explore advanced data visualization techniques
-- Learn about user experience optimization
-- Practice with cloud deployment and scaling
-- Understand security best practices for URL services
-- Explore machine learning for click prediction
+```python title="urlshorteneranalytics.py"
+SELECT COUNT(DISTINCT ip_address) FROM clicks WHERE url_id = ?
+```
+"Unique clicks" here counts distinct IPs. It's a reasonable approximation but imperfect: people behind the same office NAT share an IP (undercount), and mobile users roam across IPs (overcount). Real analytics use a cookie or fingerprint. Know the limitation when you quote the number.
+
+## Production Notes
+
+| Issue | Fix |
+|---|---|
+| `debug=True, host='0.0.0.0'` | `debug=False`; bind deliberately |
+| Recomputing `unique_clicks` on every click | Expensive at scale — precompute or cache |
+| Charts rendered per request with matplotlib | Cache, or move to client-side JS charts |
+| No auth on delete/analytics | Tie links to accounts; check ownership |
+| `random` short codes | Fine; for guaranteed-unguessable use `secrets` |
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Short code collisions | Not checking existing codes | Loop until unique (the code does) |
+| Expired links still redirect | Forgot the expiry check | Compare `expires_at` before redirecting; return `410` |
+| Every visitor counts as "unique" | No IP/cookie dedup | `COUNT(DISTINCT ip_address)` or cookies |
+| `matplotlib` errors on a server | No display backend | Use the `Agg` backend (`matplotlib.use('Agg')`) |
+| Redirect loops | Shortened a URL pointing at your own domain | Reject self-referential URLs |
+| Slow dashboard | Re-aggregating everything each load | Index `clicks.url_id`; cache results |
+
+## Variations to Try
+
+1. **Accounts & ownership** — users manage only their own links.
+2. **Cookie-based unique visitors** — more accurate than IP.
+3. **Geo-analytics** — map clicks by country via an IP-geolocation API.
+4. **Password-protected links** — the schema already has `password_hash`.
+5. **Bulk shortening** — upload a CSV of URLs.
+6. **Client-side charts** — swap matplotlib for Chart.js.
+7. **Link editing** — change the destination without changing the code.
+8. **Rate limiting** — stop abuse of the shorten endpoint.
+
+## Real-World Applications
+- **Marketing** — trackable campaign links (UTM-style).
+- **Social media** — fit long URLs into character limits.
+- **Print/QR** — short codes behind posters and packaging.
+- **Internal analytics** — measure which docs/links get traffic.
 
 ## Educational Value
+- **Code generation** — uniqueness, alphabets, collision handling.
+- **Event-log analytics** — store raw, aggregate with `GROUP BY`.
+- **HTTP introspection** — user-agent and referrer parsing.
+- **Multi-interface design** — one engine behind web, API, and CLI.
 
-This project teaches:
-- **Database Design**: Creating normalized schemas for analytics data
-- **Web Development**: Building full-stack applications with Flask
-- **Data Analytics**: Implementing comprehensive tracking and reporting
-- **QR Codes**: Generating and integrating QR codes for mobile experiences
-- **User Agent Parsing**: Extracting device and browser information
-- **Data Visualization**: Creating charts and graphs with matplotlib
-- **REST APIs**: Designing and implementing RESTful web services
-- **URL Validation**: Ensuring proper URL format and security
-
-Perfect for understanding web analytics, database design, and building production-ready web applications with comprehensive tracking capabilities.
+## Next Steps
+- Add **accounts** and per-user link management.
+- Switch unique counting to **cookies** and add **geo** data.
+- Enable **password-protected** and **editable** links.
+- Move charts **client-side** and add **rate limiting**.
+
+## Conclusion
+You built a URL shortener that doesn't just redirect — it *measures*, turning every click into an event you aggregate into a real dashboard with devices, browsers, referrers, and trends. The store-raw-events-then-`GROUP BY` pattern is exactly how production analytics works, and you wrapped it in a web UI, a REST API, and a CLI off a single engine. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/urlshorteneranalytics.py). Explore more web and analytics projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/url_expander.mdx b/src/content/docs/projects/intermediate/url_expander.mdx
deleted file mode 100644
index 67227a3a..00000000
--- a/src/content/docs/projects/intermediate/url_expander.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: URL Expander
-sidebar:
-  order: 19
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/url_expander.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-URL Expander is a Python project that takes shortened URLs and expands them to their original form. It demonstrates API usage, HTTP requests, and GUI development. This project is ideal for learning about web APIs, networking, and user interaction.
-
-## Prerequisites
-- Python 3.6 or above
-- requests (`pip install requests`)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Install Python and requests. Prepare a list of shortened URLs for testing.
-
-## Getting Started
-1. Create a folder named `url-expander`.
-2. Create a file named `url_expander.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/url_expander.py" lang="python" title="URL Expander" />
-4. Run the script: `python url_expander.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import required modules.**
-```python
-import requests
-import tkinter as tk
-```
-2. **Expand shortened URL.**
-```python
-response = requests.head(short_url, allow_redirects=True)
-expanded_url = response.url
-```
-3. **Display result in GUI.**
-```python
-root = tk.Tk()
-root.title('URL Expander')
-# ...setup widgets for input and display...
-root.mainloop()
-```
-
-## Features
-- Expands shortened URLs
-- GUI for user interaction
-- Easy to extend for more features
-
-## How It Works
-- User enters shortened URL
-- App expands and displays original URL
-
-## GUI Components
-- **Entry box:** For URL input
-- **Button:** Expands URL
-- **Label:** Shows expanded URL
-
-## Use Cases
-- Reveal original links
-- Learn API and HTTP requests
-- Build web utilities
-
-## Next Steps
-You can enhance this project by:
-- Supporting batch expansion
-- Logging expanded URLs
-- Improving GUI design
-- Adding URL validation
-
-## Enhanced Version Ideas
-```python
-def expand_batch():
-    # Expand multiple URLs at once
-    pass
-
-def log_expansions():
-    # Save expanded URLs to file
-    pass
-```
-
-## Troubleshooting Tips
-- **Invalid URL:** Check input format
-- **No expansion:** Check internet connection
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches API usage, HTTP requests, and GUI basics. Extend it for more features and better user experience.
diff --git a/src/content/docs/projects/intermediate/weather-app-with-voice-commands.mdx b/src/content/docs/projects/intermediate/weather-app-with-voice-commands.mdx
index 9a0dc1db..54593f5b 100644
--- a/src/content/docs/projects/intermediate/weather-app-with-voice-commands.mdx
+++ b/src/content/docs/projects/intermediate/weather-app-with-voice-commands.mdx
@@ -1,5 +1,6 @@
 ---
 title: Weather App with Voice Commands
+description: Build a voice-controlled weather app in Python — speak a city name, recognize it with SpeechRecognition, fetch conditions from OpenWeatherMap — then add text-to-speech replies, threading, wake-word listening, and robust error handling.
 sidebar:
   order: 99
 hero:
@@ -12,66 +13,150 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Talking to your computer feels like magic — and it's surprisingly approachable. This project chains two services together: **speech recognition** (turn your voice into text) and a **weather API** (turn a city name into a forecast). You click a button, say a city, and the app speaks-or-shows the weather. You'll learn how the microphone, recognizer, and Google's speech API cooperate, then upgrade the experience with spoken replies (text-to-speech), a responsive threaded UI, and the error handling that voice apps absolutely require.
 
-Build a Weather App that fetches weather information based on voice commands. The app uses speech recognition to capture user queries and displays weather data from an API. This project demonstrates API integration, speech recognition, and GUI development in Python.
+You will leave understanding:
+- The capture → recognize → act pipeline behind every voice assistant.
+- How `speech_recognition` wraps the mic and a cloud recognizer.
+- Why each failure mode (`UnknownValueError`, `RequestError`) needs its own handling.
+- How to close the loop with text-to-speech for a hands-free experience.
 
 ## Prerequisites
-- Python 3.6 or above
-- Text Editor or IDE
-- Basic understanding of Python syntax
-- Familiarity with Tkinter for GUI development
-- Knowledge of speech recognition and API requests
+- Python 3.6 or above.
+- A text editor or IDE, and a working **microphone**.
+- `pip install SpeechRecognition requests pyaudio` (PyAudio powers the mic; on Windows `pip install pipwin && pipwin install pyaudio` if it fails).
+- A free [OpenWeatherMap](https://openweathermap.org/api) API key.
+- Familiarity with the [Simple Weather Forecast App](./simple-weather-forecast-app) helps — it covers the API half.
 
 ## Getting Started
-### Creating a new project
-1. Create a new project folder and name it `weather_app_with_voice_commands`.
-2. Create a new file inside the folder and name it `weather_app_with_voice_commands.py`.
-3. Open the project folder in your favorite text editor or IDE.
-4. Copy the code below and paste it into the `weather_app_with_voice_commands.py` file.
+
+### Create the project
+1. Create a folder named `voice-weather`.
+2. Inside it, create `weather_app_with_voice_commands.py`.
+3. Install dependencies and set your API key in the code.
 
 ### Write the code
 <FileCode file="projects/intermediate/weather_app_with_voice_commands.py" lang="python" title="weather_app_with_voice_commands.py" showLineNumbers={1} />
 
-## Key Features
-- Voice recognition to capture city names
-- Fetch weather data from an API
-- Display weather information in a user-friendly format
-- GUI interface for user interaction
+### Run it
+```cmd title="command"
+C:\Users\Your Name\voice-weather> python weather_app_with_voice_commands.py
+# Click "Speak", say a city like "London", and the weather appears.
+```
 
-## Explanation
+## Step-by-Step Explanation
 
-### Speech Recognition
-The app uses the `speech_recognition` library to capture voice input:
-```python title="weather_app_with_voice_commands.py" showLineNumbers={1}
+### 1. The recognizer and microphone
+```python title="weather_app_with_voice_commands.py"
 recognizer = sr.Recognizer()
 with sr.Microphone() as source:
     audio = recognizer.listen(source)
     city = recognizer.recognize_google(audio)
 ```
+`Recognizer` is the engine; `Microphone()` opens the default mic as a context manager (so it's released cleanly). `listen` records until you stop talking, and `recognize_google` sends the audio to Google's free speech API and returns text. That's the whole speech half in four lines.
+
+### 2. Handling what can go wrong
+```python title="weather_app_with_voice_commands.py"
+except sr.UnknownValueError:
+    messagebox.showerror("Error", "Sorry, I could not understand the audio.")
+except sr.RequestError:
+    messagebox.showerror("Error", "Could not request results, please check your internet connection.")
+```
+Voice input is *unreliable* — background noise, mumbling, or no internet all fail differently. `UnknownValueError` = "I heard you but couldn't parse it"; `RequestError` = "I couldn't reach the API." Distinct messages help the user fix the actual problem.
 
-### Fetching Weather Data
-Weather data is fetched from the OpenWeatherMap API:
-```python title="weather_app_with_voice_commands.py" showLineNumbers={1}
+### 3. Fetching the weather
+```python title="weather_app_with_voice_commands.py"
 params = {"q": city, "appid": API_KEY, "units": "metric"}
 response = requests.get(BASE_URL, params=params)
+data = response.json()
+if response.status_code == 200:
+    weather = data["weather"][0]["description"].capitalize()
+    temp = data["main"]["temp"]
+    ...
 ```
+Same pattern as a normal weather app — the recognized city flows straight into the API query. Always check `status_code` before parsing.
+
+### 4. Showing the result
+The formatted multi-line string lands in `result_label`. Next we'll *speak* it instead.
+
+## Close the Loop: Text-to-Speech
 
-### Displaying Results
-Weather information is shown in a Tkinter Label widget:
-```python title="weather_app_with_voice_commands.py" showLineNumbers={1}
-self.result_label.config(text=f"Weather: {weather}\nTemperature: {temp}°C")
+A voice app that only listens is half-built. Add spoken replies with `pyttsx3` (offline, no API):
+```python title="speak.py"
+import pyttsx3                 # pip install pyttsx3
+engine = pyttsx3.init()
+
+def say(text):
+    engine.say(text)
+    engine.runAndWait()
+
+# after fetching:
+say(f"The weather in {city} is {weather}, {temp} degrees.")
 ```
+Now it's hands-free: ask, and it answers aloud.
+
+## Don't Freeze While Listening
+
+`recognizer.listen` blocks — on the main thread the whole window freezes during recording. Run it on a background thread and update the UI via `after`:
+```python title="threaded.py"
+import threading
+
+def get_weather_by_voice(self):
+    threading.Thread(target=self._listen_and_fetch, daemon=True).start()
 
-## Running the Application
-1. Save the file.
-2. Install required dependencies:
-```bash
-pip install speechrecognition requests
+def _listen_and_fetch(self):
+    # ... listen + recognize + fetch ...
+    self.root.after(0, lambda: self.result_label.config(text=result))
 ```
-3. Run the application:
-```bash
-python weather_app_with_voice_commands.py
+
+## Calibrate for Noise
+
+In a noisy room, recognition accuracy plummets. Let the recognizer sample the ambient level first:
+```python title="calibrate.py"
+with sr.Microphone() as source:
+    recognizer.adjust_for_ambient_noise(source, duration=1)
+    audio = recognizer.listen(source, timeout=5, phrase_time_limit=4)
 ```
+`adjust_for_ambient_noise` sets the energy threshold; `timeout`/`phrase_time_limit` stop it listening forever.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| `PyAudio` won't install | Missing build tools / wheels | `pipwin install pyaudio` (Windows); `brew install portaudio` (Mac) |
+| Always "couldn't understand" | Noisy mic / bad threshold | `adjust_for_ambient_noise` first |
+| Window freezes while listening | `listen` on the main thread | Listen on a background thread |
+| `RequestError` constantly | No internet (Google API needs it) | Check connection; use an offline engine like Vosk |
+| `KeyError` on weather data | Parsed before checking status | Guard with `status_code == 200` |
+| City misheard ("you York") | Speech ambiguity | Show the recognized text; let the user confirm/retry |
+
+## Variations to Try
+
+1. **Spoken replies** — add `pyttsx3` text-to-speech (above).
+2. **Wake word** — listen continuously for "weather" before acting.
+3. **Richer queries** — parse "weather in Paris tomorrow" for a forecast.
+4. **Offline recognition** — swap Google for Vosk (no internet needed).
+5. **Multi-language** — pass `language="es-ES"` to `recognize_google`.
+6. **Voice everything** — extend into a mini assistant (time, news, reminders).
+7. **Visual feedback** — animate a "listening" indicator while recording.
+
+## Real-World Applications
+- **Voice assistants** — the Alexa/Siri/Google pattern in miniature.
+- **Accessibility** — hands-free apps for users who can't type.
+- **Smart home** — voice control for devices and dashboards.
+- **In-car / kitchen apps** — eyes-and-hands-busy contexts.
+
+## Educational Value
+- **Speech recognition** — mics, recognizers, and cloud STT.
+- **Service chaining** — wiring two APIs into one flow.
+- **Failure handling** — voice and network are both unreliable.
+- **Accessible design** — multimodal input/output.
+
+## Next Steps
+- Add **text-to-speech** replies.
+- Move listening to a **background thread** and **calibrate** for noise.
+- Add a **wake word** and **richer query parsing**.
+- Try **offline recognition** with Vosk.
 
 ## Conclusion
-This Weather App with Voice Commands project is a great way to learn about API integration and speech recognition in Python. You can extend it by adding support for more languages, weather forecasts, or voice feedback.
+You built a voice-controlled weather app by chaining speech recognition to a weather API, then made it conversational with text-to-speech and responsive with threading. The capture → recognize → act → respond loop is exactly how every voice assistant works — you've just built a focused one. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/weather_app_with_voice_commands.py). Explore more voice and API projects on Python Central Hub.
diff --git a/src/content/docs/projects/intermediate/weather_app_with_voice_commands.mdx b/src/content/docs/projects/intermediate/weather_app_with_voice_commands.mdx
deleted file mode 100644
index 4f3bdb16..00000000
--- a/src/content/docs/projects/intermediate/weather_app_with_voice_commands.mdx
+++ /dev/null
@@ -1,105 +0,0 @@
----
-title: Weather App with Voice Commands
-sidebar:
-    order: 12
-hero:
-  actions:
-    - text: View on GitHub
-      link: https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/weather_app_with_voice_commands.py
-      icon: github
-      variant: primary
----
-import FileCode from '../../../../components/FileCode.astro'
-
-## Abstract
-Weather App with Voice Commands is a Python project that fetches weather data and allows users to interact using voice commands. It demonstrates API integration, speech recognition, and GUI development. This project is ideal for learning about voice interfaces, REST APIs, and real-world automation.
-
-## Prerequisites
-- Python 3.6 or above
-- requests (`pip install requests`)
-- speech_recognition (`pip install SpeechRecognition`)
-- tkinter (usually pre-installed)
-
-## Before you Start
-Install Python, requests, and SpeechRecognition. Obtain a free API key from a weather service (e.g., OpenWeatherMap).
-
-## Getting Started
-1. Create a folder named `weather-voice-app`.
-2. Create a file named `weather_app_with_voice_commands.py`.
-3. Copy the code below into your file.
-<FileCode file="projects/intermediate/weather_app_with_voice_commands.py" lang="python" title="Weather App with Voice Commands" />
-4. Run the script: `python weather_app_with_voice_commands.py`
-
-## Explanation
-
-### Code Breakdown
-1. **Import modules**
-```python
-import requests
-import speech_recognition as sr
-import tkinter as tk
-```
-2. **Fetch weather and process voice**
-```python
-def get_weather(city):
-    # Fetch weather data from API
-    pass
-
-def listen_for_command():
-    # Use microphone to get user input
-    pass
-```
-3. **GUI for weather display**
-```python
-root = tk.Tk()
-root.title('Weather App with Voice Commands')
-# ...setup widgets for weather info and voice input...
-root.mainloop()
-```
-
-## Features
-- Fetches weather data from API
-- Accepts voice commands
-- GUI for display
-- Easy to extend for more features
-
-## How It Works
-- Listens for voice input
-- Fetches weather for requested city
-- Displays info in GUI
-
-## GUI Components
-- **Label:** Shows weather info
-- **Button:** Starts voice recognition
-- **Entry box:** For manual city input
-
-## Use Cases
-- Hands-free weather updates
-- Learn API and voice integration
-- Build smart home apps
-
-## Next Steps
-You can enhance this project by:
-- Adding more voice commands
-- Supporting multiple languages
-- Improving GUI design
-- Integrating with other smart devices
-
-## Enhanced Version Ideas
-```python
-def add_language_support():
-    # Recognize commands in other languages
-    pass
-
-def integrate_with_smart_home():
-    # Control devices based on weather
-    pass
-```
-
-## Troubleshooting Tips
-- **API key errors:** Check your key
-- **Voice not recognized:** Check microphone
-- **GUI not showing:** Ensure Tkinter is installed
-
-## Conclusion
-This project teaches API usage, speech recognition, and GUI basics. Extend it for more features and smart automation.
diff --git a/src/content/docs/projects/intermediate/web-scraping-pipeline.mdx b/src/content/docs/projects/intermediate/web-scraping-pipeline.mdx
index 902e9e61..2e1ae018 100644
--- a/src/content/docs/projects/intermediate/web-scraping-pipeline.mdx
+++ b/src/content/docs/projects/intermediate/web-scraping-pipeline.mdx
@@ -1,6 +1,6 @@
 ---
 title: Web Scraping Pipeline
-description: Professional web scraping system with automated scheduling, data processing, monitoring, and comprehensive analytics for large-scale data extraction.
+description: Build a production-grade web scraping pipeline in Python — per-domain rate limiting, robots.txt compliance, requests + Selenium, config-driven extraction rules, content-hash dedup, validation, scheduling, monitoring alerts, and a Flask dashboard.
 sidebar: 
     order: 65
 hero:
@@ -13,367 +13,157 @@ hero:
 import FileCode from '../../../../components/FileCode.astro'
 
 ## Abstract
+Anyone can write a 10-line scraper. This project teaches the other 99% — the engineering that makes scraping **reliable, respectful, and maintainable** at scale. It's a full pipeline: a per-domain **rate limiter**, **robots.txt** compliance, a dual `requests`/**Selenium** engine (for JavaScript-heavy sites and infinite scroll), **config-driven extraction rules** so you scrape new sites without new code, **content-hash deduplication**, data validation, scheduling, monitoring with alerts, and a Flask dashboard. If [Basic Web Scraper](../../beginners/basicwebscrapper) was your first scraper, this is what a real one looks like.
 
-Build a comprehensive web scraping pipeline that automates data extraction from multiple websites with advanced features like scheduling, monitoring, rate limiting, data processing, and comprehensive analytics.
+You will leave understanding:
+- The ethics and mechanics of polite scraping: robots.txt, rate limits, delays, headers.
+- When to use `requests` vs. **Selenium**, and how to handle infinite scroll.
+- Why extraction rules should be **data, not code**.
+- How content hashing deduplicates and how monitoring keeps a pipeline healthy.
 
 ## Prerequisites
-
-- Python 3.8 or above
-- Text Editor or IDE
-- Solid understanding of Python syntax and OOP concepts
-- Knowledge of web technologies (HTML, CSS, JavaScript)
-- Familiarity with HTTP protocols and web requests
-- Understanding of data processing and analysis
-- Experience with scheduling and automation
-- Basic knowledge of web scraping ethics and robots.txt
+- Python 3.7 or above.
+- A text editor or IDE.
+- `pip install requests beautifulsoup4 pandas selenium flask plotly` (+ ChromeDriver for Selenium).
+- Comfort with HTML/CSS selectors and the basics from [Advanced Web Scraping](./advanced-web-scraping).
+- Understanding of HTTP and SQL.
 
 ## Getting Started
 
-### Create a new project
-1. Create a new project folder and name it `webScrapingPipeline`.
-2. Create a new file and name it `webscrapingpipeline.py`.
-3. Install required dependencies: `pip install requests beautifulsoup4 pandas sqlite3 selenium flask plotly nltk textblob wordcloud matplotlib seaborn schedule`
-4. Open the project folder in your favorite text editor or IDE.
-5. Copy the code below and paste it into your `webscrapingpipeline.py` file.
+### Create the project
+1. Create a folder named `scraping-pipeline`.
+2. Inside it, create `webscrapingpipeline.py`.
+3. Install dependencies. Selenium features need Chrome + ChromeDriver (optional — it degrades gracefully).
 
 ### Write the code
-1. Add the following code to your `webscrapingpipeline.py` file.
-<FileCode file="projects/intermediate/webscrapingpipeline.py" lang="python" title="Web Scraping Pipeline" />
-2. Save the file.
-3. Run the following command to run the application.
-```cmd title="command" showLineNumbers{1}
-C:\Users\username\Documents\webScrapingPipeline> python webscrapingpipeline.py
-🕷️ Web Scraping Pipeline
-==================================================
-🚀 Starting scraping platform...
-🌐 Dashboard available at: http://localhost:5000
-🔍 Scraping engine ready
-📊 Analytics system loaded
-```
-
-## 🎯 What You'll Build
-
-A professional-grade web scraping system featuring:
+<FileCode file="projects/intermediate/webscrapingpipeline.py" lang="python" title="webscrapingpipeline.py" />
 
-### Core Scraping Features
-- **Multi-Method Extraction**: Support for requests and Selenium-based scraping
-- **Intelligent Rate Limiting**: Respectful scraping with domain-specific rate limits
-- **Robots.txt Compliance**: Automatic robots.txt checking and compliance
-- **Duplicate Detection**: Hash-based duplicate data detection
-- **Error Handling**: Comprehensive error handling and retry mechanisms
-
-### Automation & Scheduling
-- **Flexible Scheduling**: Support for interval, daily, and weekly schedules
-- **Background Processing**: Non-blocking scheduled execution
-- **Project Management**: Multiple independent scraping projects
-- **Task Monitoring**: Real-time monitoring of scraping tasks
-
-### Data Processing & Validation
-- **Data Cleaning**: Text normalization and cleaning
-- **Sentiment Analysis**: Automatic sentiment analysis of text content
-- **Keyword Extraction**: Intelligent keyword extraction from content
-- **Data Validation**: Configurable validation rules and data quality checks
-- **Type Conversion**: Automatic data type conversion and formatting
+### Run it
+```cmd title="command"
+C:\Users\Your Name\scraping-pipeline> python webscrapingpipeline.py
+# Define a project (target URLs + extraction rules), run it, watch the dashboard.
+```
 
-### Analytics & Reporting
-- **Performance Metrics**: Success rates, execution times, error analysis
-- **Trend Analysis**: Daily and weekly scraping trends
-- **Data Quality Metrics**: Uniqueness, completeness, and size analysis
-- **Export Capabilities**: CSV, JSON, and Excel export options
+## Scrape Responsibly (Read This First)
 
-### Web Interface
-- **Dashboard**: Comprehensive overview of all scraping projects
-- **Project Management**: Create, edit, and monitor scraping projects
-- **Real-time Monitoring**: Live status updates and performance metrics
-- **Interactive Analytics**: Charts and graphs for data visualization
+The pipeline bakes in good citizenship — copy this mindset into every scraper you write:
+- **Honor robots.txt.** Check what a site permits before fetching.
+- **Rate-limit per domain.** Don't hammer one server.
+- **Add delays** and a real **User-Agent**. Behave like a browser, not a flood.
+- **Cache and dedupe.** Don't re-fetch unchanged pages.
 
-## 🏗️ Architecture Overview
+Scraping aggressively can get you IP-banned, break sites, or cross legal lines. The engineering below is also the *ethics*.
 
-The system is built with several interconnected components:
+## Step-by-Step Explanation
 
-```python title="webscrapingpipeline.py" showLineNumbers{1}
+### 1. Per-domain rate limiting
+```python title="webscrapingpipeline.py"
 class RateLimiter:
-    """Implements domain-specific rate limiting for respectful scraping."""
-    
-    def __init__(self, max_requests=10, time_window=60):
-        self.max_requests = max_requests
-        self.time_window = time_window
-        self.requests = defaultdict(deque)
-    
     def is_allowed(self, domain):
-        """Check if request to domain is allowed based on rate limit."""
-        # Rate limiting logic with time window tracking
-
-class WebScraper:
-    """Main scraping engine with support for multiple extraction methods."""
-    
-    def scrape_url(self, url, scraping_config):
-        """Scrape a single URL with given configuration."""
-        # Robots.txt checking, rate limiting, and data extraction
-        
-    def _extract_data(self, html_content, extraction_rules):
-        """Extract data using CSS selectors, regex, and XPath."""
-        # BeautifulSoup-based data extraction with multiple rule types
-
-class DataProcessor:
-    """Advanced data processing and validation engine."""
-    
-    def process_scraped_data(self, raw_data, processing_rules):
-        """Process raw scraped data using configurable rules."""
-        # Text cleaning, sentiment analysis, and data transformation
-
-class ScrapingScheduler:
-    """Automated scheduling system for scraping projects."""
-    
-    def _run_scraping_project(self, project_id):
-        """Execute a scheduled scraping project."""
-        # Project execution with logging and data storage
+        now = time.time()
+        dq = self.requests[domain]
+        while dq and dq[0] <= now - self.time_window:   # drop old timestamps
+            dq.popleft()
+        if len(dq) < self.max_requests:
+            dq.append(now)
+            return True
+        return False
 ```
-
-## 💾 Database Schema
-
-The system uses SQLite with a comprehensive schema:
-
-```python title="webscrapingpipeline.py" showLineNumbers{35}
-def init_database(self):
-    """Create database tables for web scraping pipeline."""
-    
-    # Scraping projects - project configurations
-    # Scraped data - extracted and processed data
-    # Scraping logs - execution history and monitoring
-    # Validation rules - data quality enforcement
-    # Monitoring alerts - automated notifications
-    # Exported reports - export history tracking
-    # Site metadata - robots.txt and crawl policies
+A `deque` of timestamps **per domain** implements a sliding-window limit ("≤10 requests / 60s"). Old timestamps fall off the left; if the window is full, the request is denied. This is the same algorithm APIs use to rate-limit *you*.
+
+### 2. robots.txt compliance
+```python title="webscrapingpipeline.py"
+rp = RobotFileParser()
+rp.set_url(urljoin(domain, '/robots.txt'))
+rp.read()
+return rp.can_fetch('*', url)         # cached per domain
 ```
-
-## 🔧 Core Features
-
-### 1. Intelligent Web Scraping
-
-```python title="webscrapingpipeline.py" showLineNumbers{200}
-def scrape_url(self, url, scraping_config):
-    """Comprehensive URL scraping with multiple safeguards."""
-    
-    # Check robots.txt compliance
-    if not self.check_robots_txt(url):
-        return {'status': 'skipped', 'error': 'Robots.txt disallows crawling'}
-    
-    # Apply rate limiting
-    domain = urlparse(url).netloc
-    if not self.rate_limiter.is_allowed(domain):
-        wait_time = self.rate_limiter.wait_time(domain)
-        return {'status': 'rate_limited', 'error': f'Rate limited. Wait {wait_time:.1f} seconds'}
-    
-    # Choose appropriate scraping method
-    if scraping_config.get('use_selenium', False):
-        response_data = self._scrape_with_selenium(url, scraping_config)
-    else:
-        response_data = self._scrape_with_requests(url, scraping_config)
+Python's standard `RobotFileParser` reads a site's rules; `can_fetch` tells you if a path is allowed. The result is cached per domain so you fetch `/robots.txt` once. Skipping this check is how scrapers get banned.
+
+### 3. Two engines: requests vs. Selenium
+```python title="webscrapingpipeline.py"
+if scraping_config.get('use_selenium', False) and self.use_selenium:
+    response_data = self._scrape_with_selenium(url, scraping_config)
+else:
+    response_data = self._scrape_with_requests(url, scraping_config)
 ```
-
-### 2. Advanced Data Processing
-
-```python title="webscrapingpipeline.py" showLineNumbers{400}
-def process_scraped_data(self, raw_data, processing_rules):
-    """Multi-stage data processing pipeline."""
-    
-    processed_data = {}
-    
-    for field_name, value in raw_data.items():
-        if field_name in processing_rules:
-            # Apply text cleaning, sentiment analysis, validation
-            processed_data[field_name] = self._apply_processing_rules(
-                value, processing_rules[field_name]
-            )
-        else:
-            processed_data[field_name] = value
-    
-    # Calculate derived fields (concatenation, calculations)
-    if 'derived_fields' in processing_rules:
-        for derived_field, rule in processing_rules['derived_fields'].items():
-            processed_data[derived_field] = self._calculate_derived_field(processed_data, rule)
+**`requests`** is fast and cheap — use it for static HTML. **Selenium** drives a real headless browser — necessary when content is rendered by JavaScript. The pipeline picks per-config and **degrades gracefully** to `requests` if ChromeDriver isn't installed. Choosing the cheapest tool that works is a core scraping skill.
+
+### 4. Handling infinite scroll
+```python title="webscrapingpipeline.py"
+last_height = self.driver.execute_script("return document.body.scrollHeight")
+while True:
+    self.driver.execute_script("window.scrollTo(0, document.body.scrollHeight);")
+    time.sleep(2)
+    new_height = self.driver.execute_script("return document.body.scrollHeight")
+    if new_height == last_height:   # nothing new loaded
+        break
+    last_height = new_height
 ```
-
-### 3. Automated Scheduling
-
-```python title="webscrapingpipeline.py" showLineNumbers{550}
-def _schedule_project(self, project_id, project_name, schedule_config):
-    """Configure automated project scheduling."""
-    
-    if schedule_config['type'] == 'interval':
-        if schedule_config['unit'] == 'minutes':
-            schedule.every(schedule_config['value']).minutes.do(
-                self._run_scraping_project, project_id
-            )
-        elif schedule_config['unit'] == 'hours':
-            schedule.every(schedule_config['value']).hours.do(
-                self._run_scraping_project, project_id
-            )
-    elif schedule_config['type'] == 'daily':
-        schedule.every().day.at(schedule_config['time']).do(
-            self._run_scraping_project, project_id
-        )
+Scroll to the bottom, wait for new content, repeat until the page stops growing — the standard trick for lazy-loaded feeds.
+
+### 5. Extraction rules as data, not code
+The scraper reads *what to extract* from a config (CSS selectors per field), so adding a new site is a config edit, not a code change:
+```python title="config-example.py"
+extraction_rules = {
+    "title": {"selector": "h1.product-title", "type": "text"},
+    "price": {"selector": "span.price", "type": "text"},
+    "image": {"selector": "img.main", "type": "attr", "attr": "src"},
+}
 ```
+Separating rules from engine is what lets one scraper serve hundreds of sites — the difference between a script and a *platform*.
 
-### 4. Comprehensive Analytics
-
-```python title="webscrapingpipeline.py" showLineNumbers{650}
-def generate_project_report(self, project_id, days_back=30):
-    """Generate detailed project performance report."""
-    
-    # Get scraping statistics
-    stats = pd.read_sql_query('''
-        SELECT 
-            COUNT(*) as total_attempts,
-            SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as successful_scrapes,
-            AVG(execution_time) as avg_execution_time,
-            MAX(execution_time) as max_execution_time
-        FROM scraping_logs 
-        WHERE project_id = ? AND timestamp >= ?
-    ''', conn, params=[project_id, start_date])
-    
-    # Analyze daily trends, error patterns, and data quality
-    return comprehensive_report
+### 6. Deduplication by content hash
+```python title="webscrapingpipeline.py"
+import hashlib
+data_hash = hashlib.sha256(raw_data.encode()).hexdigest()
+# status CHECK(... 'duplicate'): skip storing if this hash already exists
 ```
-
-## 🚀 Getting Started
-
-### 1. Install Dependencies
-
-```bash title="terminal" showLineNumbers{1}
-pip install requests beautifulsoup4 pandas sqlite3 selenium flask plotly
-pip install nltk textblob wordcloud matplotlib seaborn schedule
-```
-
-### 2. Run the Application
-
-```python title="webscrapingpipeline.py" showLineNumbers{850}
-def main():
-    """Main function with interface selection."""
-    
-    choice = input("\nChoose interface:\n1. Web Interface\n2. CLI Demo\nEnter choice (1-2): ")
-    
-    if choice == '2':
-        # CLI demo with sample scraping
-        print("🕷️ Running CLI Demo...")
-        # Execute demo scraping with test URLs
-    else:
-        # Launch Flask web interface
-        app = ScrapingWebInterface()
-        app.run()
-```
-
-### 3. Web Interface Features
-
-The Flask-based web interface provides:
-
-- **Dashboard**: Overview of all scraping projects and system status
-- **Project Management**: Create, edit, and configure scraping projects
-- **Live Monitoring**: Real-time status updates and performance metrics
-- **Data Export**: Download scraped data in multiple formats
-- **Analytics**: Interactive charts and comprehensive reporting
-
-## 📊 Sample Output
-
-### Project Creation
-```
-🕷️ Web Scraping Pipeline
-==================================================
-🚀 Starting scraping platform...
-🌐 Access the dashboard at: http://localhost:5000
-
-🔥 Scraping Features:
-   - Multi-site data extraction
-   - Automated scheduling and monitoring
-   - Rate limiting and robots.txt compliance
-   - Data validation and processing
-   - Export in multiple formats
-   - Comprehensive analytics and reporting
-   - Web interface for easy management
-```
-
-### Scraping Execution
-```
-Starting scheduled scraping: News Website Monitor
-Scraping: https://example-news.com/latest
-  ✅ Success: 2,847 characters extracted
-  📊 Data: {'title': 'Breaking News Today', 'articles': [...]}
-  
-Scraping: https://example-news.com/technology
-  ✅ Success: 1,923 characters extracted
-  📊 Data: {'title': 'Tech Updates', 'articles': [...]}
-
-Completed scheduled scraping: News Website Monitor
-Success Rate: 95.2% | Avg Time: 1.3s | Total Records: 156
-```
-
-### Analytics Report
-```
-📈 Project Performance Report
-================================
-Project: E-commerce Product Tracker
-Period: Last 30 days
-
-📊 Summary Statistics:
-   • Total Attempts: 4,320
-   • Successful Scrapes: 4,118 (95.3%)
-   • Failed Scrapes: 202 (4.7%)
-   • Average Execution Time: 2.1 seconds
-   • Data Records Collected: 3,847
-
-🔍 Data Quality:
-   • Unique Records: 3,692 (95.9%)
-   • Average Data Size: 1.2 KB
-   • Duplicate Rate: 4.1%
-
-⚠️ Top Errors:
-   • Connection timeout: 89 occurrences (44.1%)
-   • Rate limit exceeded: 67 occurrences (33.2%)
-   • Invalid selector: 46 occurrences (22.8%)
-```
-
-## 🎓 Learning Objectives
-
-### Web Scraping Fundamentals
-- **HTTP Requests**: Understanding web protocols and response handling
-- **HTML Parsing**: DOM navigation and data extraction techniques
-- **CSS Selectors**: Advanced selector patterns for precise targeting
-- **JavaScript Rendering**: When and how to use browser automation
-
-### System Design Principles
-- **Rate Limiting**: Implementing respectful scraping practices
-- **Error Handling**: Comprehensive error management and recovery
-- **Data Pipelines**: Building robust data processing workflows
-- **Monitoring**: System health tracking and alerting
-
-## Explanation
-
-1. The `WebScrapingPipeline` class orchestrates the complete scraping system with Flask web interface.
-2. The `RateLimiter` ensures respectful scraping practices with domain-specific rate limiting.
-3. The `WebScraper` handles both requests-based and Selenium browser automation for data extraction.
-4. The `DataProcessor` provides text analysis, sentiment analysis, and keyword extraction.
-5. The `ScrapingScheduler` manages automated scheduling with flexible timing options.
-6. The `ProjectManager` organizes multiple scraping projects with individual configurations.
-7. Analytics engine provides comprehensive performance metrics and trend analysis.
-8. Database design supports project management, data storage, and historical tracking.
-9. Error handling includes retry mechanisms and comprehensive logging.
-10. Web dashboard provides real-time monitoring and project management.
-11. Robots.txt compliance ensures ethical scraping practices.
-12. Export capabilities support multiple data formats for further analysis.
+Hash the scraped content; if you've seen that hash, it's a duplicate — skip it. Cheap, exact change-detection that avoids storing the same page twice (the same idea as the [File Version Control System](./basic-file-version-control-system)).
+
+### 7. Logging, validation, and monitoring
+Every fetch writes a row to `scraping_logs` (status, response code, timing). Validation rules check scraped fields (required/type/format/range). Monitoring alerts fire when error rates or data-quality thresholds are breached. **Observability is what separates a pipeline from a one-off script** — when a site changes its HTML, you want an alert, not silent garbage.
+
+## Common Mistakes
+
+| Problem | Cause | Fix |
+|---|---|---|
+| IP banned mid-scrape | Too fast, no delays | Rate-limit per domain, add random delays |
+| Empty results | JS-rendered content | Use Selenium for dynamic pages |
+| `WebDriverException` | ChromeDriver missing/mismatched | Install matching driver; code falls back to `requests` |
+| Same data stored repeatedly | No dedup | Hash content; skip seen hashes |
+| Scraper silently breaks | Site changed its HTML | Validation rules + monitoring alerts |
+| Legal/ToS trouble | Ignored robots.txt / terms | Check robots.txt; respect site terms |
+| Memory blows up on infinite scroll | Scrolling forever | Cap iterations; stop when height stops changing |
+
+## Variations to Try
+
+1. **Proxy rotation** — distribute requests across IPs (responsibly).
+2. **Async engine** — `aiohttp` + `asyncio` for high-throughput static scraping.
+3. **Distributed scraping** — a task queue (Celery/RQ) across workers.
+4. **Auto-detect extraction** — infer selectors instead of hard-coding.
+5. **Change alerts** — notify when a tracked value (e.g. price) changes.
+6. **Incremental crawls** — only re-fetch pages older than N hours.
+7. **Export targets** — push to CSV, Parquet, or a data warehouse.
+8. **CAPTCHA-aware backoff** — detect blocks and pause gracefully.
+
+## Real-World Applications
+- **Price monitoring** — track competitor or retail prices.
+- **Market research** — aggregate listings, reviews, jobs.
+- **News & content aggregation** — feed pipelines (see [News Aggregator](./news-aggregator)).
+- **Data engineering** — populate warehouses for analytics/ML.
+
+## Educational Value
+- **Ethical scraping** — robots.txt, rate limits, delays, identification.
+- **Tool selection** — requests vs. Selenium, graceful degradation.
+- **Pipeline design** — config-driven rules, dedup, validation, monitoring.
+- **Observability** — logging and alerting for long-running jobs.
 
 ## Next Steps
-
-Congratulations! You have successfully created a Web Scraping Pipeline in Python. Experiment with the code and see if you can modify the application. Here are a few suggestions:
-- Add machine learning for content classification
-- Implement distributed scraping with multiple workers
-- Create advanced data visualization dashboards
-- Add cloud storage integration for scalability
-- Implement real-time monitoring and alerting
-- Create API endpoints for programmatic access
-- Add support for JavaScript-heavy websites
-- Integrate with data analysis and BI tools
+- Add an **async engine** for static-page throughput.
+- Implement **change alerts** and **incremental crawls**.
+- Add **proxy rotation** and a **task queue** for scale.
+- Push results to a **data warehouse**.
 
 ## Conclusion
-
-In this project, you learned how to create a professional Web Scraping Pipeline in Python with automation, monitoring, and analytics. You explored ethical web scraping, data processing, scheduling systems, and building comprehensive data extraction platforms. You can find the source code on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/webscrapingpipeline.py)
+You built a scraping *pipeline*, not a script: it respects robots.txt, rate-limits per domain, picks requests or Selenium per site, extracts via swappable config rules, dedupes by content hash, validates output, and monitors itself. That engineering — and the ethics baked into it — is the difference between a scraper that survives in production and one that gets banned by lunch. Full source on [GitHub](https://github.com/Ravikisha/PythonCentralHub/blob/main/projects/intermediate/webscrapingpipeline.py). Explore more data-engineering projects on Python Central Hub.
diff --git a/src/content/docs/tutorials/Boolean.mdx b/src/content/docs/tutorials/Boolean.mdx
index 1625e69f..3054f52d 100644
--- a/src/content/docs/tutorials/Boolean.mdx
+++ b/src/content/docs/tutorials/Boolean.mdx
@@ -59,6 +59,23 @@ Ten is greater than nine!
 
 Logical operators in Python are used to perform operations on Boolean values. The three primary logical operators are `and`, `or`, and `not`.
 
+**Diagram**:
+```mermaid title="logical operators" desc="Truth outcomes for and, or, not"
+graph TD
+    A[Two boolean inputs] --> B["and: True only if BOTH true"]
+    A --> C["or: True if AT LEAST ONE true"]
+    D[One boolean input] --> E["not: flips the value"]
+```
+
+The full truth table for `and` and `or`:
+
+| `a` | `b` | `a and b` | `a or b` |
+| :---: | :---: | :---: | :---: |
+| True | True | True | True |
+| True | False | False | True |
+| False | True | False | True |
+| False | False | False | False |
+
 ### `and` Operator
 
 The `and` operator returns `True` if both operands are true; otherwise, it returns `False`.
@@ -111,6 +128,39 @@ C:\Users\Your Name> python booleans.py
 False
 ```
 
+### Short-Circuit Evaluation
+
+Python stops evaluating a logical expression as soon as the result is known. With `and`, if the first operand is falsy the second is never checked; with `or`, if the first is truthy the second is skipped. This is called **short-circuiting**.
+
+```python title="short_circuit.py" showLineNumbers{1} {1-3}
+def expensive():
+    print("expensive() was called")
+    return True
+
+False and expensive()   # expensive() is NEVER called
+True or expensive()     # expensive() is NEVER called
+```
+
+A practical use is guarding against errors — the right side runs only when it is safe:
+
+```python title="guard.py" showLineNumbers{1} {2}
+name = ""
+if name and name[0] == "A":   # name[0] only runs if name is non-empty
+    print("Starts with A")
+```
+
+### `and` / `or` Return Operands, Not Just Booleans
+
+A subtle but useful fact: `and` and `or` return one of the **actual operands**, not necessarily `True`/`False`. `or` returns the first truthy value; `and` returns the first falsy value (or the last operand).
+
+```python title="operands.py" showLineNumbers{1} {1-3}
+print("" or "default")    # default   -> first truthy value
+print("Alice" or "guest") # Alice     -> first truthy value
+print(5 and 0 and 9)      # 0         -> first falsy value
+```
+
+This powers the common "default value" idiom: `username = entered_name or "Anonymous"`.
+
 ## Comparison Operators
 
 Comparison operators are used to compare values and return Boolean results. These operators include `==` (equal), `!=` (not equal), `<` (less than), `>` (greater than), `<=` (less than or equal to), and `>=` (greater than or equal to).
@@ -237,6 +287,29 @@ False
 False
 ```
 
+### Truthy and Falsy Values
+
+Every Python object is either **truthy** or **falsy** when used in a boolean context (like an `if`). Only a small set of values are falsy; everything else is truthy.
+
+| Falsy values | Truthy values |
+| :--- | :--- |
+| `False`, `None` | Any non-zero number |
+| `0`, `0.0`, `0j` | Any non-empty string |
+| `""` (empty string) | Any non-empty list/tuple/dict/set |
+| `[]`, `()`, `{}`, `set()` | Most objects |
+
+This lets you write clean checks — `if my_list:` instead of `if len(my_list) > 0:`.
+
+### Booleans Are Integers
+
+As noted earlier, `bool` is a subclass of `int`: `True` equals `1` and `False` equals `0`. This means you can do arithmetic with them, which is handy for counting:
+
+```python title="bool_int.py" showLineNumbers{1} {1-3}
+votes = [True, False, True, True, False]
+print(sum(votes))      # 3  -> counts how many are True
+print(True + True)     # 2
+```
+
 ## Conclusion
 
 Boolean logic is an integral part of Python programming, enabling developers to create conditions, make decisions, and control the flow of their code. Understanding Boolean values, logical operators, and their applications in conditional statements, functions, and loops is essential for writing clear, efficient, and effective Python code.
diff --git a/src/content/docs/tutorials/Comment.mdx b/src/content/docs/tutorials/Comment.mdx
index 44cec1e3..af14f31a 100644
--- a/src/content/docs/tutorials/Comment.mdx
+++ b/src/content/docs/tutorials/Comment.mdx
@@ -9,6 +9,25 @@ import DataCampExercise from "../../../components/DataCampExercise.astro";
 
 Comments are used in Python to add explanations or notes to the code. They are not executed and do not affect the program's functionality. Comments are crucial for enhancing code readability and for providing context to readers.
 
+A good comment explains **why** the code does something, not **what** it does — the code itself already shows the *what*.
+
+```python title="why_not_what.py" showLineNumbers{1} {1,4}
+# Bad: restates the obvious
+x = x + 1  # add 1 to x
+
+# Good: explains the reason
+x = x + 1  # advance to the next page; pages are 1-indexed
+```
+
+**Diagram**:
+```mermaid title="how Python treats comments" desc="The interpreter ignores everything after the hash"
+graph LR
+    A[Source line] --> B{Contains #?}
+    B -->|Yes| C[Run code before #]
+    C --> D[Ignore text after #]
+    B -->|No| E[Run the whole line]
+```
+
 ## Single-line Comments
 
 In Python, single-line comments start with the `#` symbol. Anything following the `#` on that line is considered a comment.
@@ -66,6 +85,48 @@ result = add_numbers(5, 3)
 print("Result:", result)
 ```
 
+### Accessing a Docstring
+
+Unlike ordinary comments, docstrings are kept by Python at runtime. You can read them with the built-in `help()` function or the `__doc__` attribute — this is how editors and `help()` show documentation.
+
+```python title="docstring_access.py" showLineNumbers{1} {1}
+print(add_numbers.__doc__)   # prints the docstring text
+help(add_numbers)            # prints formatted help
+```
+
+## Commenting Out Code
+
+During debugging it is common to temporarily disable a line by turning it into a comment. Most editors do this for a whole selection with `Ctrl + /`.
+
+```python title="disable.py" showLineNumbers{1} {2}
+print("This runs")
+# print("This line is disabled for now")
+print("This runs too")
+```
+
+## TODO and FIXME Conventions
+
+Teams use tagged comments so tools and editors can find pending work. Common tags include `TODO`, `FIXME`, and `NOTE`:
+
+```python title="tags.py" showLineNumbers{1}
+# TODO: handle negative numbers
+# FIXME: this crashes when the list is empty
+# NOTE: prices are stored in cents, not dollars
+```
+
+## The Shebang Line
+
+On Linux and macOS, the first line of an executable script can be a special comment called a **shebang**. It tells the system which interpreter to use, so the script can be run directly:
+
+```python title="script.py" showLineNumbers{1} {1}
+#!/usr/bin/env python3
+print("Run me directly with ./script.py")
+```
+
+:::note
+The shebang is only meaningful as the **first line** of the file. Anywhere else it is just an ordinary comment.
+:::
+
 ## Best Practices for Comments
 
 1. **Be Clear and Concise:** Write comments that are easy to understand. Avoid unnecessary comments that restate the obvious.
diff --git a/src/content/docs/tutorials/DataType.mdx b/src/content/docs/tutorials/DataType.mdx
index 24d04b18..bee802f3 100644
--- a/src/content/docs/tutorials/DataType.mdx
+++ b/src/content/docs/tutorials/DataType.mdx
@@ -11,6 +11,45 @@ import DataCampExercise from "../../../components/DataCampExercise.astro";
 
 Data types in Python are a fundamental concept that plays a crucial role in defining the nature of variables and how they behave during operations. Python is a dynamically-typed language, which means that the interpreter can determine the type of a variable at runtime. This flexibility allows for more concise and expressive code. Let's delve into the essential data types in Python.
 
+**Diagram**:
+```mermaid title="Python built-in data types" desc="The main categories of built-in types"
+graph TD
+    A[Python Data Types] --> B[Numeric]
+    A --> C[Sequence]
+    A --> D[Set]
+    A --> E[Mapping]
+    A --> F[Boolean]
+    A --> G[None]
+    B --> B1[int]
+    B --> B2[float]
+    B --> B3[complex]
+    C --> C1[str]
+    C --> C2[list]
+    C --> C3[tuple]
+    D --> D1[set]
+    D --> D2[frozenset]
+    E --> E1[dict]
+```
+
+### Dynamic Typing
+
+Because Python infers types at runtime, the *same* variable can hold different types over its life — the type belongs to the value, not the variable.
+
+```python title="dynamic.py" showLineNumbers{1} {1-4}
+x = 42          # x is now an int
+print(type(x))  # <class 'int'>
+x = "hello"     # x is now a str — perfectly legal
+print(type(x))  # <class 'str'>
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python dynamic.py
+<class 'int'>
+<class 'str'>
+```
+
 ## Numeric Data Types
 
 ### Integers
@@ -218,6 +257,30 @@ There are many more data types in Python, but the ones listed above are the most
 
 
 
+## Mutable vs. Immutable Types
+
+A crucial distinction: some objects can be changed after creation (**mutable**), and some cannot (**immutable**). Trying to change an immutable object creates a new object instead.
+
+| Mutable (can change) | Immutable (cannot change) |
+| :--- | :--- |
+| `list`, `dict`, `set`, `bytearray` | `int`, `float`, `complex`, `bool` |
+| | `str`, `tuple`, `frozenset`, `bytes` |
+
+```python title="mutability.py" showLineNumbers{1} {1-7}
+# Lists are mutable - same object is modified
+numbers = [1, 2, 3]
+numbers[0] = 99
+print(numbers)        # [99, 2, 3]
+
+# Strings are immutable - this raises an error
+text = "hello"
+# text[0] = "H"       # TypeError: 'str' object does not support item assignment
+```
+
+:::note
+You can check whether two names point to the *same* object with the `id()` function or the `is` operator. Mutating a mutable object is visible through every name that references it.
+:::
+
 ## Conclusion
 
 Understanding Python's data types is fundamental to writing effective and efficient code. Python's flexibility in handling various data types makes it suitable for a wide range of applications, from simple scripts to complex data analysis and machine learning tasks. As you continue your journey in Python programming, a solid grasp of data types will empower you to manipulate and process data effectively.
diff --git a/src/content/docs/tutorials/Datatype Casting.mdx b/src/content/docs/tutorials/Datatype Casting.mdx
index 94089b7a..c427ee5a 100644
--- a/src/content/docs/tutorials/Datatype Casting.mdx	
+++ b/src/content/docs/tutorials/Datatype Casting.mdx	
@@ -10,6 +10,17 @@ import DataCampExercise from "../../../components/DataCampExercise.astro";
 ## Navigating Data Types: A Guide to Data Type Casting in Python
 Data type casting, also known as type conversion, is a fundamental concept in Python that allows you to change the data type of a variable or value. This process is crucial when working with different data types and ensures the compatibility of variables in various operations. In this comprehensive guide, we'll explore the basics of data type casting in Python, including the built-in functions used for conversion and best practices.
 
+There are two kinds of conversion. **Implicit** conversion is done automatically by Python; **explicit** conversion is done by you, using a built-in function.
+
+**Diagram**:
+```mermaid title="implicit vs explicit casting" desc="The two kinds of type conversion in Python"
+graph TD
+    A[Type Conversion] --> B[Implicit: Python does it]
+    A --> C[Explicit: you call a function]
+    B --> B1["int + float -> float automatically"]
+    C --> C1["int('42'), float(x), str(n)"]
+```
+
 ## Understanding Data Types in Python
 Before we dive into the details of data type casting, let's take a moment to understand the different data types in Python. Python is a dynamically typed language, which means that the interpreter automatically assigns a data type to a variable based on the value it holds. For example, if you assign the value `5` to a variable, the interpreter will assign the integer data type to that variable. Similarly, if you assign the value `5.0` to a variable, the interpreter will assign the float data type to that variable.
 
@@ -72,8 +83,10 @@ Python also allows you to explicitly convert one data type to another using buil
 | `bytes()` | Converts a value to bytes |
 | `bytearray()` | Converts a value to a byte array |
 | `complex()` | Converts a value to a complex number |
-| `range()` | Converts a value to a range |
-| `None` | Converts a value to None |
+
+:::caution
+`range()` and `None` are **not** casting functions. `range()` generates a sequence of numbers, and `None` is a value (not a converter). They are sometimes mistakenly listed as casts — do not treat them that way.
+:::
 
 
 ## Integer Conversion
@@ -98,6 +111,20 @@ C:\Users\Your Name> python casting.py
 
 In the above example, we have used the `int()` function to convert a float to an integer. The `int()` function takes a single argument and returns an integer. The result of the `int()` function is then assigned to the variable `y`. The value of `y` is then printed to the console.
 
+:::caution
+**Two things to watch with `int()`:**
+
+1. **Data loss** — converting a float to an int *truncates* (chops off) the decimal part, it does not round: `int(5.9)` is `5`, not `6`.
+2. **Conversion errors** — `int()` only parses strings that look like whole numbers. `int("3.14")` and `int("hello")` both raise `ValueError`.
+
+```python title="casting_errors.py" showLineNumbers{1} {1-3}
+print(int(5.9))      # 5  (truncated, not rounded)
+# print(int("3.14")) # ValueError: invalid literal for int()
+print(int(float("3.14")))  # 3  -> go via float first
+```
+Wrap risky conversions in `try/except ValueError` when the value comes from user input or a file.
+:::
+
 ## Float Conversion
 #### `float()` Function
 The `float()` function converts a value to a float. The following example demonstrates how to use the `float()` function in Python:
diff --git a/src/content/docs/tutorials/GetStarted.mdx b/src/content/docs/tutorials/GetStarted.mdx
index 938d5c66..d7b297e1 100644
--- a/src/content/docs/tutorials/GetStarted.mdx
+++ b/src/content/docs/tutorials/GetStarted.mdx
@@ -9,7 +9,27 @@ sidebar:
 
 To start coding in Python, you need to have Python installed on your computer. Follow the installation guide on our [Installation Page](/tutorials/installation) if you haven't done so already.
 
-Once Python is installed, you can run Python code using the command line or terminal.
+Once Python is installed, you can run Python code in several ways. Pick the one that fits what you are doing.
+
+**Diagram**:
+```mermaid title="ways to run Python" desc="Different ways to execute Python code"
+graph TD
+    A[Write Python code] --> B[Interactive shell / REPL]
+    A --> C[Run a .py file]
+    A --> D[One-liner with -c]
+    A --> E[IDE Run button]
+    B --> F[Output]
+    C --> F
+    D --> F
+    E --> F
+```
+
+| Method | Best for |
+| :--- | :--- |
+| Interactive shell (REPL) | Quick experiments, testing one expression |
+| Running a `.py` file | Real programs and scripts |
+| `python -c "code"` | A throwaway one-liner from the terminal |
+| IDE / editor Run button | Day-to-day development |
 
 ### Using the Command Line or Terminal
 
@@ -47,6 +67,29 @@ Once Python is installed, you can run Python code using the command line or term
 4. **Run Your Python Script:**
    Follow the steps mentioned above to navigate to the file's directory in the command line or terminal and run the script.
 
+:::tip
+**Naming `.py` files:** use lowercase letters and underscores (`hello_world.py`, `data_loader.py`). Avoid spaces, and never name a file after a standard library module (e.g. `random.py` or `math.py`) — doing so shadows the real module and causes confusing import errors.
+:::
+
+### Running a One-Liner
+
+For a quick test you do not even need a file. The `-c` flag runs a string of code directly:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python -c "print(2 ** 10)"
+1024
+```
+
+### Running a Module
+
+The `-m` flag runs an installed module as a script. This is how you start common tools:
+
+```bash title="command" showLineNumbers{1}
+python -m venv venv          # create a virtual environment
+python -m pip install requests
+python -m http.server        # start a quick local web server
+```
+
 ## Important Python Commands
 
 ### Interactive Mode
@@ -85,6 +128,10 @@ Hello, World!
 C:\Users\Your Name>
 ```
 
+:::note
+You can also leave the shell with a keyboard shortcut: **`Ctrl + Z` then Enter** on Windows, or **`Ctrl + D`** on macOS/Linux. Both do the same thing as `exit()`.
+:::
+
 ### Running a Python File
 
 - **Run a Python Script:**
diff --git a/src/content/docs/tutorials/Input.mdx b/src/content/docs/tutorials/Input.mdx
index 0fc84b1b..87dfd93a 100644
--- a/src/content/docs/tutorials/Input.mdx
+++ b/src/content/docs/tutorials/Input.mdx
@@ -15,6 +15,20 @@ User input is a crucial component of many Python programs, enabling interaction
 
 The `input()` function is used to receive input from the user. It displays a prompt and waits for the user to enter data. The entered data is then returned as a string.
 
+**Diagram**:
+```mermaid title="how input() works" desc="The flow of reading user input"
+graph LR
+    A[Show prompt] --> B[Wait for user to type + press Enter]
+    B --> C[Return the text as a str]
+    C --> D{Need a number?}
+    D -->|Yes| E[Convert with int / float]
+    D -->|No| F[Use the string directly]
+```
+
+:::caution
+`input()` **always** returns a `str`, even if the user types digits. `input()` plus arithmetic without converting first leads to bugs: `"5" + "3"` is `"53"`, not `8`. Wrap it in `int()` or `float()` when you need a number.
+:::
+
 The syntax of the `input()` function is as follows:
 
 ```python title="input.py" showLineNumbers{1}
@@ -109,6 +123,31 @@ Enter your height in meters: 1.75
 
 In this example, `int()` and `float()` functions are used to convert the user input to integer and float data types, respectively.
 
+## Reading Multiple Values at Once
+
+To read several values from a single line, use `str.split()` to break the input on whitespace (or any separator). Combine it with `map()` to convert them all in one step.
+
+```python title="multi_input.py" showLineNumbers{1} {1-6}
+# User types: 3 7 1 9
+numbers = input("Enter numbers separated by spaces: ").split()
+print(numbers)                       # ['3', '7', '1', '9']  (strings)
+
+# Convert every item to int
+numbers = list(map(int, input("Enter numbers: ").split()))
+print(sum(numbers))                  # 20
+```
+
+Unpacking works too, when you know exactly how many values to expect:
+
+```python title="unpack_input.py" showLineNumbers{1} {1-2}
+x, y = input("Enter two values: ").split(",")   # split on a comma
+print(x, y)
+```
+
+:::tip
+User input often has stray spaces. Clean it with `.strip()` before using it: `name = input("Name: ").strip()`.
+:::
+
 ## Handling User Input Validation
 
 Ensuring that the user provides valid input is crucial for the robustness of your program. Using conditional statements and exception handling, you can validate and handle potential errors gracefully:
diff --git a/src/content/docs/tutorials/Installation.mdx b/src/content/docs/tutorials/Installation.mdx
index 887c6f35..e15b9057 100644
--- a/src/content/docs/tutorials/Installation.mdx
+++ b/src/content/docs/tutorials/Installation.mdx
@@ -17,6 +17,14 @@ Visit the official Python website at [python.org](https://www.python.org/) to do
 
 - **Linux:** Most Linux distributions come with Python pre-installed. If not, use your package manager to install Python.
 
+:::danger
+On **Windows**, the installer shows a checkbox labelled **"Add Python to PATH"** on the first screen. **Tick it** before clicking Install. Without it, the `python` and `pip` commands will not be recognised in the terminal, and you will see `'python' is not recognized as an internal or external command`.
+:::
+
+:::tip
+On macOS you can also install Python with [Homebrew](https://brew.sh/) (`brew install python`), and on Linux with your package manager (`sudo apt install python3` on Debian/Ubuntu). These keep Python easy to upgrade later.
+:::
+
 ## Step 2: Verify Installation
 
 Once the installation is complete, it's essential to verify that Python has been installed correctly. Open a command prompt (or terminal) and enter the following command:
@@ -27,6 +35,32 @@ python --version
 
 You should see the Python version number displayed, indicating a successful installation.
 
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python --version
+Python 3.12.2
+```
+
+:::note
+On Windows, if `python` does not work, try the **Python launcher** `py`:
+```cmd title="command" showLineNumbers{1}
+py --version
+```
+On macOS/Linux the command is often `python3` (and `pip3`) to avoid clashing with an old system Python 2.
+:::
+
+Also confirm that **pip**, Python's package installer, came along with it:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> pip --version
+pip 24.0 from C:\...\site-packages\pip (python 3.12)
+```
+
+It is good practice to upgrade pip right away:
+
+```bash title="command" showLineNumbers{1}
+python -m pip install --upgrade pip
+```
+
 ## Step 3: Install a Code Editor (Optional)
 
 While Python can be written and run using a simple text editor, using a dedicated code editor can enhance your development experience. Choose a code editor that suits your preferences; popular choices include:
@@ -37,6 +71,16 @@ While Python can be written and run using a simple text editor, using a dedicate
 
 ## Step 4: Set Up a Virtual Environment (Optional but Recommended)
 
+A **virtual environment** is an isolated folder that holds its own copy of Python and its own installed packages. Each project gets its own, so upgrading a library for one project never breaks another. This is the single most important habit for a clean Python setup.
+
+**Diagram**:
+```mermaid title="why use a virtual environment" desc="Isolated dependencies per project"
+graph TD
+    A[Global Python] --> B[Project A venv: pandas 1.5]
+    A --> C[Project B venv: pandas 2.2]
+    A --> D[Project C venv: no extras]
+```
+
 To manage project dependencies and ensure a clean development environment, consider setting up a virtual environment. In your project directory, run:
 
 ```bash title="command" showLineNumbers{1}
@@ -54,6 +98,18 @@ Activate the virtual environment:
   source venv/bin/activate
   ```
 
+Once activated, your prompt shows `(venv)`. Install packages with pip, record them in a `requirements.txt`, and run `deactivate` when finished:
+
+```bash title="command" showLineNumbers{1}
+pip install requests
+pip freeze > requirements.txt   # save the exact versions
+deactivate                      # leave the environment
+```
+
+:::tip
+Commit `requirements.txt` (not the `venv/` folder) to version control. Anyone can then recreate the exact environment with `pip install -r requirements.txt`.
+:::
+
 ## Step 5: Ready to Code!
 
 With Python installed and your development environment set up, you're now ready to explore the tutorials and projects on Python Central Hub. Start with our [Introduction to Python](/tutorials/introduction/) tutorial to kick off your Python journey!
diff --git a/src/content/docs/tutorials/Introduction.mdx b/src/content/docs/tutorials/Introduction.mdx
index e0fcfeb1..4296d5ba 100644
--- a/src/content/docs/tutorials/Introduction.mdx
+++ b/src/content/docs/tutorials/Introduction.mdx
@@ -7,9 +7,55 @@ sidebar:
 
 import DataCampExercise from "../../../components/DataCampExercise.astro";
 
+## What is Python?
+
+Python is a **high-level, interpreted, general-purpose** programming language. Each of those words means something concrete:
+
+- **High-level** — you work with human-friendly concepts (lists, dictionaries, objects) instead of memory addresses and registers.
+- **Interpreted** — code runs line by line through the Python interpreter; there is no separate compile step you manage by hand.
+- **General-purpose** — the same language powers websites, data pipelines, automation scripts, games, and AI models.
+- **Dynamically typed** — you do not declare variable types; Python figures them out at runtime.
+
+```python title="hello.py" showLineNumbers{1}
+print("Hello, World!")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python hello.py
+Hello, World!
+```
+
+That single line is a complete Python program. The same idea in C or Java needs imports, a class, and a `main` function — Python's brevity is exactly why beginners and experts alike reach for it.
+
 ## History of Python
 
-Python, a high-level programming language known for its readability and versatility, was conceived by Guido van Rossum in the late 1980s. The first official Python release, Python 0.9.0, occurred in 1991. Over the years, Python has evolved through multiple versions, with Python 3 being the latest major release. The language's design philosophy prioritizes code readability and ease of use, making it a favorite among developers for various applications.
+Python, a high-level programming language known for its readability and versatility, was conceived by **Guido van Rossum** in the late 1980s at CWI in the Netherlands. He named it after the British comedy group *Monty Python*, not the snake. The first official release, Python 0.9.0, arrived in 1991. Over the years, Python has evolved through multiple versions, with Python 3 being the current major release. The language's design philosophy prioritizes code readability and ease of use, making it a favorite among developers for various applications.
+
+**Diagram**:
+```mermaid title="Python release timeline" desc="Major milestones in Python's history"
+graph LR
+    A[1991: Python 0.9.0] --> B[2000: Python 2.0]
+    B --> C[2008: Python 3.0]
+    C --> D[2020: Python 2 end-of-life]
+    D --> E[Today: Python 3.x]
+```
+
+### Python 2 vs. Python 3
+
+Python 2 reached **end-of-life in 2020** and no longer receives updates. All new projects should use Python 3. A few visible differences:
+
+| Feature | Python 2 | Python 3 |
+| :--- | :--- | :--- |
+| `print` | statement: `print "hi"` | function: `print("hi")` |
+| Division `5 / 2` | `2` (integer) | `2.5` (float) |
+| Strings | ASCII by default | Unicode by default |
+| Status | Dead (no support) | Actively developed |
+
+:::caution
+If you find old tutorials using `print "hello"` (no parentheses), they are Python 2 and will not run on a modern interpreter. Everything on Python Central Hub uses Python 3.
+:::
 
 ## Usage of Python
 
@@ -67,6 +113,54 @@ With libraries like Tkinter, Python enables the development of cross-platform de
 
 Python's networking capabilities make it a preferred language for developing networking tools and applications.
 
+## How Python Code Runs
+
+When you run a Python file, the interpreter does not execute your text directly. It first compiles your source code into **bytecode** (a lower-level, platform-independent representation), then the **Python Virtual Machine (PVM)** executes that bytecode. This all happens automatically.
+
+**Diagram**:
+```mermaid title="Python execution model" desc="How source code becomes running output"
+graph LR
+    A[Source code: hello.py] --> B[Compiler]
+    B --> C[Bytecode: .pyc]
+    C --> D[Python Virtual Machine]
+    D --> E[Output]
+```
+
+The reference implementation of Python is called **CPython** (written in C). Other implementations exist — **PyPy** (faster, with a just-in-time compiler), **Jython** (runs on the Java JVM), and **MicroPython** (for microcontrollers).
+
+## The Interactive Shell (REPL)
+
+Beyond running files, Python ships with an interactive shell — the **REPL** (Read–Eval–Print Loop). Type `python` in your terminal and experiment line by line:
+
+```cmd title="command" showLineNumbers{1} {2,4,6}
+C:\Users\Your Name> python
+>>> 2 + 3
+5
+>>> name = "Python"
+>>> print("Hello,", name)
+Hello, Python
+>>> exit()
+```
+
+The REPL is perfect for testing a small idea before putting it in a file.
+
+## The Zen of Python
+
+Python's design philosophy is captured in a set of guiding aphorisms. Run `import this` to read them all:
+
+```python title="zen.py" showLineNumbers{1}
+import this
+```
+
+A few highlights:
+
+> Beautiful is better than ugly.
+> Explicit is better than implicit.
+> Simple is better than complex.
+> Readability counts.
+
+These principles explain *why* Python looks the way it does — and following them makes your own code more "Pythonic".
+
 ---
 
 ## Try it: Interactive Python Exercises
diff --git a/src/content/docs/tutorials/Modern Python/Concurrency.mdx b/src/content/docs/tutorials/Modern Python/Concurrency.mdx
new file mode 100644
index 00000000..d6e70cee
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Concurrency.mdx	
@@ -0,0 +1,260 @@
+---
+title: Python Concurrency — threading, multiprocessing, asyncio
+description: A deep dive into Python concurrency. Learn the GIL, threading for I/O, multiprocessing for CPU work, and asyncio with async/await — when to use each, with examples and practice exercises.
+sidebar:
+  order: 2
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+Concurrency means making progress on **more than one task at a time**. Python offers three approaches, each suited to a different kind of work:
+
+| Approach | Best for | Why |
+|:---|:---|:---|
+| **threading** | I/O-bound work (network, disk) | Threads wait together; cheap to create. |
+| **multiprocessing** | CPU-bound work (number crunching) | Separate processes use multiple cores. |
+| **asyncio** | Many I/O tasks at once | One thread, cooperative `await`, very scalable. |
+
+## The GIL — why it matters
+
+CPython has a **Global Interpreter Lock (GIL)**: only one thread executes Python bytecode at a time. So threads **don't** speed up CPU-bound code — but they're great for I/O, where threads spend most time *waiting* (and release the GIL while waiting). For CPU-bound parallelism, use **multiprocessing**, which sidesteps the GIL with separate processes.
+
+> Rule of thumb: **I/O-bound → threading or asyncio. CPU-bound → multiprocessing.**
+
+## threading
+
+Run functions in separate threads. Start them, then `join` to wait for completion.
+
+```python title="threading_basic.py"
+import threading
+import time
+
+def worker(name):
+    print(f"{name} starting")
+    time.sleep(1)               # simulates an I/O wait
+    print(f"{name} done")
+
+threads = [threading.Thread(target=worker, args=(f"T{i}",)) for i in range(3)]
+for t in threads:
+    t.start()                   # begin running concurrently
+for t in threads:
+    t.join()                    # wait for each to finish
+print("all done")
+```
+
+Because the threads sleep concurrently, three 1-second waits finish in about **1 second**, not 3.
+
+### Sharing data safely with a Lock
+
+When threads modify shared state, guard it with a `Lock` to avoid race conditions.
+
+```python title="lock.py"
+import threading
+
+counter = 0
+lock = threading.Lock()
+
+def increment():
+    global counter
+    for _ in range(100_000):
+        with lock:              # only one thread at a time
+            counter += 1
+
+ts = [threading.Thread(target=increment) for _ in range(2)]
+for t in ts: t.start()
+for t in ts: t.join()
+print(counter)                  # 200000 (correct, thanks to the lock)
+```
+
+## concurrent.futures — a simpler interface
+
+`ThreadPoolExecutor` / `ProcessPoolExecutor` manage a pool of workers and collect results for you.
+
+```python title="executor.py"
+from concurrent.futures import ThreadPoolExecutor
+
+def square(n):
+    return n * n
+
+with ThreadPoolExecutor(max_workers=4) as pool:
+    results = list(pool.map(square, [1, 2, 3, 4, 5]))
+print(results)                  # [1, 4, 9, 16, 25]
+```
+
+Swap `ThreadPoolExecutor` for `ProcessPoolExecutor` to run CPU-bound work across cores — the API is identical.
+
+## multiprocessing
+
+Each process has its own Python interpreter and memory, so they run truly in parallel on multiple cores.
+
+```python title="multiprocessing_basic.py"
+from multiprocessing import Pool
+
+def heavy(n):
+    return sum(i * i for i in range(n))
+
+if __name__ == "__main__":          # required guard on Windows/macOS
+    with Pool(processes=4) as pool:
+        results = pool.map(heavy, [10_000, 20_000, 30_000])
+    print(results)
+```
+
+> Always wrap multiprocessing entry code in `if __name__ == "__main__":` — without it, spawned processes re-import and re-run your script.
+
+## asyncio — async/await
+
+`asyncio` runs many I/O tasks on a **single thread** using cooperative multitasking. An `async def` function is a **coroutine**; `await` yields control while waiting, letting other coroutines run.
+
+```python title="asyncio_basic.py"
+import asyncio
+
+async def fetch(name, delay):
+    print(f"{name} start")
+    await asyncio.sleep(delay)      # non-blocking wait
+    print(f"{name} done")
+    return name
+
+async def main():
+    # Run three coroutines concurrently
+    results = await asyncio.gather(
+        fetch("A", 1),
+        fetch("B", 1),
+        fetch("C", 1),
+    )
+    print(results)
+
+asyncio.run(main())                 # entry point
+```
+
+All three "fetches" overlap, so the total time is about **1 second**, not 3.
+
+### Key asyncio pieces
+
+| Piece | Purpose |
+|:---|:---|
+| `async def` | Defines a coroutine. |
+| `await x` | Wait for an awaitable without blocking the thread. |
+| `asyncio.run(coro)` | Run the top-level coroutine. |
+| `asyncio.gather(*coros)` | Run many coroutines concurrently, collect results. |
+| `asyncio.create_task(coro)` | Schedule a coroutine to run in the background. |
+| `asyncio.sleep(s)` | Non-blocking sleep. |
+
+## Choosing the right tool
+
+```text title="decision.txt"
+Is the work CPU-bound (math, parsing, compression)?
+   -> multiprocessing (use all cores, beat the GIL)
+
+Is the work I/O-bound (HTTP, files, DB)?
+   A few tasks, simple code?      -> threading / ThreadPoolExecutor
+   Hundreds/thousands of tasks?   -> asyncio
+```
+
+## Common pitfalls
+
+- **Threads won't speed up CPU work** — the GIL serializes them; use multiprocessing.
+- **Forgetting `join`** — the main program may exit before threads finish.
+- **Unguarded shared state** — use a `Lock` around shared mutable data.
+- **Blocking calls inside asyncio** — `time.sleep` or heavy CPU work freezes the whole event loop; use `await asyncio.sleep` and run CPU work in an executor.
+- **Missing `if __name__ == "__main__":`** — breaks multiprocessing on Windows/macOS.
+
+## Practice Exercises
+
+### Exercise 1 – Run work in threads
+
+<DataCampExercise
+  lang="python"
+  hint={`Call t.start() to begin a thread and t.join() to wait for it.`}
+  code={`# Task: Start the thread and wait for it to finish.
+import threading
+
+def task():
+    print("working")
+
+t = threading.Thread(target=task)
+t.___()      # begin running
+t.join()     # wait for completion
+print("finished")
+
+# Expected Output:
+# working
+# finished`}
+  solution={`import threading
+
+def task():
+    print("working")
+
+t = threading.Thread(target=task)
+t.start()
+t.join()
+print("finished")`}
+  sct={`test_output_contains("finished")
+success_msg("start() launches the thread; join() waits for it.")`}
+  height={190}
+/>
+
+### Exercise 2 – Define and run a coroutine
+
+<DataCampExercise
+  lang="python"
+  hint={`Use 'async def' to define the coroutine and asyncio.run to start it.`}
+  code={`# Task: Complete the async function and run it with asyncio.run.
+import asyncio
+
+___ def main():
+    await asyncio.sleep(0)
+    print("hello from async")
+
+asyncio.run(main())
+
+# Expected Output:
+# hello from async`}
+  solution={`import asyncio
+
+async def main():
+    await asyncio.sleep(0)
+    print("hello from async")
+
+asyncio.run(main())`}
+  sct={`test_output_contains("hello from async")
+success_msg("async def creates a coroutine; asyncio.run drives it.")`}
+  height={180}
+/>
+
+### Exercise 3 – Map work over a thread pool
+
+<DataCampExercise
+  lang="python"
+  hint={`Use pool.map(func, iterable) to apply the function to every item.`}
+  code={`# Task: Square each number using a ThreadPoolExecutor.
+from concurrent.futures import ThreadPoolExecutor
+
+def square(n):
+    return n * n
+
+with ThreadPoolExecutor() as pool:
+    results = list(pool.___(square, [1, 2, 3, 4]))
+print(results)
+
+# Expected Output:
+# [1, 4, 9, 16]`}
+  solution={`from concurrent.futures import ThreadPoolExecutor
+
+def square(n):
+    return n * n
+
+with ThreadPoolExecutor() as pool:
+    results = list(pool.map(square, [1, 2, 3, 4]))
+print(results)`}
+  sct={`test_output_contains("[1, 4, 9, 16]")
+success_msg("pool.map runs the function across worker threads.")`}
+  height={190}
+/>
+
+## Summary
+
+- The **GIL** means threads don't parallelize CPU work — they shine for I/O.
+- **threading** + `Lock` for simple concurrent I/O; **`concurrent.futures`** for pools and results.
+- **multiprocessing** for CPU-bound parallelism across cores (guard with `__main__`).
+- **asyncio** (`async`/`await`, `gather`, `run`) scales to many concurrent I/O tasks on one thread.
+- Match the tool to the workload: CPU → processes, I/O → threads/async.
diff --git a/src/content/docs/tutorials/Modern Python/Dataclasses.mdx b/src/content/docs/tutorials/Modern Python/Dataclasses.mdx
new file mode 100644
index 00000000..e532182d
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Dataclasses.mdx	
@@ -0,0 +1,268 @@
+---
+title: Python Dataclasses (@dataclass)
+description: A deep dive into Python dataclasses. Learn how @dataclass auto-generates __init__, __repr__, and __eq__, plus defaults, default_factory, frozen and ordered classes, post-init, and asdict — with examples and practice exercises.
+sidebar:
+  order: 5
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+A **dataclass** is a class that mainly stores data. The `@dataclass` decorator (from the `dataclasses` module, Python 3.7+) writes the boilerplate for you: `__init__`, `__repr__`, `__eq__`, and more — generated from the field annotations.
+
+```python title="quickstart.py"
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+p = Point(3, 4)
+print(p)            # Point(x=3, y=4)   <- free __repr__
+print(p.x, p.y)     # 3 4
+print(p == Point(3, 4))   # True        <- free __eq__
+```
+
+## What it generates for you
+
+Without dataclasses, that `Point` would need a hand-written `__init__`, `__repr__`, and `__eq__`. The decorator generates them from the annotated fields:
+
+| You write | `@dataclass` generates |
+|:---|:---|
+| `x: int` | A parameter in `__init__` and an attribute. |
+| (nothing) | `__repr__` → `Point(x=3, y=4)`. |
+| (nothing) | `__eq__` → field-by-field equality. |
+| `order=True` | `<`, `<=`, `>`, `>=` comparisons. |
+| `frozen=True` | Immutable, hashable instances. |
+
+## Default values
+
+Give fields defaults just like function parameters. Fields with defaults must come **after** those without.
+
+```python title="defaults.py"
+from dataclasses import dataclass
+
+@dataclass
+class User:
+    name: str
+    active: bool = True
+    role: str = "member"
+
+print(User("Ada"))                  # User(name='Ada', active=True, role='member')
+print(User("Bo", role="admin"))    # User(name='Bo', active=True, role='admin')
+```
+
+## Mutable defaults — use default_factory
+
+You **cannot** use a mutable default (like `[]` or `{}`) directly — it would be shared across all instances. Use `field(default_factory=...)`.
+
+```python title="default_factory.py"
+from dataclasses import dataclass, field
+
+@dataclass
+class Cart:
+    items: list = field(default_factory=list)   # a fresh list per instance
+    tags: dict = field(default_factory=dict)
+
+a = Cart()
+a.items.append("apple")
+b = Cart()
+print(a.items)   # ['apple']
+print(b.items)   # []   <- not shared, thanks to default_factory
+```
+
+> Writing `items: list = []` raises a `ValueError` in dataclasses precisely to prevent the shared-mutable-default bug.
+
+## Frozen (immutable) dataclasses
+
+`frozen=True` makes instances read-only and hashable — usable as dict keys or set members.
+
+```python title="frozen.py"
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Coord:
+    lat: float
+    lon: float
+
+c = Coord(51.5, -0.1)
+print(c)                 # Coord(lat=51.5, lon=-0.1)
+locations = {c: "London"}   # works: frozen instances are hashable
+# c.lat = 0.0            # would raise FrozenInstanceError
+```
+
+## Ordered dataclasses
+
+`order=True` adds comparison operators based on the fields (compared as a tuple, top to bottom).
+
+```python title="order.py"
+from dataclasses import dataclass
+
+@dataclass(order=True)
+class Version:
+    major: int
+    minor: int
+
+versions = [Version(2, 0), Version(1, 5), Version(1, 9)]
+print(sorted(versions))
+# [Version(major=1, minor=5), Version(major=1, minor=9), Version(major=2, minor=0)]
+```
+
+## __post_init__ — validation and derived fields
+
+`__post_init__` runs right after the generated `__init__`, perfect for validation or computing derived values.
+
+```python title="post_init.py"
+from dataclasses import dataclass
+
+@dataclass
+class Rectangle:
+    width: float
+    height: float
+    area: float = 0.0
+
+    def __post_init__(self):
+        if self.width < 0 or self.height < 0:
+            raise ValueError("dimensions must be non-negative")
+        self.area = self.width * self.height
+
+r = Rectangle(3, 4)
+print(r.area)    # 12.0
+```
+
+## Converting to dict or tuple
+
+```python title="asdict.py"
+from dataclasses import dataclass, asdict, astuple
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+p = Point(1, 2)
+print(asdict(p))    # {'x': 1, 'y': 2}
+print(astuple(p))   # (1, 2)
+```
+
+## When to use what
+
+| Need | Use |
+|:---|:---|
+| A mutable record with methods | **`@dataclass`** |
+| An immutable, hashable record | `@dataclass(frozen=True)` |
+| A tiny immutable record, tuple-like | `namedtuple` |
+| Arbitrary, schemaless data | a plain `dict` |
+
+## Common pitfalls
+
+- **Mutable defaults** — never `x: list = []`; use `field(default_factory=list)`.
+- **Field order** — non-default fields must precede default ones.
+- **Equality is field-based** — two instances with equal fields are `==` (usually what you want).
+- **`frozen=True` blocks attribute assignment** — set everything via `__init__`/`__post_init__`.
+
+## Practice Exercises
+
+### Exercise 1 – Define a dataclass
+
+<DataCampExercise
+  lang="python"
+  hint={`Decorate the class with @dataclass and annotate the fields.`}
+  code={`# Task: Make Book a dataclass with title and pages, then print an instance.
+from dataclasses import dataclass
+
+@___
+class Book:
+    title: str
+    pages: int
+
+print(Book("Dune", 412))
+
+# Expected Output:
+# Book(title='Dune', pages=412)`}
+  solution={`from dataclasses import dataclass
+
+@dataclass
+class Book:
+    title: str
+    pages: int
+
+print(Book("Dune", 412))`}
+  sct={`test_output_contains("Book(title='Dune', pages=412)")
+success_msg("@dataclass generated __init__ and __repr__ for you.")`}
+  height={190}
+/>
+
+### Exercise 2 – Safe mutable default
+
+<DataCampExercise
+  lang="python"
+  hint={`Use field(default_factory=list) so each instance gets its own list.`}
+  code={`# Task: Give 'items' a per-instance default list using default_factory.
+from dataclasses import dataclass, field
+
+@dataclass
+class Cart:
+    items: list = field(default_factory=___)
+
+c = Cart()
+c.items.append("apple")
+print(c.items)
+print(Cart().items)
+
+# Expected Output:
+# ['apple']
+# []`}
+  solution={`from dataclasses import dataclass, field
+
+@dataclass
+class Cart:
+    items: list = field(default_factory=list)
+
+c = Cart()
+c.items.append("apple")
+print(c.items)
+print(Cart().items)`}
+  sct={`test_output_contains("['apple']")
+test_output_contains("[]")
+success_msg("default_factory gives each instance a fresh list.")`}
+  height={210}
+/>
+
+### Exercise 3 – Convert to a dict
+
+<DataCampExercise
+  lang="python"
+  hint={`Import asdict from dataclasses and call asdict(instance).`}
+  code={`# Task: Convert a dataclass instance to a dict with asdict.
+from dataclasses import dataclass, ___
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+print(asdict(Point(1, 2)))
+
+# Expected Output:
+# {'x': 1, 'y': 2}`}
+  solution={`from dataclasses import dataclass, asdict
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+print(asdict(Point(1, 2)))`}
+  sct={`test_output_contains("{'x': 1, 'y': 2}")
+success_msg("asdict turns a dataclass into a plain dictionary.")`}
+  height={190}
+/>
+
+## Summary
+
+- `@dataclass` auto-generates `__init__`, `__repr__`, and `__eq__` from field annotations.
+- Use defaults like function parameters; use `field(default_factory=...)` for mutable defaults.
+- `frozen=True` makes immutable, hashable records; `order=True` adds comparisons.
+- `__post_init__` validates or computes derived fields; `asdict`/`astuple` convert instances.
+- Reach for dataclasses whenever a class is mostly structured data.
diff --git a/src/content/docs/tutorials/Modern Python/F-Strings Deep Dive.mdx b/src/content/docs/tutorials/Modern Python/F-Strings Deep Dive.mdx
new file mode 100644
index 00000000..45fd3372
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/F-Strings Deep Dive.mdx	
@@ -0,0 +1,209 @@
+---
+title: Python f-strings Deep Dive
+description: An in-depth guide to Python f-strings — embedded expressions, the format spec mini-language (alignment, width, precision, thousands, number bases), the = debug specifier, conversions, and nesting. With examples and practice exercises.
+sidebar:
+  order: 7
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+**f-strings** (formatted string literals, PEP 498, Python 3.6+) are the fastest and most readable way to build strings. Prefix a string with `f` and embed expressions in `{}`. This page goes deep into formatting; for the broader picture of `%`, `.format()`, and templates, see [String Formatting](../../python-strings/formatting-string/).
+
+```python title="quickstart.py"
+name = "Ada"
+age = 36
+print(f"{name} is {age}")          # Ada is 36
+print(f"Next year: {age + 1}")     # Next year: 37  (any expression works)
+```
+
+## Expressions, not just variables
+
+Anything that evaluates to a value can go inside the braces — arithmetic, method calls, indexing, conditionals.
+
+```python title="expressions.py"
+items = ["a", "b", "c"]
+print(f"{len(items)} items")          # 3 items
+print(f"upper: {'hi'.upper()}")       # upper: HI
+print(f"first: {items[0]}")           # first: a
+print(f"{'even' if 4 % 2 == 0 else 'odd'}")  # even
+```
+
+## The format spec mini-language
+
+After a colon inside the braces comes a **format spec** that controls width, alignment, precision, and type. The general shape is:
+
+```text title="spec.txt"
+{value:[fill][align][sign][width][,][.precision][type]}
+```
+
+### Number precision
+
+```python title="precision.py"
+pi = 3.14159265
+print(f"{pi:.2f}")     # 3.14    (2 decimal places)
+print(f"{pi:.0f}")     # 3       (no decimals)
+print(f"{1/3:.4f}")    # 0.3333
+```
+
+### Width, alignment, and fill
+
+| Spec | Meaning |
+|:---|:---|
+| `:<10` | Left-align in width 10. |
+| `:>10` | Right-align in width 10. |
+| `:^10` | Center in width 10. |
+| `:*^10` | Center, padding with `*`. |
+| `:08` | Zero-pad to width 8. |
+
+```python title="align.py"
+print(f"{'hi':<6}|")    # hi    |
+print(f"{'hi':>6}|")    # |    hi  -> right aligned
+print(f"{'hi':^6}|")    # |  hi  |
+print(f"{42:08}")        # 00000042
+print(f"{'x':*^7}")      # ***x***
+```
+
+### Thousands separators and percent
+
+```python title="numbers.py"
+print(f"{1000000:,}")        # 1,000,000
+print(f"{1234.5:,.2f}")      # 1,234.50
+print(f"{0.1234:.1%}")       # 12.3%   (percent with 1 decimal)
+print(f"{255:#x}")           # 0xff    (hex with prefix)
+```
+
+### Number bases
+
+| Type | Base |
+|:---|:---|
+| `:b` | Binary |
+| `:o` | Octal |
+| `:x` / `:X` | Hex (lower/upper) |
+| `:e` | Scientific notation |
+
+```python title="bases.py"
+n = 255
+print(f"{n:b}")    # 11111111
+print(f"{n:o}")    # 377
+print(f"{n:x}")    # ff
+print(f"{12345.678:.2e}")   # 1.23e+04
+```
+
+## The `=` debug specifier (3.8+)
+
+Add `=` inside the braces to print **both the expression and its value** — perfect for quick debugging.
+
+```python title="debug.py"
+x = 10
+y = 3
+print(f"{x=}")          # x=10
+print(f"{x + y=}")      # x + y=13
+print(f"{x / y=:.2f}")  # x / y=3.33   (combine with a format spec)
+```
+
+## Conversions: !r, !s, !a
+
+Apply `repr()`, `str()`, or `ascii()` before formatting with `!r`, `!s`, `!a`.
+
+```python title="conversions.py"
+name = "Ada"
+print(f"{name!r}")    # 'Ada'   (repr -> shows quotes)
+print(f"{name!s}")    # Ada     (str)
+```
+
+## Nesting and dynamic specs
+
+Braces can contain expressions that themselves come from variables — even the format spec.
+
+```python title="nesting.py"
+value = 3.14159
+places = 3
+print(f"{value:.{places}f}")   # 3.142  (precision taken from a variable)
+
+width = 10
+print(f"{'hi':>{width}}")      # right-align in a width from a variable
+```
+
+## Multiline f-strings and escaping braces
+
+```python title="multiline_escape.py"
+name, role = "Ada", "admin"
+msg = (
+    f"User: {name}\n"
+    f"Role: {role}"
+)
+print(msg)
+
+# To print literal braces, double them
+print(f"{{not a placeholder}} but {name}")   # {not a placeholder} but Ada
+```
+
+## Common pitfalls
+
+- **Forgetting the `f`** — `"{x}"` prints the braces literally; `f"{x}"` substitutes.
+- **Literal braces need doubling** — `{{` and `}}` to print `{` and `}`.
+- **Quote clashes** — don't reuse the outer quote inside (or use the other quote): `f"{d['key']}"`.
+- **Heavy logic in braces hurts readability** — compute first, then format.
+
+## Practice Exercises
+
+### Exercise 1 – Two decimal places
+
+<DataCampExercise
+  lang="python"
+  hint={`Use the :.2f format spec inside the braces.`}
+  code={`# Task: Format pi to exactly two decimal places.
+pi = 3.14159
+print(f"{pi:___}")
+
+# Expected Output:
+# 3.14`}
+  solution={`pi = 3.14159
+print(f"{pi:.2f}")`}
+  sct={`test_output_contains("3.14")
+success_msg(".2f rounds to two decimal places.")`}
+  height={150}
+/>
+
+### Exercise 2 – Thousands separator
+
+<DataCampExercise
+  lang="python"
+  hint={`Put a comma in the format spec: {value:,}.`}
+  code={`# Task: Print the number with thousands separators.
+amount = 1234567
+print(f"{amount:___}")
+
+# Expected Output:
+# 1,234,567`}
+  solution={`amount = 1234567
+print(f"{amount:,}")`}
+  sct={`test_output_contains("1,234,567")
+success_msg("The , format spec groups digits by thousands.")`}
+  height={150}
+/>
+
+### Exercise 3 – The debug specifier
+
+<DataCampExercise
+  lang="python"
+  hint={`Add an = sign right after the expression inside the braces.`}
+  code={`# Task: Use the = debug specifier to print both name and value.
+score = 95
+print(f"{score___}")
+
+# Expected Output:
+# score=95`}
+  solution={`score = 95
+print(f"{score=}")`}
+  sct={`test_output_contains("score=95")
+success_msg("The = specifier prints 'expr=value', great for debugging.")`}
+  height={150}
+/>
+
+## Summary
+
+- f-strings embed any expression in `{}` and are the fastest, clearest way to format strings.
+- The format spec (`:[fill][align][sign][width][,][.precision][type]`) controls precision, padding, separators, and number bases.
+- `{expr=}` prints the expression and its value — handy for debugging.
+- Use `!r`/`!s`/`!a` for conversions, nest `{...}` for dynamic specs, and double `{{ }}` for literal braces.
diff --git a/src/content/docs/tutorials/Modern Python/Networking.mdx b/src/content/docs/tutorials/Modern Python/Networking.mdx
new file mode 100644
index 00000000..f661305f
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Networking.mdx	
@@ -0,0 +1,224 @@
+---
+title: Python Networking — requests, urllib & sockets
+description: A practical guide to networking in Python. Make HTTP calls with requests and urllib, build and parse URLs with urllib.parse, and understand low-level TCP sockets. With examples and practice exercises.
+sidebar:
+  order: 4
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+Networking in Python spans two levels: **high-level HTTP** (talking to web APIs and sites) and **low-level sockets** (raw TCP/UDP connections). Most apps live at the HTTP level.
+
+| Tool | Level | Notes |
+|:---|:---|:---|
+| `requests` | High (HTTP) | Third-party, the de-facto standard. `pip install requests`. |
+| `urllib.request` | High (HTTP) | Built in; more verbose, no install needed. |
+| `urllib.parse` | Helper | Build and parse URLs (pure, no network). |
+| `socket` | Low (TCP/UDP) | Raw connections; build your own protocols. |
+
+## requests — the friendly HTTP client
+
+`requests` makes HTTP calls readable. Install it first (`pip install requests`).
+
+```python title="requests_get.py"
+import requests
+
+resp = requests.get("https://api.example.com/users", params={"page": 2})
+print(resp.status_code)     # 200
+print(resp.headers["Content-Type"])
+data = resp.json()          # parse a JSON body into Python
+print(data)
+```
+
+```python title="requests_post.py"
+import requests
+
+# Send JSON in the body
+resp = requests.post(
+    "https://api.example.com/users",
+    json={"name": "Ada", "role": "admin"},
+    headers={"Authorization": "Bearer TOKEN"},
+    timeout=10,
+)
+resp.raise_for_status()     # raise if status is 4xx/5xx
+print(resp.json())
+```
+
+| `requests` piece | Purpose |
+|:---|:---|
+| `requests.get/post/put/delete` | The HTTP verbs. |
+| `params={...}` | Query-string parameters. |
+| `json={...}` | Send a JSON body. |
+| `headers={...}` | Custom request headers. |
+| `resp.status_code` | The HTTP status (200, 404, ...). |
+| `resp.json()` / `resp.text` | Parsed JSON / raw text. |
+| `resp.raise_for_status()` | Turn error statuses into exceptions. |
+| `timeout=` | Fail fast instead of hanging forever. |
+
+## urllib — the standard-library option
+
+When you can't add dependencies, `urllib.request` does the same job with more ceremony.
+
+```python title="urllib_get.py"
+import urllib.request
+import json
+
+req = urllib.request.Request(
+    "https://api.example.com/data",
+    headers={"User-Agent": "my-app"},
+)
+with urllib.request.urlopen(req, timeout=10) as resp:
+    body = resp.read().decode("utf-8")
+    data = json.loads(body)
+print(data)
+```
+
+## urllib.parse — build and parse URLs
+
+This part of `urllib` is pure (no network) and extremely useful for assembling query strings and dissecting URLs.
+
+```python title="urllib_parse.py"
+from urllib.parse import urlencode, urlparse, parse_qs
+
+# Build a query string from a dict
+qs = urlencode({"q": "python", "page": 2})
+print(qs)                     # q=python&page=2
+
+# Dissect a URL
+parts = urlparse("https://example.com/search?q=python&page=2")
+print(parts.scheme)           # https
+print(parts.netloc)           # example.com
+print(parts.path)             # /search
+print(parse_qs(parts.query))  # {'q': ['python'], 'page': ['2']}
+```
+
+## socket — low-level TCP
+
+For custom protocols or learning how the network really works, use raw sockets. Here's a minimal echo server and client.
+
+```python title="tcp_server.py"
+import socket
+
+server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+server.bind(("127.0.0.1", 9000))
+server.listen()
+print("listening on 9000")
+
+conn, addr = server.accept()      # blocks until a client connects
+with conn:
+    data = conn.recv(1024)        # read up to 1024 bytes
+    conn.sendall(data)            # echo it back
+```
+
+```python title="tcp_client.py"
+import socket
+
+with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+    s.connect(("127.0.0.1", 9000))
+    s.sendall(b"hello")
+    reply = s.recv(1024)
+print(reply)                      # b'hello'
+```
+
+| socket call | Purpose |
+|:---|:---|
+| `socket(AF_INET, SOCK_STREAM)` | Create a TCP socket. |
+| `bind((host, port))` | Attach a server to an address. |
+| `listen()` / `accept()` | Wait for and accept a connection. |
+| `connect((host, port))` | Client connects to a server. |
+| `sendall(bytes)` / `recv(n)` | Send / receive raw bytes. |
+
+> Sockets speak **bytes**, not strings — encode with `.encode()` and decode with `.decode()`.
+
+## Choosing a level
+
+```text title="decision.txt"
+Talking to a web API or website?   -> requests (or urllib if no installs)
+Just building/parsing a URL?       -> urllib.parse
+Custom protocol / raw TCP/UDP?     -> socket
+```
+
+## Common pitfalls
+
+- **No timeout** — network calls can hang forever; always pass `timeout=`.
+- **Ignoring status codes** — check `resp.status_code` or call `raise_for_status()`.
+- **Sending strings over sockets** — sockets need bytes; encode/decode explicitly.
+- **`requests` isn't built in** — it needs `pip install requests`; `urllib` does not.
+
+## Practice Exercises
+
+These exercises use `urllib.parse`, which runs without any network access.
+
+### Exercise 1 – Build a query string
+
+<DataCampExercise
+  lang="python"
+  hint={`urlencode turns a dict into key=value&key=value form.`}
+  code={`# Task: Build a query string from the params dict.
+from urllib.parse import urlencode
+
+params = {"q": "python", "page": 2}
+print(___(params))
+
+# Expected Output:
+# q=python&page=2`}
+  solution={`from urllib.parse import urlencode
+
+params = {"q": "python", "page": 2}
+print(urlencode(params))`}
+  sct={`test_output_contains("q=python&page=2")
+success_msg("urlencode safely builds the query portion of a URL.")`}
+  height={160}
+/>
+
+### Exercise 2 – Extract the host from a URL
+
+<DataCampExercise
+  lang="python"
+  hint={`urlparse returns an object; the host is in the .netloc attribute.`}
+  code={`# Task: Print the host (netloc) of the URL.
+from urllib.parse import urlparse
+
+parts = urlparse("https://docs.python.org/3/library/urllib.html")
+print(parts.___)
+
+# Expected Output:
+# docs.python.org`}
+  solution={`from urllib.parse import urlparse
+
+parts = urlparse("https://docs.python.org/3/library/urllib.html")
+print(parts.netloc)`}
+  sct={`test_output_contains("docs.python.org")
+success_msg("urlparse splits a URL into scheme, netloc, path, query, etc.")`}
+  height={160}
+/>
+
+### Exercise 3 – Parse query parameters
+
+<DataCampExercise
+  lang="python"
+  hint={`parse_qs returns a dict mapping each key to a list of values.`}
+  code={`# Task: Parse the query string into a dict of lists.
+from urllib.parse import parse_qs
+
+query = "q=python&page=2"
+print(___(query))
+
+# Expected Output:
+# {'q': ['python'], 'page': ['2']}`}
+  solution={`from urllib.parse import parse_qs
+
+query = "q=python&page=2"
+print(parse_qs(query))`}
+  sct={`test_output_contains("'q': ['python']")
+success_msg("parse_qs decodes a query string back into structured data.")`}
+  height={160}
+/>
+
+## Summary
+
+- For HTTP, reach for **`requests`** (clean API) or **`urllib.request`** (built in, verbose).
+- Always set a **`timeout`** and check the **status code**.
+- **`urllib.parse`** builds and dissects URLs with `urlencode`, `urlparse`, and `parse_qs`.
+- **`socket`** gives raw TCP/UDP for custom protocols — remember it speaks bytes.
+- Pick the level that matches the task: APIs → requests, URLs → urllib.parse, raw connections → socket.
diff --git a/src/content/docs/tutorials/Modern Python/Type Hints and typing.mdx b/src/content/docs/tutorials/Modern Python/Type Hints and typing.mdx
new file mode 100644
index 00000000..8d71ab63
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Type Hints and typing.mdx	
@@ -0,0 +1,286 @@
+---
+title: Python Type Hints & the typing Module
+description: A deep dive into Python type hints — List, Dict, Optional, Union, the modern | syntax, Callable, TypeVar generics, type aliases, and static checking with mypy. Includes examples and practice exercises.
+sidebar:
+  order: 1
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+**Type hints** annotate the expected types of variables, parameters, and return values. They don't change how your code runs — Python ignores them at runtime — but they make code self-documenting and let tools like **mypy** catch bugs *before* you run anything. This page goes well beyond basic annotations (see also the [Function Annotations](../../python-function/function-annotations/) page for the basics).
+
+```python title="quickstart.py"
+def greet(name: str, excited: bool = False) -> str:
+    msg = f"Hello, {name}"
+    return msg + "!" if excited else msg
+
+age: int = 30
+pi: float = 3.14159
+names: list[str] = ["Ada", "Bob"]
+```
+
+## Why bother?
+
+- **Documentation that can't drift** — the signature states the contract.
+- **Editor support** — autocomplete and inline errors.
+- **Static checking** — `mypy` flags type mismatches without running the code.
+- **Safer refactors** — change a type, and the checker shows every break.
+
+## Built-in collection generics
+
+Since Python 3.9 you can subscript the built-in containers directly. (Older code imports `List`, `Dict`, etc. from `typing`.)
+
+| Modern (3.9+) | Legacy (`from typing import ...`) | Means |
+|:---|:---|:---|
+| `list[int]` | `List[int]` | A list of ints. |
+| `dict[str, int]` | `Dict[str, int]` | A dict: str keys, int values. |
+| `tuple[int, str]` | `Tuple[int, str]` | A 2-tuple. |
+| `set[str]` | `Set[str]` | A set of strings. |
+| `tuple[int, ...]` | `Tuple[int, ...]` | A tuple of any length of ints. |
+
+```python title="collections.py"
+def total(prices: list[float]) -> float:
+    return sum(prices)
+
+def counts(words: list[str]) -> dict[str, int]:
+    result: dict[str, int] = {}
+    for w in words:
+        result[w] = result.get(w, 0) + 1
+    return result
+```
+
+## Optional and Union
+
+A value that may be `None` is **Optional**. A value that may be one of several types is a **Union**.
+
+```python title="optional_union.py"
+from typing import Optional, Union
+
+# Optional[str] means "str or None"
+def find_user(uid: int) -> Optional[str]:
+    users = {1: "Ada"}
+    return users.get(uid)        # returns str or None
+
+# Union means "any of these types"
+def to_int(x: Union[int, str]) -> int:
+    return int(x)
+```
+
+Since Python 3.10 you can use the cleaner **`|`** syntax:
+
+```python title="pipe_union.py"
+def find_user(uid: int) -> str | None:      # same as Optional[str]
+    ...
+
+def to_int(x: int | str) -> int:            # same as Union[int, str]
+    return int(x)
+```
+
+> `Optional[X]` is exactly `X | None`. It does **not** mean the argument is optional — it means the *value* can be `None`.
+
+## Any, and when to avoid it
+
+`Any` disables type checking for that value — use it sparingly, as it defeats the purpose.
+
+```python title="any.py"
+from typing import Any
+
+def debug(value: Any) -> None:    # accepts literally anything
+    print(repr(value))
+```
+
+## Callable — typing functions
+
+`Callable[[ArgTypes], ReturnType]` describes a function passed as a value.
+
+```python title="callable.py"
+from typing import Callable
+
+def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
+    return func(a, b)
+
+print(apply(lambda x, y: x + y, 3, 4))   # 7
+```
+
+## Type aliases
+
+Give a complex type a readable name.
+
+```python title="aliases.py"
+from typing import Union
+
+# A reusable alias
+Number = Union[int, float]
+Matrix = list[list[float]]
+
+def scale(m: Matrix, factor: Number) -> Matrix:
+    return [[cell * factor for cell in row] for row in m]
+```
+
+## Generics with TypeVar
+
+A **TypeVar** lets you write functions and classes that work for *any* type while preserving the relationship between input and output.
+
+```python title="generics.py"
+from typing import TypeVar
+
+T = TypeVar("T")
+
+def first(items: list[T]) -> T:      # returns the SAME type the list holds
+    return items[0]
+
+x: int = first([1, 2, 3])            # checker knows x is int
+y: str = first(["a", "b"])           # checker knows y is str
+```
+
+Generic **classes** subclass `Generic[T]`:
+
+```python title="generic_class.py"
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+class Box(Generic[T]):
+    def __init__(self, item: T) -> None:
+        self.item = item
+    def get(self) -> T:
+        return self.item
+
+b: Box[int] = Box(42)
+print(b.get())   # 42
+```
+
+## Other handy typing tools
+
+| Tool | Use |
+|:---|:---|
+| `Literal["a", "b"]` | Restrict to specific literal values. |
+| `Final` | Mark a constant that shouldn't be reassigned. |
+| `TypedDict` | A dict with a fixed set of typed keys. |
+| `Sequence` / `Iterable` / `Mapping` | Accept any sequence/iterable/mapping, not just `list`/`dict`. |
+
+```python title="abc_types.py"
+from typing import Iterable
+
+# Accept ANY iterable of ints (list, tuple, generator, ...)
+def total(nums: Iterable[int]) -> int:
+    return sum(nums)
+
+print(total([1, 2, 3]))      # 6
+print(total((4, 5)))         # 9
+```
+
+## Checking types with mypy
+
+Hints are not enforced at runtime — run a checker to catch mistakes.
+
+```bash title="terminal"
+$ pip install mypy
+$ mypy myscript.py
+myscript.py:3: error: Argument 1 to "greet" has incompatible type "int"; expected "str"
+```
+
+## Common pitfalls
+
+- **Hints don't enforce anything at runtime** — `def f(x: int)` still accepts a string unless a checker complains.
+- **`Optional[X]` is about `None`**, not about omittable arguments (that's a default value).
+- **Use `Sequence`/`Iterable` for parameters**, concrete types for return values — accept broadly, return precisely.
+- **Don't overuse `Any`** — it silences the checker.
+
+## Practice Exercises
+
+### Exercise 1 – Annotate a function
+
+<DataCampExercise
+  lang="python"
+  hint={`Annotate both params as int and the return as int, then add them.`}
+  code={`# Task: Add type hints: two ints in, one int out.
+def add(a: ___, b: int) -> int:
+    return a + b
+
+print(add(2, 5))
+
+# Expected Output:
+# 7`}
+  solution={`def add(a: int, b: int) -> int:
+    return a + b
+
+print(add(2, 5))`}
+  sct={`test_output_contains("7")
+success_msg("Type hints document the contract without changing behaviour.")`}
+  height={160}
+/>
+
+### Exercise 2 – Optional return
+
+<DataCampExercise
+  lang="python"
+  hint={`Optional[str] means the function may return a str or None.`}
+  code={`# Task: Complete the Optional hint for a function that may return None.
+from typing import Optional
+
+def lookup(key: str) -> ___[str]:
+    table = {"a": "apple"}
+    return table.get(key)
+
+print(lookup("a"))
+print(lookup("z"))
+
+# Expected Output:
+# apple
+# None`}
+  solution={`from typing import Optional
+
+def lookup(key: str) -> Optional[str]:
+    table = {"a": "apple"}
+    return table.get(key)
+
+print(lookup("a"))
+print(lookup("z"))`}
+  sct={`test_output_contains("apple")
+test_output_contains("None")
+success_msg("Optional[str] == str | None.")`}
+  height={200}
+/>
+
+### Exercise 3 – A generic 'first' function
+
+<DataCampExercise
+  lang="python"
+  hint={`Create a TypeVar T and use list[T] -> T.`}
+  code={`# Task: Make 'first' generic so it returns the element type.
+from typing import TypeVar
+
+T = TypeVar("___")
+
+def first(items: list[T]) -> T:
+    return items[0]
+
+print(first([10, 20, 30]))
+print(first(["x", "y"]))
+
+# Expected Output:
+# 10
+# x`}
+  solution={`from typing import TypeVar
+
+T = TypeVar("T")
+
+def first(items: list[T]) -> T:
+    return items[0]
+
+print(first([10, 20, 30]))
+print(first(["x", "y"]))`}
+  sct={`test_output_contains("10")
+test_output_contains("x")
+success_msg("A TypeVar preserves the relationship between input and output types.")`}
+  height={210}
+/>
+
+## Summary
+
+- Type hints document expected types; they're ignored at runtime but power editors and `mypy`.
+- Use built-in generics (`list[int]`, `dict[str, int]`) on 3.9+, or `typing` equivalents on older versions.
+- `Optional[X]` / `X | None` for nullable values; `Union` / `A | B` for multiple types.
+- Type functions with `Callable`, reuse complex types with aliases, and write reusable code with `TypeVar`/`Generic`.
+- Prefer `Iterable`/`Sequence` for inputs; run `mypy` to enforce.
diff --git a/src/content/docs/tutorials/Modern Python/Virtual Environments and pip.mdx b/src/content/docs/tutorials/Modern Python/Virtual Environments and pip.mdx
new file mode 100644
index 00000000..f5524245
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Virtual Environments and pip.mdx	
@@ -0,0 +1,186 @@
+---
+title: Python Virtual Environments & pip
+description: Learn to isolate project dependencies with venv and manage packages with pip — creating environments, activating them, installing/freezing/uninstalling packages, and requirements.txt. With examples and practice exercises.
+sidebar:
+  order: 3
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+A **virtual environment** is an isolated Python installation for a single project. It keeps each project's packages separate so versions never clash, and it keeps your global Python clean. **pip** is the tool that installs and manages those packages. (For installing Python itself, see the [Installation](../../installation/) page.)
+
+> Golden rule: **one virtual environment per project**, and never `pip install` into your system Python.
+
+## Why isolate?
+
+Without isolation, every project shares one set of packages:
+
+- Project A needs `django==3.2`, Project B needs `django==4.2` — they can't coexist globally.
+- A global install can break system tools that rely on specific versions.
+- You can't reproduce "exactly what this project needs" for a teammate or server.
+
+A virtual environment solves all three.
+
+## Creating an environment with venv
+
+`venv` ships with Python. Create an environment (commonly named `.venv`) in your project folder:
+
+```bash title="terminal"
+# Create a virtual environment in the .venv folder
+python -m venv .venv
+```
+
+This makes a `.venv/` directory containing a private copy of Python and a place for packages.
+
+## Activating and deactivating
+
+You must **activate** the environment so `python` and `pip` point at it.
+
+```bash title="macOS / Linux"
+source .venv/bin/activate
+```
+
+```powershell title="Windows (PowerShell)"
+.venv\Scripts\Activate.ps1
+```
+
+Once active, your prompt usually shows `(.venv)`. To leave it:
+
+```bash title="terminal"
+deactivate
+```
+
+> Tip: add `.venv/` to your `.gitignore` — environments are rebuilt from `requirements.txt`, not committed.
+
+## Installing packages with pip
+
+With the environment active:
+
+```bash title="terminal"
+pip install requests              # latest version
+pip install "django==4.2"         # a specific version
+pip install "flask>=2,<3"         # a version range
+pip install --upgrade requests    # upgrade to the newest
+pip uninstall requests            # remove a package
+```
+
+| Command | Does |
+|:---|:---|
+| `pip install NAME` | Install the latest version. |
+| `pip install NAME==X.Y` | Install an exact version. |
+| `pip install --upgrade NAME` | Upgrade a package. |
+| `pip uninstall NAME` | Remove a package. |
+| `pip list` | List installed packages. |
+| `pip show NAME` | Show details about a package. |
+
+## requirements.txt — reproducible installs
+
+Record exact versions so anyone can recreate the environment.
+
+```bash title="terminal"
+# Save the current environment's packages
+pip freeze > requirements.txt
+
+# Recreate it elsewhere (in a fresh venv)
+pip install -r requirements.txt
+```
+
+A `requirements.txt` looks like:
+
+```text title="requirements.txt"
+requests==2.31.0
+flask==3.0.0
+python-dotenv==1.0.0
+```
+
+## A typical project workflow
+
+```bash title="terminal"
+mkdir myproject && cd myproject
+python -m venv .venv
+source .venv/bin/activate          # (Windows: .venv\Scripts\Activate.ps1)
+pip install requests flask
+pip freeze > requirements.txt
+# ... write code ...
+deactivate
+```
+
+## Common pitfalls
+
+- **Forgetting to activate** — `pip install` then lands in global Python. Check your prompt for `(.venv)`.
+- **Committing `.venv/`** — it's large and machine-specific; commit `requirements.txt` instead.
+- **Mixing `pip` and the system package manager** — inside a venv, always use `pip`.
+- **`python` vs `python3`** — on some systems the command is `python3`; the same goes for `pip`/`pip3`.
+
+## Practice Exercises
+
+These run plain Python that mirrors what the tools do under the hood.
+
+### Exercise 1 – Check the running Python version
+
+<DataCampExercise
+  lang="python"
+  hint={`sys.version_info.major gives the major version number.`}
+  code={`# Task: Print the MAJOR version of the running Python (knowing your
+# interpreter is the first step when managing environments).
+import sys
+
+print(sys.version_info.___)
+
+# Expected Output:
+# 3`}
+  solution={`import sys
+
+print(sys.version_info.major)`}
+  sct={`test_output_contains("3")
+success_msg("sys.version_info tells you which interpreter is active.")`}
+  height={160}
+/>
+
+### Exercise 2 – Parse a requirements line
+
+<DataCampExercise
+  lang="python"
+  hint={`Split the line on '==' and take the first part for the package name.`}
+  code={`# Task: Extract the package NAME from a requirements line.
+line = "requests==2.31.0"
+name = line.split("___")[0]
+print(name)
+
+# Expected Output:
+# requests`}
+  solution={`line = "requests==2.31.0"
+name = line.split("==")[0]
+print(name)`}
+  sct={`test_output_contains("requests")
+success_msg("requirements.txt pins NAME==VERSION; splitting on == gives the name.")`}
+  height={160}
+/>
+
+### Exercise 3 – Build a pip install command
+
+<DataCampExercise
+  lang="python"
+  hint={`Join the package list with spaces and prefix it with 'pip install '.`}
+  code={`# Task: Build the shell command to install several packages at once.
+packages = ["requests", "flask", "pytest"]
+command = "pip install " + " ".___(packages)
+print(command)
+
+# Expected Output:
+# pip install requests flask pytest`}
+  solution={`packages = ["requests", "flask", "pytest"]
+command = "pip install " + " ".join(packages)
+print(command)`}
+  sct={`test_output_contains("pip install requests flask pytest")
+success_msg("pip installs many packages in one command, space-separated.")`}
+  height={170}
+/>
+
+## Summary
+
+- A **virtual environment** isolates one project's packages; create it with `python -m venv .venv`.
+- **Activate** it before working (`source .venv/bin/activate` or `Activate.ps1`), `deactivate` to leave.
+- Use **pip** to `install`, `upgrade`, `uninstall`, and `list` packages.
+- Pin versions with `pip freeze > requirements.txt` and restore with `pip install -r requirements.txt`.
+- Commit `requirements.txt`, not the `.venv/` folder.
diff --git a/src/content/docs/tutorials/Modern Python/Walrus Operator.mdx b/src/content/docs/tutorials/Modern Python/Walrus Operator.mdx
new file mode 100644
index 00000000..7f857884
--- /dev/null
+++ b/src/content/docs/tutorials/Modern Python/Walrus Operator.mdx	
@@ -0,0 +1,170 @@
+---
+title: Python Walrus Operator (:=)
+description: A focused guide to Python's walrus operator (:=), the assignment expression introduced in 3.8. Learn where it shines — while loops, if statements, and comprehensions — plus pitfalls and practice exercises.
+sidebar:
+  order: 6
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+The **walrus operator** `:=` (introduced in Python 3.8, PEP 572) is an **assignment expression**: it assigns a value to a variable **and** returns that value, all in one expression. The name comes from its resemblance to a walrus's eyes and tusks.
+
+```python title="quickstart.py"
+# Without walrus: compute, store, then test
+n = len("hello")
+if n > 3:
+    print(f"{n} characters")
+
+# With walrus: assign and test in one line
+if (n := len("hello")) > 3:
+    print(f"{n} characters")
+# 5 characters
+```
+
+## Assignment statement vs assignment expression
+
+| `=` (statement) | `:=` (expression) |
+|:---|:---|
+| `x = 5` stands alone. | `(x := 5)` can sit inside a larger expression. |
+| Returns nothing. | Evaluates to the assigned value. |
+| Can't be used in `if`/`while` conditions. | Designed exactly for that. |
+
+> Wrap walrus expressions in parentheses in most contexts — it keeps intent clear and is required in several places.
+
+## Where it shines
+
+### 1. While loops that read-and-test
+
+Avoid duplicating the "read" both before and inside the loop.
+
+```python title="while_loop.py"
+# Process items from an iterator until a sentinel (0) appears
+data = [5, 8, 3, 0, 9]
+it = iter(data)
+
+while (value := next(it, 0)) != 0:
+    print(value)
+# 5
+# 8
+# 3
+```
+
+A classic real-world shape is reading chunks from a file or stream:
+
+```python title="read_chunks.py"
+# Pseudocode pattern — read until there's nothing left
+# while (chunk := file.read(1024)):
+#     process(chunk)
+```
+
+### 2. if statements that capture a result
+
+Compute once, test, then reuse the captured value in the body.
+
+```python title="if_capture.py"
+text = "hello world"
+
+if (count := text.count("o")) > 1:
+    print(f"Found 'o' {count} times")
+# Found 'o' 2 times
+```
+
+### 3. Comprehensions without recomputing
+
+Compute an expensive value once and both filter and keep it.
+
+```python title="comprehension.py"
+numbers = [1, 2, 3, 4, 5, 6]
+
+# Keep doubled values that exceed 5 — double() is computed once per item
+result = [doubled for n in numbers if (doubled := n * 2) > 5]
+print(result)   # [6, 8, 10, 12]
+```
+
+Without the walrus you'd compute `n * 2` twice (once to filter, once to keep) or need a longer loop.
+
+## Common pitfalls
+
+- **It's not a plain `=`** — you can't write `(x := 5)` to replace a normal top-level assignment; just use `x = 5` there.
+- **Readability** — overusing `:=` makes lines dense. Reach for it when it removes duplication, not to win at code golf.
+- **Parentheses** — `n := len(s)` alone is a syntax error in many spots; write `(n := len(s))`.
+- **Python 3.8+ only** — older interpreters reject `:=`.
+
+## Practice Exercises
+
+### Exercise 1 – Capture a length in an if
+
+<DataCampExercise
+  lang="python"
+  hint={`Use (n := len(word)) inside the if condition.`}
+  code={`# Task: Capture the length with := and print it when it's > 3.
+word = "python"
+
+if (n ___ len(word)) > 3:
+    print(n)
+
+# Expected Output:
+# 6`}
+  solution={`word = "python"
+
+if (n := len(word)) > 3:
+    print(n)`}
+  sct={`test_output_contains("6")
+success_msg("The walrus assigned len(word) to n and tested it at once.")`}
+  height={150}
+/>
+
+### Exercise 2 – Filter in a comprehension
+
+<DataCampExercise
+  lang="python"
+  hint={`Compute the square once with (sq := n * n) and filter on it.`}
+  code={`# Task: Keep squares greater than 4, computing each square only once.
+numbers = [1, 2, 3, 4]
+
+result = [sq for n in numbers if (sq ___ n * n) > 4]
+print(result)
+
+# Expected Output:
+# [9, 16]`}
+  solution={`numbers = [1, 2, 3, 4]
+
+result = [sq for n in numbers if (sq := n * n) > 4]
+print(result)`}
+  sct={`test_output_contains("[9, 16]")
+success_msg("The walrus computes n*n once and reuses it.")`}
+  height={160}
+/>
+
+### Exercise 3 – Loop until a sentinel
+
+<DataCampExercise
+  lang="python"
+  hint={`Use while (value := next(it, 0)) != 0 to read until a 0 appears.`}
+  code={`# Task: Print values from the iterator until you hit 0.
+data = [7, 4, 0, 9]
+it = iter(data)
+
+while (value := next(it, 0)) ___ 0:
+    print(value)
+
+# Expected Output:
+# 7
+# 4`}
+  solution={`data = [7, 4, 0, 9]
+it = iter(data)
+
+while (value := next(it, 0)) != 0:
+    print(value)`}
+  sct={`test_output_contains("7")
+test_output_contains("4")
+success_msg("The walrus reads and tests each value in the loop condition.")`}
+  height={170}
+/>
+
+## Summary
+
+- `:=` assigns **and** returns a value, so it works inside expressions.
+- Great for `while` loops (read-and-test), `if` statements (capture-and-test), and comprehensions (compute once).
+- Always parenthesize it; use it to remove duplication, not to obscure code.
+- Requires Python 3.8+.
diff --git a/src/content/docs/tutorials/Numbers.mdx b/src/content/docs/tutorials/Numbers.mdx
index 3f6b41eb..6048e276 100644
--- a/src/content/docs/tutorials/Numbers.mdx
+++ b/src/content/docs/tutorials/Numbers.mdx
@@ -24,6 +24,33 @@ result = a + b  # Result is -5
 
 Python allows unlimited precision for integers, meaning they can be as large as your system's memory allows.
 
+```python title="bignum.py" showLineNumbers{1} {1-2}
+big = 2 ** 100      # no overflow, Python handles huge integers
+print(big)          # 1267650600228229401496703205376
+```
+
+### Number Bases and Readable Literals
+
+Integers can be written in binary, octal, and hexadecimal using prefixes, and you can group digits with underscores for readability (the underscores are ignored by Python):
+
+```python title="bases.py" showLineNumbers{1} {1-8}
+binary = 0b1010      # binary  -> 10
+octal = 0o17         # octal   -> 15
+hexadecimal = 0xFF   # hex     -> 255
+million = 1_000_000  # underscores aid reading -> 1000000
+
+print(binary, octal, hexadecimal, million)
+print(bin(10), oct(15), hex(255))   # convert back to base strings
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python bases.py
+10 15 255 1000000
+0b1010 0o17 0xff
+```
+
 ## Floating-Point Numbers
 #### `float`
 
@@ -37,6 +64,28 @@ area = pi * (radius ** 2)  # Calculating the area of a circle
 
 While floating-point numbers are powerful for scientific and mathematical computations, they may introduce precision issues due to the binary representation of real numbers.
 
+### The Floating-Point Precision Gotcha
+
+This surprises every beginner — floats are stored in binary, so some decimals cannot be represented exactly:
+
+```python title="precision.py" showLineNumbers{1} {1-2}
+print(0.1 + 0.2)            # 0.30000000000000004
+print(0.1 + 0.2 == 0.3)     # False!
+```
+
+When exact decimal arithmetic matters (money, for example), use the `decimal` module:
+
+```python title="decimal_money.py" showLineNumbers{1} {1-4}
+from decimal import Decimal
+
+price = Decimal("0.1") + Decimal("0.2")
+print(price)                # 0.3  (exact)
+```
+
+:::tip
+To compare floats safely, do not use `==`. Use `math.isclose(a, b)` to check whether they are *approximately* equal.
+:::
+
 ## Complex Numbers
 #### `complex`
 
@@ -125,10 +174,10 @@ import math
 sqrt_result = math.sqrt(25)  # Result is 5.0
 ```
 :::caution
-The `math` module only works with floating-point numbers. If you want to perform mathematical operations on integers, use the `cmath` module instead.
+`math` functions accept integers and floats but **always return a float** (`math.sqrt(25)` is `5.0`, not `5`). For complex numbers, `math` raises an error — use the `cmath` module instead, which is built specifically for complex math.
 :::
 :::note
-For more information on the `math` module, check out our [Python Math Module Tutorial](https://docs.python.org/3/library/math.html).
+For more information, see the official [`math` module documentation](https://docs.python.org/3/library/math.html). Useful members include `math.pi`, `math.e`, `math.floor()`, `math.ceil()`, `math.factorial()`, and `math.gcd()`.
 :::
 
 ## Random Numbers
@@ -143,7 +192,30 @@ print(random.randrange(1, 10))  # Prints a random integer between 1 and 10
 For more information on the `random` module, check out our [Python Random Module Tutorial](https://docs.python.org/3/library/random.html).
 :::
 
+## Built-in Number Functions
 
+You do not always need the `math` module. Python has several handy built-ins for numbers:
+
+```python title="builtins.py" showLineNumbers{1} {1-6}
+print(abs(-7))        # 7    -> absolute value
+print(round(3.14159, 2))  # 3.14 -> round to 2 decimals
+print(pow(2, 8))      # 256  -> 2 to the power 8
+print(divmod(17, 5))  # (3, 2) -> quotient and remainder together
+print(max(3, 9, 1))   # 9
+print(min(3, 9, 1))   # 1
+```
+
+## Augmented Assignment
+
+Operators like `+=`, `-=`, `*=`, `/=`, `//=`, `%=`, and `**=` update a variable in place — a shorthand that keeps code concise:
+
+```python title="augmented.py" showLineNumbers{1} {1-5}
+count = 10
+count += 5     # same as: count = count + 5
+count *= 2     # same as: count = count * 2
+count //= 3    # floor division assignment
+print(count)   # 10
+```
 
 ## Conclusion
 
diff --git a/src/content/docs/tutorials/Print.mdx b/src/content/docs/tutorials/Print.mdx
index 0eb49c63..65d71d0c 100644
--- a/src/content/docs/tutorials/Print.mdx
+++ b/src/content/docs/tutorials/Print.mdx
@@ -62,6 +62,29 @@ C:\Users\Your Name> python print.py
 Bob is 30 years old.
 ```
 
+#### F-String Format Specifiers
+
+F-strings can do much more than insert values — a `:` inside the braces starts a **format specifier** that controls width, alignment, decimal places, and more.
+
+```python title="fstring_format.py" showLineNumbers{1} {1-6}
+pi = 3.14159
+price = 1234.5
+ratio = 0.875
+
+print(f"{pi:.2f}")       # 3.14    -> 2 decimal places
+print(f"{price:,.2f}")   # 1,234.50 -> thousands separator
+print(f"{ratio:.1%}")    # 87.5%   -> percentage
+print(f"{42:05d}")       # 00042   -> pad with zeros to width 5
+print(f"{'hi':>10}")     # '        hi' -> right-align in 10 cols
+```
+
+You can also print the expression *and* its value with a trailing `=` (great for debugging):
+
+```python title="fstring_debug.py" showLineNumbers{1} {2}
+x = 10
+print(f"{x = }")   # x = 10
+```
+
 ### String Formatting
 
 The `format()` method allows for more controlled string formatting:
@@ -131,6 +154,37 @@ This is a lineThis is another line
 
 In this example, we've used the `end` parameter to remove the newline character from the first `print()` function. This allows us to print the second line on the same line as the first.
 
+**Diagram**:
+```mermaid title="print() parameters" desc="How sep, end, and file shape the output"
+graph TD
+    A["print(a, b, c, sep, end, file)"] --> B["sep: placed BETWEEN values"]
+    A --> C["end: placed AFTER the last value"]
+    A --> D["file: where output goes (default: screen)"]
+```
+
+### Unpacking a List into print
+
+The `*` operator unpacks an iterable so each element becomes a separate argument — combine it with `sep` to format collections neatly:
+
+```python title="unpack_print.py" showLineNumbers{1} {1-2}
+fruits = ["apple", "banana", "cherry"]
+print(*fruits, sep=", ")   # apple, banana, cherry
+```
+
+### Printing to Standard Error
+
+By default `print()` writes to standard output. Pass `file=sys.stderr` to send messages to the error stream instead — useful for warnings and logs that should not mix with normal output. The `flush=True` argument forces the output to appear immediately.
+
+```python title="stderr.py" showLineNumbers{1} {1,3}
+import sys
+print("Normal result")
+print("Something went wrong", file=sys.stderr)
+print("Loading...", end="", flush=True)   # appears at once, no buffering
+```
+
+:::note
+`print()` itself returns `None` — it produces output as a side effect, it does not give back a value you can store.
+:::
 
 ## Printing Variables and Expressions
 
diff --git a/src/content/docs/tutorials/Python Comprehensions/Comprehensions.mdx b/src/content/docs/tutorials/Python Comprehensions/Comprehensions.mdx
new file mode 100644
index 00000000..288e3ced
--- /dev/null
+++ b/src/content/docs/tutorials/Python Comprehensions/Comprehensions.mdx	
@@ -0,0 +1,294 @@
+---
+title: Comprehensions in Python
+description: Learn about list, dictionary, and set comprehensions in Python. Master the compact syntax for building collections, add conditions and nested loops, and understand when comprehensions improve readability over traditional loops.
+sidebar: 
+    order: 100
+---
+
+## Mastering Comprehensions in Python: A Comprehensive Guide
+Comprehensions are one of Python's most loved features. They let you build a list, dictionary, or set from an existing iterable in a single, readable line — replacing a multi-line `for` loop and `append()` call. In this guide, we'll explore list, dictionary, and set comprehensions, add filtering conditions, and cover nested comprehensions.
+
+## What is a Comprehension?
+A **comprehension** is a concise way to create a collection by transforming and filtering items from another iterable. Instead of writing a loop that appends to a list, you describe the result directly.
+
+Compare the traditional loop with a list comprehension:
+
+```python title="loop_vs_comprehension.py" showLineNumbers{1} {1-9}
+# Traditional loop
+squares = []
+for x in range(5):
+    squares.append(x * x)
+print(squares)
+
+# List comprehension - same result, one line
+squares = [x * x for x in range(5)]
+print(squares)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python loop_vs_comprehension.py
+[0, 1, 4, 9, 16]
+[0, 1, 4, 9, 16]
+```
+
+## List Comprehension
+A list comprehension builds a new list. It is written inside square brackets `[]`.
+
+The syntax of a list comprehension in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+[expression for item in iterable]
+```
+
+- **expression** — what to put in the new list (often a transformation of `item`).
+- **item** — the loop variable.
+- **iterable** — the source you loop over.
+
+```python title="list_comp.py" showLineNumbers{1} {1-5}
+fruits = ["apple", "banana", "cherry"]
+
+# Uppercase every fruit
+upper = [fruit.upper() for fruit in fruits]
+print(upper)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python list_comp.py
+['APPLE', 'BANANA', 'CHERRY']
+```
+
+## Adding a Condition (Filtering)
+You can add an `if` clause at the end to keep only items that match a condition.
+
+The syntax with a condition is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+[expression for item in iterable if condition]
+```
+
+```python title="filter_comp.py" showLineNumbers{1} {1-4}
+numbers = range(10)
+
+# Keep only the even numbers
+evens = [n for n in numbers if n % 2 == 0]
+print(evens)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python filter_comp.py
+[0, 2, 4, 6, 8]
+```
+
+## Conditional Expression (if-else)
+To *transform* items differently based on a condition (rather than filter them out), put an `if-else` *before* the `for`. This is a ternary expression.
+
+```python title="if_else_comp.py" showLineNumbers{1} {1-3}
+numbers = range(5)
+labels = ["even" if n % 2 == 0 else "odd" for n in numbers]
+print(labels)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python if_else_comp.py
+['even', 'odd', 'even', 'odd', 'even']
+```
+
+:::caution
+Placement matters! A **filtering** `if` goes *after* the `for` (`[x for x in it if cond]`). A **transforming** `if-else` goes *before* the `for` (`[a if cond else b for x in it]`).
+:::
+
+## Dictionary Comprehension
+A dictionary comprehension builds a dictionary. It uses curly braces `{}` and a `key: value` pair.
+
+The syntax of a dictionary comprehension is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+{key_expression: value_expression for item in iterable}
+```
+
+```python title="dict_comp.py" showLineNumbers{1} {1-4}
+numbers = [1, 2, 3, 4]
+
+# Map each number to its square
+squares = {n: n * n for n in numbers}
+print(squares)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python dict_comp.py
+{1: 1, 2: 4, 3: 9, 4: 16}
+```
+
+A common use is swapping keys and values, or building a lookup from two lists with `zip()`:
+
+```python title="dict_zip.py" showLineNumbers{1} {1-4}
+names = ["Alice", "Bob"]
+ages = [30, 25]
+people = {name: age for name, age in zip(names, ages)}
+print(people)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python dict_zip.py
+{'Alice': 30, 'Bob': 25}
+```
+
+## Set Comprehension
+A set comprehension builds a set (unique, unordered values). It uses curly braces `{}` like a dict, but with single values instead of pairs.
+
+The syntax of a set comprehension is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+{expression for item in iterable}
+```
+
+```python title="set_comp.py" showLineNumbers{1} {1-4}
+words = ["hi", "hello", "hey", "hi", "hello"]
+
+# Unique word lengths
+lengths = {len(word) for word in words}
+print(lengths)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python set_comp.py
+{2, 5, 3}
+```
+
+## Nested Comprehensions
+You can use more than one `for` clause to loop over nested data, such as flattening a list of lists.
+
+```python title="nested_comp.py" showLineNumbers{1} {1-4}
+matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
+
+# Flatten the matrix into a single list
+flat = [value for row in matrix for value in row]
+print(flat)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python nested_comp.py
+[1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
+
+:::note
+Read nested comprehensions left to right, exactly as you would write the nested loops: the first `for` is the outer loop, the second `for` is the inner loop.
+:::
+
+## When to Use Comprehensions
+| Use a comprehension when... | Avoid a comprehension when... |
+| :--- | :--- |
+| The logic fits on one readable line | The logic needs many conditions or side effects |
+| You are transforming or filtering an iterable | You need `try/except` inside the loop |
+| Building a new list, dict, or set | You only loop for side effects (just use a `for` loop) |
+
+:::tip
+If a comprehension becomes hard to read, switch back to a normal `for` loop. Comprehensions should make code *clearer*, not denser.
+:::
+
+## Conclusion
+Comprehensions provide a compact, expressive way to build lists, dictionaries, and sets directly from iterables. List comprehensions use `[]`, dictionary comprehensions use `{key: value}`, and set comprehensions use `{}` with single values. You can add a trailing `if` to filter, a leading `if-else` to transform conditionally, and stack multiple `for` clauses to handle nested data. Used wisely, comprehensions make your code shorter and more readable. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Comprehensions Exercises
+
+### Exercise 1 – Basic List Comprehension
+
+<DataCampExercise
+  lang="python"
+  hint={`Syntax: [expression for item in iterable]`}
+  code={`# Task: Exercise 1 - Basic List Comprehension
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: build a list of cubes for numbers 1..5.
+# Hint: the expression is n ** 3.
+cubes = [___ for n in range(1, 6)]  # replace ___ with the expression
+
+print(cubes)
+
+# -- Expected Output --------------------------------------------
+# [1, 8, 27, 64, 125]
+# ---------------------------------------------------------------`}
+  solution={`cubes = [n ** 3 for n in range(1, 6)]
+print(cubes)`}
+  sct={`test_output_contains("[1, 8, 27, 64, 125]")
+success_msg("You wrote a list comprehension!")`}
+  height={180}
+/>
+
+### Exercise 2 – Comprehension with a Condition
+
+<DataCampExercise
+  lang="python"
+  hint={`A filtering 'if' goes AFTER the for clause.`}
+  code={`# Task: Exercise 2 - Comprehension with a Condition
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+numbers = range(1, 11)
+
+# Step: keep only the numbers divisible by 3.
+# Hint: condition is n % 3 == 0, placed AFTER the for.
+multiples = [n for n in numbers ___ n % 3 == 0]  # replace ___ with the keyword
+
+print(multiples)
+
+# -- Expected Output --------------------------------------------
+# [3, 6, 9]
+# ---------------------------------------------------------------`}
+  solution={`numbers = range(1, 11)
+multiples = [n for n in numbers if n % 3 == 0]
+print(multiples)`}
+  sct={`test_output_contains("[3, 6, 9]")
+success_msg("You filtered with a comprehension!")`}
+  height={200}
+/>
+
+### Exercise 3 – Dictionary Comprehension
+
+<DataCampExercise
+  lang="python"
+  hint={`Syntax: {key: value for item in iterable}`}
+  code={`# Task: Exercise 3 - Dictionary Comprehension
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+words = ["cat", "tiger", "ox"]
+
+# Step: map each word to its length.
+# Hint: key is the word, value is len(word).
+lengths = {word: ___ for word in words}  # replace ___ with the value expression
+
+print(lengths)
+
+# -- Expected Output --------------------------------------------
+# {'cat': 3, 'tiger': 5, 'ox': 2}
+# ---------------------------------------------------------------`}
+  solution={`words = ["cat", "tiger", "ox"]
+lengths = {word: len(word) for word in words}
+print(lengths)`}
+  sct={`test_output_contains("'cat': 3")
+test_output_contains("'tiger': 5")
+success_msg("You built a dictionary comprehension!")`}
+  height={200}
+/>
diff --git a/src/content/docs/tutorials/Python Context Managers/Context Managers.mdx b/src/content/docs/tutorials/Python Context Managers/Context Managers.mdx
new file mode 100644
index 00000000..29b67ed8
--- /dev/null
+++ b/src/content/docs/tutorials/Python Context Managers/Context Managers.mdx	
@@ -0,0 +1,296 @@
+---
+title: Context Managers (with statement) in Python
+description: Learn about context managers and the with statement in Python. Understand automatic resource management, the __enter__ and __exit__ methods, building class-based context managers, and the contextlib.contextmanager decorator.
+sidebar: 
+    order: 104
+---
+
+## Mastering Context Managers in Python: A Comprehensive Guide
+Opening a file, connecting to a database, or acquiring a lock all share a pattern: you set something up, use it, and must clean it up afterwards — even if an error occurs. **Context managers** automate this setup-and-teardown through the `with` statement, guaranteeing cleanup happens. In this guide, we'll explore the `with` statement, the `__enter__` and `__exit__` methods, and the `contextlib` module.
+
+## The Problem Context Managers Solve
+Without a context manager, you must remember to release resources manually — and handle errors so cleanup still runs.
+
+```python title="manual.py" showLineNumbers{1} {1-7}
+# Manual cleanup - easy to forget, fragile if an error occurs
+file = open("data.txt", "w")
+try:
+    file.write("Hello")
+finally:
+    file.close()   # must remember this, even on error
+```
+
+The `with` statement does all of this for you.
+
+## The with Statement
+The `with` statement wraps a block of code so that resources are automatically cleaned up when the block ends — whether it ends normally or because of an exception.
+
+The syntax of the `with` statement in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-2}
+with expression as variable:
+    # code that uses the resource
+```
+
+The classic example is file handling:
+
+```python title="with_file.py" showLineNumbers{1} {1-4}
+with open("data.txt", "w") as file:
+    file.write("Hello, World!")
+# file is automatically closed here - even if write() raised an error
+print("File closed:", file.closed)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python with_file.py
+File closed: True
+```
+
+**Diagram**:
+```mermaid title="with statement flow" desc="How the with statement manages a resource"
+graph TD
+    A[Enter with block] --> B[Call __enter__: set up resource]
+    B --> C[Run the indented body]
+    C --> D{Exception?}
+    D -->|No| E[Call __exit__: clean up]
+    D -->|Yes| F[Call __exit__: clean up, then handle]
+    E --> G[Continue program]
+    F --> G[Continue program]
+```
+
+:::tip
+Always use `with open(...)` instead of a bare `open(...)`. It guarantees the file is closed, freeing the operating system handle even if your code crashes.
+:::
+
+## What is a Context Manager?
+A **context manager** is any object that implements two special methods:
+
+- `__enter__(self)` — runs when the `with` block is entered. Its return value is bound to the `as` variable.
+- `__exit__(self, exc_type, exc_value, traceback)` — runs when the block exits, for cleanup. It receives details of any exception that occurred.
+
+## Building a Class-Based Context Manager
+Let's build a `Timer` that measures how long the `with` block takes.
+
+```python title="timer.py" showLineNumbers{1} {1-18}
+import time
+
+class Timer:
+    def __enter__(self):
+        self.start = time.time()
+        print("Timer started")
+        return self           # bound to the 'as' variable
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        elapsed = time.time() - self.start
+        print(f"Elapsed: {elapsed:.2f}s")
+        return False          # do not suppress exceptions
+
+with Timer() as t:
+    total = sum(range(1_000_000))
+
+print("Done")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python timer.py
+Timer started
+Elapsed: 0.03s
+Done
+```
+
+### The __exit__ Return Value
+If `__exit__` returns `True`, any exception raised inside the block is **suppressed** (swallowed). If it returns `False` (or `None`), the exception **propagates** normally after cleanup. Most context managers return `False`.
+
+```python title="suppress.py" showLineNumbers{1} {1-13}
+class Suppressor:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is ValueError:
+            print("Suppressed a ValueError")
+            return True       # swallow ValueError
+        return False
+
+with Suppressor():
+    raise ValueError("boom")   # caught and suppressed
+print("Program continues")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python suppress.py
+Suppressed a ValueError
+Program continues
+```
+
+## The contextlib Approach
+Writing a whole class can be heavy. The `contextlib.contextmanager` decorator lets you build a context manager from a simple generator function. The code **before** `yield` is the setup (`__enter__`), and the code **after** `yield` is the cleanup (`__exit__`).
+
+```python title="contextlib_timer.py" showLineNumbers{1} {1-15}
+from contextlib import contextmanager
+import time
+
+@contextmanager
+def timer():
+    start = time.time()       # setup (like __enter__)
+    print("Timer started")
+    yield                     # the 'with' body runs here
+    elapsed = time.time() - start
+    print(f"Elapsed: {elapsed:.2f}s")   # cleanup (like __exit__)
+
+with timer():
+    total = sum(range(1_000_000))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python contextlib_timer.py
+Timer started
+Elapsed: 0.03s
+```
+
+:::caution
+With `@contextmanager`, wrap the `yield` in a `try/finally` if cleanup must run even when the body raises an exception. The `finally` block guarantees the teardown code runs.
+:::
+
+## Multiple Context Managers
+You can manage several resources in one `with` statement by separating them with commas.
+
+```python title="multiple.py" showLineNumbers{1} {1-3}
+with open("input.txt") as src, open("output.txt", "w") as dst:
+    dst.write(src.read())
+# both files are closed automatically
+```
+
+## Conclusion
+Context managers automate resource setup and cleanup through the `with` statement, guaranteeing teardown even when errors occur. Any object with `__enter__` and `__exit__` methods is a context manager; `__enter__` sets up and returns the resource, while `__exit__` cleans up and decides whether to suppress exceptions. For lighter cases, the `@contextmanager` decorator from `contextlib` turns a generator into a context manager using `yield` to split setup from cleanup. Reach for `with` whenever you handle files, locks, or connections. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Context Managers Exercises
+
+### Exercise 1 – The with Statement
+
+<DataCampExercise
+  lang="python"
+  hint={`Use 'with open(path, "w") as f:' and write inside the block.`}
+  code={`# Task: Exercise 1 - The with Statement
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: open "note.txt" for writing using a context manager.
+# Hint: with open(name, mode) as variable:
+___ open("note.txt", "w") as f:  # replace ___ with the correct keyword
+    f.write("saved")
+
+# The file is auto-closed here. Confirm it.
+print("Closed:", f.closed)
+
+# -- Expected Output --------------------------------------------
+# Closed: True
+# ---------------------------------------------------------------`}
+  solution={`with open("note.txt", "w") as f:
+    f.write("saved")
+
+print("Closed:", f.closed)`}
+  sct={`test_output_contains("Closed: True")
+success_msg("You used the with statement!")`}
+  height={200}
+/>
+
+### Exercise 2 – Class-Based Context Manager
+
+<DataCampExercise
+  lang="python"
+  hint={`Define __enter__ (returns self) and __exit__ (cleanup).`}
+  code={`# Task: Exercise 2 - Class-Based Context Manager
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+class Greeter:
+    # Step: __enter__ runs on entry and returns the resource.
+    def ___(self):  # replace ___ with the enter method name
+        print("Enter")
+        return self
+    # Step: __exit__ runs on exit for cleanup.
+    def ___(self, exc_type, exc_value, traceback):  # replace ___ with the exit method name
+        print("Exit")
+        return False
+
+with Greeter():
+    print("Inside")
+
+# -- Expected Output --------------------------------------------
+# Enter
+# Inside
+# Exit
+# ---------------------------------------------------------------`}
+  solution={`class Greeter:
+    def __enter__(self):
+        print("Enter")
+        return self
+    def __exit__(self, exc_type, exc_value, traceback):
+        print("Exit")
+        return False
+
+with Greeter():
+    print("Inside")`}
+  sct={`test_output_contains("Enter")
+test_output_contains("Inside")
+test_output_contains("Exit")
+success_msg("You built a class-based context manager!")`}
+  height={280}
+/>
+
+### Exercise 3 – contextlib Generator
+
+<DataCampExercise
+  lang="python"
+  hint={`Decorate with @contextmanager; code before yield is setup, after is cleanup.`}
+  code={`# Task: Exercise 3 - contextlib Generator
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+from contextlib import contextmanager
+
+# Step: apply the decorator that turns a generator into a context manager.
+@___  # replace ___ with the decorator name
+def section():
+    print("start")
+    # Hint: this keyword hands control to the 'with' body.
+    ___  # replace ___ with the keyword that pauses the generator
+    print("end")
+
+with section():
+    print("body")
+
+# -- Expected Output --------------------------------------------
+# start
+# body
+# end
+# ---------------------------------------------------------------`}
+  solution={`from contextlib import contextmanager
+
+@contextmanager
+def section():
+    print("start")
+    yield
+    print("end")
+
+with section():
+    print("body")`}
+  sct={`test_output_contains("start")
+test_output_contains("body")
+test_output_contains("end")
+success_msg("You built a contextlib context manager!")`}
+  height={280}
+/>
diff --git a/src/content/docs/tutorials/Python Exception Handling/Exception Handling.mdx b/src/content/docs/tutorials/Python Exception Handling/Exception Handling.mdx
new file mode 100644
index 00000000..4581045b
--- /dev/null
+++ b/src/content/docs/tutorials/Python Exception Handling/Exception Handling.mdx	
@@ -0,0 +1,385 @@
+---
+title: Exception Handling in Python
+description: Learn about exception handling in Python. Master the try, except, else, and finally blocks, learn how to raise exceptions with the raise keyword, and create your own custom exception classes to write robust, crash-resistant programs.
+sidebar: 
+    order: 98
+---
+
+## Mastering Exception Handling in Python: A Comprehensive Guide
+Errors are unavoidable in real programs — a file may be missing, a user may type text where a number was expected, or a network call may fail. Exception handling is the mechanism Python provides to detect these errors and respond to them gracefully instead of crashing. In this guide, we'll explore the `try`, `except`, `else`, and `finally` blocks, the `raise` keyword, and how to build your own custom exceptions.
+
+## What is an Exception?
+An **exception** is an event that occurs during the execution of a program that disrupts the normal flow of instructions. When Python encounters an error it cannot handle, it *raises* an exception. If the exception is not handled, the program stops and prints a **traceback**.
+
+```python title="error.py" showLineNumbers{1} {2}
+# An unhandled exception
+print(10 / 0)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python error.py
+Traceback (most recent call last):
+  File "error.py", line 2, in <module>
+    print(10 / 0)
+ZeroDivisionError: division by zero
+```
+
+The program never reaches any code after line 2 — the `ZeroDivisionError` terminates it. Exception handling lets us catch that error and continue.
+
+## Errors vs. Exceptions
+- **Syntax errors** are mistakes in the structure of the code (a missing colon, an unclosed bracket). They are caught *before* the program runs and cannot be handled at runtime.
+- **Exceptions** are raised *while* the program runs. These are the errors we handle with `try`/`except`.
+
+```python title="syntax_error.py" showLineNumbers{1} {2}
+# Syntax error - cannot be caught with try/except
+if True
+    print("missing colon")
+```
+
+## The try-except Block
+The `try` block contains code that *might* raise an exception. The `except` block contains the code that runs *if* an exception occurs.
+
+The syntax of the `try-except` block in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-4}
+try:
+    # code that might raise an exception
+except ExceptionType:
+    # code that runs if the exception occurs
+```
+
+**Diagram**:
+```mermaid title="try-except flow" desc="Flow of the try-except block in Python"
+graph TD
+    A[Start] --> B[Run try block]
+    B --> C{Exception raised?}
+    C -->|No| D[Skip except block]
+    C -->|Yes| E[Run except block]
+    D --> F[End]
+    E --> F[End]
+```
+
+The following example demonstrates how to catch a `ZeroDivisionError`:
+
+```python title="try_except.py" showLineNumbers{1} {1-4}
+try:
+    result = 10 / 0
+    print(result)
+except ZeroDivisionError:
+    print("You cannot divide by zero!")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python try_except.py
+You cannot divide by zero!
+```
+
+In the above example, the division raises a `ZeroDivisionError`. Python jumps to the matching `except` block, prints the message, and the program continues normally instead of crashing.
+
+:::tip
+Catch the most specific exception you can. Catching `ZeroDivisionError` is better than catching every error, because it documents exactly what you expect to go wrong.
+:::
+
+## Catching the Exception Object
+You can capture the exception object itself using the `as` keyword. This gives you access to the error message.
+
+```python title="as_keyword.py" showLineNumbers{1} {3-4}
+try:
+    number = int("hello")
+except ValueError as error:
+    print("Conversion failed:", error)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python as_keyword.py
+Conversion failed: invalid literal for int() with base 10: 'hello'
+```
+
+## Handling Multiple Exceptions
+A single `try` block can be followed by several `except` blocks. Python runs the first one that matches the raised exception.
+
+```python title="multiple.py" showLineNumbers{1} {1-8}
+try:
+    value = int(input("Enter a number: "))
+    result = 100 / value
+    print(result)
+except ValueError:
+    print("That was not a valid number.")
+except ZeroDivisionError:
+    print("You cannot divide by zero.")
+```
+
+You can also handle several exception types in one block by passing a tuple:
+
+```python title="tuple_except.py" showLineNumbers{1} {3}
+try:
+    risky_operation()
+except (ValueError, TypeError, KeyError) as error:
+    print("Something went wrong:", error)
+```
+
+:::caution
+A bare `except:` (with no exception type) catches *everything*, including `KeyboardInterrupt` and `SystemExit`. Avoid it. If you must catch broadly, use `except Exception:` instead.
+:::
+
+## The else Clause
+The `else` block runs **only if no exception was raised** in the `try` block. It is useful for code that should run after a successful `try`, keeping the `try` block focused on the risky operation alone.
+
+```python title="else_clause.py" showLineNumbers{1} {1-7}
+try:
+    number = int("42")
+except ValueError:
+    print("Invalid number.")
+else:
+    print("Conversion succeeded:", number)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python else_clause.py
+Conversion succeeded: 42
+```
+
+## The finally Clause
+The `finally` block runs **no matter what** — whether or not an exception was raised, and even if a `return` statement executes. It is used for cleanup tasks such as closing files or releasing resources.
+
+```python title="finally_clause.py" showLineNumbers{1} {1-8}
+try:
+    file = open("data.txt", "r")
+    data = file.read()
+except FileNotFoundError:
+    print("File not found.")
+finally:
+    print("Cleaning up...")
+```
+
+**Diagram**:
+```mermaid title="try-except-else-finally" desc="Full exception handling flow in Python"
+graph TD
+    A[Start] --> B[Run try block]
+    B --> C{Exception?}
+    C -->|No| D[Run else block]
+    C -->|Yes| E[Run except block]
+    D --> F[Run finally block]
+    E --> F[Run finally block]
+    F --> G[End]
+```
+
+:::note
+The order is fixed: `try` → `except` → `else` → `finally`. The `else` and `finally` clauses are both optional.
+:::
+
+## The raise Keyword
+You can deliberately raise an exception using the `raise` keyword. This is useful for signalling that something is wrong with the input to your function.
+
+```python title="raise.py" showLineNumbers{1} {1-6}
+def set_age(age):
+    if age < 0:
+        raise ValueError("Age cannot be negative")
+    print("Age set to", age)
+
+set_age(-5)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python raise.py
+Traceback (most recent call last):
+  ...
+ValueError: Age cannot be negative
+```
+
+### Re-raising an Exception
+Inside an `except` block, a bare `raise` re-raises the current exception after you have done some work (such as logging).
+
+```python title="reraise.py" showLineNumbers{1} {3-5}
+try:
+    risky()
+except ValueError:
+    print("Logging the error before re-raising...")
+    raise
+```
+
+## Custom Exceptions
+You can define your own exception types by subclassing the built-in `Exception` class. Custom exceptions make your code more readable and let callers catch *your* specific error.
+
+```python title="custom_exception.py" showLineNumbers{1} {1-13}
+class InsufficientFundsError(Exception):
+    """Raised when a withdrawal exceeds the available balance."""
+    pass
+
+def withdraw(balance, amount):
+    if amount > balance:
+        raise InsufficientFundsError(
+            f"Cannot withdraw {amount}; balance is only {balance}"
+        )
+    return balance - amount
+
+try:
+    withdraw(100, 250)
+except InsufficientFundsError as error:
+    print("Transaction failed:", error)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python custom_exception.py
+Transaction failed: Cannot withdraw 250; balance is only 100
+```
+
+:::tip
+By convention, custom exception class names end with `Error`. Always inherit from `Exception` (not from `BaseException`).
+:::
+
+## Common Built-in Exceptions
+| Exception | Raised when |
+| :--- | :--- |
+| `ValueError` | A function gets an argument of the right type but wrong value (e.g. `int("abc")`). |
+| `TypeError` | An operation is applied to an object of the wrong type. |
+| `KeyError` | A dictionary key is not found. |
+| `IndexError` | A sequence index is out of range. |
+| `FileNotFoundError` | A file or directory is requested but does not exist. |
+| `ZeroDivisionError` | The second argument of a division or modulo is zero. |
+| `AttributeError` | An attribute reference or assignment fails. |
+| `ImportError` | An `import` statement fails to find the module. |
+
+## Conclusion
+Exception handling lets your programs respond to errors gracefully instead of crashing. The `try` block holds risky code, `except` handles failures, `else` runs on success, and `finally` always runs for cleanup. The `raise` keyword lets you signal errors, and custom exception classes make your error handling expressive and precise. Master these tools and your Python programs will be far more robust. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Exception Handling Exercises
+
+### Exercise 1 – Catch a ZeroDivisionError
+
+<DataCampExercise
+  lang="python"
+  hint={`Wrap the division in a try block and catch ZeroDivisionError in the except block.`}
+  code={`# Task: Exercise 1 - Catch a ZeroDivisionError
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Hint: Structure: try: / except ExceptionType: 
+# Step: Put the risky division inside the try block.
+try:
+    result = 10 / ___  # replace ___ with 0 to trigger the error
+    print(result)
+# Hint: Name the exception type that division by zero raises.
+except ___:  # replace ___ with the correct exception type
+    # Step: Call print() with a helpful message.
+    # Example structure: print("Cannot divide by zero!")
+    print(___)  # replace ___ with the correct expression
+
+# -- Expected Output --------------------------------------------
+# Cannot divide by zero!
+# ---------------------------------------------------------------`}
+  solution={`try:
+    result = 10 / 0
+    print(result)
+except ZeroDivisionError:
+    print("Cannot divide by zero!")`}
+  sct={`test_output_contains("Cannot divide by zero!")
+success_msg("You caught the ZeroDivisionError!")`}
+  height={200}
+/>
+
+### Exercise 2 – try / except / else / finally
+
+<DataCampExercise
+  lang="python"
+  hint={`else runs only when no exception is raised; finally always runs.`}
+  code={`# Task: Exercise 2 - try / except / else / finally
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: Assign a value that CAN be converted to int (e.g. "42").
+text = ___  # replace ___ with the correct value
+
+try:
+    number = int(text)
+# Hint: int("abc") raises this exception.
+except ValueError:
+    print("Invalid number")
+# Hint: 'else' runs when the try block succeeds.
+else:
+    # Step: print the converted number with a label.
+    print(___)  # replace ___ with the correct expression
+# Hint: 'finally' always runs, success or failure.
+finally:
+    print(___)  # replace ___ with the message "Done"
+
+# -- Expected Output --------------------------------------------
+# Converted: 42
+# Done
+# ---------------------------------------------------------------`}
+  solution={`text = "42"
+try:
+    number = int(text)
+except ValueError:
+    print("Invalid number")
+else:
+    print("Converted:", number)
+finally:
+    print("Done")`}
+  sct={`test_output_contains("Converted: 42")
+test_output_contains("Done")
+success_msg("You mastered try/except/else/finally!")`}
+  height={260}
+/>
+
+### Exercise 3 – Raise a Custom Exception
+
+<DataCampExercise
+  lang="python"
+  hint={`Subclass Exception, then use 'raise' when the rule is broken.`}
+  code={`# Task: Exercise 3 - Raise a Custom Exception
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Hint: A custom exception subclasses the built-in Exception class.
+# Step: Make NegativeAgeError inherit from Exception.
+class NegativeAgeError(___):  # replace ___ with the base class
+    pass
+
+def set_age(age):
+    if age < 0:
+        # Step: raise the custom exception with a message.
+        raise ___("Age cannot be negative")  # replace ___ with the class name
+    return age
+
+try:
+    set_age(-1)
+# Step: catch your custom exception and bind it to 'e'.
+except ___ as e:  # replace ___ with the class name
+    print("Error:", e)
+
+# -- Expected Output --------------------------------------------
+# Error: Age cannot be negative
+# ---------------------------------------------------------------`}
+  solution={`class NegativeAgeError(Exception):
+    pass
+
+def set_age(age):
+    if age < 0:
+        raise NegativeAgeError("Age cannot be negative")
+    return age
+
+try:
+    set_age(-1)
+except NegativeAgeError as e:
+    print("Error:", e)`}
+  sct={`test_output_contains("Age cannot be negative")
+success_msg("You built and raised a custom exception!")`}
+  height={280}
+/>
diff --git a/src/content/docs/tutorials/Python Function/Args and Kwargs.mdx b/src/content/docs/tutorials/Python Function/Args and Kwargs.mdx
new file mode 100644
index 00000000..097fd68e
--- /dev/null
+++ b/src/content/docs/tutorials/Python Function/Args and Kwargs.mdx	
@@ -0,0 +1,285 @@
+---
+title: "*args and **kwargs in Python"
+description: Learn about arbitrary arguments in Python with *args and **kwargs. Understand how to accept any number of positional and keyword arguments, the packing and unpacking operators, argument order, and how to forward arguments between functions.
+sidebar: 
+    order: 43.5
+---
+
+## Mastering *args and **kwargs in Python: A Comprehensive Guide
+Sometimes you do not know in advance how many arguments a function will receive — think of `print()`, which accepts any number of values. Python solves this with `*args` and `**kwargs`, which let a function accept an arbitrary number of positional and keyword arguments. In this guide, we'll explore packing and unpacking, the correct argument order, and how to pass arguments between functions.
+
+## Recap: Positional and Keyword Arguments
+Before arbitrary arguments, recall the two basic kinds:
+
+- **Positional arguments** are matched by their position: `add(2, 3)`.
+- **Keyword arguments** are matched by name: `add(x=2, y=3)`.
+
+`*args` and `**kwargs` extend these so a function can take *as many as the caller passes*.
+
+## *args – Arbitrary Positional Arguments
+Putting a single `*` before a parameter name tells Python to **pack** all extra positional arguments into a **tuple**. By convention the parameter is named `args`, but any name works.
+
+The syntax of `*args` in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-2}
+def function_name(*args):
+    # args is a tuple of all positional arguments
+```
+
+```python title="args_basic.py" showLineNumbers{1} {1-6}
+def add_all(*args):
+    print("args is:", args)     # a tuple
+    return sum(args)
+
+print(add_all(1, 2, 3))
+print(add_all(10, 20, 30, 40))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python args_basic.py
+args is: (1, 2, 3)
+6
+args is: (10, 20, 30, 40)
+100
+```
+
+:::note
+`*args` collects only the *extra* positional arguments. You can have regular parameters before it: `def greet(greeting, *names)` — `greeting` takes the first argument and `*names` packs the rest.
+:::
+
+## **kwargs – Arbitrary Keyword Arguments
+Putting a double `**` before a parameter name **packs** all extra keyword arguments into a **dictionary**. By convention it is named `kwargs`.
+
+The syntax of `**kwargs` in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-2}
+def function_name(**kwargs):
+    # kwargs is a dict of all keyword arguments
+```
+
+```python title="kwargs_basic.py" showLineNumbers{1} {1-6}
+def build_profile(**kwargs):
+    print("kwargs is:", kwargs)    # a dict
+    for key, value in kwargs.items():
+        print(f"{key}: {value}")
+
+build_profile(name="Alice", age=30, city="Paris")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python kwargs_basic.py
+kwargs is: {'name': 'Alice', 'age': 30, 'city': 'Paris'}
+name: Alice
+age: 30
+city: Paris
+```
+
+## Combining Everything
+You can mix regular parameters, `*args`, default parameters, and `**kwargs` in one function. The order is **fixed**:
+
+```python title="Syntax" showLineNumbers{1} {1}
+def function(positional, *args, keyword_default=value, **kwargs):
+```
+
+The required order is:
+1. Standard positional parameters
+2. `*args`
+3. Keyword-only / default parameters
+4. `**kwargs`
+
+```python title="combined.py" showLineNumbers{1} {1-9}
+def order(main, *extras, sauce="ketchup", **details):
+    print("Main:", main)
+    print("Extras:", extras)
+    print("Sauce:", sauce)
+    print("Details:", details)
+
+order("Burger", "Fries", "Coke", sauce="mayo", size="large", spicy=True)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python combined.py
+Main: Burger
+Extras: ('Fries', 'Coke')
+Sauce: mayo
+Details: {'size': 'large', 'spicy': True}
+```
+
+**Diagram**:
+```mermaid title="argument packing" desc="How arguments are distributed into parameters"
+graph TD
+    A["order('Burger', 'Fries', 'Coke', sauce='mayo', size='large', spicy=True)"] --> B[main = 'Burger']
+    A --> C["extras = ('Fries', 'Coke')"]
+    A --> D[sauce = 'mayo']
+    A --> E["details = {size, spicy}"]
+```
+
+## Unpacking with * and **
+The `*` and `**` operators also work in the *opposite* direction. When **calling** a function, `*` unpacks a list/tuple into positional arguments and `**` unpacks a dict into keyword arguments.
+
+```python title="unpacking.py" showLineNumbers{1} {1-11}
+def introduce(name, age, city):
+    print(f"{name} is {age} and lives in {city}")
+
+# Unpack a list into positional arguments
+data = ["Bob", 25, "London"]
+introduce(*data)
+
+# Unpack a dict into keyword arguments
+info = {"name": "Carol", "age": 28, "city": "Berlin"}
+introduce(**info)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python unpacking.py
+Bob is 25 and lives in London
+Carol is 28 and lives in Berlin
+```
+
+:::tip
+Packing happens in the function *definition* (`def f(*args)`); unpacking happens at the *call site* (`f(*mylist)`). Same symbols, opposite directions.
+:::
+
+## Forwarding Arguments
+A common pattern is a wrapper function that accepts anything and passes it straight through to another function. This is how decorators wrap arbitrary functions.
+
+```python title="forwarding.py" showLineNumbers{1} {1-10}
+def logged(func, *args, **kwargs):
+    print(f"Calling {func.__name__} with {args} {kwargs}")
+    return func(*args, **kwargs)     # forward everything
+
+def power(base, exponent):
+    return base ** exponent
+
+print(logged(power, 2, exponent=10))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python forwarding.py
+Calling power with (2,) {'exponent': 10}
+1024
+```
+
+## Conclusion
+`*args` and `**kwargs` let functions accept any number of arguments: `*args` packs extra positional arguments into a tuple, and `**kwargs` packs extra keyword arguments into a dictionary. The same `*` and `**` operators unpack sequences and dictionaries back into arguments at the call site. Combine them with regular parameters in the fixed order — positional, `*args`, keyword defaults, `**kwargs` — and use them to write flexible wrappers and decorators. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: *args and **kwargs Exercises
+
+### Exercise 1 – Collect with *args
+
+<DataCampExercise
+  lang="python"
+  hint={`Prefix the parameter with a single * to pack extra positional args into a tuple.`}
+  code={`# Task: Exercise 1 - Collect with *args
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: accept any number of positional arguments.
+# Hint: one star before the parameter name.
+def multiply_all(___args):  # replace ___ with the correct symbol
+    result = 1
+    for n in args:
+        result *= n
+    return result
+
+print(multiply_all(2, 3, 4))
+
+# -- Expected Output --------------------------------------------
+# 24
+# ---------------------------------------------------------------`}
+  solution={`def multiply_all(*args):
+    result = 1
+    for n in args:
+        result *= n
+    return result
+
+print(multiply_all(2, 3, 4))`}
+  sct={`test_output_contains("24")
+success_msg("You collected arguments with *args!")`}
+  height={220}
+/>
+
+### Exercise 2 – Collect with **kwargs
+
+<DataCampExercise
+  lang="python"
+  hint={`Prefix the parameter with ** to pack extra keyword args into a dict.`}
+  code={`# Task: Exercise 2 - Collect with **kwargs
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: accept any number of keyword arguments.
+# Hint: two stars before the parameter name.
+def show(___kwargs):  # replace ___ with the correct symbol
+    for key, value in kwargs.items():
+        print(key, "=", value)
+
+show(a=1, b=2)
+
+# -- Expected Output --------------------------------------------
+# a = 1
+# b = 2
+# ---------------------------------------------------------------`}
+  solution={`def show(**kwargs):
+    for key, value in kwargs.items():
+        print(key, "=", value)
+
+show(a=1, b=2)`}
+  sct={`test_output_contains("a = 1")
+test_output_contains("b = 2")
+success_msg("You collected keyword arguments with **kwargs!")`}
+  height={220}
+/>
+
+### Exercise 3 – Unpacking at the Call Site
+
+<DataCampExercise
+  lang="python"
+  hint={`Use * to unpack a list and ** to unpack a dict into arguments.`}
+  code={`# Task: Exercise 3 - Unpacking at the Call Site
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def introduce(name, age):
+    print(f"{name} is {age}")
+
+data = ["Bob", 25]
+info = {"name": "Carol", "age": 28}
+
+# Step: unpack the LIST into positional arguments.
+introduce(___data)  # replace ___ with the correct symbol
+
+# Step: unpack the DICT into keyword arguments.
+introduce(___info)  # replace ___ with the correct symbol
+
+# -- Expected Output --------------------------------------------
+# Bob is 25
+# Carol is 28
+# ---------------------------------------------------------------`}
+  solution={`def introduce(name, age):
+    print(f"{name} is {age}")
+
+data = ["Bob", 25]
+info = {"name": "Carol", "age": 28}
+
+introduce(*data)
+introduce(**info)`}
+  sct={`test_output_contains("Bob is 25")
+test_output_contains("Carol is 28")
+success_msg("You unpacked arguments with * and **!")`}
+  height={240}
+/>
diff --git a/src/content/docs/tutorials/Python Function/Function Annotations.mdx b/src/content/docs/tutorials/Python Function/Function Annotations.mdx
index 2bbef4a0..3e071985 100644
--- a/src/content/docs/tutorials/Python Function/Function Annotations.mdx	
+++ b/src/content/docs/tutorials/Python Function/Function Annotations.mdx	
@@ -5,6 +5,10 @@ sidebar:
     order: 44
 ---
 
+:::tip[Go deeper]
+This page covers the basics of annotations. For `Optional`, `Union`, the `|` syntax, `Callable`, generics (`TypeVar`), type aliases, and static checking with mypy, see the dedicated [Type Hints & the typing Module](../../modern-python/type-hints-and-typing/) tutorial.
+:::
+
 ## Unraveling Function Annotations in Python: A Comprehensive Guide
 
 Function annotations in Python provide a way to attach metadata, including type hints, to the parameters and return values of functions. Introduced in PEP 3107 and enhanced in subsequent PEPs (Python Enhancement Proposals), function annotations offer a mechanism for developers to provide additional information about the expected types and purpose of function parameters and return values. In this comprehensive guide, we'll explore the syntax, use cases, and best practices associated with function annotations in Python.
diff --git a/src/content/docs/tutorials/Python Functional Programming/Closures and Scope.mdx b/src/content/docs/tutorials/Python Functional Programming/Closures and Scope.mdx
new file mode 100644
index 00000000..820c1b8c
--- /dev/null
+++ b/src/content/docs/tutorials/Python Functional Programming/Closures and Scope.mdx	
@@ -0,0 +1,326 @@
+---
+title: Closures and Scope (LEGB) in Python
+description: Learn about variable scope and closures in Python. Master the LEGB rule (Local, Enclosing, Global, Built-in), the global and nonlocal keywords, and how closures capture variables from their enclosing function.
+sidebar: 
+    order: 101
+---
+
+## Mastering Closures and Scope in Python: A Comprehensive Guide
+Every variable in Python lives in a **scope** — a region of the program where that name is visible. Understanding scope explains why some variables are accessible inside a function and others are not, and why changing a variable inside a function sometimes affects the outside and sometimes does not. **Closures** build on scope: they let an inner function remember variables from the function that created it. In this guide, we'll explore the LEGB rule, the `global` and `nonlocal` keywords, and closures.
+
+## What is Scope?
+**Scope** determines where a name (variable, function) can be accessed. Python resolves names using the **LEGB rule**, searching four scopes in order:
+
+1. **L**ocal — names assigned inside the current function.
+2. **E**nclosing — names in any enclosing (outer) function.
+3. **G**lobal — names at the top level of the module.
+4. **B**uilt-in — names pre-defined by Python (`len`, `print`, `range`, ...).
+
+**Diagram**:
+```mermaid title="LEGB rule" desc="Order Python searches scopes to resolve a name"
+graph TD
+    A[Name used] --> B[Local scope?]
+    B -->|Found| Z[Use it]
+    B -->|Not found| C[Enclosing scope?]
+    C -->|Found| Z
+    C -->|Not found| D[Global scope?]
+    D -->|Found| Z
+    D -->|Not found| E[Built-in scope?]
+    E -->|Found| Z
+    E -->|Not found| F[NameError]
+```
+
+The following example shows all four levels being resolved:
+
+```python title="legb.py" showLineNumbers{1} {1-12}
+x = "global"          # Global scope
+
+def outer():
+    y = "enclosing"   # Enclosing scope
+
+    def inner():
+        z = "local"   # Local scope
+        print(z)      # found in Local
+        print(y)      # found in Enclosing
+        print(x)      # found in Global
+        print(len)    # found in Built-in
+
+    inner()
+
+outer()
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python legb.py
+local
+enclosing
+global
+<built-in function len>
+```
+
+## Local Scope
+A variable assigned inside a function is **local** to that function and disappears when the function returns. It cannot be accessed from outside.
+
+```python title="local.py" showLineNumbers{1} {1-5}
+def greet():
+    message = "Hello"   # local variable
+    print(message)
+
+greet()
+print(message)          # NameError: 'message' is not defined
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python local.py
+Hello
+Traceback (most recent call last):
+NameError: name 'message' is not defined
+```
+
+## Global Scope and the global Keyword
+By default, a function can **read** a global variable but **assigning** to a name inside a function creates a *new local* variable. To modify a global variable from inside a function, use the `global` keyword.
+
+```python title="global_keyword.py" showLineNumbers{1} {1-12}
+count = 0
+
+def increment_wrong():
+    count = count + 1     # ERROR: count is treated as local
+
+def increment_right():
+    global count          # tell Python to use the global 'count'
+    count = count + 1
+
+increment_right()
+increment_right()
+print(count)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python global_keyword.py
+2
+```
+
+:::caution
+Overusing `global` makes code hard to follow and test. Prefer passing values in as arguments and returning results instead of mutating globals.
+:::
+
+## Enclosing Scope and the nonlocal Keyword
+When you have a function defined inside another function, the inner function can read the outer function's variables. To **reassign** an enclosing variable, use the `nonlocal` keyword.
+
+```python title="nonlocal_keyword.py" showLineNumbers{1} {1-13}
+def counter():
+    count = 0
+
+    def increment():
+        nonlocal count     # refer to 'count' in the enclosing scope
+        count += 1
+        return count
+
+    print(increment())
+    print(increment())
+    print(increment())
+
+counter()
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python nonlocal_keyword.py
+1
+2
+3
+```
+
+:::note
+`global` reaches all the way to module scope. `nonlocal` reaches only to the nearest enclosing *function* scope — not to the global scope.
+:::
+
+## What is a Closure?
+A **closure** is a function that remembers the variables from its enclosing scope even after that outer function has finished running. Three conditions make a closure:
+
+1. There is a nested (inner) function.
+2. The inner function refers to a variable from the enclosing function.
+3. The enclosing function returns the inner function.
+
+```python title="closure.py" showLineNumbers{1} {1-12}
+def make_multiplier(factor):
+    # 'factor' is captured by the inner function
+    def multiplier(number):
+        return number * factor
+    return multiplier        # return the function, do not call it
+
+double = make_multiplier(2)
+triple = make_multiplier(3)
+
+print(double(5))   # 10
+print(triple(5))   # 15
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python closure.py
+10
+15
+```
+
+Even though `make_multiplier` has already returned, `double` still remembers `factor = 2` and `triple` still remembers `factor = 3`. Each closure carries its own captured value.
+
+**Diagram**:
+```mermaid title="closure" desc="How a closure captures an enclosing variable"
+graph TD
+    A[Call make_multiplier 2] --> B[factor = 2 captured]
+    B --> C[Return inner function 'double']
+    C --> D[make_multiplier finishes]
+    D --> E[double still remembers factor = 2]
+    E --> F[double 5 returns 10]
+```
+
+## Inspecting a Closure
+You can see the values a closure has captured through its `__closure__` attribute.
+
+```python title="inspect_closure.py" showLineNumbers{1} {1-5}
+double = make_multiplier(2)
+print(double.__closure__[0].cell_contents)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python inspect_closure.py
+2
+```
+
+## Why Closures Matter
+- They let you build **function factories** (like `make_multiplier`) that generate customised functions.
+- They are the foundation of **decorators**.
+- They keep data private inside a function without needing a class.
+
+## Conclusion
+Scope controls where names are visible, and Python resolves them with the LEGB rule: Local, then Enclosing, then Global, then Built-in. Use `global` to reassign a module-level variable and `nonlocal` to reassign an enclosing function's variable. Closures take this further — an inner function returned from an outer one remembers the variables it captured, enabling powerful patterns like function factories and decorators. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Closures and Scope Exercises
+
+### Exercise 1 – The global Keyword
+
+<DataCampExercise
+  lang="python"
+  hint={`Use 'global name' inside the function to modify the module-level variable.`}
+  code={`# Task: Exercise 1 - The global Keyword
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+total = 0
+
+def add(n):
+    # Step: declare that we want to modify the global 'total'.
+    ___ total  # replace ___ with the correct keyword
+    total = total + n
+
+add(5)
+add(10)
+print(total)
+
+# -- Expected Output --------------------------------------------
+# 15
+# ---------------------------------------------------------------`}
+  solution={`total = 0
+
+def add(n):
+    global total
+    total = total + n
+
+add(5)
+add(10)
+print(total)`}
+  sct={`test_output_contains("15")
+success_msg("You used the global keyword!")`}
+  height={220}
+/>
+
+### Exercise 2 – The nonlocal Keyword
+
+<DataCampExercise
+  lang="python"
+  hint={`Use 'nonlocal count' to reassign the enclosing function's variable.`}
+  code={`# Task: Exercise 2 - The nonlocal Keyword
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def counter():
+    count = 0
+    def increment():
+        # Step: refer to the enclosing 'count', not a new local one.
+        ___ count  # replace ___ with the correct keyword
+        count += 1
+        return count
+    return increment
+
+c = counter()
+print(c())
+print(c())
+
+# -- Expected Output --------------------------------------------
+# 1
+# 2
+# ---------------------------------------------------------------`}
+  solution={`def counter():
+    count = 0
+    def increment():
+        nonlocal count
+        count += 1
+        return count
+    return increment
+
+c = counter()
+print(c())
+print(c())`}
+  sct={`test_output_contains("1")
+test_output_contains("2")
+success_msg("You used nonlocal in a closure!")`}
+  height={260}
+/>
+
+### Exercise 3 – Build a Closure
+
+<DataCampExercise
+  lang="python"
+  hint={`Return the inner function (no parentheses) so it captures 'factor'.`}
+  code={`# Task: Exercise 3 - Build a Closure
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def make_adder(amount):
+    def adder(number):
+        return number + amount
+    # Step: return the inner function so it remembers 'amount'.
+    return ___  # replace ___ with the function name (no parentheses)
+
+add10 = make_adder(10)
+print(add10(5))
+
+# -- Expected Output --------------------------------------------
+# 15
+# ---------------------------------------------------------------`}
+  solution={`def make_adder(amount):
+    def adder(number):
+        return number + amount
+    return adder
+
+add10 = make_adder(10)
+print(add10(5))`}
+  sct={`test_output_contains("15")
+success_msg("You built a working closure!")`}
+  height={220}
+/>
diff --git a/src/content/docs/tutorials/Python Functional Programming/Map Filter Reduce.mdx b/src/content/docs/tutorials/Python Functional Programming/Map Filter Reduce.mdx
new file mode 100644
index 00000000..fa8d6d53
--- /dev/null
+++ b/src/content/docs/tutorials/Python Functional Programming/Map Filter Reduce.mdx	
@@ -0,0 +1,270 @@
+---
+title: Map, Filter, and Reduce in Python
+description: Learn functional programming tools in Python. Master the map() function to transform iterables, filter() to select items, and reduce() from functools to combine values into a single result, and compare them with comprehensions.
+sidebar: 
+    order: 102
+---
+
+## Mastering Map, Filter, and Reduce in Python: A Comprehensive Guide
+`map()`, `filter()`, and `reduce()` are the classic tools of **functional programming**. Each takes a function and applies it across an iterable: `map` transforms every item, `filter` selects items that pass a test, and `reduce` combines all items into a single value. They pair naturally with `lambda` functions. In this guide, we'll explore each one with examples and compare them to comprehensions.
+
+## What is Functional Programming?
+Functional programming treats functions as values you can pass around. Instead of writing explicit loops, you describe *what* transformation to apply and let the tool handle the iteration. `map`, `filter`, and `reduce` are the three building blocks.
+
+| Tool | Purpose | Result |
+| :--- | :--- | :--- |
+| `map(func, iterable)` | Apply `func` to every item | An iterator of transformed items |
+| `filter(func, iterable)` | Keep items where `func` returns `True` | An iterator of kept items |
+| `reduce(func, iterable)` | Combine items pairwise into one value | A single value |
+
+## The map() Function
+`map()` applies a function to every element of an iterable and returns a **map object** (an iterator). Convert it to a list to see the results.
+
+The syntax of the `map()` function in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+map(function, iterable)
+```
+
+```python title="map_basic.py" showLineNumbers{1} {1-7}
+numbers = [1, 2, 3, 4]
+
+def square(n):
+    return n * n
+
+squared = map(square, numbers)
+print(list(squared))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python map_basic.py
+[1, 4, 9, 16]
+```
+
+Most often `map` is used with a `lambda`:
+
+```python title="map_lambda.py" showLineNumbers{1} {1-3}
+numbers = [1, 2, 3, 4]
+squared = map(lambda n: n * n, numbers)
+print(list(squared))
+```
+
+You can also pass **multiple iterables** — the function then receives one item from each:
+
+```python title="map_multi.py" showLineNumbers{1} {1-4}
+a = [1, 2, 3]
+b = [10, 20, 30]
+sums = map(lambda x, y: x + y, a, b)
+print(list(sums))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python map_multi.py
+[11, 22, 33]
+```
+
+## The filter() Function
+`filter()` keeps only the elements for which the function returns `True`. It also returns an iterator.
+
+The syntax of the `filter()` function in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1}
+filter(function, iterable)
+```
+
+```python title="filter_basic.py" showLineNumbers{1} {1-4}
+numbers = [1, 2, 3, 4, 5, 6]
+
+evens = filter(lambda n: n % 2 == 0, numbers)
+print(list(evens))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python filter_basic.py
+[2, 4, 6]
+```
+
+:::tip
+If you pass `None` as the function, `filter` keeps only the *truthy* items: `list(filter(None, [0, 1, "", "hi", None]))` gives `[1, 'hi']`.
+:::
+
+## The reduce() Function
+`reduce()` repeatedly applies a function of two arguments to the items of an iterable, accumulating them into a single value. Unlike `map` and `filter`, it lives in the `functools` module and must be imported.
+
+The syntax of the `reduce()` function in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-2}
+from functools import reduce
+reduce(function, iterable, initializer)
+```
+
+```python title="reduce_sum.py" showLineNumbers{1} {1-5}
+from functools import reduce
+
+numbers = [1, 2, 3, 4]
+total = reduce(lambda acc, n: acc + n, numbers)
+print(total)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python reduce_sum.py
+10
+```
+
+**Diagram**:
+```mermaid title="reduce" desc="How reduce accumulates a list into one value"
+graph LR
+    A["1 + 2 = 3"] --> B["3 + 3 = 6"]
+    B --> C["6 + 4 = 10"]
+    C --> D["Result: 10"]
+```
+
+`reduce` accepts an optional **initializer** — the starting value for the accumulator. It is safer because it defines the result for an empty iterable.
+
+```python title="reduce_init.py" showLineNumbers{1} {1-4}
+from functools import reduce
+
+numbers = [1, 2, 3, 4]
+product = reduce(lambda acc, n: acc * n, numbers, 1)   # start at 1
+print(product)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python reduce_init.py
+24
+```
+
+## map / filter vs. Comprehensions
+A list comprehension can do everything `map` and `filter` do, and is often considered more Pythonic and readable.
+
+```python title="vs_comprehension.py" showLineNumbers{1} {1-9}
+numbers = [1, 2, 3, 4, 5, 6]
+
+# map + filter
+result_fp = list(map(lambda n: n * n, filter(lambda n: n % 2 == 0, numbers)))
+
+# equivalent comprehension
+result_comp = [n * n for n in numbers if n % 2 == 0]
+
+print(result_fp, result_comp)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python vs_comprehension.py
+[4, 16, 36] [4, 16, 36]
+```
+
+:::note
+Prefer comprehensions for `map`/`filter`-style work — they read better. Reach for `reduce` (or a plain loop) when you need to fold a sequence into a single accumulated value.
+:::
+
+## Conclusion
+`map`, `filter`, and `reduce` apply a function across an iterable in three different ways: `map` transforms every item, `filter` selects the items that pass a test, and `reduce` collapses the whole iterable into one value. `map` and `filter` are built in and return lazy iterators; `reduce` lives in `functools`. While comprehensions often replace `map` and `filter` more readably, `reduce` remains the go-to for accumulation. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Map, Filter, and Reduce Exercises
+
+### Exercise 1 – map()
+
+<DataCampExercise
+  lang="python"
+  hint={`map(function, iterable) applies the function to every item.`}
+  code={`# Task: Exercise 1 - map()
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+numbers = [1, 2, 3, 4]
+
+# Step: double every number with map and a lambda.
+# Hint: lambda n: n * 2
+doubled = map(___, numbers)  # replace ___ with the lambda
+
+# Step: turn the map object into a list to see it.
+print(list(___))  # replace ___ with the map result variable
+
+# -- Expected Output --------------------------------------------
+# [2, 4, 6, 8]
+# ---------------------------------------------------------------`}
+  solution={`numbers = [1, 2, 3, 4]
+doubled = map(lambda n: n * 2, numbers)
+print(list(doubled))`}
+  sct={`test_output_contains("[2, 4, 6, 8]")
+success_msg("You used map()!")`}
+  height={200}
+/>
+
+### Exercise 2 – filter()
+
+<DataCampExercise
+  lang="python"
+  hint={`filter keeps items where the function returns True.`}
+  code={`# Task: Exercise 2 - filter()
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+numbers = [5, 12, 7, 20, 3, 18]
+
+# Step: keep only numbers greater than 10.
+# Hint: lambda n: n > 10
+big = filter(___, numbers)  # replace ___ with the lambda
+
+print(list(big))
+
+# -- Expected Output --------------------------------------------
+# [12, 20, 18]
+# ---------------------------------------------------------------`}
+  solution={`numbers = [5, 12, 7, 20, 3, 18]
+big = filter(lambda n: n > 10, numbers)
+print(list(big))`}
+  sct={`test_output_contains("[12, 20, 18]")
+success_msg("You used filter()!")`}
+  height={200}
+/>
+
+### Exercise 3 – reduce()
+
+<DataCampExercise
+  lang="python"
+  hint={`Import reduce from functools; the lambda takes (accumulator, item).`}
+  code={`# Task: Exercise 3 - reduce()
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: import reduce from the functools module.
+from functools import ___  # replace ___ with the function name
+
+numbers = [1, 2, 3, 4, 5]
+
+# Step: multiply all numbers together (start at 1).
+# Hint: lambda acc, n: acc * n
+product = reduce(___, numbers, 1)  # replace ___ with the lambda
+
+print(product)
+
+# -- Expected Output --------------------------------------------
+# 120
+# ---------------------------------------------------------------`}
+  solution={`from functools import reduce
+
+numbers = [1, 2, 3, 4, 5]
+product = reduce(lambda acc, n: acc * n, numbers, 1)
+print(product)`}
+  sct={`test_output_contains("120")
+success_msg("You used reduce()!")`}
+  height={240}
+/>
diff --git a/src/content/docs/tutorials/Python Functional Programming/Recursion.mdx b/src/content/docs/tutorials/Python Functional Programming/Recursion.mdx
new file mode 100644
index 00000000..ef225ffb
--- /dev/null
+++ b/src/content/docs/tutorials/Python Functional Programming/Recursion.mdx	
@@ -0,0 +1,261 @@
+---
+title: Recursion in Python
+description: Learn about recursion in Python. Understand base cases and recursive cases, write recursive functions for factorials, Fibonacci numbers, and traversals, learn about the recursion limit, and compare recursion with iteration.
+sidebar: 
+    order: 103
+---
+
+## Mastering Recursion in Python: A Comprehensive Guide
+**Recursion** is when a function calls itself to solve a smaller version of the same problem. It is a powerful technique for problems that are naturally self-similar — factorials, tree traversals, and divide-and-conquer algorithms. In this guide, we'll explore base cases and recursive cases, build classic recursive functions, look at Python's recursion limit, and compare recursion with iteration.
+
+## What is Recursion?
+A **recursive function** is a function that calls itself. Every recursive solution has two parts:
+
+1. **Base case** — the simplest input, which the function answers directly *without* recursing. This stops the recursion.
+2. **Recursive case** — the function calls itself with a smaller or simpler input, moving toward the base case.
+
+:::caution
+Every recursive function **must** have a base case. Without one, the function calls itself forever and Python raises `RecursionError: maximum recursion depth exceeded`.
+:::
+
+## A First Example: Countdown
+```python title="countdown.py" showLineNumbers{1} {1-8}
+def countdown(n):
+    if n == 0:           # base case
+        print("Liftoff!")
+        return
+    print(n)
+    countdown(n - 1)     # recursive case - smaller input
+
+countdown(3)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python countdown.py
+3
+2
+1
+Liftoff!
+```
+
+**Diagram**:
+```mermaid title="recursion call stack" desc="How recursive countdown calls stack and unwind"
+graph TD
+    A["countdown(3)"] --> B["countdown(2)"]
+    B --> C["countdown(1)"]
+    C --> D["countdown(0) base case"]
+    D --> E["Liftoff! returns"]
+```
+
+## The Factorial Function
+The factorial of `n` (written `n!`) is the product of all positive integers up to `n`. It has a natural recursive definition: `n! = n * (n-1)!`, with `0! = 1` as the base case.
+
+```python title="factorial.py" showLineNumbers{1} {1-7}
+def factorial(n):
+    if n == 0 or n == 1:     # base case
+        return 1
+    return n * factorial(n - 1)   # recursive case
+
+print(factorial(5))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python factorial.py
+120
+```
+
+Here is how the calls expand and then collapse:
+
+```text title="factorial(5) expansion" showLineNumbers{1}
+factorial(5)
+= 5 * factorial(4)
+= 5 * (4 * factorial(3))
+= 5 * (4 * (3 * factorial(2)))
+= 5 * (4 * (3 * (2 * factorial(1))))
+= 5 * 4 * 3 * 2 * 1
+= 120
+```
+
+## The Fibonacci Sequence
+Each Fibonacci number is the sum of the two before it: `fib(n) = fib(n-1) + fib(n-2)`, with `fib(0) = 0` and `fib(1) = 1` as base cases.
+
+```python title="fibonacci.py" showLineNumbers{1} {1-8}
+def fib(n):
+    if n < 2:             # base cases: fib(0)=0, fib(1)=1
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+for i in range(7):
+    print(fib(i), end=" ")
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python fibonacci.py
+0 1 1 2 3 5 8
+```
+
+:::tip
+Naive recursive Fibonacci recomputes the same values many times and is slow for large `n`. Cache results with `functools.lru_cache` to make it fast: add `@lru_cache` above the function.
+:::
+
+## Recursion with a Collection: Summing a List
+Recursion also works on collections — handle the first item, then recurse on the rest.
+
+```python title="sum_list.py" showLineNumbers{1} {1-7}
+def sum_list(items):
+    if not items:            # base case: empty list
+        return 0
+    return items[0] + sum_list(items[1:])   # first + sum of the rest
+
+print(sum_list([1, 2, 3, 4, 5]))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python sum_list.py
+15
+```
+
+## The Recursion Limit
+Python limits how deep recursion can go (default around 1000 calls) to prevent a stack overflow from crashing the interpreter. You can inspect and change it.
+
+```python title="limit.py" showLineNumbers{1} {1-4}
+import sys
+print(sys.getrecursionlimit())   # default: 1000
+sys.setrecursionlimit(2000)      # raise it (use with care)
+```
+
+:::caution
+Raising the recursion limit too high can crash Python with a real stack overflow. If you need very deep recursion, rewrite the algorithm iteratively instead.
+:::
+
+## Recursion vs. Iteration
+Any recursive solution can be rewritten as a loop, and vice versa. The factorial as a loop:
+
+```python title="factorial_iterative.py" showLineNumbers{1} {1-6}
+def factorial(n):
+    result = 1
+    for i in range(2, n + 1):
+        result *= i
+    return result
+
+print(factorial(5))   # 120
+```
+
+| Recursion | Iteration |
+| :--- | :--- |
+| Often clearer for self-similar problems (trees, divide & conquer) | Often faster and uses less memory |
+| Uses the call stack — limited depth | No depth limit beyond available memory |
+| Elegant, fewer lines | More explicit state management |
+
+## Conclusion
+Recursion solves a problem by having a function call itself on a smaller input until it reaches a base case. Always define a base case to stop the recursion, and ensure each recursive call moves toward it. Classic examples include factorials, Fibonacci numbers, and list traversals. Remember Python's recursion depth limit, cache repeated work with `lru_cache`, and consider iteration when performance or depth matters. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Recursion Exercises
+
+### Exercise 1 – Factorial
+
+<DataCampExercise
+  lang="python"
+  hint={`Base case: n == 0 or 1 returns 1. Recursive case: n * factorial(n-1).`}
+  code={`# Task: Exercise 1 - Factorial
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def factorial(n):
+    # Step: base case - return 1 when n is 0 or 1.
+    if n == 0 or n == 1:
+        return ___  # replace ___ with the base value
+    # Step: recursive case - n times factorial of (n-1).
+    return n * factorial(___)  # replace ___ with the smaller input
+
+print(factorial(5))
+
+# -- Expected Output --------------------------------------------
+# 120
+# ---------------------------------------------------------------`}
+  solution={`def factorial(n):
+    if n == 0 or n == 1:
+        return 1
+    return n * factorial(n - 1)
+
+print(factorial(5))`}
+  sct={`test_output_contains("120")
+success_msg("You wrote a recursive factorial!")`}
+  height={220}
+/>
+
+### Exercise 2 – Sum a List Recursively
+
+<DataCampExercise
+  lang="python"
+  hint={`Base case: empty list returns 0. Recursive case: first item + sum of the rest.`}
+  code={`# Task: Exercise 2 - Sum a List Recursively
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def sum_list(items):
+    # Step: base case - an empty list sums to 0.
+    if not items:
+        return ___  # replace ___ with the base value
+    # Step: first element + sum of the remaining slice.
+    return items[0] + sum_list(items[___:])  # replace ___ so it skips the first item
+
+print(sum_list([10, 20, 30, 40]))
+
+# -- Expected Output --------------------------------------------
+# 100
+# ---------------------------------------------------------------`}
+  solution={`def sum_list(items):
+    if not items:
+        return 0
+    return items[0] + sum_list(items[1:])
+
+print(sum_list([10, 20, 30, 40]))`}
+  sct={`test_output_contains("100")
+success_msg("You summed a list with recursion!")`}
+  height={240}
+/>
+
+### Exercise 3 – Fibonacci
+
+<DataCampExercise
+  lang="python"
+  hint={`Base case: n < 2 returns n. Recursive case: fib(n-1) + fib(n-2).`}
+  code={`# Task: Exercise 3 - Fibonacci
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def fib(n):
+    # Step: base case - return n when n is 0 or 1.
+    if n < 2:
+        return ___  # replace ___ with the base value
+    # Step: sum of the two previous Fibonacci numbers.
+    return fib(n - 1) + fib(___)  # replace ___ with the second smaller input
+
+print(fib(7))
+
+# -- Expected Output --------------------------------------------
+# 13
+# ---------------------------------------------------------------`}
+  solution={`def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+print(fib(7))`}
+  sct={`test_output_contains("13")
+success_msg("You wrote a recursive Fibonacci!")`}
+  height={220}
+/>
diff --git a/src/content/docs/tutorials/Python Iterators and Generators/Iterators and Generators.mdx b/src/content/docs/tutorials/Python Iterators and Generators/Iterators and Generators.mdx
new file mode 100644
index 00000000..8eb34bab
--- /dev/null
+++ b/src/content/docs/tutorials/Python Iterators and Generators/Iterators and Generators.mdx	
@@ -0,0 +1,341 @@
+---
+title: Iterators and Generators in Python
+description: Learn about iterators and generators in Python. Understand the iterator protocol with __iter__ and __next__, build your own iterators, and use the yield keyword and generator expressions to produce values lazily and save memory.
+sidebar: 
+    order: 99
+---
+
+## Mastering Iterators and Generators in Python: A Comprehensive Guide
+Whenever you write a `for` loop over a list, string, or file, Python is using an **iterator** behind the scenes. Iterators let you walk through a collection one element at a time without loading everything into memory. **Generators** are a simple, elegant way to build iterators using the `yield` keyword. In this guide, we'll explore the iterator protocol, build custom iterators, and master generators and generator expressions.
+
+## What is an Iterable?
+An **iterable** is any object you can loop over — lists, tuples, strings, dictionaries, sets, and files are all iterables. An iterable can be passed to the built-in `iter()` function to get an **iterator**.
+
+```python title="iterable.py" showLineNumbers{1} {1-3}
+numbers = [1, 2, 3]
+for n in numbers:      # 'numbers' is an iterable
+    print(n)
+```
+
+## What is an Iterator?
+An **iterator** is an object that produces the next value each time you call `next()` on it. An iterator remembers its position. It follows the **iterator protocol**: it implements two methods, `__iter__()` and `__next__()`.
+
+```python title="iterator.py" showLineNumbers{1} {1-6}
+numbers = [10, 20, 30]
+it = iter(numbers)      # get an iterator from the iterable
+print(next(it))         # 10
+print(next(it))         # 20
+print(next(it))         # 30
+print(next(it))         # raises StopIteration
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-7}
+C:\Users\Your Name> python iterator.py
+10
+20
+30
+Traceback (most recent call last):
+StopIteration
+```
+
+When there are no more values, the iterator raises `StopIteration`. A `for` loop catches this exception automatically and stops looping.
+
+**Diagram**:
+```mermaid title="iterator protocol" desc="How a for loop uses the iterator protocol"
+graph TD
+    A[Start for loop] --> B[Call iter on iterable]
+    B --> C[Call next on iterator]
+    C --> D{StopIteration?}
+    D -->|No| E[Run loop body]
+    E --> C
+    D -->|Yes| F[End loop]
+```
+
+## Iterable vs. Iterator
+| Concept | Has `__iter__()` | Has `__next__()` | Example |
+| :--- | :---: | :---: | :--- |
+| Iterable | Yes | No | `list`, `str`, `dict` |
+| Iterator | Yes | Yes | result of `iter(list)` |
+
+:::note
+Every iterator is also an iterable (its `__iter__` returns itself), but not every iterable is an iterator. A `list` is iterable but not an iterator — you cannot call `next()` on it directly.
+:::
+
+## Building a Custom Iterator
+To create your own iterator class, implement `__iter__()` (which returns the iterator object, usually `self`) and `__next__()` (which returns the next value or raises `StopIteration`).
+
+```python title="custom_iterator.py" showLineNumbers{1} {1-17}
+class CountUpTo:
+    """Iterator that yields numbers from 1 up to a limit."""
+    def __init__(self, limit):
+        self.limit = limit
+        self.current = 0
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if self.current >= self.limit:
+            raise StopIteration
+        self.current += 1
+        return self.current
+
+for number in CountUpTo(3):
+    print(number)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python custom_iterator.py
+1
+2
+3
+```
+
+## What is a Generator?
+A **generator** is a special function that returns an iterator. Instead of `return`, it uses the `yield` keyword. Each time `yield` runs, the function's state is frozen and a value is produced; execution resumes from that point on the next `next()` call.
+
+The syntax of a generator function in Python is as follows:
+
+```python title="Syntax" showLineNumbers{1} {1-3}
+def generator_function():
+    yield value1
+    yield value2
+```
+
+The same `CountUpTo` logic as a generator — far shorter:
+
+```python title="generator.py" showLineNumbers{1} {1-8}
+def count_up_to(limit):
+    current = 1
+    while current <= limit:
+        yield current
+        current += 1
+
+for number in count_up_to(3):
+    print(number)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python generator.py
+1
+2
+3
+```
+
+:::tip
+A function is a generator if it contains *at least one* `yield` statement. Calling it does not run the body — it returns a generator object immediately. The body runs only as you iterate.
+:::
+
+## yield vs. return
+- `return` sends back a single value and ends the function permanently.
+- `yield` produces a value and *pauses* the function, keeping its local state so it can resume later.
+
+```python title="yield_pause.py" showLineNumbers{1} {1-10}
+def demo():
+    print("start")
+    yield 1
+    print("resumed")
+    yield 2
+    print("done")
+
+gen = demo()
+print(next(gen))   # prints 'start' then 1
+print(next(gen))   # prints 'resumed' then 2
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-5}
+C:\Users\Your Name> python yield_pause.py
+start
+1
+resumed
+2
+```
+
+## Why Generators Save Memory
+A generator produces values **lazily** — one at a time, only when requested. This means it never builds the whole sequence in memory. Compare creating a list of one million squares versus a generator:
+
+```python title="memory.py" showLineNumbers{1} {1-9}
+import sys
+
+# List: stores all million values at once
+squares_list = [x * x for x in range(1_000_000)]
+print("list bytes:", sys.getsizeof(squares_list))
+
+# Generator: stores almost nothing
+squares_gen = (x * x for x in range(1_000_000))
+print("generator bytes:", sys.getsizeof(squares_gen))
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-3}
+C:\Users\Your Name> python memory.py
+list bytes: 8448728
+generator bytes: 208
+```
+
+## Generator Expressions
+A **generator expression** looks like a list comprehension but uses parentheses `()` instead of square brackets `[]`. It produces a generator instead of a list.
+
+```python title="genexpr.py" showLineNumbers{1} {1-5}
+# List comprehension - builds a list
+squares = [x * x for x in range(5)]
+
+# Generator expression - lazy, no list built
+lazy_squares = (x * x for x in range(5))
+
+print(sum(x * x for x in range(5)))   # pass directly to sum()
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python genexpr.py
+30
+```
+
+:::tip
+When a generator expression is the only argument to a function, you can drop the extra parentheses: `sum(x*x for x in range(5))`.
+:::
+
+## Infinite Sequences
+Because generators are lazy, they can represent **infinite** sequences — something impossible with a list.
+
+```python title="infinite.py" showLineNumbers{1} {1-10}
+def naturals():
+    n = 1
+    while True:         # never stops on its own
+        yield n
+        n += 1
+
+gen = naturals()
+for value in gen:
+    if value > 5:
+        break
+    print(value)
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2-6}
+C:\Users\Your Name> python infinite.py
+1
+2
+3
+4
+5
+```
+
+## Conclusion
+Iterators are objects that produce values one at a time via `__iter__()` and `__next__()`, and they power every `for` loop in Python. Generators give you the same behaviour with far less code through the `yield` keyword, while generator expressions offer a compact, memory-efficient alternative to list comprehensions. Because they produce values lazily, generators can handle huge or even infinite sequences with almost no memory. For more hands-on examples and in-depth tutorials, explore our resources on Python Central Hub!
+
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+## Try it: Iterators and Generators Exercises
+
+### Exercise 1 – Using iter() and next()
+
+<DataCampExercise
+  lang="python"
+  hint={`iter(list) gives an iterator; next(iterator) returns the next item.`}
+  code={`# Task: Exercise 1 - Using iter() and next()
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+colors = ["red", "green", "blue"]
+
+# Step: turn the list into an iterator with iter().
+it = ___(colors)  # replace ___ with the correct function
+
+# Hint: next(it) returns the next element each time.
+print(___(it))  # replace ___ -> should print red
+print(___(it))  # replace ___ -> should print green
+
+# -- Expected Output --------------------------------------------
+# red
+# green
+# ---------------------------------------------------------------`}
+  solution={`colors = ["red", "green", "blue"]
+it = iter(colors)
+print(next(it))
+print(next(it))`}
+  sct={`test_output_contains("red")
+test_output_contains("green")
+success_msg("You used the iterator protocol!")`}
+  height={200}
+/>
+
+### Exercise 2 – Write a Generator Function
+
+<DataCampExercise
+  lang="python"
+  hint={`Use 'yield' inside a loop. A function with yield is a generator.`}
+  code={`# Task: Exercise 2 - Write a Generator Function
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+def count_up_to(limit):
+    current = 1
+    while current <= limit:
+        # Hint: produce the value WITHOUT ending the function.
+        ___ current  # replace ___ with the correct keyword
+        current += 1
+
+# Step: loop over the generator and print each value.
+for number in count_up_to(3):
+    print(number)
+
+# -- Expected Output --------------------------------------------
+# 1
+# 2
+# 3
+# ---------------------------------------------------------------`}
+  solution={`def count_up_to(limit):
+    current = 1
+    while current <= limit:
+        yield current
+        current += 1
+
+for number in count_up_to(3):
+    print(number)`}
+  sct={`test_output_contains("1")
+test_output_contains("3")
+success_msg("You wrote a generator with yield!")`}
+  height={240}
+/>
+
+### Exercise 3 – Generator Expression
+
+<DataCampExercise
+  lang="python"
+  hint={`A generator expression uses parentheses: (expr for item in iterable).`}
+  code={`# Task: Exercise 3 - Generator Expression
+# Follow the steps below and fill in the blanks.
+# Use the 'Show Solution' button only after you have tried!
+
+# Step: build a generator expression of squares for 1..5.
+# Hint: use () not [] so it stays lazy.
+squares = (x * x for ___ in range(1, 6))  # replace ___ with the loop variable
+
+# Step: sum the generator and print the total (1+4+9+16+25 = 55).
+print(sum(___))  # replace ___ with the generator variable
+
+# -- Expected Output --------------------------------------------
+# 55
+# ---------------------------------------------------------------`}
+  solution={`squares = (x * x for x in range(1, 6))
+print(sum(squares))`}
+  sct={`test_output_contains("55")
+success_msg("You mastered generator expressions!")`}
+  height={200}
+/>
diff --git a/src/content/docs/tutorials/Python Standard Library/Argparse and sys.argv.mdx b/src/content/docs/tutorials/Python Standard Library/Argparse and sys.argv.mdx
new file mode 100644
index 00000000..b1b7b584
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Argparse and sys.argv.mdx	
@@ -0,0 +1,216 @@
+---
+title: Python argparse & sys.argv — CLI Arguments
+description: A detailed guide to building command-line interfaces in Python with sys.argv and argparse. Learn positional and optional arguments, types, defaults, flags, and help text — with examples and practice exercises.
+sidebar:
+  order: 10
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+When you run a script from the terminal, the words after the script name are **command-line arguments**. Python gives you two ways to read them: the raw `sys.argv` list, and the full-featured `argparse` library.
+
+```python title="run_example.py"
+# $ python greet.py Ada --times 3
+import sys
+print(sys.argv)   # ['greet.py', 'Ada', '--times', '3']
+```
+
+## sys.argv — the raw list
+
+`sys.argv` is a list of strings. The first item is always the script name; the rest are the arguments, **as strings**.
+
+```python title="sys_argv.py"
+import sys
+
+# $ python add.py 3 4
+if len(sys.argv) != 3:
+    print("Usage: python add.py NUM NUM")
+    sys.exit(1)
+
+a = int(sys.argv[1])    # convert from string!
+b = int(sys.argv[2])
+print(a + b)            # 7
+```
+
+`sys.argv` is fine for one or two arguments, but it forces you to handle conversion, validation, defaults, and help text by hand. For anything real, use `argparse`.
+
+## argparse — the proper way
+
+`argparse` parses arguments, converts types, generates `--help`, and reports errors automatically.
+
+```python title="argparse_basic.py"
+import argparse
+
+parser = argparse.ArgumentParser(description="Greet someone.")
+parser.add_argument("name", help="who to greet")
+parser.add_argument("--times", type=int, default=1, help="how many times")
+
+args = parser.parse_args()           # reads from sys.argv
+for _ in range(args.times):
+    print(f"Hello, {args.name}!")
+```
+
+Running it:
+
+```bash title="terminal"
+$ python greet.py Ada --times 2
+Hello, Ada!
+Hello, Ada!
+
+$ python greet.py --help
+usage: greet.py [-h] [--times TIMES] name
+...
+```
+
+## Positional vs optional arguments
+
+| Kind | Defined as | Example |
+|:---|:---|:---|
+| **Positional** | `add_argument("name")` | `python app.py Ada` |
+| **Optional** | `add_argument("--times")` | `python app.py --times 3` |
+| **Flag** | `add_argument("--verbose", action="store_true")` | `python app.py --verbose` |
+
+```python title="positional_optional.py"
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("filename")                      # required positional
+parser.add_argument("--limit", type=int, default=10) # optional with default
+parser.add_argument("--verbose", action="store_true")# flag -> True/False
+
+# parse_args can take an explicit list (handy for testing)
+args = parser.parse_args(["data.txt", "--limit", "5", "--verbose"])
+print(args.filename)   # data.txt
+print(args.limit)      # 5
+print(args.verbose)    # True
+```
+
+> Tip: `parse_args()` reads `sys.argv` by default, but you can pass a list — `parse_args(["a", "b"])` — which is perfect for tests and examples.
+
+## Useful add_argument options
+
+| Option | Effect |
+|:---|:---|
+| `type=int` | Convert the value (to int, float, etc.). |
+| `default=...` | Value used when the argument is omitted. |
+| `required=True` | Make an optional argument mandatory. |
+| `choices=[...]` | Restrict to a fixed set of values. |
+| `action="store_true"` | Boolean flag (no value needed). |
+| `nargs="+"` | Accept multiple values into a list. |
+| `help="..."` | Text shown in `--help`. |
+
+```python title="advanced.py"
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--mode", choices=["fast", "safe"], default="safe")
+parser.add_argument("--files", nargs="+")   # one or more values
+args = parser.parse_args(["--mode", "fast", "--files", "a.txt", "b.txt"])
+print(args.mode)    # fast
+print(args.files)   # ['a.txt', 'b.txt']
+```
+
+## Short flags
+
+Add a one-letter alias alongside the long name:
+
+```python title="short_flags.py"
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("-n", "--number", type=int, default=1)
+args = parser.parse_args(["-n", "7"])
+print(args.number)   # 7
+```
+
+## Common pitfalls
+
+- **`sys.argv` values are strings** — convert with `int()`/`float()`.
+- **`sys.argv[0]` is the script name**, not the first argument.
+- **Dashes become underscores** — `--max-size` is read as `args.max_size`.
+- **`store_true` flags default to `False`** — presence flips them to `True`.
+- **argparse exits on bad input** — it prints usage and calls `sys.exit`, which is usually what you want.
+
+## Practice Exercises
+
+### Exercise 1 – Read from a simulated argv
+
+<DataCampExercise
+  lang="python"
+  hint={`Index sys.argv: [0] is the script, [1] is the first real argument.`}
+  code={`# Task: Pretend the script was run as: python app.py hello
+# Print the first real argument (index 1).
+import sys
+sys.argv = ["app.py", "hello", "world"]
+
+print(sys.argv[___])
+
+# Expected Output:
+# hello`}
+  solution={`import sys
+sys.argv = ["app.py", "hello", "world"]
+
+print(sys.argv[1])`}
+  sct={`test_output_contains("hello")
+success_msg("Index 1 is the first argument after the script name.")`}
+  height={170}
+/>
+
+### Exercise 2 – Parse a positional argument
+
+<DataCampExercise
+  lang="python"
+  hint={`add_argument("name"), then read args.name. Pass the list to parse_args.`}
+  code={`# Task: Define a positional 'name' argument and print it.
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("___")
+args = parser.parse_args(["Ada"])
+print(args.name)
+
+# Expected Output:
+# Ada`}
+  solution={`import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("name")
+args = parser.parse_args(["Ada"])
+print(args.name)`}
+  sct={`test_output_contains("Ada")
+success_msg("A positional argument is read by its name attribute.")`}
+  height={180}
+/>
+
+### Exercise 3 – An optional integer with a default
+
+<DataCampExercise
+  lang="python"
+  hint={`Use type=int and default=1, then parse an empty list to get the default.`}
+  code={`# Task: Define --count (int, default 5) and print the default value.
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--count", type=int, default=___)
+args = parser.parse_args([])   # no args -> use the default
+print(args.count)
+
+# Expected Output:
+# 5`}
+  solution={`import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--count", type=int, default=5)
+args = parser.parse_args([])
+print(args.count)`}
+  sct={`test_output_contains("5")
+success_msg("With no args supplied, argparse uses the default.")`}
+  height={190}
+/>
+
+## Summary
+
+- `sys.argv` is the raw list of string arguments (`argv[0]` is the script name).
+- `argparse` adds types, defaults, choices, flags, validation, and auto-generated `--help`.
+- Positional args are required; `--optional` args can have defaults; `store_true` makes boolean flags.
+- Pass an explicit list to `parse_args([...])` for testing and examples.
diff --git a/src/content/docs/tutorials/Python Standard Library/CSV.mdx b/src/content/docs/tutorials/Python Standard Library/CSV.mdx
new file mode 100644
index 00000000..dbd98e22
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/CSV.mdx	
@@ -0,0 +1,233 @@
+---
+title: Python csv — Read & Write CSV
+description: A detailed guide to Python's csv module. Learn to read and write CSV files with reader, writer, DictReader, and DictWriter, handle headers and dialects, with examples and practice exercises.
+sidebar:
+  order: 8
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+**CSV** (Comma-Separated Values) is the universal format for tabular data — spreadsheets, exports, datasets. The `csv` module reads and writes it correctly, handling quoting, commas inside fields, and newlines that naive string splitting would get wrong.
+
+```python title="quickstart.py"
+import csv
+import io
+
+# Read rows from CSV text
+text = "name,age\nAda,36\nBob,25"
+reader = csv.reader(io.StringIO(text))
+for row in reader:
+    print(row)
+# ['name', 'age']
+# ['Ada', '36']
+# ['Bob', '25']
+```
+
+> **Always open files with `newline=""`** when using `csv`. This lets the module handle line endings itself and prevents blank rows on Windows.
+
+## The four tools
+
+| Tool | Direction | Row shape |
+|:---|:---|:---|
+| `csv.reader(file)` | Read | Each row is a **list**. |
+| `csv.writer(file)` | Write | You pass **lists**. |
+| `csv.DictReader(file)` | Read | Each row is a **dict** keyed by header. |
+| `csv.DictWriter(file, fieldnames)` | Write | You pass **dicts**. |
+
+## Writing with csv.writer
+
+```python title="writer.py"
+import csv
+
+rows = [
+    ["name", "city"],
+    ["Ada", "London"],
+    ["Bob", "New York, NY"],   # comma inside a field is handled automatically
+]
+
+with open("people.csv", "w", newline="", encoding="utf-8") as f:
+    writer = csv.writer(f)
+    writer.writerow(["title", "year"])   # one row
+    writer.writerows(rows)               # many rows
+```
+
+The module **quotes** fields that contain commas, quotes, or newlines, so `"New York, NY"` stays a single field.
+
+## Reading with csv.reader
+
+```python title="reader.py"
+import csv
+
+with open("people.csv", "r", newline="", encoding="utf-8") as f:
+    reader = csv.reader(f)
+    header = next(reader)        # pull the header row off first
+    print("Header:", header)
+    for row in reader:
+        print(row)               # each row is a list of strings
+```
+
+> Every value read from CSV is a **string**. Convert numbers yourself: `int(row[1])`, `float(row[2])`.
+
+## DictReader — rows as dictionaries
+
+`DictReader` uses the first row as keys, so you access columns by name instead of position.
+
+```python title="dictreader.py"
+import csv
+import io
+
+text = "name,age,city\nAda,36,London\nBob,25,NYC"
+reader = csv.DictReader(io.StringIO(text))
+for row in reader:
+    print(row["name"], "is", row["age"])
+# Ada is 36
+# Bob is 25
+```
+
+## DictWriter — write dictionaries
+
+`DictWriter` needs `fieldnames`; call `writeheader()` to emit the header row.
+
+```python title="dictwriter.py"
+import csv
+
+people = [
+    {"name": "Ada", "age": 36},
+    {"name": "Bob", "age": 25},
+]
+
+with open("out.csv", "w", newline="", encoding="utf-8") as f:
+    writer = csv.DictWriter(f, fieldnames=["name", "age"])
+    writer.writeheader()
+    writer.writerows(people)
+```
+
+## Custom delimiters and dialects
+
+Not every "CSV" uses commas. Pass `delimiter` for TSV (tabs), semicolons, or pipes.
+
+```python title="delimiters.py"
+import csv
+import io
+
+tsv = "name\tage\nAda\t36"
+reader = csv.reader(io.StringIO(tsv), delimiter="\t")
+print(list(reader))   # [['name', 'age'], ['Ada', '36']]
+```
+
+| Parameter | Controls |
+|:---|:---|
+| `delimiter` | Field separator (default `,`). |
+| `quotechar` | Character used to quote fields (default `"`). |
+| `quoting` | When to quote (`csv.QUOTE_MINIMAL`, `QUOTE_ALL`, ...). |
+| `escapechar` | Escape character for special chars. |
+
+## Common pitfalls
+
+- **Missing `newline=""`** — causes blank rows between every record on Windows.
+- **Forgetting values are strings** — `row["age"] + 1` fails; convert with `int(...)` first.
+- **`DictWriter` without `writeheader()`** — produces a file with no header row.
+- **Mismatched `fieldnames`** — a dict key not in `fieldnames` raises `ValueError`.
+
+## Practice Exercises
+
+### Exercise 1 – Parse CSV text
+
+<DataCampExercise
+  lang="python"
+  hint={`Wrap the text in io.StringIO and pass it to csv.reader.`}
+  code={`# Task: Read the CSV text and print each row as a list.
+import csv
+import io
+
+text = "a,b\\n1,2\\n3,4"
+reader = csv.___(io.StringIO(text))
+for row in reader:
+    print(row)
+
+# Expected Output:
+# ['a', 'b']
+# ['1', '2']
+# ['3', '4']`}
+  solution={`import csv
+import io
+
+text = "a,b\\n1,2\\n3,4"
+reader = csv.reader(io.StringIO(text))
+for row in reader:
+    print(row)`}
+  sct={`test_output_contains("['1', '2']")
+success_msg("csv.reader splits each line into a list of fields.")`}
+  height={210}
+/>
+
+### Exercise 2 – Sum a numeric column
+
+<DataCampExercise
+  lang="python"
+  hint={`DictReader gives dicts; convert row['score'] to int before adding.`}
+  code={`# Task: Sum the 'score' column. Remember CSV values are strings!
+import csv
+import io
+
+text = "name,score\\nAda,10\\nBob,20\\nCara,30"
+reader = csv.DictReader(io.StringIO(text))
+total = 0
+for row in reader:
+    total += ___(row["score"])
+print(total)
+
+# Expected Output:
+# 60`}
+  solution={`import csv
+import io
+
+text = "name,score\\nAda,10\\nBob,20\\nCara,30"
+reader = csv.DictReader(io.StringIO(text))
+total = 0
+for row in reader:
+    total += int(row["score"])
+print(total)`}
+  sct={`test_output_contains("60")
+success_msg("int() converts the string score so it can be summed.")`}
+  height={230}
+/>
+
+### Exercise 3 – Write rows to CSV text
+
+<DataCampExercise
+  lang="python"
+  hint={`Use csv.writer on an io.StringIO buffer, then read getvalue().`}
+  code={`# Task: Write two rows and print the resulting CSV string.
+import csv
+import io
+
+buf = io.StringIO()
+writer = csv.writer(buf)
+writer.___(["x", "y"])
+writer.writerow([1, 2])
+print(buf.getvalue().strip())
+
+# Expected Output:
+# x,y
+# 1,2`}
+  solution={`import csv
+import io
+
+buf = io.StringIO()
+writer = csv.writer(buf)
+writer.writerow(["x", "y"])
+writer.writerow([1, 2])
+print(buf.getvalue().strip())`}
+  sct={`test_output_contains("x,y")
+success_msg("writerow turns a list into one CSV line.")`}
+  height={210}
+/>
+
+## Summary
+
+- The `csv` module handles quoting and embedded commas/newlines that manual splitting breaks.
+- Use `reader`/`writer` for lists, `DictReader`/`DictWriter` for dicts keyed by header.
+- Open files with `newline=""` and an explicit `encoding`.
+- Remember every read value is a **string** — convert numbers yourself.
+- Set `delimiter` for TSV and other separated formats.
diff --git a/src/content/docs/tutorials/Python Standard Library/Collections.mdx b/src/content/docs/tutorials/Python Standard Library/Collections.mdx
new file mode 100644
index 00000000..6555c4b4
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Collections.mdx	
@@ -0,0 +1,261 @@
+---
+title: Python collections — Counter, defaultdict, namedtuple, deque
+description: A detailed guide to Python's collections module. Learn Counter, defaultdict, namedtuple, deque, OrderedDict, and ChainMap with examples and practice exercises.
+sidebar:
+  order: 4
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+The `collections` module provides **specialized container types** that go beyond the built-in `list`, `dict`, `tuple`, and `set`. They make common tasks — counting, grouping, fixed-field records, and fast queues — shorter and faster.
+
+```python title="overview.py"
+from collections import Counter, defaultdict, namedtuple, deque
+
+print(Counter("banana"))                  # Counter({'a': 3, 'n': 2, 'b': 1})
+print(defaultdict(list))                  # defaultdict(<class 'list'>, {})
+Point = namedtuple("Point", "x y")
+print(Point(1, 2))                         # Point(x=1, y=2)
+print(deque([1, 2, 3]))                    # deque([1, 2, 3])
+```
+
+| Type | Use it for |
+|:---|:---|
+| `Counter` | Counting hashable items (tallies, frequencies). |
+| `defaultdict` | A dict that auto-creates default values for missing keys. |
+| `namedtuple` | Lightweight, immutable records with named fields. |
+| `deque` | Fast appends/pops at **both** ends (queues, stacks). |
+| `OrderedDict` | A dict with extra order-related methods. |
+| `ChainMap` | Search multiple dicts as one. |
+
+## Counter
+
+`Counter` is a `dict` subclass for counting. Pass any iterable and it tallies occurrences.
+
+```python title="counter.py"
+from collections import Counter
+
+votes = ["a", "b", "a", "c", "a", "b"]
+c = Counter(votes)
+print(c)                  # Counter({'a': 3, 'b': 2, 'c': 1})
+print(c["a"])             # 3
+print(c["z"])             # 0  (missing keys return 0, never KeyError)
+
+# Most common items
+print(c.most_common(2))   # [('a', 3), ('b', 2)]
+
+# Counters do arithmetic
+c2 = Counter("aab")
+print(c + c2)             # combine counts
+print(c - c2)             # subtract counts
+
+# Update with more data
+c.update(["a", "d"])
+print(c["a"], c["d"])     # 4 1
+```
+
+| Method | Returns |
+|:---|:---|
+| `c.most_common(n)` | The `n` highest-count `(item, count)` pairs. |
+| `c.elements()` | An iterator repeating each element by its count. |
+| `c.update(iterable)` | Add counts from another iterable/Counter. |
+| `c.total()` | Sum of all counts (Python 3.10+). |
+
+## defaultdict
+
+A regular dict raises `KeyError` for a missing key. A `defaultdict` instead calls a **factory** function to create a default value automatically — perfect for grouping and accumulating.
+
+```python title="defaultdict.py"
+from collections import defaultdict
+
+# Group words by their first letter
+words = ["apple", "banana", "avocado", "cherry", "blueberry"]
+groups = defaultdict(list)
+for w in words:
+    groups[w[0]].append(w)
+print(dict(groups))
+# {'a': ['apple', 'avocado'], 'b': ['banana', 'blueberry'], 'c': ['cherry']}
+
+# Count with an int factory (default 0)
+counts = defaultdict(int)
+for ch in "mississippi":
+    counts[ch] += 1
+print(dict(counts))   # {'m': 1, 'i': 4, 's': 4, 'p': 2}
+```
+
+The factory can be `list`, `int`, `set`, `dict`, or any zero-argument callable.
+
+## namedtuple
+
+`namedtuple` creates a tuple subclass with **named fields** — readable, immutable records without writing a full class.
+
+```python title="namedtuple.py"
+from collections import namedtuple
+
+Point = namedtuple("Point", ["x", "y"])
+p = Point(3, 4)
+
+print(p.x, p.y)          # 3 4   (access by name)
+print(p[0], p[1])        # 3 4   (still a tuple — index access works)
+
+# Unpacking works too
+x, y = p
+print(x, y)              # 3 4
+
+# Handy helpers
+print(p._asdict())       # {'x': 3, 'y': 4}
+p2 = p._replace(y=10)    # returns a NEW point (immutable)
+print(p2)                # Point(x=3, y=10)
+```
+
+Use a namedtuple when you have a small fixed set of fields and want clarity over a bare tuple or dict.
+
+## deque
+
+A `deque` ("double-ended queue") supports **O(1)** appends and pops from both ends — unlike a list, which is slow at the front.
+
+```python title="deque.py"
+from collections import deque
+
+dq = deque([1, 2, 3])
+dq.append(4)         # add right -> deque([1, 2, 3, 4])
+dq.appendleft(0)     # add left  -> deque([0, 1, 2, 3, 4])
+print(dq.pop())      # 4  (remove right)
+print(dq.popleft())  # 0  (remove left)
+print(dq)            # deque([1, 2, 3])
+
+# Fixed-size deque: old items drop off automatically
+last3 = deque(maxlen=3)
+for i in range(6):
+    last3.append(i)
+print(last3)         # deque([3, 4, 5], maxlen=3)
+
+# Rotate
+d = deque([1, 2, 3, 4])
+d.rotate(1)          # deque([4, 1, 2, 3])
+print(d)
+```
+
+| Method | Effect |
+|:---|:---|
+| `append(x)` / `appendleft(x)` | Add to the right / left. |
+| `pop()` / `popleft()` | Remove from the right / left. |
+| `extend(it)` / `extendleft(it)` | Add many to the right / left. |
+| `rotate(n)` | Rotate items `n` steps to the right. |
+| `maxlen` | Optional fixed length; overflow drops the opposite end. |
+
+## OrderedDict and ChainMap (briefly)
+
+```python title="others.py"
+from collections import OrderedDict, ChainMap
+
+# OrderedDict: insertion order is preserved (regular dicts do this too since 3.7),
+# but it adds move_to_end() and an order-sensitive ==.
+od = OrderedDict([("a", 1), ("b", 2)])
+od.move_to_end("a")
+print(list(od))             # ['b', 'a']
+
+# ChainMap: search several dicts as one, first match wins.
+defaults = {"color": "red", "size": "M"}
+overrides = {"color": "blue"}
+settings = ChainMap(overrides, defaults)
+print(settings["color"])    # blue  (overrides win)
+print(settings["size"])     # M     (falls back to defaults)
+```
+
+## Common pitfalls
+
+- **`defaultdict` creates keys on access** — even just reading `d[missing]` inserts it. Use `d.get(k)` if you don't want that.
+- **namedtuples are immutable** — `_replace` returns a new instance; it doesn't mutate.
+- **Use `deque` for queues**, not `list.pop(0)`, which is O(n).
+- **`Counter` values can go negative** after subtraction; use `+c` to drop non-positive counts.
+
+## Practice Exercises
+
+### Exercise 1 – Count characters
+
+<DataCampExercise
+  lang="python"
+  hint={`Pass the string straight into Counter, then call most_common(1).`}
+  code={`# Task: Find the most common character in the word and its count.
+from collections import Counter
+
+word = "mountain"
+c = ___(word)
+print(c.most_common(1))
+
+# Expected Output:
+# [('n', 2)]`}
+  solution={`from collections import Counter
+
+word = "mountain"
+c = Counter(word)
+print(c.most_common(1))`}
+  sct={`test_output_contains("('n', 2)")
+success_msg("Counter.most_common(1) returns the single top item.")`}
+  height={170}
+/>
+
+### Exercise 2 – Group numbers by even/odd
+
+<DataCampExercise
+  lang="python"
+  hint={`Use defaultdict(list) and append each number under the key 'even' or 'odd'.`}
+  code={`# Task: Split numbers into 'even' and 'odd' lists.
+from collections import defaultdict
+
+nums = [1, 2, 3, 4, 5, 6]
+groups = defaultdict(___)
+for n in nums:
+    key = "even" if n % 2 == 0 else "odd"
+    groups[key].append(n)
+print(dict(groups))
+
+# Expected Output:
+# {'odd': [1, 3, 5], 'even': [2, 4, 6]}`}
+  solution={`from collections import defaultdict
+
+nums = [1, 2, 3, 4, 5, 6]
+groups = defaultdict(list)
+for n in nums:
+    key = "even" if n % 2 == 0 else "odd"
+    groups[key].append(n)
+print(dict(groups))`}
+  sct={`test_output_contains("'odd': [1, 3, 5]")
+success_msg("defaultdict(list) auto-creates an empty list per new key.")`}
+  height={200}
+/>
+
+### Exercise 3 – Keep the last 3 items
+
+<DataCampExercise
+  lang="python"
+  hint={`Create a deque with maxlen=3, then append all six numbers.`}
+  code={`# Task: Keep only the last 3 numbers seen using a bounded deque.
+from collections import deque
+
+recent = deque(maxlen=___)
+for i in range(6):
+    recent.append(i)
+print(list(recent))
+
+# Expected Output:
+# [3, 4, 5]`}
+  solution={`from collections import deque
+
+recent = deque(maxlen=3)
+for i in range(6):
+    recent.append(i)
+print(list(recent))`}
+  sct={`test_output_contains("[3, 4, 5]")
+success_msg("A maxlen deque drops the oldest item when full.")`}
+  height={180}
+/>
+
+## Summary
+
+- **`Counter`** tallies items and ranks them with `most_common`.
+- **`defaultdict`** removes `KeyError` boilerplate for grouping/accumulating.
+- **`namedtuple`** gives readable, immutable records with named fields.
+- **`deque`** is the right tool for fast double-ended queues and bounded buffers.
+- **`OrderedDict`** and **`ChainMap`** cover order-sensitive and layered-lookup needs.
diff --git a/src/content/docs/tutorials/Python Standard Library/Date and Time.mdx b/src/content/docs/tutorials/Python Standard Library/Date and Time.mdx
new file mode 100644
index 00000000..9f24276c
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Date and Time.mdx	
@@ -0,0 +1,305 @@
+---
+title: Python Date & Time — datetime, time, calendar
+description: A detailed guide to Python's datetime, time, and calendar modules. Learn to create, format, parse, and do arithmetic with dates and times, handle time zones, and work with calendars — with examples and practice exercises.
+sidebar:
+  order: 2
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+Python ships three complementary modules for working with dates and times:
+
+- **`datetime`** — high-level objects for dates, times, and durations. This is what you reach for most.
+- **`time`** — lower-level, OS-facing functions (timestamps, sleeping, performance timers).
+- **`calendar`** — calendar-related helpers (leap years, weekday names, month grids).
+
+```python title="overview.py"
+import datetime, time, calendar
+
+print(datetime.date.today())        # 2025-01-31
+print(time.time())                  # 1738291200.123  (seconds since epoch)
+print(calendar.isleap(2024))        # True
+```
+
+## The `datetime` module
+
+It defines four key classes:
+
+| Class | Represents |
+|:---|:---|
+| `date` | A calendar date — year, month, day. |
+| `time` | A time of day — hour, minute, second, microsecond. |
+| `datetime` | A date **and** a time combined. |
+| `timedelta` | A **duration** — the difference between two dates/times. |
+
+### Creating dates and times
+
+```python title="creating.py"
+from datetime import date, time, datetime
+
+d = date(2025, 1, 31)
+print(d.year, d.month, d.day)   # 2025 1 31
+
+t = time(14, 30, 15)
+print(t.hour, t.minute)         # 14 30
+
+dt = datetime(2025, 1, 31, 14, 30, 15)
+print(dt)                       # 2025-01-31 14:30:15
+
+# "Now" helpers
+print(date.today())             # today's date
+print(datetime.now())           # local date + time right now
+```
+
+### Accessing parts
+
+```python title="attributes.py"
+from datetime import datetime
+
+dt = datetime(2025, 1, 31, 14, 30, 15)
+print(dt.date())        # 2025-01-31
+print(dt.time())        # 14:30:15
+print(dt.weekday())     # 4  (Mon=0 ... Sun=6)
+print(dt.isoweekday())  # 5  (Mon=1 ... Sun=7)
+print(dt.isoformat())   # 2025-01-31T14:30:15
+```
+
+## Formatting with `strftime`
+
+`strftime` ("string format time") turns a date/time **into** a string using format codes.
+
+| Code | Meaning | Example |
+|:---|:---|:---|
+| `%Y` | 4-digit year | 2025 |
+| `%y` | 2-digit year | 25 |
+| `%m` | Month, zero-padded | 01 |
+| `%B` | Full month name | January |
+| `%b` | Abbreviated month | Jan |
+| `%d` | Day of month | 31 |
+| `%A` | Full weekday name | Friday |
+| `%a` | Abbreviated weekday | Fri |
+| `%H` | Hour (24-hour) | 14 |
+| `%I` | Hour (12-hour) | 02 |
+| `%M` | Minute | 30 |
+| `%S` | Second | 15 |
+| `%p` | AM / PM | PM |
+| `%j` | Day of the year | 031 |
+
+```python title="strftime.py"
+from datetime import datetime
+
+dt = datetime(2025, 1, 31, 14, 30, 15)
+print(dt.strftime("%Y-%m-%d"))            # 2025-01-31
+print(dt.strftime("%A, %B %d, %Y"))       # Friday, January 31, 2025
+print(dt.strftime("%I:%M %p"))            # 02:30 PM
+```
+
+## Parsing with `strptime`
+
+`strptime` ("string parse time") does the reverse — it reads a string **into** a `datetime`, given a format that describes its layout.
+
+```python title="strptime.py"
+from datetime import datetime
+
+s = "2025-01-31 14:30"
+dt = datetime.strptime(s, "%Y-%m-%d %H:%M")
+print(dt)             # 2025-01-31 14:30:00
+print(type(dt))       # <class 'datetime.datetime'>
+
+# ISO strings have a dedicated fast parser:
+print(datetime.fromisoformat("2025-01-31T14:30:15"))
+```
+
+## Date arithmetic with `timedelta`
+
+A `timedelta` is a span of time. Add or subtract it from dates; subtract two dates to get a `timedelta`.
+
+```python title="timedelta.py"
+from datetime import date, datetime, timedelta
+
+today = date(2025, 1, 31)
+week_later = today + timedelta(days=7)
+print(week_later)                 # 2025-02-07
+
+start = datetime(2025, 1, 1, 9, 0)
+end = datetime(2025, 1, 1, 17, 30)
+worked = end - start
+print(worked)                     # 8:30:00
+print(worked.total_seconds())     # 30600.0
+
+# timedelta accepts weeks, days, hours, minutes, seconds
+print(timedelta(weeks=2, days=3)) # 17 days, 0:00:00
+```
+
+## Time zones (aware vs naive)
+
+A datetime with no time zone is **naive**; one carrying `tzinfo` is **aware**. Prefer aware datetimes for anything crossing zones. Since Python 3.9 the standard library includes `zoneinfo`.
+
+```python title="timezones.py"
+from datetime import datetime, timezone, timedelta
+from zoneinfo import ZoneInfo
+
+# UTC-aware "now"
+now_utc = datetime.now(timezone.utc)
+print(now_utc.tzinfo)             # UTC
+
+# Convert between zones
+ny = datetime(2025, 1, 31, 12, 0, tzinfo=ZoneInfo("America/New_York"))
+tokyo = ny.astimezone(ZoneInfo("Asia/Tokyo"))
+print(tokyo)                      # 2025-02-01 02:00:00+09:00
+```
+
+## The `time` module
+
+Lower-level utilities tied to the operating system clock.
+
+| Function | Purpose |
+|:---|:---|
+| `time.time()` | Seconds since the epoch (a float timestamp). |
+| `time.sleep(secs)` | Pause execution. |
+| `time.localtime()` | Convert a timestamp to a local `struct_time`. |
+| `time.gmtime()` | Convert a timestamp to a UTC `struct_time`. |
+| `time.strftime(fmt, t)` | Format a `struct_time`. |
+| `time.perf_counter()` | High-resolution timer for benchmarking. |
+
+```python title="time_module.py"
+import time
+
+start = time.perf_counter()
+time.sleep(0.1)                       # pause 100 ms
+elapsed = time.perf_counter() - start
+print(f"Slept for {elapsed:.3f}s")    # Slept for 0.100s
+
+ts = time.time()
+print(time.strftime("%Y-%m-%d", time.localtime(ts)))
+```
+
+> Use `perf_counter()` to **measure durations**, and `time()` to get a **timestamp**. Never use `time()` for benchmarking — it can jump if the system clock changes.
+
+## The `calendar` module
+
+Helpers for reasoning about months, weeks, and leap years.
+
+| Function | Returns |
+|:---|:---|
+| `calendar.isleap(year)` | `True` if the year is a leap year. |
+| `calendar.monthrange(y, m)` | `(first_weekday, num_days)` for that month. |
+| `calendar.weekday(y, m, d)` | Weekday index (Mon=0). |
+| `calendar.month(y, m)` | A text calendar for the month. |
+| `calendar.day_name[i]` | Full weekday name for index `i`. |
+
+```python title="calendar_module.py"
+import calendar
+
+print(calendar.isleap(2024))           # True
+print(calendar.monthrange(2025, 2))    # (5, 28)  -> starts Sat, 28 days
+print(calendar.day_name[0])            # Monday
+
+# Print a whole month grid
+print(calendar.month(2025, 1))
+```
+
+## Putting it together
+
+```python title="age_in_days.py"
+from datetime import date
+
+def days_until_birthday(birth_month, birth_day):
+    today = date.today()
+    this_year = date(today.year, birth_month, birth_day)
+    next_bday = this_year if this_year >= today else date(today.year + 1, birth_month, birth_day)
+    return (next_bday - today).days
+
+print(days_until_birthday(12, 25))   # days until the next Dec 25
+```
+
+## Common pitfalls
+
+- **Mixing naive and aware datetimes** raises `TypeError` when you subtract them. Pick one and stick with it.
+- **`weekday()` vs `isoweekday()`** — one starts Monday at 0, the other at 1.
+- **`strptime` format must match exactly**, including separators, or it raises `ValueError`.
+- **`time.sleep` blocks the whole thread** — fine for scripts, but use async patterns in servers.
+
+## Practice Exercises
+
+### Exercise 1 – Format today's date
+
+<DataCampExercise
+  lang="python"
+  hint={`Build a date, then call strftime with the codes %Y, %m, and %d.`}
+  code={`# Task: Print the date 2025-01-31 in the format "31/01/2025".
+# Step 1: import the date class.
+# Step 2: use strftime with the right format codes.
+from datetime import date
+
+d = date(2025, 1, 31)
+print(d.strftime("___"))
+
+# Expected Output:
+# 31/01/2025`}
+  solution={`from datetime import date
+
+d = date(2025, 1, 31)
+print(d.strftime("%d/%m/%Y"))`}
+  sct={`test_output_contains("31/01/2025")
+success_msg("Great! %d/%m/%Y gives day/month/year.")`}
+  height={170}
+/>
+
+### Exercise 2 – Days between two dates
+
+<DataCampExercise
+  lang="python"
+  hint={`Subtract the earlier date from the later one and read the .days attribute.`}
+  code={`# Task: Compute how many days are between 2025-01-01 and 2025-12-31.
+from datetime import date
+
+start = date(2025, 1, 1)
+end = date(2025, 12, 31)
+diff = ___ - ___
+print(diff.___)
+
+# Expected Output:
+# 364`}
+  solution={`from datetime import date
+
+start = date(2025, 1, 1)
+end = date(2025, 12, 31)
+diff = end - start
+print(diff.days)`}
+  sct={`test_output_contains("364")
+success_msg("Subtracting dates yields a timedelta; .days is the day count.")`}
+  height={180}
+/>
+
+### Exercise 3 – Is it a leap year?
+
+<DataCampExercise
+  lang="python"
+  hint={`The calendar module has a function named isleap.`}
+  code={`# Task: Print whether 2024 and 2025 are leap years.
+import calendar
+
+print(calendar.___(2024))
+print(calendar.___(2025))
+
+# Expected Output:
+# True
+# False`}
+  solution={`import calendar
+
+print(calendar.isleap(2024))
+print(calendar.isleap(2025))`}
+  sct={`test_output_contains("True")
+test_output_contains("False")
+success_msg("calendar.isleap tells you if a year has 366 days.")`}
+  height={160}
+/>
+
+## Summary
+
+- Use **`datetime`** for dates, times, durations (`timedelta`), and arithmetic.
+- **Format** with `strftime`, **parse** with `strptime` / `fromisoformat`.
+- Prefer **aware** datetimes (`timezone.utc`, `zoneinfo.ZoneInfo`) when zones matter.
+- **`time`** gives timestamps, sleeping, and `perf_counter` for benchmarks.
+- **`calendar`** answers leap-year, weekday, and month-grid questions.
diff --git a/src/content/docs/tutorials/Python Standard Library/Itertools and Functools.mdx b/src/content/docs/tutorials/Python Standard Library/Itertools and Functools.mdx
new file mode 100644
index 00000000..9de2cc11
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Itertools and Functools.mdx	
@@ -0,0 +1,270 @@
+---
+title: Python itertools & functools
+description: A detailed guide to Python's itertools and functools modules. Learn iterator building blocks (chain, product, combinations, groupby, accumulate) and higher-order helpers (reduce, lru_cache, partial, wraps) with examples and practice exercises.
+sidebar:
+  order: 5
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+These two modules power Python's **functional** toolkit:
+
+- **`itertools`** — fast, memory-efficient building blocks for working with iterators.
+- **`functools`** — higher-order functions that act on or return other functions (caching, partial application, reduction).
+
+```python title="overview.py"
+import itertools, functools
+
+print(list(itertools.chain([1, 2], [3, 4])))     # [1, 2, 3, 4]
+print(functools.reduce(lambda a, b: a + b, [1, 2, 3, 4]))  # 10
+```
+
+## itertools
+
+Iterators produce values **lazily** — one at a time, without building a whole list in memory. Many `itertools` tools return infinite or large iterators, so wrap them in `list(...)` or `islice(...)` to inspect them.
+
+### Infinite iterators
+
+| Function | Produces |
+|:---|:---|
+| `count(start, step)` | `start, start+step, ...` forever. |
+| `cycle(iterable)` | Repeats the iterable endlessly. |
+| `repeat(x, n)` | `x`, `n` times (or forever if `n` omitted). |
+
+```python title="infinite.py"
+from itertools import count, cycle, repeat, islice
+
+print(list(islice(count(10, 2), 4)))   # [10, 12, 14, 16]
+print(list(islice(cycle("AB"), 5)))    # ['A', 'B', 'A', 'B', 'A']
+print(list(repeat("x", 3)))            # ['x', 'x', 'x']
+```
+
+### Combining and slicing iterators
+
+| Function | Effect |
+|:---|:---|
+| `chain(a, b, ...)` | Concatenate iterables end to end. |
+| `islice(it, stop)` | Slice an iterator like a list. |
+| `compress(data, sel)` | Keep items where the selector is truthy. |
+| `zip_longest(a, b)` | Like `zip` but pads the shorter one. |
+
+```python title="combining.py"
+from itertools import chain, islice, compress, zip_longest
+
+print(list(chain([1, 2], [3], [4, 5])))            # [1, 2, 3, 4, 5]
+print(list(compress("ABCD", [1, 0, 1, 0])))        # ['A', 'C']
+print(list(zip_longest([1, 2, 3], ["a"], fillvalue="-")))
+# [(1, 'a'), (2, '-'), (3, '-')]
+```
+
+### Combinatorics
+
+| Function | Produces |
+|:---|:---|
+| `product(a, b)` | Cartesian product (nested loops). |
+| `permutations(it, r)` | All ordered arrangements of length `r`. |
+| `combinations(it, r)` | All unordered selections of length `r`. |
+| `combinations_with_replacement(it, r)` | Selections allowing repeats. |
+
+```python title="combinatorics.py"
+from itertools import product, permutations, combinations
+
+print(list(product([1, 2], ["a", "b"])))
+# [(1, 'a'), (1, 'b'), (2, 'a'), (2, 'b')]
+print(list(permutations([1, 2, 3], 2)))
+# [(1, 2), (1, 3), (2, 1), (2, 3), (3, 1), (3, 2)]
+print(list(combinations([1, 2, 3], 2)))
+# [(1, 2), (1, 3), (2, 3)]
+```
+
+### Grouping and accumulating
+
+```python title="group_accumulate.py"
+from itertools import groupby, accumulate
+
+# groupby groups CONSECUTIVE equal keys -> sort first if needed
+data = [("fruit", "apple"), ("fruit", "pear"), ("veg", "kale")]
+for key, items in groupby(data, key=lambda pair: pair[0]):
+    print(key, [name for _, name in items])
+# fruit ['apple', 'pear']
+# veg ['kale']
+
+# accumulate yields running totals (or any binary function)
+print(list(accumulate([1, 2, 3, 4])))            # [1, 3, 6, 10]
+print(list(accumulate([1, 2, 3, 4], max)))       # [1, 2, 3, 4]
+```
+
+## functools
+
+### reduce
+
+`reduce` folds an iterable into a single value by repeatedly applying a two-argument function.
+
+```python title="reduce.py"
+from functools import reduce
+
+print(reduce(lambda a, b: a + b, [1, 2, 3, 4]))      # 10
+print(reduce(lambda a, b: a * b, [1, 2, 3, 4]))      # 24
+print(reduce(lambda a, b: a if a > b else b, [3, 9, 2]))  # 9 (max)
+```
+
+### lru_cache and cache — memoization
+
+`@lru_cache` stores recent results so repeated calls with the same arguments are instant. Great for expensive or recursive functions.
+
+```python title="lru_cache.py"
+from functools import lru_cache
+
+@lru_cache(maxsize=None)   # unbounded cache
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+print(fib(30))             # 832040 — fast, thanks to caching
+print(fib.cache_info())    # CacheInfo(hits=..., misses=..., ...)
+```
+
+> In Python 3.9+, `@functools.cache` is a simpler alias for `@lru_cache(maxsize=None)`.
+
+### partial — pre-fill arguments
+
+`partial` creates a new function with some arguments already supplied.
+
+```python title="partial.py"
+from functools import partial
+
+def power(base, exp):
+    return base ** exp
+
+square = partial(power, exp=2)
+cube = partial(power, exp=3)
+print(square(5))   # 25
+print(cube(2))     # 8
+
+# Common in callbacks: partial(int, base=2) parses binary
+to_binary = partial(int, base=2)
+print(to_binary("1010"))   # 10
+```
+
+### wraps — preserve metadata in decorators
+
+When you write a decorator, `@wraps` copies the original function's name and docstring onto the wrapper.
+
+```python title="wraps.py"
+from functools import wraps
+
+def shout(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs).upper()
+    return wrapper
+
+@shout
+def greet(name):
+    "Return a greeting."
+    return f"hello {name}"
+
+print(greet("ada"))      # HELLO ADA
+print(greet.__name__)    # greet  (preserved by @wraps)
+print(greet.__doc__)     # Return a greeting.
+```
+
+| functools tool | Purpose |
+|:---|:---|
+| `reduce(func, it)` | Fold an iterable to one value. |
+| `lru_cache` / `cache` | Memoize function results. |
+| `partial(func, *args)` | Bind some arguments ahead of time. |
+| `wraps` | Keep metadata when writing decorators. |
+| `cmp_to_key` | Adapt an old-style comparison function for `sorted`. |
+| `total_ordering` | Fill in missing comparison methods on a class. |
+
+## Common pitfalls
+
+- **Iterators are single-use** — once consumed, they're empty. Re-create them to iterate again.
+- **`groupby` only groups adjacent equal keys** — sort by the key first if groups aren't contiguous.
+- **Infinite iterators** (`count`, `cycle`) will hang `list()` — slice them with `islice`.
+- **`lru_cache` requires hashable arguments** — you can't cache calls that take lists or dicts.
+
+## Practice Exercises
+
+### Exercise 1 – Running totals
+
+<DataCampExercise
+  lang="python"
+  hint={`itertools.accumulate yields a running total by default.`}
+  code={`# Task: Print the running totals of [10, 20, 30].
+from itertools import accumulate
+
+nums = [10, 20, 30]
+print(list(___(nums)))
+
+# Expected Output:
+# [10, 30, 60]`}
+  solution={`from itertools import accumulate
+
+nums = [10, 20, 30]
+print(list(accumulate(nums)))`}
+  sct={`test_output_contains("[10, 30, 60]")
+success_msg("accumulate produces a cumulative sum.")`}
+  height={160}
+/>
+
+### Exercise 2 – Multiply a list with reduce
+
+<DataCampExercise
+  lang="python"
+  hint={`reduce applies the function pairwise: ((1*2)*3)*4.`}
+  code={`# Task: Multiply all numbers together using functools.reduce.
+from functools import reduce
+
+nums = [1, 2, 3, 4]
+product = ___(lambda a, b: a * b, nums)
+print(product)
+
+# Expected Output:
+# 24`}
+  solution={`from functools import reduce
+
+nums = [1, 2, 3, 4]
+product = reduce(lambda a, b: a * b, nums)
+print(product)`}
+  sct={`test_output_contains("24")
+success_msg("reduce folds the list into a single product.")`}
+  height={170}
+/>
+
+### Exercise 3 – Pre-fill an argument with partial
+
+<DataCampExercise
+  lang="python"
+  hint={`partial(func, exp=2) fixes the exp argument to 2.`}
+  code={`# Task: Build a 'square' function from 'power' using functools.partial.
+from functools import partial
+
+def power(base, exp):
+    return base ** exp
+
+square = ___(power, exp=2)
+print(square(6))
+
+# Expected Output:
+# 36`}
+  solution={`from functools import partial
+
+def power(base, exp):
+    return base ** exp
+
+square = partial(power, exp=2)
+print(square(6))`}
+  sct={`test_output_contains("36")
+success_msg("partial binds exp=2, leaving base to be supplied later.")`}
+  height={190}
+/>
+
+## Summary
+
+- **`itertools`** offers lazy building blocks: infinite generators, combiners (`chain`, `zip_longest`), combinatorics (`product`, `permutations`, `combinations`), and `groupby`/`accumulate`.
+- Slice infinite iterators with `islice`; sort before `groupby`.
+- **`functools`** adds `reduce`, memoization (`lru_cache`/`cache`), argument binding (`partial`), and decorator helpers (`wraps`).
+- These tools make data pipelines shorter, faster, and clearer.
diff --git a/src/content/docs/tutorials/Python Standard Library/JSON.mdx b/src/content/docs/tutorials/Python Standard Library/JSON.mdx
new file mode 100644
index 00000000..8bcc83e2
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/JSON.mdx	
@@ -0,0 +1,267 @@
+---
+title: Python json — Parse & Serialize JSON
+description: A detailed guide to Python's json module. Learn to serialize Python objects to JSON and parse JSON back into Python, with dumps/loads/dump/load, formatting options, custom encoders, and practice exercises.
+sidebar:
+  order: 3
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+**JSON** (JavaScript Object Notation) is the most common format for exchanging data between programs, APIs, and config files. Python's built-in `json` module converts between JSON text and Python objects — no installation needed.
+
+```python title="quickstart.py"
+import json
+
+data = {"name": "Ada", "age": 36, "skills": ["math", "code"]}
+text = json.dumps(data)         # Python -> JSON string
+print(text)                     # {"name": "Ada", "age": 36, "skills": ["math", "code"]}
+
+back = json.loads(text)         # JSON string -> Python
+print(back["skills"][0])        # math
+```
+
+## The four functions
+
+The module has two pairs: one works with **strings**, the other with **files**.
+
+| Function | Direction | Works with |
+|:---|:---|:---|
+| `json.dumps(obj)` | Python → JSON | A **string** ("dump string"). |
+| `json.loads(text)` | JSON → Python | A **string** ("load string"). |
+| `json.dump(obj, file)` | Python → JSON | A **file** object. |
+| `json.load(file)` | JSON → Python | A **file** object. |
+
+Remember the **s**: `dumps`/`loads` end in **s** for **string**; `dump`/`load` are for files.
+
+## How types map
+
+Serialization converts Python types to their JSON equivalents (and back):
+
+| Python | JSON |
+|:---|:---|
+| `dict` | object |
+| `list`, `tuple` | array |
+| `str` | string |
+| `int`, `float` | number |
+| `True` / `False` | `true` / `false` |
+| `None` | `null` |
+
+> Note: tuples become JSON arrays, and JSON arrays always load back as **lists** — so a round-trip turns a tuple into a list.
+
+## Serializing: `dumps`
+
+```python title="dumps.py"
+import json
+
+data = {"name": "Ada", "active": True, "score": None, "tags": ["a", "b"]}
+
+# Compact (default)
+print(json.dumps(data))
+
+# Pretty-printed with indentation
+print(json.dumps(data, indent=2))
+
+# Sort keys alphabetically
+print(json.dumps(data, sort_keys=True))
+
+# Custom separators for the most compact output
+print(json.dumps(data, separators=(",", ":")))
+```
+
+Common `dumps` / `dump` options:
+
+| Option | Effect |
+|:---|:---|
+| `indent=n` | Pretty-print with `n` spaces per level. |
+| `sort_keys=True` | Order object keys alphabetically. |
+| `separators=(item, key)` | Control the item and key-value separators. |
+| `ensure_ascii=False` | Keep non-ASCII characters as-is (e.g. emoji, accents). |
+| `default=func` | A fallback function to serialize unknown types. |
+
+```python title="unicode.py"
+import json
+
+data = {"city": "São Paulo", "emoji": "🐍"}
+print(json.dumps(data))                       # escapes non-ASCII
+print(json.dumps(data, ensure_ascii=False))   # keeps São Paulo and 🐍 readable
+```
+
+## Parsing: `loads`
+
+```python title="loads.py"
+import json
+
+text = '{"name": "Ada", "age": 36, "skills": ["math", "code"], "active": true}'
+obj = json.loads(text)
+
+print(type(obj))          # <class 'dict'>
+print(obj["name"])        # Ada
+print(obj["active"])      # True  (JSON true -> Python True)
+print(obj["skills"][1])   # code
+```
+
+## Working with files
+
+Use `dump`/`load` to read and write JSON files directly.
+
+```python title="files.py"
+import json
+
+config = {"theme": "dark", "version": 2, "plugins": ["a", "b"]}
+
+# Write to a file
+with open("config.json", "w", encoding="utf-8") as f:
+    json.dump(config, f, indent=2)
+
+# Read it back
+with open("config.json", "r", encoding="utf-8") as f:
+    loaded = json.load(f)
+
+print(loaded["theme"])    # dark
+```
+
+## Handling errors
+
+Invalid JSON raises `json.JSONDecodeError` (a subclass of `ValueError`). Always guard parsing of untrusted input.
+
+```python title="errors.py"
+import json
+
+bad = '{"name": "Ada", }'   # trailing comma is invalid JSON
+
+try:
+    json.loads(bad)
+except json.JSONDecodeError as e:
+    print("Could not parse:", e)
+```
+
+## Serializing custom objects
+
+By default, `json` only knows the built-in types. For your own classes, pass a `default` function (or convert to a dict first).
+
+```python title="custom.py"
+import json
+from datetime import datetime
+
+def encode(obj):
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Cannot serialize {type(obj).__name__}")
+
+event = {"name": "launch", "when": datetime(2025, 1, 31, 9, 0)}
+print(json.dumps(event, default=encode))
+# {"name": "launch", "when": "2025-01-31T09:00:00"}
+```
+
+## Practical example — a tiny API response
+
+```python title="api_like.py"
+import json
+
+response = '''
+{
+  "status": "ok",
+  "users": [
+    {"id": 1, "name": "Ada"},
+    {"id": 2, "name": "Linus"}
+  ]
+}
+'''
+
+data = json.loads(response)
+for user in data["users"]:
+    print(user["id"], "->", user["name"])
+# 1 -> Ada
+# 2 -> Linus
+```
+
+## Common pitfalls
+
+- **Single quotes** — JSON requires **double** quotes around keys and strings. `"{'a': 1}"` fails; use `'{"a": 1}'`.
+- **Trailing commas** are invalid in JSON (unlike Python).
+- **`True`/`None` vs `true`/`null`** — Python prints capitalized; JSON uses lowercase. The module handles the conversion for you, but watch for it when hand-writing JSON.
+- **Non-serializable types** (sets, datetimes, custom classes) raise `TypeError` unless you supply `default`.
+- **Keys become strings** — JSON object keys are always strings, so `{1: "a"}` serializes to `{"1": "a"}`.
+
+## Practice Exercises
+
+### Exercise 1 – Serialize a dictionary
+
+<DataCampExercise
+  lang="python"
+  hint={`Use json.dumps to turn the dict into a JSON string.`}
+  code={`# Task: Convert the Python dict into a JSON string.
+import json
+
+person = {"name": "Ada", "age": 36}
+text = json.___(person)
+print(text)
+
+# Expected Output:
+# {"name": "Ada", "age": 36}`}
+  solution={`import json
+
+person = {"name": "Ada", "age": 36}
+text = json.dumps(person)
+print(text)`}
+  sct={`test_output_contains('"name": "Ada"')
+success_msg("Great! json.dumps serializes a Python object to JSON text.")`}
+  height={170}
+/>
+
+### Exercise 2 – Parse JSON and read a value
+
+<DataCampExercise
+  lang="python"
+  hint={`Use json.loads to parse the string into a dict, then index it.`}
+  code={`# Task: Parse the JSON string and print the value of "city".
+import json
+
+text = '{"city": "Paris", "population": 2148000}'
+data = json.___(text)
+print(data["___"])
+
+# Expected Output:
+# Paris`}
+  solution={`import json
+
+text = '{"city": "Paris", "population": 2148000}'
+data = json.loads(text)
+print(data["city"])`}
+  sct={`test_output_contains("Paris")
+success_msg("json.loads turns JSON text into a Python dict you can index.")`}
+  height={170}
+/>
+
+### Exercise 3 – Pretty-print with indentation
+
+<DataCampExercise
+  lang="python"
+  hint={`Pass the indent keyword argument to json.dumps.`}
+  code={`# Task: Pretty-print the dict with 2-space indentation.
+import json
+
+data = {"a": 1, "b": 2}
+print(json.dumps(data, ___=2))
+
+# Expected Output (indented):
+# {
+#   "a": 1,
+#   "b": 2
+# }`}
+  solution={`import json
+
+data = {"a": 1, "b": 2}
+print(json.dumps(data, indent=2))`}
+  sct={`test_output_contains('"a": 1')
+success_msg("The indent option makes JSON human-readable.")`}
+  height={190}
+/>
+
+## Summary
+
+- `json` converts between JSON text and Python objects with **four functions**: `dumps`/`loads` (strings) and `dump`/`load` (files).
+- Python types map cleanly to JSON; tuples and JSON arrays both become **lists** on the way back.
+- Format output with `indent`, `sort_keys`, `separators`, and `ensure_ascii`.
+- Guard parsing with `try/except json.JSONDecodeError`.
+- Serialize custom types with a `default` function.
diff --git a/src/content/docs/tutorials/Python Standard Library/Logging.mdx b/src/content/docs/tutorials/Python Standard Library/Logging.mdx
new file mode 100644
index 00000000..cf552c95
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Logging.mdx	
@@ -0,0 +1,224 @@
+---
+title: Python logging — Structured Application Logs
+description: A detailed guide to Python's logging module. Learn log levels, basic configuration, formatters, handlers, and per-module loggers — with examples and practice exercises.
+sidebar:
+  order: 9
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+The `logging` module is the standard way to record what your program is doing. Unlike `print`, it has **severity levels**, can route messages to files or the network, includes timestamps and source info, and can be turned up or down without touching your code.
+
+```python title="quickstart.py"
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logging.info("App started")
+logging.warning("Low disk space")
+logging.error("Connection failed")
+# INFO:root:App started
+# WARNING:root:Low disk space
+# ERROR:root:Connection failed
+```
+
+## Why not just use print?
+
+| `print` | `logging` |
+|:---|:---|
+| One firehose to stdout. | Severity levels you can filter. |
+| No timestamps or context. | Timestamps, module, line number, etc. |
+| Edit code to silence it. | Change one config line. |
+| Goes one place. | Files, console, syslog, email — many handlers. |
+
+## Log levels
+
+Each message has a level. The logger only emits messages **at or above** its configured level.
+
+| Level | Value | Use for |
+|:---|:---|:---|
+| `DEBUG` | 10 | Detailed diagnostic info. |
+| `INFO` | 20 | Normal events ("server started"). |
+| `WARNING` | 30 | Something unexpected, but still working (the default). |
+| `ERROR` | 40 | A failure in some operation. |
+| `CRITICAL` | 50 | A serious failure; the program may stop. |
+
+```python title="levels.py"
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+logging.debug("variable x = 42")     # shown only because level is DEBUG
+logging.info("processing record")
+logging.warning("retrying")
+logging.error("gave up")
+print(logging.getLevelName(20))      # INFO
+```
+
+> The default level is `WARNING`, so `debug` and `info` messages are **hidden** until you lower the level with `basicConfig(level=...)`.
+
+## basicConfig — quick setup
+
+`basicConfig` configures the root logger in one call. Set it **once**, early, before logging anything.
+
+```python title="basic_config.py"
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%H:%M:%S",
+)
+logging.info("ready")
+# 14:30:01 [INFO] root: ready
+
+# Write to a file instead of the console
+logging.basicConfig(filename="app.log", level=logging.INFO)
+```
+
+### Common format placeholders
+
+| Placeholder | Inserts |
+|:---|:---|
+| `%(asctime)s` | Human-readable timestamp. |
+| `%(levelname)s` | The level name (INFO, ERROR, ...). |
+| `%(name)s` | The logger's name. |
+| `%(message)s` | The log message. |
+| `%(filename)s` / `%(lineno)d` | Source file / line number. |
+
+## Named loggers — one per module
+
+Instead of the root logger, create a logger per module with `getLogger(__name__)`. This tags every message with where it came from and lets you tune modules independently.
+
+```python title="named_loggers.py"
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+logger.info("module-specific message")
+# INFO:__main__:module-specific message
+```
+
+## Handlers and formatters
+
+For real apps, attach **handlers** (where logs go) and **formatters** (how they look). You can have several at once — e.g. INFO to console, ERROR to a file.
+
+```python title="handlers.py"
+import logging
+
+logger = logging.getLogger("myapp")
+logger.setLevel(logging.DEBUG)
+
+# Console handler at INFO
+console = logging.StreamHandler()
+console.setLevel(logging.INFO)
+console.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+
+# File handler at DEBUG
+file = logging.FileHandler("debug.log")
+file.setLevel(logging.DEBUG)
+
+logger.addHandler(console)
+logger.addHandler(file)
+
+logger.debug("only in the file")
+logger.info("console + file")
+```
+
+## Logging exceptions
+
+Inside an `except` block, `logger.exception(...)` logs the message **plus the full traceback**.
+
+```python title="exceptions.py"
+import logging
+
+logging.basicConfig(level=logging.ERROR)
+try:
+    1 / 0
+except ZeroDivisionError:
+    logging.exception("Math went wrong")
+# ERROR:root:Math went wrong
+# Traceback (most recent call last): ...
+```
+
+## Common pitfalls
+
+- **Default level hides INFO/DEBUG** — call `basicConfig(level=logging.DEBUG)` to see them.
+- **`basicConfig` only works once** — the first call wins; later calls are ignored unless `force=True`.
+- **Use `%s` lazy formatting**: `logger.info("user %s", name)`, not f-strings, so the string is only built if the message is actually emitted.
+- **Don't log secrets** — passwords, tokens, and personal data should never hit the logs.
+
+## Practice Exercises
+
+### Exercise 1 – Level names and values
+
+<DataCampExercise
+  lang="python"
+  hint={`logging.getLevelName(30) returns the name for the value 30.`}
+  code={`# Task: Print the name of the log level whose numeric value is 30.
+import logging
+
+print(logging.getLevelName(___))
+
+# Expected Output:
+# WARNING`}
+  solution={`import logging
+
+print(logging.getLevelName(30))`}
+  sct={`test_output_contains("WARNING")
+success_msg("30 maps to WARNING, the default level.")`}
+  height={150}
+/>
+
+### Exercise 2 – Configure and log info
+
+<DataCampExercise
+  lang="python"
+  hint={`Call basicConfig with level=logging.INFO before logging.info.`}
+  code={`# Task: Lower the level to INFO so the info message is emitted.
+import logging
+
+logging.basicConfig(level=logging.___)
+logging.info("Service ready")
+print("done")
+
+# Expected Output (order may vary; 'done' is checked):
+# done`}
+  solution={`import logging
+
+logging.basicConfig(level=logging.INFO)
+logging.info("Service ready")
+print("done")`}
+  sct={`test_output_contains("done")
+success_msg("Setting level=INFO lets info() messages through.")`}
+  height={170}
+/>
+
+### Exercise 3 – Create a named logger
+
+<DataCampExercise
+  lang="python"
+  hint={`Use logging.getLogger("orders") and read its .name attribute.`}
+  code={`# Task: Create a logger named "orders" and print its name.
+import logging
+
+logger = logging.___("orders")
+print(logger.name)
+
+# Expected Output:
+# orders`}
+  solution={`import logging
+
+logger = logging.getLogger("orders")
+print(logger.name)`}
+  sct={`test_output_contains("orders")
+success_msg("getLogger(name) returns a named logger you can configure.")`}
+  height={150}
+/>
+
+## Summary
+
+- `logging` replaces `print` with leveled, timestamped, routable messages.
+- Levels: `DEBUG < INFO < WARNING < ERROR < CRITICAL`; default is `WARNING`.
+- Configure quickly with `basicConfig(level=..., format=...)`.
+- Use `getLogger(__name__)` per module, and attach handlers/formatters for fine control.
+- Log tracebacks with `logger.exception` inside `except` blocks.
diff --git a/src/content/docs/tutorials/Python Standard Library/Math Random Statistics.mdx b/src/content/docs/tutorials/Python Standard Library/Math Random Statistics.mdx
new file mode 100644
index 00000000..c40b7cda
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Math Random Statistics.mdx	
@@ -0,0 +1,230 @@
+---
+title: Python math, random & statistics
+description: A detailed guide to Python's math, random, and statistics modules. Learn numeric functions and constants, random number generation and sampling, and descriptive statistics with examples and practice exercises.
+sidebar:
+  order: 6
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+Three modules cover everyday numeric work:
+
+- **`math`** — mathematical functions and constants for real numbers.
+- **`random`** — pseudo-random numbers, choices, shuffling, and sampling.
+- **`statistics`** — descriptive statistics (mean, median, standard deviation).
+
+```python title="overview.py"
+import math, random, statistics
+
+print(math.sqrt(144))                 # 12.0
+print(random.randint(1, 6))           # a dice roll, e.g. 4
+print(statistics.mean([2, 4, 6]))     # 4
+```
+
+## The math module
+
+### Constants
+
+| Constant | Value |
+|:---|:---|
+| `math.pi` | 3.141592653589793 |
+| `math.e` | 2.718281828459045 |
+| `math.tau` | 6.283185307179586 (2π) |
+| `math.inf` | Positive infinity |
+| `math.nan` | Not-a-Number |
+
+### Common functions
+
+| Function | Returns |
+|:---|:---|
+| `math.sqrt(x)` | Square root. |
+| `math.pow(x, y)` | `x` to the power `y` (as a float). |
+| `math.floor(x)` / `math.ceil(x)` | Round down / up to an integer. |
+| `math.trunc(x)` | Drop the fractional part. |
+| `math.factorial(n)` | `n!` |
+| `math.gcd(a, b)` / `math.lcm(a, b)` | Greatest common divisor / least common multiple. |
+| `math.exp(x)` / `math.log(x, base)` | e^x / logarithm. |
+| `math.isclose(a, b)` | Safe float comparison. |
+| `math.comb(n, k)` / `math.perm(n, k)` | Combinations / permutations count. |
+
+```python title="math_funcs.py"
+import math
+
+print(math.floor(3.7), math.ceil(3.2))   # 3 4
+print(math.factorial(5))                  # 120
+print(math.gcd(12, 18))                   # 6
+print(math.log(8, 2))                     # 3.0
+print(math.comb(5, 2))                    # 10
+
+# Never compare floats with == ; use isclose
+print(0.1 + 0.2 == 0.3)                   # False (float rounding!)
+print(math.isclose(0.1 + 0.2, 0.3))       # True
+```
+
+### Trigonometry
+
+Trig functions work in **radians**. Convert with `radians` / `degrees`.
+
+```python title="trig.py"
+import math
+
+print(math.sin(math.pi / 2))     # 1.0
+print(math.degrees(math.pi))     # 180.0
+print(math.radians(180))         # 3.141592653589793
+print(math.hypot(3, 4))          # 5.0  (Euclidean distance)
+```
+
+## The random module
+
+`random` generates **pseudo-random** values. For reproducible results (tests, demos) set a seed first.
+
+| Function | Returns |
+|:---|:---|
+| `random.random()` | A float in `[0.0, 1.0)`. |
+| `random.uniform(a, b)` | A float in `[a, b]`. |
+| `random.randint(a, b)` | An integer in `[a, b]` (inclusive). |
+| `random.randrange(stop)` | An integer like `range`. |
+| `random.choice(seq)` | One random element. |
+| `random.choices(seq, k=n)` | `n` elements **with** replacement (weights allowed). |
+| `random.sample(seq, k=n)` | `n` unique elements **without** replacement. |
+| `random.shuffle(list)` | Shuffle a list **in place**. |
+| `random.seed(n)` | Make results reproducible. |
+
+```python title="random_funcs.py"
+import random
+
+random.seed(42)                       # reproducible output
+
+print(random.random())                # 0.6394...
+print(random.randint(1, 6))           # dice roll
+print(random.choice(["a", "b", "c"])) # one element
+
+deck = [1, 2, 3, 4, 5]
+random.shuffle(deck)                  # shuffles in place
+print(deck)
+
+print(random.sample(range(1, 50), 6)) # lottery: 6 unique numbers
+print(random.choices(["heads", "tails"], weights=[1, 1], k=3))
+```
+
+> `random` is **not** cryptographically secure. For passwords, tokens, or keys, use the `secrets` module instead.
+
+## The statistics module
+
+Descriptive statistics on numeric data, no third-party libraries required.
+
+| Function | Returns |
+|:---|:---|
+| `statistics.mean(data)` | Arithmetic average. |
+| `statistics.median(data)` | Middle value. |
+| `statistics.mode(data)` | Most common value. |
+| `statistics.stdev(data)` | Sample standard deviation. |
+| `statistics.pstdev(data)` | Population standard deviation. |
+| `statistics.variance(data)` | Sample variance. |
+| `statistics.harmonic_mean(data)` | Harmonic mean. |
+
+```python title="stats.py"
+import statistics
+
+scores = [88, 92, 79, 93, 85, 92]
+print(statistics.mean(scores))      # 88.16...
+print(statistics.median(scores))    # 90.0
+print(statistics.mode(scores))      # 92
+print(round(statistics.stdev(scores), 2))   # 5.34
+print(statistics.variance(scores))          # 28.57...
+```
+
+## Putting it together
+
+```python title="dice_simulation.py"
+import random
+import statistics
+
+random.seed(1)
+rolls = [random.randint(1, 6) for _ in range(1000)]
+print("mean:", round(statistics.mean(rolls), 2))   # close to 3.5
+print("mode:", statistics.mode(rolls))
+```
+
+## Common pitfalls
+
+- **Float `==` is unreliable** — `0.1 + 0.2 != 0.3`. Use `math.isclose`.
+- **Trig uses radians**, not degrees — convert with `math.radians`.
+- **`random.shuffle` returns `None`** — it shuffles in place; don't write `x = random.shuffle(x)`.
+- **`statistics.mode` errors on ties** in older versions; `multimode` returns all top values.
+- **Use `secrets`, not `random`,** for anything security-sensitive.
+
+## Practice Exercises
+
+### Exercise 1 – Square root and rounding
+
+<DataCampExercise
+  lang="python"
+  hint={`Use math.sqrt for the root and math.floor to round down.`}
+  code={`# Task: Print the floor of the square root of 50.
+import math
+
+result = math.___(math.sqrt(50))
+print(result)
+
+# Expected Output:
+# 7`}
+  solution={`import math
+
+result = math.floor(math.sqrt(50))
+print(result)`}
+  sct={`test_output_contains("7")
+success_msg("sqrt(50) is about 7.07; floor rounds it down to 7.")`}
+  height={160}
+/>
+
+### Exercise 2 – Reproducible dice roll
+
+<DataCampExercise
+  lang="python"
+  hint={`Call random.seed(0) first, then random.randint(1, 6).`}
+  code={`# Task: Seed the generator with 0, then roll a die (1-6).
+import random
+
+random.___(0)
+roll = random.randint(1, ___)
+print(roll)
+
+# Expected Output:
+# (a number from 1 to 6, same every run because of the seed)`}
+  solution={`import random
+
+random.seed(0)
+roll = random.randint(1, 6)
+print(roll)`}
+  sct={`success_msg("Seeding makes random output reproducible across runs.")`}
+  height={180}
+/>
+
+### Exercise 3 – Average of a list
+
+<DataCampExercise
+  lang="python"
+  hint={`statistics.mean returns the arithmetic average.`}
+  code={`# Task: Print the mean of the scores.
+import statistics
+
+scores = [10, 20, 30, 40]
+print(statistics.___(scores))
+
+# Expected Output:
+# 25`}
+  solution={`import statistics
+
+scores = [10, 20, 30, 40]
+print(statistics.mean(scores))`}
+  sct={`test_output_contains("25")
+success_msg("statistics.mean sums the values and divides by the count.")`}
+  height={160}
+/>
+
+## Summary
+
+- **`math`** provides constants (`pi`, `e`, `tau`) and functions for roots, logs, factorials, gcd/lcm, trig, and safe float comparison (`isclose`).
+- **`random`** generates pseudo-random numbers and supports `choice`, `choices`, `sample`, and `shuffle`; seed it for reproducibility and use `secrets` for security.
+- **`statistics`** computes mean, median, mode, variance, and standard deviation without external libraries.
diff --git a/src/content/docs/tutorials/Python Standard Library/Pathlib.mdx b/src/content/docs/tutorials/Python Standard Library/Pathlib.mdx
new file mode 100644
index 00000000..5a81490b
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Pathlib.mdx	
@@ -0,0 +1,222 @@
+---
+title: Python pathlib — Modern File Paths
+description: A detailed guide to Python's pathlib module. Learn to build, inspect, and manipulate filesystem paths with the Path object, read and write files, and glob directories — with examples and practice exercises.
+sidebar:
+  order: 11
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+`pathlib` provides an **object-oriented** way to work with filesystem paths. Instead of juggling strings and `os.path.join`, you use a `Path` object with clean attributes and methods that work the same on Windows, macOS, and Linux.
+
+```python title="quickstart.py"
+from pathlib import Path
+
+p = Path("data") / "reports" / "2025.csv"   # join with the / operator
+print(p)            # data/reports/2025.csv  (uses the OS separator)
+print(p.name)       # 2025.csv
+print(p.suffix)     # .csv
+print(p.parent)     # data/reports
+```
+
+## Why pathlib over os.path?
+
+| `os.path` (old) | `pathlib` (modern) |
+|:---|:---|
+| `os.path.join(a, b)` | `Path(a) / b` |
+| `os.path.basename(p)` | `p.name` |
+| `os.path.splitext(p)[1]` | `p.suffix` |
+| `os.path.exists(p)` | `p.exists()` |
+| Strings everywhere. | One tidy object. |
+
+## Building paths
+
+Use the `/` operator to join parts — it's readable and cross-platform.
+
+```python title="building.py"
+from pathlib import Path
+
+base = Path("/home/user")
+config = base / "app" / "config.json"
+print(config)                 # /home/user/app/config.json
+
+# Current working directory and home directory
+print(Path.cwd())             # where the script runs
+print(Path.home())            # the user's home folder
+```
+
+## Inspecting a path
+
+| Attribute / method | Returns |
+|:---|:---|
+| `p.name` | Final component (`2025.csv`). |
+| `p.stem` | Name without suffix (`2025`). |
+| `p.suffix` | The extension (`.csv`). |
+| `p.parent` | The containing directory. |
+| `p.parts` | A tuple of all components. |
+| `p.with_suffix(".txt")` | A new path with a changed extension. |
+| `p.with_name("new.csv")` | A new path with a changed final name. |
+
+```python title="inspecting.py"
+from pathlib import Path
+
+p = Path("reports/q1/sales.csv")
+print(p.name)               # sales.csv
+print(p.stem)               # sales
+print(p.suffix)             # .csv
+print(p.parent)             # reports/q1
+print(p.parts)              # ('reports', 'q1', 'sales.csv')
+print(p.with_suffix(".json"))  # reports/q1/sales.json
+```
+
+## Checking existence and type
+
+```python title="checks.py"
+from pathlib import Path
+
+p = Path("notes.txt")
+print(p.exists())     # True if the path exists
+print(p.is_file())    # True if it's a file
+print(p.is_dir())     # True if it's a directory
+```
+
+## Reading and writing files
+
+`pathlib` can read and write whole files in one line — no `open()` boilerplate for simple cases.
+
+```python title="read_write.py"
+from pathlib import Path
+
+p = Path("greeting.txt")
+p.write_text("Hello, file!", encoding="utf-8")   # write (and create)
+print(p.read_text(encoding="utf-8"))              # Hello, file!
+
+# Binary variants
+p.write_bytes(b"\x00\x01")
+print(p.read_bytes())                             # b'\x00\x01'
+```
+
+## Listing and globbing directories
+
+```python title="listing.py"
+from pathlib import Path
+
+folder = Path(".")
+
+# Everything directly inside
+for item in folder.iterdir():
+    print(item)
+
+# Only .py files in this folder
+for py in folder.glob("*.py"):
+    print(py)
+
+# Recursively, every .py file under here
+for py in folder.rglob("*.py"):
+    print(py)
+```
+
+| Method | Finds |
+|:---|:---|
+| `p.iterdir()` | Every item directly inside `p`. |
+| `p.glob(pattern)` | Items matching a pattern in `p`. |
+| `p.rglob(pattern)` | Matches **recursively** in all subfolders. |
+
+## Creating and removing
+
+```python title="create_remove.py"
+from pathlib import Path
+
+d = Path("output/logs")
+d.mkdir(parents=True, exist_ok=True)   # create folders; don't error if present
+
+f = d / "run.log"
+f.touch()                              # create an empty file
+f.unlink(missing_ok=True)             # delete a file (no error if missing)
+```
+
+## Common pitfalls
+
+- **`Path("a") / "b"` only works with a Path on the left** — `"a" / Path("b")` fails; start from a `Path`.
+- **`p.suffix` includes the dot** — `.csv`, not `csv`.
+- **`mkdir` errors if the parent is missing** — pass `parents=True`.
+- **`read_text` raises if the file doesn't exist** — check `p.exists()` first or catch the error.
+- **Convert to `str(p)`** only when a library insists on a string.
+
+## Practice Exercises
+
+### Exercise 1 – Extract the file extension
+
+<DataCampExercise
+  lang="python"
+  hint={`The suffix attribute returns the extension, including the dot.`}
+  code={`# Task: Print the extension of the path "archive/data.tar.gz".
+from pathlib import Path
+
+p = Path("archive/data.tar.gz")
+print(p.___)
+
+# Expected Output:
+# .gz`}
+  solution={`from pathlib import Path
+
+p = Path("archive/data.tar.gz")
+print(p.suffix)`}
+  sct={`test_output_contains(".gz")
+success_msg("suffix returns the last extension, including the dot.")`}
+  height={160}
+/>
+
+### Exercise 2 – Join paths with the / operator
+
+<DataCampExercise
+  lang="python"
+  hint={`Use the / operator to join base, then a folder, then a file.`}
+  code={`# Task: Build the path base / "src" / "main.py".
+from pathlib import Path
+
+base = Path("project")
+full = base ___ "src" / "main.py"
+print(full)
+
+# Expected Output:
+# project/src/main.py`}
+  solution={`from pathlib import Path
+
+base = Path("project")
+full = base / "src" / "main.py"
+print(full)`}
+  sct={`test_output_contains("project/src/main.py")
+success_msg("The / operator joins path parts cleanly.")`}
+  height={170}
+/>
+
+### Exercise 3 – Name without the extension
+
+<DataCampExercise
+  lang="python"
+  hint={`The stem attribute is the file name without its suffix.`}
+  code={`# Task: Print the file name without its extension for "docs/readme.md".
+from pathlib import Path
+
+p = Path("docs/readme.md")
+print(p.___)
+
+# Expected Output:
+# readme`}
+  solution={`from pathlib import Path
+
+p = Path("docs/readme.md")
+print(p.stem)`}
+  sct={`test_output_contains("readme")
+success_msg("stem is the final name minus the suffix.")`}
+  height={160}
+/>
+
+## Summary
+
+- `pathlib.Path` is the modern, object-oriented replacement for `os.path`.
+- Join paths with `/`; inspect them with `name`, `stem`, `suffix`, `parent`, `parts`.
+- Read/write files directly with `read_text`/`write_text` (and `_bytes` variants).
+- List and search folders with `iterdir`, `glob`, and `rglob`.
+- Create and remove with `mkdir(parents=True, exist_ok=True)`, `touch`, and `unlink`.
diff --git a/src/content/docs/tutorials/Python Standard Library/Pickle.mdx b/src/content/docs/tutorials/Python Standard Library/Pickle.mdx
new file mode 100644
index 00000000..706fa344
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Pickle.mdx	
@@ -0,0 +1,210 @@
+---
+title: Python pickle — Object Serialization
+description: A detailed guide to Python's pickle module. Learn to serialize and deserialize Python objects with dumps/loads/dump/load, understand what is picklable, pickle vs JSON, and the critical security warning — with examples and practice exercises.
+sidebar:
+  order: 13
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+`pickle` converts almost any Python object into a **byte stream** (serializing / "pickling") and back again (deserializing / "unpickling"). Use it to save program state, cache results, or pass objects between Python processes.
+
+```python title="quickstart.py"
+import pickle
+
+data = {"name": "Ada", "scores": [88, 92], "active": True}
+
+blob = pickle.dumps(data)        # object -> bytes
+restored = pickle.loads(blob)    # bytes -> object
+print(restored)                  # {'name': 'Ada', 'scores': [88, 92], 'active': True}
+print(restored == data)          # True
+```
+
+## Security warning — read this first
+
+> **Never unpickle data you do not trust.** Unpickling can execute arbitrary code, so a malicious pickle file can take over your program. Only load pickles you created yourself or received from a trusted source. For untrusted or cross-language data, use **JSON** instead.
+
+## The four functions
+
+Like `json`, `pickle` has a string/bytes pair and a file pair.
+
+| Function | Direction | Works with |
+|:---|:---|:---|
+| `pickle.dumps(obj)` | Object → bytes | A bytes object. |
+| `pickle.loads(bytes)` | bytes → Object | A bytes object. |
+| `pickle.dump(obj, file)` | Object → bytes | A **binary** file. |
+| `pickle.load(file)` | bytes → Object | A **binary** file. |
+
+## Saving to and loading from a file
+
+Pickle writes **binary**, so open files in binary mode (`"wb"` / `"rb"`).
+
+```python title="files.py"
+import pickle
+
+model = {"weights": [0.1, 0.2, 0.3], "bias": 0.5}
+
+# Save
+with open("model.pkl", "wb") as f:
+    pickle.dump(model, f)
+
+# Load
+with open("model.pkl", "rb") as f:
+    loaded = pickle.load(f)
+
+print(loaded["bias"])   # 0.5
+```
+
+## What can be pickled?
+
+Pickle handles far more than JSON: nearly all built-in types, plus custom class instances.
+
+| Picklable | Not picklable |
+|:---|:---|
+| `int`, `float`, `str`, `bool`, `None` | Open file handles |
+| `list`, `tuple`, `dict`, `set` | Network sockets, DB connections |
+| Nested combinations of the above | Lambdas (use a named function) |
+| Instances of your own classes | Generators / running threads |
+
+```python title="custom_objects.py"
+import pickle
+
+class Point:
+    def __init__(self, x, y):
+        self.x = x
+        self.y = y
+    def __repr__(self):
+        return f"Point({self.x}, {self.y})"
+
+p = Point(3, 4)
+blob = pickle.dumps(p)
+p2 = pickle.loads(blob)
+print(p2)          # Point(3, 4)
+print(p2 is p)     # False -> a brand-new, equal object
+```
+
+> To unpickle a custom class, its **class definition must be importable** in the program doing the loading.
+
+## Protocols
+
+Pickle has several binary **protocol** versions; higher numbers are more efficient. Use `pickle.HIGHEST_PROTOCOL` for the best, or `pickle.DEFAULT_PROTOCOL` for broad compatibility.
+
+```python title="protocols.py"
+import pickle
+
+data = list(range(1000))
+blob = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)
+print(len(blob), "bytes")
+print(pickle.loads(blob)[:3])   # [0, 1, 2]
+```
+
+## pickle vs JSON
+
+| | pickle | JSON |
+|:---|:---|:---|
+| Output | Binary, Python-only | Text, language-neutral |
+| Types | Almost any Python object | Basic types only |
+| Human-readable | No | Yes |
+| Safe with untrusted data | **No** | Yes |
+| Best for | Caching/state between Python programs | APIs, configs, data exchange |
+
+Choose **JSON** for data shared with other systems or users; choose **pickle** only for trusted, Python-to-Python data that JSON can't represent.
+
+## Common pitfalls
+
+- **Binary mode required** — open files with `"wb"`/`"rb"`, not `"w"`/`"r"`.
+- **Cross-version risk** — a pickle made in one Python version may not load in another.
+- **Lambdas don't pickle** — use a module-level `def` function instead.
+- **Security** — never `loads`/`load` data from an untrusted source.
+
+## Practice Exercises
+
+### Exercise 1 – Round-trip a dictionary
+
+<DataCampExercise
+  lang="python"
+  hint={`Use pickle.dumps to serialize, then pickle.loads to restore.`}
+  code={`# Task: Pickle the dict to bytes, then unpickle it and print the result.
+import pickle
+
+data = {"a": 1, "b": 2}
+blob = pickle.___(data)
+restored = pickle.loads(blob)
+print(restored)
+
+# Expected Output:
+# {'a': 1, 'b': 2}`}
+  solution={`import pickle
+
+data = {"a": 1, "b": 2}
+blob = pickle.dumps(data)
+restored = pickle.loads(blob)
+print(restored)`}
+  sct={`test_output_contains("{'a': 1, 'b': 2}")
+success_msg("dumps -> loads round-trips the object back to an equal copy.")`}
+  height={190}
+/>
+
+### Exercise 2 – Confirm equality after a round-trip
+
+<DataCampExercise
+  lang="python"
+  hint={`loads(dumps(x)) returns an equal object; compare with ==.`}
+  code={`# Task: Show that a list survives a pickle round-trip unchanged.
+import pickle
+
+original = [1, [2, 3], "four"]
+copy = pickle.loads(pickle.dumps(original))
+print(copy == ___)
+
+# Expected Output:
+# True`}
+  solution={`import pickle
+
+original = [1, [2, 3], "four"]
+copy = pickle.loads(pickle.dumps(original))
+print(copy == original)`}
+  sct={`test_output_contains("True")
+success_msg("The unpickled copy equals the original, even when nested.")`}
+  height={180}
+/>
+
+### Exercise 3 – Pickle a custom object
+
+<DataCampExercise
+  lang="python"
+  hint={`dumps then loads the Dog instance; read its .name afterwards.`}
+  code={`# Task: Round-trip a custom object and print its name.
+import pickle
+
+class Dog:
+    def __init__(self, name):
+        self.name = name
+
+d = Dog("Rex")
+restored = pickle.loads(pickle.___(d))
+print(restored.name)
+
+# Expected Output:
+# Rex`}
+  solution={`import pickle
+
+class Dog:
+    def __init__(self, name):
+        self.name = name
+
+d = Dog("Rex")
+restored = pickle.loads(pickle.dumps(d))
+print(restored.name)`}
+  sct={`test_output_contains("Rex")
+success_msg("pickle serializes custom instances when the class is importable.")`}
+  height={210}
+/>
+
+## Summary
+
+- `pickle` serializes almost any Python object to bytes and back.
+- Use `dumps`/`loads` for bytes, `dump`/`load` for **binary** files.
+- It handles custom classes (the class must be importable to unpickle).
+- **Never unpickle untrusted data** — it can run arbitrary code; prefer JSON for shared data.
+- Pick pickle for trusted Python-to-Python state; pick JSON for interoperability.
diff --git a/src/content/docs/tutorials/Python Standard Library/Regular Expressions.mdx b/src/content/docs/tutorials/Python Standard Library/Regular Expressions.mdx
new file mode 100644
index 00000000..8b3955b7
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Regular Expressions.mdx	
@@ -0,0 +1,313 @@
+---
+title: Python re — Regular Expressions
+description: A detailed guide to Python's re module. Learn pattern syntax, metacharacters, special sequences, groups, flags, and the full re API with examples and practice exercises.
+sidebar:
+  order: 1
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+The `re` module is Python's built-in engine for **regular expressions** — compact patterns that describe sets of strings. Use it to search, match, extract, validate, and replace text. It ships with the standard library, so no installation is needed:
+
+```python title="import_re.py"
+import re
+
+text = "Contact: alice@example.com, bob@work.org"
+emails = re.findall(r"[\w.+-]+@[\w-]+\.[\w.-]+", text)
+print(emails)
+# ['alice@example.com', 'bob@work.org']
+```
+
+## Raw strings — always use `r"..."`
+
+Regex patterns use the backslash (`\`) heavily. Python *also* uses backslash for string escapes, so a plain string like `"\b"` becomes a backspace character before `re` ever sees it. **Raw strings** (prefix `r`) turn off Python's escaping so the pattern reaches `re` intact.
+
+```python title="raw_strings.py"
+# Without raw string: Python eats the backslash
+print("\bword")        # prints a backspace control char + 'word'
+
+# With raw string: the regex engine receives \b (word boundary)
+import re
+print(re.findall(r"\bword\b", "a word here"))  # ['word']
+```
+
+> Rule of thumb: write **every** pattern as a raw string. It costs nothing and avoids subtle bugs.
+
+## The core functions
+
+| Function | What it does |
+|:---|:---|
+| `re.search(pattern, string)` | Scan the whole string; return the **first** match (or `None`). |
+| `re.match(pattern, string)` | Match only at the **start** of the string. |
+| `re.fullmatch(pattern, string)` | Match only if the **entire** string fits the pattern. |
+| `re.findall(pattern, string)` | Return a list of all non-overlapping matches. |
+| `re.finditer(pattern, string)` | Return an iterator of `Match` objects (memory-friendly). |
+| `re.sub(pattern, repl, string)` | Replace all matches with `repl`; returns a new string. |
+| `re.subn(pattern, repl, string)` | Like `sub` but returns `(new_string, count)`. |
+| `re.split(pattern, string)` | Split the string by the pattern. |
+| `re.compile(pattern)` | Pre-compile a pattern into a reusable `Pattern` object. |
+| `re.escape(string)` | Escape all special chars in a literal string. |
+
+```python title="core_functions.py"
+import re
+
+s = "The year 2024 and the year 2025."
+
+print(re.search(r"\d{4}", s).group())   # 2024  (first hit)
+print(re.match(r"\d{4}", s))            # None  (string starts with 'The')
+print(re.findall(r"\d{4}", s))          # ['2024', '2025']
+print(re.sub(r"\d{4}", "YEAR", s))      # The year YEAR and the year YEAR.
+print(re.split(r",\s*", "a, b,c,  d"))  # ['a', 'b', 'c', 'd']
+```
+
+## The Match object
+
+`search`, `match`, `fullmatch`, and each item from `finditer` return a **Match** object. It carries position info and captured groups.
+
+| Method / attribute | Returns |
+|:---|:---|
+| `m.group(0)` / `m.group()` | The whole match. |
+| `m.group(n)` | The text of the nth capture group. |
+| `m.groups()` | A tuple of all groups. |
+| `m.groupdict()` | A dict of all **named** groups. |
+| `m.start()` / `m.end()` | Start / end index of the match. |
+| `m.span()` | `(start, end)` tuple. |
+
+```python title="match_object.py"
+import re
+
+m = re.search(r"(\d{4})-(\d{2})-(\d{2})", "Date: 2025-01-31 ok")
+print(m.group(0))   # 2025-01-31
+print(m.group(1))   # 2025
+print(m.groups())   # ('2025', '01', '31')
+print(m.span())     # (6, 16)
+```
+
+## Metacharacters
+
+These characters have special meaning inside a pattern.
+
+| Token | Meaning |
+|:---|:---|
+| `.` | Any character except newline. |
+| `^` | Start of string (or line, with `re.MULTILINE`). |
+| `$` | End of string (or line, with `re.MULTILINE`). |
+| `*` | 0 or more of the previous token. |
+| `+` | 1 or more of the previous token. |
+| `?` | 0 or 1 (also makes a quantifier lazy). |
+| `{m,n}` | Between m and n repetitions. |
+| `[...]` | A character class — any one char listed. |
+| `[^...]` | Negated class — any char **not** listed. |
+| `\|` | Alternation — "this OR that". |
+| `()` | A capture group. |
+| `\` | Escape a metacharacter, or start a special sequence. |
+
+## Special sequences
+
+| Sequence | Matches |
+|:---|:---|
+| `\d` | A digit (`0-9`). |
+| `\D` | A non-digit. |
+| `\w` | A word char (letters, digits, underscore). |
+| `\W` | A non-word char. |
+| `\s` | Whitespace (space, tab, newline). |
+| `\S` | Non-whitespace. |
+| `\b` | A word boundary. |
+| `\B` | A non-boundary. |
+| `\A` / `\Z` | Start / end of the whole string. |
+
+## Quantifiers — greedy vs lazy
+
+By default quantifiers are **greedy**: they grab as much as possible. Add `?` to make them **lazy** (as little as possible).
+
+```python title="greedy_lazy.py"
+import re
+
+html = "<a><b>"
+print(re.findall(r"<.+>", html))   # ['<a><b>']   greedy: one big match
+print(re.findall(r"<.+?>", html))  # ['<a>', '<b>'] lazy: smallest matches
+```
+
+## Groups: capturing, named, and non-capturing
+
+```python title="groups.py"
+import re
+
+# Named groups make code self-documenting
+pattern = r"(?P<user>[\w.]+)@(?P<domain>[\w.]+)"
+m = re.search(pattern, "send to jane.doe@mail.com please")
+print(m.group("user"))     # jane.doe
+print(m.group("domain"))   # mail.com
+print(m.groupdict())       # {'user': 'jane.doe', 'domain': 'mail.com'}
+
+# Non-capturing group (?:...) groups without storing a capture
+print(re.findall(r"(?:ab)+", "abababxab"))  # ['ababab', 'ab']
+```
+
+You can also reference captured groups in a replacement using `\1`, `\2`, or `\g<name>`:
+
+```python title="sub_backref.py"
+import re
+# Swap "First Last" -> "Last, First"
+print(re.sub(r"(\w+)\s+(\w+)", r"\2, \1", "Ada Lovelace"))  # Lovelace, Ada
+```
+
+## Flags
+
+Pass flags to change matching behaviour. Combine them with `|`.
+
+| Flag | Short | Effect |
+|:---|:---|:---|
+| `re.IGNORECASE` | `re.I` | Case-insensitive matching. |
+| `re.MULTILINE` | `re.M` | `^` and `$` match at each line. |
+| `re.DOTALL` | `re.S` | `.` also matches newline. |
+| `re.VERBOSE` | `re.X` | Allow whitespace and comments in the pattern. |
+
+```python title="flags.py"
+import re
+
+print(re.findall(r"cat", "Cat CAT cat", re.IGNORECASE))  # ['Cat', 'CAT', 'cat']
+
+# VERBOSE makes complex patterns readable
+phone = re.compile(r"""
+    (\d{3})   # area code
+    [-.\s]?   # optional separator
+    (\d{3})   # prefix
+    [-.\s]?
+    (\d{4})   # line number
+""", re.VERBOSE)
+print(phone.search("Call 415-555-1234").groups())  # ('415', '555', '1234')
+```
+
+## Compile once, reuse many times
+
+When a pattern is used repeatedly (e.g. inside a loop), pre-compile it with `re.compile` for clarity and a small speed gain.
+
+```python title="compile.py"
+import re
+
+word_re = re.compile(r"\b\w+\b")
+for line in ["hello world", "spam eggs"]:
+    print(word_re.findall(line))
+# ['hello', 'world']
+# ['spam', 'eggs']
+```
+
+## Practical examples
+
+```python title="validate.py"
+import re
+
+def is_valid_email(s):
+    return re.fullmatch(r"[\w.+-]+@[\w-]+\.[\w.-]+", s) is not None
+
+print(is_valid_email("user@example.com"))  # True
+print(is_valid_email("not-an-email"))       # False
+
+# Extract all hashtags
+print(re.findall(r"#(\w+)", "Loving #python and #regex"))  # ['python', 'regex']
+
+# Clean up extra whitespace
+print(re.sub(r"\s+", " ", "too    many\tspaces").strip())  # 'too many spaces'
+```
+
+## Common pitfalls
+
+- **Forgetting the raw string** — `"\d"` may warn or break; always write `r"\d"`.
+- **Greedy by accident** — `.*` can swallow far more than intended; reach for `.*?` or a tighter class like `[^"]*`.
+- **`match` vs `search`** — `match` anchors at the start. Use `search` to find a pattern anywhere.
+- **Catastrophic backtracking** — nested quantifiers like `(a+)+` on long input can hang. Keep patterns simple.
+
+## Practice Exercises
+
+Try these in the interactive editor. Use the **Hint** and **Show Solution** buttons only after attempting them yourself.
+
+### Exercise 1 – Find all numbers
+
+<DataCampExercise
+  lang="python"
+  hint={`Use re.findall with the pattern for one-or-more digits.`}
+  code={`# Task: Extract every whole number from the sentence.
+# Step 1: import the re module.
+# Step 2: use re.findall with a digit pattern to get ['12', '7', '2025'].
+import ___
+
+text = "I have 12 apples, 7 oranges, bought in 2025."
+numbers = re.findall(r"___", text)
+print(numbers)
+
+# Expected Output:
+# ['12', '7', '2025']`}
+  solution={`import re
+
+text = "I have 12 apples, 7 oranges, bought in 2025."
+numbers = re.findall(r"\\d+", text)
+print(numbers)`}
+  sct={`test_output_contains("'12', '7', '2025'")
+success_msg("Nice! \\\\d+ matches one or more digits.")`}
+  height={170}
+/>
+
+### Exercise 2 – Validate a phone number
+
+<DataCampExercise
+  lang="python"
+  hint={`Use re.fullmatch with three groups of digits separated by hyphens.`}
+  code={`# Task: Return True only when the string is a NNN-NNN-NNNN phone number.
+import re
+
+def is_phone(s):
+    # Use re.fullmatch so the WHOLE string must match.
+    return re.fullmatch(r"___", s) is not None
+
+print(is_phone("415-555-1234"))  # True
+print(is_phone("hello"))          # False
+
+# Expected Output:
+# True
+# False`}
+  solution={`import re
+
+def is_phone(s):
+    return re.fullmatch(r"\\d{3}-\\d{3}-\\d{4}", s) is not None
+
+print(is_phone("415-555-1234"))
+print(is_phone("hello"))`}
+  sct={`test_output_contains("True")
+test_output_contains("False")
+success_msg("Great! fullmatch anchors the pattern to the entire string.")`}
+  height={190}
+/>
+
+### Exercise 3 – Mask sensitive words
+
+<DataCampExercise
+  lang="python"
+  hint={`Use re.sub to replace the matched word with '****'.`}
+  code={`# Task: Replace the word 'secret' (any case) with '****'.
+# Step 1: use re.sub with the re.IGNORECASE flag.
+import re
+
+text = "This is Secret. Keep the SECRET safe."
+masked = re.sub(r"___", "____", text, flags=re.IGNORECASE)
+print(masked)
+
+# Expected Output:
+# This is ****. Keep the **** safe.`}
+  solution={`import re
+
+text = "This is Secret. Keep the SECRET safe."
+masked = re.sub(r"secret", "****", text, flags=re.IGNORECASE)
+print(masked)`}
+  sct={`test_output_contains("This is ****")
+success_msg("Perfect! re.sub with IGNORECASE replaces all case variants.")`}
+  height={170}
+/>
+
+## Summary
+
+- `re` matches, searches, extracts, and replaces text with patterns.
+- Always write patterns as **raw strings** (`r"..."`).
+- Learn the core functions (`search`, `findall`, `finditer`, `sub`, `split`) and the `Match` object.
+- Master metacharacters, special sequences, quantifiers (greedy vs lazy), groups, and flags.
+- Pre-compile hot patterns and keep them simple to avoid backtracking blowups.
diff --git a/src/content/docs/tutorials/Python Standard Library/SQLite3.mdx b/src/content/docs/tutorials/Python Standard Library/SQLite3.mdx
new file mode 100644
index 00000000..fdc09ace
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/SQLite3.mdx	
@@ -0,0 +1,270 @@
+---
+title: Python sqlite3 — Database Basics
+description: A detailed guide to Python's sqlite3 module. Learn to connect, create tables, insert, query, parameterize, and commit using SQLite — with examples and practice exercises.
+sidebar:
+  order: 7
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+`sqlite3` is Python's built-in interface to **SQLite**, a tiny, serverless SQL database stored in a single file (or in memory). No setup, no server — perfect for scripts, prototypes, tests, and small apps.
+
+```python title="quickstart.py"
+import sqlite3
+
+conn = sqlite3.connect(":memory:")     # database that lives in RAM
+cur = conn.cursor()
+cur.execute("CREATE TABLE users (id INTEGER, name TEXT)")
+cur.execute("INSERT INTO users VALUES (1, 'Ada')")
+conn.commit()
+
+cur.execute("SELECT * FROM users")
+print(cur.fetchall())                  # [(1, 'Ada')]
+conn.close()
+```
+
+## The workflow
+
+Every sqlite3 program follows the same shape:
+
+1. **Connect** to a database file (or `:memory:`).
+2. Get a **cursor** to run SQL.
+3. **execute** statements.
+4. **commit** changes that modify data.
+5. **fetch** results from queries.
+6. **close** the connection.
+
+| Object / method | Purpose |
+|:---|:---|
+| `sqlite3.connect(path)` | Open (or create) a database. |
+| `conn.cursor()` | Create a cursor to run statements. |
+| `cur.execute(sql, params)` | Run one SQL statement. |
+| `cur.executemany(sql, seq)` | Run a statement for many rows. |
+| `cur.fetchone()` / `fetchall()` | Get one row / all rows. |
+| `conn.commit()` | Save pending changes. |
+| `conn.close()` | Close the connection. |
+
+## Creating tables and inserting
+
+```python title="create_insert.py"
+import sqlite3
+
+conn = sqlite3.connect("app.db")       # creates app.db if missing
+cur = conn.cursor()
+
+cur.execute("""
+    CREATE TABLE IF NOT EXISTS books (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title TEXT NOT NULL,
+        year INTEGER
+    )
+""")
+
+cur.execute("INSERT INTO books (title, year) VALUES (?, ?)", ("Dune", 1965))
+conn.commit()
+print("Inserted row id:", cur.lastrowid)
+conn.close()
+```
+
+## Parameterized queries — never use string formatting
+
+Always pass values with **`?` placeholders**. Building SQL with f-strings or `+` opens the door to **SQL injection** and quoting bugs.
+
+```python title="parameters.py"
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE users (name TEXT, age INTEGER)")
+
+# SAFE: values are passed separately
+name = "Ada'; DROP TABLE users; --"     # malicious input
+cur.execute("INSERT INTO users VALUES (?, ?)", (name, 30))
+
+# Insert many rows at once
+rows = [("Bob", 25), ("Cara", 41)]
+cur.executemany("INSERT INTO users VALUES (?, ?)", rows)
+conn.commit()
+
+cur.execute("SELECT * FROM users WHERE age > ?", (28,))
+print(cur.fetchall())   # [("Ada'; DROP TABLE users; --", 30), ('Cara', 41)]
+conn.close()
+```
+
+> Rule: the SQL string stays constant; **data goes through `?` parameters**.
+
+## Reading results
+
+```python title="reading.py"
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE nums (n INTEGER)")
+cur.executemany("INSERT INTO nums VALUES (?)", [(i,) for i in range(5)])
+conn.commit()
+
+cur.execute("SELECT n FROM nums")
+print(cur.fetchone())     # (0,)  -> first row only
+print(cur.fetchall())     # [(1,), (2,), (3,), (4,)]  -> remaining rows
+
+# A cursor is iterable — stream rows without loading all at once
+cur.execute("SELECT n FROM nums")
+for (value,) in cur:
+    print(value, end=" ")  # 0 1 2 3 4
+conn.close()
+```
+
+### Rows as dictionaries
+
+By default rows are tuples. Set a `row_factory` to access columns by name.
+
+```python title="row_factory.py"
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+conn.row_factory = sqlite3.Row         # rows behave like dicts
+cur = conn.cursor()
+cur.execute("CREATE TABLE p (id INTEGER, name TEXT)")
+cur.execute("INSERT INTO p VALUES (1, 'Ada')")
+
+row = cur.execute("SELECT * FROM p").fetchone()
+print(row["name"])    # Ada
+print(row["id"])      # 1
+conn.close()
+```
+
+## Connections as context managers
+
+Using `with conn:` automatically **commits** on success or **rolls back** on error.
+
+```python title="context_manager.py"
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+conn.execute("CREATE TABLE t (x INTEGER)")
+
+with conn:                              # commits automatically
+    conn.execute("INSERT INTO t VALUES (?)", (10,))
+
+print(conn.execute("SELECT * FROM t").fetchall())  # [(10,)]
+conn.close()
+```
+
+## Common pitfalls
+
+- **Forgetting `commit()`** — changes vanish when the program ends. (A `with conn:` block handles this.)
+- **String-built SQL** — always parameterize with `?` to stay safe.
+- **A single value tuple needs a comma** — `(28,)`, not `(28)`.
+- **`:memory:` databases disappear** when the connection closes — fine for tests, not for persistence.
+
+## Practice Exercises
+
+### Exercise 1 – Create and insert
+
+<DataCampExercise
+  lang="python"
+  hint={`Use execute with a CREATE TABLE statement, then an INSERT.`}
+  code={`# Task: Create a table 'pets' and insert one row, then count rows.
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE pets (name TEXT)")
+cur.execute("INSERT INTO pets VALUES (?)", ("Rex",))
+conn.commit()
+
+cur.execute("SELECT COUNT(*) FROM ___")
+print(cur.fetchone()[0])
+
+# Expected Output:
+# 1`}
+  solution={`import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE pets (name TEXT)")
+cur.execute("INSERT INTO pets VALUES (?)", ("Rex",))
+conn.commit()
+
+cur.execute("SELECT COUNT(*) FROM pets")
+print(cur.fetchone()[0])`}
+  sct={`test_output_contains("1")
+success_msg("COUNT(*) confirms one row was inserted.")`}
+  height={220}
+/>
+
+### Exercise 2 – Parameterized filter
+
+<DataCampExercise
+  lang="python"
+  hint={`Pass the threshold as a (value,) tuple to execute.`}
+  code={`# Task: Select names of users older than 30 using a ? placeholder.
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE u (name TEXT, age INTEGER)")
+cur.executemany("INSERT INTO u VALUES (?, ?)", [("Ada", 36), ("Bo", 22)])
+conn.commit()
+
+cur.execute("SELECT name FROM u WHERE age > ?", (___,))
+print(cur.fetchall())
+
+# Expected Output:
+# [('Ada',)]`}
+  solution={`import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE u (name TEXT, age INTEGER)")
+cur.executemany("INSERT INTO u VALUES (?, ?)", [("Ada", 36), ("Bo", 22)])
+conn.commit()
+
+cur.execute("SELECT name FROM u WHERE age > ?", (30,))
+print(cur.fetchall())`}
+  sct={`test_output_contains("('Ada',)")
+success_msg("The ? placeholder safely passes 30 into the query.")`}
+  height={230}
+/>
+
+### Exercise 3 – Insert many and fetch all
+
+<DataCampExercise
+  lang="python"
+  hint={`Use executemany with a list of single-value tuples.`}
+  code={`# Task: Insert three numbers with executemany, then fetch them all.
+import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE nums (n INTEGER)")
+cur.___("INSERT INTO nums VALUES (?)", [(1,), (2,), (3,)])
+conn.commit()
+
+cur.execute("SELECT n FROM nums")
+print(cur.fetchall())
+
+# Expected Output:
+# [(1,), (2,), (3,)]`}
+  solution={`import sqlite3
+
+conn = sqlite3.connect(":memory:")
+cur = conn.cursor()
+cur.execute("CREATE TABLE nums (n INTEGER)")
+cur.executemany("INSERT INTO nums VALUES (?)", [(1,), (2,), (3,)])
+conn.commit()
+
+cur.execute("SELECT n FROM nums")
+print(cur.fetchall())`}
+  sct={`test_output_contains("(1,), (2,), (3,)")
+success_msg("executemany inserts every tuple in the list.")`}
+  height={230}
+/>
+
+## Summary
+
+- `sqlite3` is a zero-setup SQL database built into Python.
+- Follow connect → cursor → execute → commit → fetch → close.
+- **Always** parameterize values with `?` to avoid SQL injection.
+- Use `sqlite3.Row` for dict-like rows and `with conn:` for automatic commit/rollback.
diff --git a/src/content/docs/tutorials/Python Standard Library/Testing with unittest and pytest.mdx b/src/content/docs/tutorials/Python Standard Library/Testing with unittest and pytest.mdx
new file mode 100644
index 00000000..bcc9b59d
--- /dev/null
+++ b/src/content/docs/tutorials/Python Standard Library/Testing with unittest and pytest.mdx	
@@ -0,0 +1,295 @@
+---
+title: Python Testing — unittest & pytest
+description: A detailed guide to testing Python code with the built-in unittest module and the popular pytest framework. Learn assertions, test cases, fixtures, parametrization, and exception testing — with examples and practice exercises.
+sidebar:
+  order: 12
+---
+
+import DataCampExercise from "../../../../components/DataCampExercise.astro";
+
+Automated tests check that your code does what you expect — and keep doing it as the code changes. Python ships **`unittest`** in the standard library, and the third-party **`pytest`** is the most popular framework in the ecosystem.
+
+```python title="why_test.py"
+def add(a, b):
+    return a + b
+
+# A test is just code that checks an assumption:
+assert add(2, 3) == 5
+assert add(-1, 1) == 0
+print("all good")
+```
+
+## The idea: Arrange, Act, Assert
+
+Most tests follow three steps:
+
+1. **Arrange** — set up inputs and state.
+2. **Act** — call the thing under test.
+3. **Assert** — check the result matches what you expect.
+
+## unittest (standard library)
+
+`unittest` groups tests into classes that subclass `TestCase`. Each method named `test_*` is a test, and you check results with `assert*` methods.
+
+```python title="unittest_basic.py"
+import unittest
+
+def add(a, b):
+    return a + b
+
+class TestAdd(unittest.TestCase):
+    def test_positive(self):
+        self.assertEqual(add(2, 3), 5)
+
+    def test_negative(self):
+        self.assertEqual(add(-1, -1), -2)
+
+    def test_type(self):
+        self.assertIsInstance(add(1, 2), int)
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+Run it from the terminal:
+
+```bash title="terminal"
+$ python -m unittest test_math.py
+...
+Ran 3 tests in 0.001s
+OK
+```
+
+### Common assert methods
+
+| Method | Passes when |
+|:---|:---|
+| `assertEqual(a, b)` | `a == b` |
+| `assertNotEqual(a, b)` | `a != b` |
+| `assertTrue(x)` / `assertFalse(x)` | `x` is truthy / falsy |
+| `assertIsNone(x)` | `x is None` |
+| `assertIn(a, b)` | `a in b` |
+| `assertIsInstance(a, cls)` | `a` is an instance of `cls` |
+| `assertRaises(Err)` | The block raises `Err` |
+
+### setUp and tearDown
+
+`setUp` runs before **each** test, `tearDown` after — great for shared fixtures.
+
+```python title="setup_teardown.py"
+import unittest
+
+class TestList(unittest.TestCase):
+    def setUp(self):
+        self.data = [1, 2, 3]      # fresh for every test
+
+    def test_append(self):
+        self.data.append(4)
+        self.assertEqual(self.data, [1, 2, 3, 4])
+
+    def test_length(self):
+        self.assertEqual(len(self.data), 3)
+```
+
+### Testing exceptions
+
+```python title="unittest_raises.py"
+import unittest
+
+def divide(a, b):
+    return a / b
+
+class TestDivide(unittest.TestCase):
+    def test_zero(self):
+        with self.assertRaises(ZeroDivisionError):
+            divide(1, 0)
+```
+
+## pytest (third-party)
+
+`pytest` lets you write tests as **plain functions** using ordinary `assert`. Install it first:
+
+```bash title="terminal"
+$ pip install pytest
+```
+
+```python title="test_pytest.py"
+# Functions named test_* are collected automatically.
+def add(a, b):
+    return a + b
+
+def test_positive():
+    assert add(2, 3) == 5
+
+def test_negative():
+    assert add(-1, 1) == 0
+```
+
+```bash title="terminal"
+$ pytest
+==== 2 passed in 0.01s ====
+```
+
+### Parametrize — one test, many cases
+
+```python title="parametrize.py"
+import pytest
+
+def square(n):
+    return n * n
+
+@pytest.mark.parametrize("value,expected", [
+    (2, 4),
+    (3, 9),
+    (-4, 16),
+])
+def test_square(value, expected):
+    assert square(value) == expected
+```
+
+### Fixtures — reusable setup
+
+```python title="fixtures.py"
+import pytest
+
+@pytest.fixture
+def sample_data():
+    return [1, 2, 3]
+
+def test_sum(sample_data):       # the fixture is injected by name
+    assert sum(sample_data) == 6
+```
+
+### Testing exceptions in pytest
+
+```python title="pytest_raises.py"
+import pytest
+
+def divide(a, b):
+    return a / b
+
+def test_zero():
+    with pytest.raises(ZeroDivisionError):
+        divide(1, 0)
+```
+
+## unittest vs pytest
+
+| | unittest | pytest |
+|:---|:---|:---|
+| Ships with Python | Yes | No (`pip install pytest`) |
+| Test style | `TestCase` classes | Plain functions |
+| Assertions | `self.assertEqual(...)` | plain `assert` |
+| Fixtures | `setUp`/`tearDown` | `@pytest.fixture` |
+| Parametrize | manual / subTest | `@pytest.mark.parametrize` |
+
+> Both are excellent. `unittest` is always available; `pytest` is more concise and has a rich plugin ecosystem. Many projects write plain `assert` tests and run them with `pytest`.
+
+## Common pitfalls
+
+- **Test functions/methods must start with `test`** or the runner skips them.
+- **Test one thing per test** — small, focused tests pinpoint failures.
+- **Don't depend on test order** — each test should stand alone.
+- **`assertEqual(a, b)` argument order** — convention is `(actual, expected)`.
+
+## Practice Exercises
+
+### Exercise 1 – Assert a function's result
+
+<DataCampExercise
+  lang="python"
+  hint={`Compare add(2, 2) to 4 with ==.`}
+  code={`# Task: Complete the assertion so it passes, then print "passed".
+def add(a, b):
+    return a + b
+
+assert add(2, 2) == ___
+print("passed")
+
+# Expected Output:
+# passed`}
+  solution={`def add(a, b):
+    return a + b
+
+assert add(2, 2) == 4
+print("passed")`}
+  sct={`test_output_contains("passed")
+success_msg("A passing assert lets execution continue to the print.")`}
+  height={170}
+/>
+
+### Exercise 2 – assertEqual in a TestCase
+
+<DataCampExercise
+  lang="python"
+  hint={`Use self.assertEqual(double(3), 6).`}
+  code={`# Task: Fill in the expected value so the test passes.
+import unittest
+
+def double(n):
+    return n * 2
+
+class TestDouble(unittest.TestCase):
+    def test_it(self):
+        self.assertEqual(double(3), ___)
+
+unittest.main(argv=["x"], exit=False)
+print("done")
+
+# Expected Output (ends with):
+# done`}
+  solution={`import unittest
+
+def double(n):
+    return n * 2
+
+class TestDouble(unittest.TestCase):
+    def test_it(self):
+        self.assertEqual(double(3), 6)
+
+unittest.main(argv=["x"], exit=False)
+print("done")`}
+  sct={`test_output_contains("done")
+success_msg("assertEqual checks double(3) equals 6.")`}
+  height={220}
+/>
+
+### Exercise 3 – Expect an exception
+
+<DataCampExercise
+  lang="python"
+  hint={`Use a with self.assertRaises(ValueError) block around int("nope").`}
+  code={`# Task: Assert that int("nope") raises a ValueError.
+import unittest
+
+class TestParse(unittest.TestCase):
+    def test_bad(self):
+        with self.___(ValueError):
+            int("nope")
+
+unittest.main(argv=["x"], exit=False)
+print("done")
+
+# Expected Output (ends with):
+# done`}
+  solution={`import unittest
+
+class TestParse(unittest.TestCase):
+    def test_bad(self):
+        with self.assertRaises(ValueError):
+            int("nope")
+
+unittest.main(argv=["x"], exit=False)
+print("done")`}
+  sct={`test_output_contains("done")
+success_msg("assertRaises confirms the code raises the expected error.")`}
+  height={210}
+/>
+
+## Summary
+
+- Tests **arrange, act, assert** to lock in expected behaviour.
+- **`unittest`** (built in) uses `TestCase` classes, `assert*` methods, and `setUp`/`tearDown`.
+- **`pytest`** (install with pip) uses plain functions, bare `assert`, fixtures, and `@parametrize`.
+- Test exceptions with `assertRaises` / `pytest.raises`.
+- Keep tests small, independent, and named `test_*`.
diff --git a/src/content/docs/tutorials/Python Strings/Formatting String.mdx b/src/content/docs/tutorials/Python Strings/Formatting String.mdx
index 0d6a54f4..a582e197 100644
--- a/src/content/docs/tutorials/Python Strings/Formatting String.mdx	
+++ b/src/content/docs/tutorials/Python Strings/Formatting String.mdx	
@@ -28,6 +28,10 @@ TypeError: can only concatenate str (not "int") to str
 The above example will throw an error because we cannot combine strings and numbers like this, using the `+` operator. We can only combine strings with other strings.
 :::
 
+:::tip[Go deeper on f-strings]
+This page introduces all the formatting techniques. For an in-depth look at f-strings — the format spec mini-language (alignment, width, precision, thousands, number bases), the `=` debug specifier, conversions, and nesting — see the [f-strings Deep Dive](../../modern-python/f-strings-deep-dive/).
+:::
+
 String formatting is the process of building a string representation dynamically by inserting the value of numeric expressions in an already existing string. Python's string concatenation operator doesn't accept a non-string operand. Hence, Python offers following string formatting techniques −
 
 - The `%` operator
diff --git a/src/content/docs/tutorials/Python Variables/Global Variables.mdx b/src/content/docs/tutorials/Python Variables/Global Variables.mdx
index 82680351..504d5133 100644
--- a/src/content/docs/tutorials/Python Variables/Global Variables.mdx	
+++ b/src/content/docs/tutorials/Python Variables/Global Variables.mdx	
@@ -7,6 +7,18 @@ sidebar:
 
 We can create a variable outside of a function. This is called a global variable. We can access the global variable inside or outside of a function. Let's see an example.
 
+A variable's **scope** is the region of the program where it is visible. A variable created outside every function lives in the *global* scope; one created inside a function lives in that function's *local* scope.
+
+**Diagram**:
+```mermaid title="global vs local scope" desc="Where variables are visible"
+graph TD
+    A[Global scope] --> B[name = 'John']
+    A --> C[Function display]
+    C --> D[Local scope: its own names]
+    D -->|can read| B
+    D -->|cannot change unless 'global'| B
+```
+
 #### Example:
 ```python title="variable.py" showLineNumbers{1} {2}
 # Global variable
@@ -82,6 +94,21 @@ Hello, Smith
 
 In this example, we used the `global` keyword to access the global variable `name` inside the function `display()`. We can access the global variable `name` inside the function `display()`. We can also access the global variable `name` outside the function `display()`.
 
+:::caution
+**Use `global` sparingly.** Functions that quietly modify global state are hard to test and debug, because their result depends on data outside the function. Prefer passing values in as parameters and returning results:
+```python title="prefer_return.py" showLineNumbers{1} {1-5}
+# Better than mutating a global
+def increment(value):
+    return value + 1
+
+count = increment(0)   # caller controls the state
+```
+:::
+
+:::note
+`global` reaches the module-level scope. To reassign a variable in an *enclosing function* (not the global scope), use the `nonlocal` keyword instead. Both are covered in depth in the [Closures and Scope (LEGB)](/tutorials/closures-and-scope/) tutorial.
+:::
+
 ---
 
 import DataCampExercise from "../../../../components/DataCampExercise.astro";
diff --git a/src/content/docs/tutorials/Python Variables/Multiple Assignment.mdx b/src/content/docs/tutorials/Python Variables/Multiple Assignment.mdx
index 5871badf..42e8d6b7 100644
--- a/src/content/docs/tutorials/Python Variables/Multiple Assignment.mdx	
+++ b/src/content/docs/tutorials/Python Variables/Multiple Assignment.mdx	
@@ -98,6 +98,37 @@ C:\Users\Your Name> python variable.py
 10 20 30
 ```
 
+## Extended Unpacking with `*`
+
+When you do not know (or do not care) how many items are in the middle, a starred variable `*` captures the rest as a list. This is called **extended unpacking**.
+
+```python title="star_unpack.py" showLineNumbers{1} {1-7}
+numbers = [1, 2, 3, 4, 5]
+
+first, *rest = numbers
+print(first, rest)        # 1 [2, 3, 4, 5]
+
+first, *middle, last = numbers
+print(first, middle, last)  # 1 [2, 3, 4] 5
+```
+
+## Swapping Variables
+
+Multiple assignment gives Python an elegant one-line swap — no temporary variable needed. The right-hand side is built into a tuple first, then unpacked.
+
+```python title="swap.py" showLineNumbers{1} {1-3}
+a, b = 5, 10
+a, b = b, a
+print(a, b)   # 10 5
+```
+
+:::caution
+The count must match (unless you use `*`). Too few or too many values raises a `ValueError`:
+```python title="mismatch.py" showLineNumbers{1} {1}
+x, y = 1, 2, 3   # ValueError: too many values to unpack (expected 2)
+```
+:::
+
 ---
 
 import DataCampExercise from "../../../../components/DataCampExercise.astro";
diff --git a/src/content/docs/tutorials/Python Variables/Naming Convention.mdx b/src/content/docs/tutorials/Python Variables/Naming Convention.mdx
index 2cfeb053..6d9f3ecc 100644
--- a/src/content/docs/tutorials/Python Variables/Naming Convention.mdx	
+++ b/src/content/docs/tutorials/Python Variables/Naming Convention.mdx	
@@ -57,7 +57,6 @@ my-name = "John"
 my name = "John"
 ```
 :::
-B
 
 ## Constant Naming Conventions
 Constants are usually declared and assigned in a module. Python does not have built-in constant types, but Python programmers use all capital letters to indicate a variable should be treated as a constant and never be changed after it is initialized.
@@ -132,6 +131,44 @@ def set_first_name():
     pass
 ```
 
+## Which Style Does Python Use?
+
+The three styles above all *run*, but Python's official style guide (**PEP 8**) assigns a specific style to each kind of identifier. Following it makes your code look like everyone else's Python.
+
+| Identifier | Convention | Example |
+| :--- | :--- | :--- |
+| Variable | `snake_case` | `user_age`, `total_price` |
+| Function | `snake_case` | `get_user()`, `calc_total()` |
+| Constant | `UPPER_SNAKE_CASE` | `MAX_SIZE`, `PI` |
+| Class | `PascalCase` (CapWords) | `BankAccount`, `UserProfile` |
+| Module / file | short `lowercase` | `utils.py`, `data_loader.py` |
+
+:::tip
+**`camelCase` is *not* idiomatic Python** even though it works. Use `snake_case` for variables and functions — reserve `PascalCase` for classes.
+:::
+
+## Underscore Conventions
+
+The underscore carries special meaning in several naming patterns:
+
+| Pattern | Meaning |
+| :--- | :--- |
+| `_name` | "Internal use" hint — a weak private signal to other developers. |
+| `name_` | Trailing underscore to avoid clashing with a keyword, e.g. `class_`, `type_`. |
+| `__name` | Name mangling inside a class — Python rewrites it to avoid subclass clashes. |
+| `__name__` | "Dunder" (double underscore) — reserved for Python, e.g. `__init__`, `__name__`. |
+| `_` | A throwaway variable for values you intend to ignore: `for _ in range(3):`. |
+
+```python title="underscores.py" showLineNumbers{1} {1-3}
+_internal = "use within this module"
+class_ = "Biology 101"     # avoids the 'class' keyword
+for _ in range(3):         # loop counter is unused
+    print("hi")
+```
+
+:::note
+For the full rules, see [PEP 8 — Style Guide for Python Code](https://peps.python.org/pep-0008/).
+:::
 
 ---
 
diff --git a/src/content/docs/tutorials/Python Variables/Variable Assignment.mdx b/src/content/docs/tutorials/Python Variables/Variable Assignment.mdx
index 177cd7b1..1cdb881f 100644
--- a/src/content/docs/tutorials/Python Variables/Variable Assignment.mdx	
+++ b/src/content/docs/tutorials/Python Variables/Variable Assignment.mdx	
@@ -6,7 +6,16 @@ sidebar:
 ---
 
 ## What is a Variable?
-Python variables are the reserved memory locations used to store values with in a Python Program. This means that when you create a variable you reserve some space in the memory. Based on the data type of a variable, Python interpreter allocates memory and decides what can be stored in the reserved memory. Therefore, by assigning different data types to Python variables, you can store integers, decimals or characters in these variables.
+A variable is a **name** that refers to a value stored in memory. In Python, a variable is best understood as a *label* attached to an object, not a box that holds the value. When you write `x = 10`, Python creates the integer object `10` and binds the name `x` to it. This "name binding" model explains a lot of Python's behaviour.
+
+**Diagram**:
+```mermaid title="variables are names bound to objects" desc="How a variable name references a value in memory"
+graph LR
+    A[Name: x] -->|refers to| B["Object: 10 (int)"]
+    C[Name: y] -->|refers to| B
+```
+
+Therefore, by assigning different data types to Python variables, you can store integers, decimals, strings, or any other object — and the name can be rebound to a different object at any time.
 
 ## Declaring Variables in Python
 In Python, variables do not need explicit declaration to reserve memory space. The declaration happens automatically when you assign a value to a variable. The equal sign (=) is used to assign values to variables.
@@ -104,6 +113,42 @@ C:\Users\Your Name> python variable.py
 20.5
 ```
 
+## Reassigning and Dynamic Typing
+
+A variable can be rebound to a value of any type at any time — Python does not lock a name to one type.
+
+```python title="variable.py" showLineNumbers{1} {1-4}
+x = 10        # x refers to an int
+x = "ten"     # now x refers to a str — perfectly legal
+x = [1, 2, 3] # now a list
+print(x)      # [1, 2, 3]
+```
+
+## Deleting a Variable
+
+The `del` statement removes a name binding. Using the name afterwards raises a `NameError`.
+
+```python title="del.py" showLineNumbers{1} {1-3}
+score = 100
+del score
+# print(score)   # NameError: name 'score' is not defined
+```
+
+## Aliasing: Two Names, One Object
+
+Because a variable is just a name, assigning one variable to another makes both names point to the **same** object. For **mutable** objects (like lists) this matters — changing it through one name is visible through the other.
+
+```python title="alias.py" showLineNumbers{1} {1-4}
+a = [1, 2, 3]
+b = a          # b and a refer to the SAME list
+b.append(4)
+print(a)       # [1, 2, 3, 4]  -> changed through b!
+```
+
+:::tip
+To get an independent copy instead of an alias, use `b = a.copy()` (or `list(a)`). See the [Data Types](/tutorials/datatype/) tutorial for mutable vs. immutable.
+:::
+
 ---
 
 import DataCampExercise from "../../../../components/DataCampExercise.astro";
diff --git a/src/content/docs/tutorials/Syntax.mdx b/src/content/docs/tutorials/Syntax.mdx
index 92b58ccb..219f96b1 100644
--- a/src/content/docs/tutorials/Syntax.mdx
+++ b/src/content/docs/tutorials/Syntax.mdx
@@ -9,6 +9,52 @@ import DataCampExercise from "../../../components/DataCampExercise.astro";
 
 ## Python Syntax: Indentation and Its Uniqueness
 
+Syntax is the set of rules that defines how a Python program is written. Compared to most languages, Python's syntax is famously minimal — no braces, no semicolons at the end of lines, no type declarations. This section covers the rules that matter most when you start.
+
+## Statements and Lines
+
+A **statement** is a single instruction Python executes. By default, one statement sits on one line, and the end of the line ends the statement — no semicolon needed.
+
+```python title="statements.py" showLineNumbers{1}
+x = 5
+y = 10
+print(x + y)
+```
+
+You *can* place multiple statements on one line with a semicolon, though it is discouraged for readability:
+
+```python title="oneline.py" showLineNumbers{1}
+x = 5; y = 10; print(x + y)   # works, but avoid this style
+```
+
+### Line Continuation
+
+For a long statement, break it across lines using a backslash `\`, or — preferably — wrap it in parentheses `()`, brackets `[]`, or braces `{}`, inside which Python ignores line breaks:
+
+```python title="continuation.py" showLineNumbers{1} {2-3,6-10}
+# Explicit continuation with a backslash
+total = 1 + 2 + 3 + \
+        4 + 5 + 6
+
+# Implicit continuation inside brackets (preferred)
+numbers = [
+    1, 2, 3,
+    4, 5, 6,
+]
+```
+
+## Code Blocks and the Colon
+
+A **block** is a group of statements that belong together (the body of an `if`, a loop, a function). In Python, a block is introduced by a colon `:` on the previous line and defined by the indentation that follows.
+
+**Diagram**:
+```mermaid title="Python block structure" desc="How a colon and indentation define a block"
+graph TD
+    A["Header line ends with ':'"] --> B[Indented body = the block]
+    B --> C[Dedent = block ends]
+    C --> D[Back to outer level]
+```
+
 ## Indentation in Python
 
 Unlike many other programming languages that use braces `{}` or keywords like `begin` and `end` to define blocks of code, Python relies on indentation to signify the beginning and end of blocks.
@@ -27,15 +73,20 @@ else:
 In the above example, the lines of code within the `if` and `else` blocks are indented to indicate the scope of each block. The level of indentation is crucial, as it determines the structure of the code.
 
 :::danger
-You must use the same number of spaces or tabs for each level of indentation. Mixing tabs and spaces can lead to errors.
-```python title="indent.py" showLineNumbers{1}
+You must use the same number of spaces or tabs for each level of indentation. Missing or inconsistent indentation raises an error. The code below is **broken** — the body of `if` is not indented:
+```python title="broken.py" showLineNumbers{1}
 if True:
-print("This is indented.")
-  print("So is this.")
-else:
-print("This is not indented.")
+print("This is indented.")     # ERROR: expected an indented block
 ```
-
+Running it produces:
+```cmd title="command" showLineNumbers{1} {2-4}
+C:\Users\Your Name> python broken.py
+  File "broken.py", line 2
+    print("This is indented.")
+    ^
+IndentationError: expected an indented block after 'if' statement on line 1
+```
+Mixing tabs and spaces in the same block raises a `TabError`. Pick one (spaces are the convention) and stay consistent.
 :::
 
 ## Importance of Indentation
@@ -66,6 +117,33 @@ In this C++ example, blocks are defined by braces `{}`. The indentation is not s
 
 3. **Use an Editor with Indentation Support:** Many code editors automatically handle indentation for you. Configure your editor to use spaces or tabs consistently.
 
+## Python is Case-Sensitive
+
+Python treats uppercase and lowercase letters as different. `Name`, `name`, and `NAME` are three separate identifiers, and keywords must be lowercase (`True`, not `true` — except the booleans which are capitalised).
+
+```python title="case.py" showLineNumbers{1}
+name = "Alice"
+Name = "Bob"
+print(name)   # Alice
+print(Name)   # Bob
+```
+
+## Keywords and Identifiers
+
+**Keywords** are reserved words with special meaning (`if`, `for`, `def`, `return`, `class`, ...). You cannot use them as variable names. **Identifiers** are the names you give to variables, functions, and classes; they may contain letters, digits, and underscores, but cannot start with a digit.
+
+```python title="keywords.py" showLineNumbers{1}
+import keyword
+print(keyword.kwlist)   # prints every reserved keyword
+```
+
+Output:
+
+```cmd title="command" showLineNumbers{1} {2}
+C:\Users\Your Name> python keywords.py
+['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break', ...]
+```
+
 ## Conclusion
 
 Understanding Python's indentation syntax is crucial for writing clean and readable code. Embrace the uniqueness of Python's syntax, and you'll find that it contributes to the language's elegance and readability.
diff --git a/src/pages/rss.xml.js b/src/pages/rss.xml.js
new file mode 100644
index 00000000..aa42a337
--- /dev/null
+++ b/src/pages/rss.xml.js
@@ -0,0 +1,27 @@
+import rss from "@astrojs/rss";
+import { getCollection } from "astro:content";
+
+export async function GET(context) {
+  const docs = await getCollection("docs");
+
+  // Syndicate tutorials and project pages (skip drafts and the 404 page).
+  const items = docs
+    .filter((entry) => {
+      const id = entry.id.toLowerCase();
+      return id.startsWith("tutorials/") || id.startsWith("projects/");
+    })
+    .filter((entry) => entry.slug !== "404")
+    .map((entry) => ({
+      title: entry.data.title,
+      description: entry.data.description ?? "",
+      link: `/${entry.slug}/`,
+    }));
+
+  return rss({
+    title: "Python Central Hub",
+    description:
+      "Tutorials and hands-on Python projects from Python Central Hub.",
+    site: context.site,
+    items,
+  });
+}
diff --git a/src/styles/global.css b/src/styles/global.css
index 26c6b305..7017fd12 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -2,6 +2,27 @@
 @tailwind components;
 @tailwind utilities;
 
+/* Skip-to-content link: hidden until focused, then visible top-left. */
+.skip-to-content {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 1000;
+  padding: 0.5rem 1rem;
+  background: var(--sl-color-accent-high, #e7c384);
+  color: var(--sl-color-black, #000);
+  border-radius: 0 0 0.5rem 0;
+  font-weight: 600;
+  transform: translateY(-150%);
+  transition: transform 0.2s ease-in-out;
+}
+.skip-to-content:focus,
+.skip-to-content:focus-visible {
+  transform: translateY(0);
+  outline: 2px solid var(--sl-color-accent-high);
+  outline-offset: 2px;
+}
+
 /* * {
   margin: 0;
   padding: 0;