# TechNoviceTools (TNT) — Site Overview for AI Collaboration
> Load this file when working on any TNT feature. It gives the AI a bird's-eye
> understanding of site purpose, structure, philosophy, and conventions.
> Last updated: 2026-08-13

---

## 1. What TNT Is

**TechNoviceTools (TNT)** is a public educational website run by a high-school computer
science teacher ("TTG" — The Tech Tools Guru, a former rocket scientist) and his students.
It has been live since **2015** and serves as:

- A **showcase** of student and teacher-built apps
- A **teaching platform** that makes coding visible, tangible, and inspiring
- A **living lab** where design, code, and pedagogy are openly iterated
- A **curriculum support tool** for three CS studio courses

The audience is primarily **high-school students (grades 9–12)** and their teachers.
The tone is energetic, a little irreverent, and always educational.

---

## 2. The Three Studio Courses

TNT supports a complete CS curriculum at the Department of Innovation:

| Course | Tag | Audience | Core Stack |
|---|---|---|---|
| **CS Foundation Studio** | Course 01 | Gr. 9–12, no prior experience | Python, Processing.py, p5.js |
| **CS Innovations Studio** | Course 02 | Gr. 10–12, some experience | JavaScript, HTML, CSS, Bootstrap 5 |
| **AP Developer Studio** | Course 03 | Gr. 11–12, pathway summit | Java, OOP, AP CS A prep |

Each course has its own color identity used across pages:
- **Foundation** → green `#90c356` / `rgba(144,195,86,...)`
- **Innovations** → yellow `#f4e542` / `rgba(244,229,66,...)`
- **AP Java** → blue `#5eb3d6` / `rgba(94,179,214,...)`

Course intro pages live at: `InnovCoursesIntro2026-06-01-Stg2/`

---

## 3. The S.P.A.R.K. Method

S.P.A.R.K. is TNT's signature AI-workflow framework. It threads through every course.

| Letter | Step | What it Means |
|---|---|---|
| **S** | Set Goals | Define what you are building before prompting |
| **P** | Prompt | Use AI as a thinking partner; you direct and own the result |
| **A** | Analyze | Never accept AI output blindly; read every line |
| **R** | Refine | Iterate; first drafts are starts, not finishes |
| **K** | Know & Share | Teaching it is the deepest test of understanding |

SPARK speeches are a formal student presentation component. See:
`SparkSpeech2026-05-05-Stg1/`

Prompting as a skill is documented at:
`InnovCoursesIntro2026-06-01-Stg2/introToPrompting.html`

---

## 4. Site Architecture

### 4a. Root-Level Pages (Main Navigation)

| File | Purpose |
|---|---|
| `index.html` | Home — hero, featured destinations, live JS demos, tech stack |
| `aboutUs.html` | Team identity, philosophy, reverse-engineering approach |
| `news.html` | Chronological log of new features/apps (accordion, newest first) |
| `explore.html` | Master catalog — 11 categories, offcanvas panels per category |
| `movie_clips.html` | Curated clips that inspire coding lessons |
| `js_apps.html` | 2026 JavaScript app grid |
| `processing_apps.html` | 2026 p5.js / Processing app grid |
| `php_apps.html` | 2026 PHP server-side app grid |
| `stylin.html` | CSS & Bootstrap showcase; vintage mode toggle |
| `resources.html` | Curated external resources, accordion by category |
| `dwrEureka.html` | "Danger Will Robinson" + Eureka log; real lesson entries in a table |
| `askCopilot.html` | Dear Abby–style Q&A column; 59+ entries; search + topic filter |
| `tnt_image_gallery.html` | Modal image gallery; search + filter by human-approved |
| `past_blasts.html` | Preserved legacy page snapshots for compare/contrast learning |

### 4b. Key Subdirectories

| Folder | Contents |
|---|---|
| `_LegacyTNT/` | Full archive of pre-2026 site; preserved for historical comparison |
| `InnovCoursesIntro2026-06-01-Stg2/` | Department of Innovation course intro hub |
| `SparkSpeech2026-05-05-Stg1/` | S.P.A.R.K. speeches system |
| `SketchWaveTNT_Current/` | TNT's own p5.js extension ecosystem |
| `adventures/` | TNT Adventures — structured scavenger hunt missions |
| `CrossTraining/` | Cross-language concept comparison (JS / Java / Python) |
| `markdownFiles/markdownSpecs/` | AI-facing planning & spec documents |
| `scripts/` | Shared JS: `linkGuard.js`, `domTargeting.js`, `tnt-index.js`, etc. |
| `styles/` | Shared CSS: `tnt-base-styles.css` + page-specific stylesheets |
| `images/` | Root-level shared images |
| `resources/` | Internal resource sub-pages (cheat sheets, guides) |
| `movie_clips/` | Individual movie clip pages |

### 4c. Per-App Folder Pattern

Each app lives in its own folder, e.g. `BingoSPARKJS2026-07-11/`.
Folder naming convention: `AppNameSPARK` or `AppName` + `YYYY-MM-DD` + optional stage tag
(`-Stg2`, `-S8`, etc.).

---

## 5. Tech Stack

| Layer | Technology | CDN Version |
|---|---|---|
| CSS framework | Bootstrap 5 | 5.3.3 |
| Icons | Font Awesome | 6.5.0 |
| Fonts | Google Fonts — Boogaloo (brand), Inter (body) | current |
| Client-side interactivity | Vanilla JavaScript (ES6+) | — |
| Graphics / animation | p5.js, Processing.js | varies per app |
| Server-side | PHP (shared host) | 5.x compat required for some files |
| AI assistant | GitHub Copilot (VS Code) | — |
| Editor | VS Code | — |

**No npm, no build step, no framework SPA.** All pages are plain HTML files.
Bootstrap and FA are loaded from CDN. Do **not** add `integrity=` SRI hashes to
Bootstrap CDN links — see DWR Entry #19 for why (hash mismatches cause silent JS failure).

---

## 6. Design System

### Colors (CSS custom properties in `tnt-base-styles.css`)

```css
--tnt-red:   #D81827;   /* brand red — TNT logo, accents */
--tnt-amber: #FF824A;   /* amber — hero CTA, icon accents */
--foundation: #90c356;  /* Course 01 green */
--innovations: #f4e542; /* Course 02 yellow */
--ap-java:    #5eb3d6;  /* Course 03 blue */
```

### Page Structure Pattern (all 2026 main pages)

```
<nav>           sticky top navbar — consistent across all pages
<main>
  <section id="hero">       full-viewport hero with background image
  <section id="...">        content sections with .container
</main>
<footer>        icon row + copyright + last-updated
```

### Navigation

Navbar is consistent across all root pages. `aria-current="page"` marks the active link.
Offcanvas panels (`tnt-offcanvas` class) are used for full category app listings on `explore.html`
and `stylin.html`.

---

## 7. JavaScript Conventions

- Page init pattern: `<body onload="init();">` with a global `init()` function
- Copyright/date: `document.getElementById('copyrightSpan')` and `'updateSpan'`
- Validate link: hidden on `localhost`; appended `?doc=URL` when live
- Search/filter: inline `input` event listeners on `#appSearch` or `#gallerySearch`
- No jQuery. No external JS libraries beyond Bootstrap bundle.
- `linkGuard.js` — included on every page; guards against broken/dead links
- `domTargeting.js` — powers the DOM Jumble demo on `index.html`

---

## 8. Content Conventions

### App Grid Pages (`js_apps.html`, `processing_apps.html`, `php_apps.html`)
- Apps listed as `<figure>` blocks inside `#appGrid`
- `<figure class="future">` for placeholders (excluded from search count)
- Each `<figcaption>` has app name + `<small>` subtitle
- `app-icon` class on the image (80×80px target)

### `news.html` Entry Pattern
- Bootstrap accordion; newest entries at top
- IDs follow `news-2026-NNN` pattern (3-digit, zero-padded)
- `lastUpdate` variable in `<script>` block must be updated when entries are added

### `dwrEureka.html` Entry Pattern
- HTML table rows; `id="dwr-NN"` on each `<tr>`
- `<span class="badge-dwr">DWR</span>` or `<span class="badge-eureka">Eureka</span>`
- `<details>/<summary>` for expandable entry body

### `askCopilot.html` Entry Pattern
- `<article class="column-entry" id="entry-NNN">` (3-digit, zero-padded)
- Newest entries at top
- Sections: `.column-entry-header`, `.column-letter`, `.column-response`
- `.column-sign` closes each section: `&mdash; Signed, [Nickname]` / `&mdash; Copilot`
- Topic badge: `<span class="column-topic-badge">Topic</span>`

---

## 9. Philosophical Guardrails

These are not negotiable. They define TNT's identity:

1. **Students stay in the driver's seat.** AI is a tool; S.P.A.R.K. keeps the human accountable.
2. **Visible learning.** Code must produce something you can see — animation, output, interaction.
3. **Real over perfect.** Show the mistakes, the DWRs, the iterations. Transparency is the lesson.
4. **Reverse engineering is valid.** Studying existing code and rebuilding it is a core method.
5. **Novice-friendly language.** Explanations on every page should be accessible to a grade-9 beginner.
6. **One page = one lesson anchor.** Apps are tied to curriculum moments; they aren't built in isolation.
7. **No dark patterns.** No forced logins, no tracking beyond Google Search Console, no ads.

---

## 10. Key Files to Know Before Editing

| File | Why It Matters |
|---|---|
| `styles/tnt-base-styles.css` | Global CSS — touch carefully |
| `scripts/linkGuard.js` | Included on every page; do not remove |
| `explore.html` | Master app catalog — must be updated when new apps ship |
| `news.html` | News log — must be updated when new features ship |
| `dwrEureka.html` | Lessons learned log — update when a notable DWR is resolved |
| `sitemap.xml` | Update when new pages are added |

---

## 11. Common Tasks (Quick Reference for AI)

| Task | Where to Work |
|---|---|
| Add a new JS app | `js_apps.html` (figure block) + `explore.html` (offcanvas + card) + `news.html` |
| Add a new Processing app | `processing_apps.html` + `explore.html` + `news.html` |
| Add a new PHP app | `php_apps.html` + `explore.html` + `news.html` |
| Add a new movie clip page | `movie_clips/yourFile.html` + `movie_clips.html` (grid card) |
| Add a new gallery image | `tnt_image_gallery.html` (button block in `#galleryGrid`) |
| Add a DWR/Eureka entry | `dwrEureka.html` (new `<tr>` at top of `<tbody>`) |
| Add an Ask Copilot entry | `askCopilot.html` (new `<article>` at top of entry list) |
| Add a news item | `news.html` (new accordion item, update `lastUpdate`) |
| Create a new app folder | Use `AppNameSPARK-YYYY-MM-DD/` naming convention |

---

## 12. What "SPARK Edition" Means

When an app is labeled "SPARK Edition," it includes one or more of:
- A **multi-stage build log** (chatlog showing the S.P.A.R.K. process)
- An **index/cover page** that introduces the app in curriculum context
- A **linked movie clip** or cultural reference that inspired it
- A **news entry** that documents when and why it shipped

Not every app is a SPARK Edition — some are straightforward utility builds.

---

*End of TNT Overview — load this alongside any page you are editing for best results.*