From 3d5b36283db3d85165e0268b84c3eb66ecd66479 Mon Sep 17 00:00:00 2001 From: Kol Tregaskes Date: Tue, 19 May 2026 15:02:15 +0100 Subject: [PATCH 1/4] feat: add Zine prototype (May 2026 design pack) Self-contained vanilla port of StackScout Prototype.html under prototype/ implementing Phase 1 of CLAUDE-HANDOFF-2026-05-zine.md: - 5-mood palette with localStorage persistence - Stack Scout wordmark + accent dot (two words, no issue number) - Cycling lead, sparklines, hover stripes, magnetic CTA, cursor spotlight - Film grain, marquee, live UTC clock, count-ups - Home rendered with placeholder data; Releases/Wire/List/Subscribe stubbed Adds DESIGN-2026-05-zine.md and CLAUDE-HANDOFF-2026-05-zine.md alongside the existing DESIGN.md so the new design spec is in-repo without overwriting the legacy spec. Live index.html is unchanged. Design pack source: W:\Websites\LOCAL-ONLY\stackscout\design-2026-05-19\ Source session: WEBSITE CODER (Linear KOL-533 family) Co-Authored-By: Claude Opus 4.7 --- CLAUDE-HANDOFF-2026-05-zine.md | 108 +++ DESIGN-2026-05-zine.md | 224 +++++++ prototype/README.md | 50 ++ prototype/index.html | 1121 ++++++++++++++++++++++++++++++++ 4 files changed, 1503 insertions(+) create mode 100644 CLAUDE-HANDOFF-2026-05-zine.md create mode 100644 DESIGN-2026-05-zine.md create mode 100644 prototype/README.md create mode 100644 prototype/index.html diff --git a/CLAUDE-HANDOFF-2026-05-zine.md b/CLAUDE-HANDOFF-2026-05-zine.md new file mode 100644 index 0000000..feefe0e --- /dev/null +++ b/CLAUDE-HANDOFF-2026-05-zine.md @@ -0,0 +1,108 @@ +# Stack Scout — Handoff to Claude Code + +This pack is for Claude Code to build the production site from. Read `DESIGN.md` first for the design spec; this file covers _how to ship it_. + +## What this is + +A complete, working HTML prototype at `StackScout Prototype.html` plus the design system in `DESIGN.md`. The prototype is build-with-Babel-in-browser React for iteration speed; production must be vanilla HTML/CSS + a thin JS layer, matching the existing `stackscout/` codebase pattern. + +## What you're replacing + +The existing `stackscout/` repo: +- builds a public site from `content/stackscout/site-source.json` + `tools-source.json` + `updates-source.json` +- via `scripts/build-stackscout.js` → static HTML in `index.html`, `catalog/`, `categories/`, etc. +- with `styles.css` + `app.js` providing the chrome +- targeting GitHub Pages + +Keep the shared source layer. Replace the chrome + page templates + IA with the design from this prototype. + +## Build order + +### Phase 1 · Shell + palette (~half day) + +1. Port `wireframes/zine-shell.jsx`'s palette + animation system to vanilla CSS custom properties + a tiny JS module. + - 5 palette presets are five CSS custom-property classes (`.mood-graphite`, `.mood-midnight`, etc.) on ``. + - Mood swap = swap class on ``. Persist to `localStorage`. Read on `DOMContentLoaded`. + - Pull `--ink`, `--muted`, `--rule`, `--rule-strong` to `:root`. Mood classes only set `--bg` and `--accent`. +2. Masthead: wordmark + dot + nav + mood toggle. No issue number, no tagline. Active page state via `data-page` attribute on ``. +3. Footer: live UTC clock chip + "Sources & method →" link to `/sources/`. Marquee with the 6 manifesto lines, CSS-only. +4. Page-header strip: breadcrumb on the left, configurable right slot. Becomes a partial in your template engine. +5. CSS keyframes: `ss-reveal-in`, `ss-rule-in`, `ss-pulse`, `ss-marquee-scroll`, `ss-text-cycle-in`, `ss-spark-rise`. All five live in one stylesheet block. + +### Phase 2 · Pages from source manifests (~1–2 days) + +Build templates for the 6 pages. Each page reads from the source layer and renders the markup the prototype shows. + +| Page | Source | Template should do | +|---|---|---| +| `index.html` (home) | `updates-source.json` (latest 4), `tools-source.json` (5 setlist + 5 list) | Cycling lead uses 4 most recent wire items. Setlist = next-90-days releases. Wire = last 48h. | +| `releases/index.html` | `tools-source.json` | Group by `releaseWindow` (week / month / quarter). Calendar view is a separate URL param or `#calendar` hash. | +| `wire/index.html` | `updates-source.json` | Paginated. Filter via query string (`?kind=funding`). | +| `list/index.html` | `tools-source.json` | Ranked list. Manual rank field; default order if missing. | +| `subscribe/index.html` | static + archive from `updates-source.json` grouped by week | Form posts to whatever subscribe endpoint Kol picks. | +| `sources/index.html` | new `sources-source.json` (Claude Code creates the schema) | Grouped Primary / Secondary / Aggregators + method explainer. | + +### Phase 3 · Filters and tags (~half day) + +The filter pills in the prototype are visual-only. Make them work. + +1. Reads from query string on load. +2. Updates query string + filters DOM on click (no router needed). +3. Tag chips on tool cards / wire items are anchor tags to the filtered URL. + +### Phase 4 · Real data hookup (Kol) + +The prototype uses placeholder data with intentionally fixed dates. Replace with: + +- `tools-source.json` entries — Claude 4.5, Cursor 2.5, GPT-5.5, Suno v5.5, Gemini 3.1 Pro/Flash, etc. +- `updates-source.json` — wire items from official changelogs only. +- `sources-source.json` — new file; see Sources page in prototype for shape. + +## Things to preserve from the prototype + +| Interaction | Where in prototype | +|---|---| +| Mood toggle (5 swatches) | `zine-shell.jsx` → `ColorToggle` | +| Cycling lead (4 headlines, blur-fade, hover-pause, click-to-jump dots) | `zine-extras.jsx` → `CyclingLead` | +| Magnetic CTA | `zine-extras.jsx` → `MagneticCta` | +| Sparkline | `zine-extras.jsx` → `Sparkline` | +| Count-up numbers | `zine-extras.jsx` → `CountUp` | +| Cursor spotlight on home hero | `zine-shell.jsx` → `Spotlight` | +| Hover stripes on rows | `zine-shell.jsx` → `HoverStripe` | +| Footer marquee, pause on hover | `zine-shell.jsx` → `FooterMarquee` | +| Live UTC clock | `zine-shell.jsx` → `useUtcClock` | +| Film grain overlay | `.ss-grain` class on `` | +| Page transitions | 200ms opacity + 4px translate on `
` swap | + +## Things to drop from the prototype + +- React + Babel — the prototype runs these in-browser for speed. Production is vanilla. +- The `ZineShell` state-machine routing — real URLs only. +- The hard-coded `DATA_HOME` / `DATA_RELEASES` / `DATA_WIRE` / `DATA_LIST` / `DATA_SOURCES` constants — read from the shared source layer. +- `Spotlight`'s mousemove handler attached to a ref — port as a one-line event listener on the home hero element. + +## Things to confirm with Kol before shipping + +See `DESIGN.md` § 7 "Open questions for Kol". + +In particular: + +- **Domain** for the wordmark. +- **List page ranking** — manual `rank` field in `tools-source.json` is the assumption. +- **Sources schema** — make a draft `content/stackscout/sources-source.json` based on the Sources page and let Kol fill it. + +## Acceptance checklist + +- [ ] 6 pages render from source manifests, no hard-coded content in templates. +- [ ] 5 palette moods work, persist across reloads. +- [ ] Filter pills filter (query string + DOM update). +- [ ] Calendar view of Releases works. +- [ ] Sources page renders Primary / Secondary / Aggregators with method explainer. +- [ ] All animations from the table above are intact. +- [ ] No 2px borders, no boxed cards (hairlines only). +- [ ] Every Wire and Release item shows a primary source. +- [ ] No fake decimal scores; verdict labels only. +- [ ] No "Issue 026" or "field log for the AI stack" in the masthead — these were design-round artefacts. +- [ ] Wordmark reads "Stack Scout" (two words), not "StackScout". +- [ ] Lighthouse desktop ≥ 95 perf, ≥ 95 a11y. +- [ ] Service worker + PWA install still works (already in `pwa.js`, `service-worker.js`). diff --git a/DESIGN-2026-05-zine.md b/DESIGN-2026-05-zine.md new file mode 100644 index 0000000..934c166 --- /dev/null +++ b/DESIGN-2026-05-zine.md @@ -0,0 +1,224 @@ +# Stack Scout — Design specification + +**Status:** Round 03 — page-by-page prototype, ready for Claude Code build +**Owner:** Kol +**Designer pass:** Claude (Anthropic) +**Last updated:** 19 May 2026 + +The prototype that this document describes lives at `StackScout Prototype.html` with all components under `wireframes/`. The existing `stackscout/` codebase (vanilla HTML + `styles.css` + `app.js` driven by JSON manifests) is the production target — this design replaces the chrome and IA of that codebase but keeps the shared source layer underneath. + +--- + +## 1. Identity + +| | | +|---|---| +| **Name** | Stack Scout (two words, not "StackScout") | +| **Tagline** | _A field log for the AI stack._ (Used sparingly — not in every header.) | +| **Tone** | Editorial · independent · used-not-listed · sharp without being shouty | +| **Mood** | Dark editorial. Closer to a printed broadsheet at night than a SaaS dashboard. | +| **What it is not** | A directory · an aggregator · "Product Hunt for AI" · ad-funded | + +The page identifies the site to the reader with the wordmark + accent dot in the masthead. No issue numbers in the masthead (these belonged to a previous round and have been removed). The tagline appears only on the Subscribe and Sources pages where it earns its place. + +--- + +## 2. Information architecture + +Top-level navigation, left to right in the masthead: + +| Slug | Label | What it is | +|---|---|---| +| `home` | Home | Front page — cycling lead news, the day's wire, the setlist of upcoming releases, the weekly stance. | +| `releases` | Releases | Every shipping date being tracked. Toggles between **List** view (grouped by window) and **Calendar** view (3-month strip). Filter rail at the top. | +| `wire` | Wire | 48-hour activity stream from primary sources. Filter rail at the top. | +| `list` | Top tools | A short, opinionated ranked list. Curated, not algorithmic. Filtered by editorial verdict. | +| `subscribe` | Subscribe | Email signup + past-issue archive. | + +Footer-only entry point (not in the top nav): + +| `sources` | Sources & method | Where the data comes from + what "Verified / Window / Confirmed / Shipped" mean. | + +### Page-shape contract (non-home pages) + +Every non-home page begins with: + +1. `"]} rightSlot={…}>` — a narrow strip with a breadcrumb on the left and a stat/clock/view-toggle on the right. +2. A 22px-padded filter rail (where relevant). +3. A hairline ``. +4. The content list. + +**Non-home pages do not get a hero block.** The breadcrumb + filter rail is the chrome; the data is the content. (This was a Round 02 mistake — the hero box on Releases and Wire wasted vertical space.) + +--- + +## 3. Visual system + +### 3.1 Palette + +Five **mood** palettes, swap-able from the toolbar in the masthead top-right. The toggle changes only `background` and `accent`. Everything else is fixed across moods so nothing flickers on swap. + +| ID | Name | Background | Accent | Use | +|---|---|---|---|---| +| `graphite` | Graphite | `#14171c` | `#6dbab1` | **Default.** Warm charcoal + dusty teal. | +| `midnight` | Midnight | `#0f1622` | `#7fb8d2` | Cool blue-black + steel. | +| `obsidian` | Obsidian | `#0a0c0f` | `#6dd5b8` | Near-black + mint. Darkest option. | +| `slate` | Slate | `#1a1d22` | `#8ec2a8` | Warm grey + sage. | +| `carbon` | Carbon | `#181b22` | `#88bdd1` | Deep blue-grey + powder blue. | + +Fixed across all moods: + +```css +--ink: #ede5d3; /* cream body text */ +--muted: #7d8086; /* metadata, captions */ +--rule: rgba(237,229,211,0.18); /* dashed hairlines */ +--rule-strong: rgba(237,229,211,0.45); /* solid hairlines, primary divisions */ +``` + +The accent is reserved for: hero verb (e.g. _without the wobble_), active nav underline, active filter pill, hover stripes, sparkline bars, the subscribe button, list-page rank numbers, calendar release dots, the live-pulse dot, and `::selection`. Nothing else. + +### 3.2 Type + +| Role | Family | Notes | +|---|---|---| +| Display + body | **Newsreader** | Variable, italic supported. Used for everything that reads like prose. | +| Captions / labels / nav / marquee / mono | **IBM Plex Mono** | All caps, ~0.16–0.22em letter-spacing. The other voice of the site. | + +There is no third font. Headings are weight 500–700, italic when emphatic. Body sizes scale from 14px (Lede small) to 96px (page hero). Bigger heroes use Newsreader Italic for the highlighted verb only. + +### 3.3 Structure + +- **No boxed containers.** Sections divide on whitespace + hairline rules. +- **No coloured cards.** No drop shadows. +- **One accent per page.** Everything else stays in the cream/muted scale. +- **Sources visible.** Every release and wire item must show its primary source. +- **No fake decimal scores.** Verdicts are editorial labels: _Recommended · Worth watching · Specialist pick · Shipped_. +- **Filter pills, not chiclets.** Round 999, 1px border, accent fill at 10% opacity when active. + +--- + +## 4. Interactions & motion + +Every animation lives in `wireframes/zine-shell.jsx` (` + + + + +
+ + +
+ + +
+ Mood ▾ +
+ + + + + +
+
+
+
+ +
+ + +
+ + +
+
+ + +
+

Lead · cycling

+

 

+

 

+
+
+ + +
+ +
+ + +
+ Also today ▾ +
+ OpenAI ships smaller-model price drop across the API tier. + OpenAI release notes · 14:20 UTC +
+
+ Cursor 2.5 changelog confirms multi-window edit reviews in stable. + Cursor changelog · 12:08 UTC +
+
+ Suno v5.5 lifts the loop-token cap; longer-form clips now in beta. + Suno blog · 09:47 UTC +
+
+ +
+ + +
+
+

Setlist · next ninety days

+ All releases → +
+
+
+ +
+ + +
+
+

+ + Wire · last 48 hours +

+ All wire → +
+
+
+ + +
+

+ This week we are with small models that ship
+ and against roadmap theatre. +

+ +
+
+ + +
+
+ Stack Scout / Releases +
+ 0Tracked + 0Confirmed + 0This week +
+
+
+
+ + + + + + + + + +
+
+

+ Phase 2 of the build wires this page to content/stackscout/tools-source.json. + List view groups by release window; calendar view is a 3-month strip. See KOL-540 (TBC) for the plumbing ticket. +

+
+ + +
+
+ Stack Scout / Wire +
+ 0Items 48h + 0Indexed + 0Sources +
+
+
+

+ Phase 2 wires this page to content/stackscout/updates-source.json with query-string filters. +

+
+ + +
+
+ Stack Scout / Top tools + Curated, not algorithmic. +
+
+

+ Phase 2 reads the manual rank field in tools-source.json. + Filter rail: All / Recommended / Worth watching / Specialist pick. +

+
+ + +
+
+ Stack Scout / Subscribe + A field log for the AI stack. +
+
+

+ Phase 2 wires the email form to the chosen subscribe endpoint and renders the past-issue archive + from updates-source.json grouped by week. +

+
+
+ +
+ + + + +
+ Stack Scout · independent · est. 2026 +
+ + + Live · --:-- UTC + + +
+
+ + + + + From f353f8ac5d06de027a5a161ad894392e46a4a546 Mon Sep 17 00:00:00 2001 From: Kol Tregaskes Date: Tue, 19 May 2026 23:55:45 +0100 Subject: [PATCH 2/4] feat: rename Stack Scout -> Stack Gazette, refresh logo mark MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit stackscout.com is owned by an active server-monitoring company and stack-scout.com (the dashed alternative) is not Kol's preference. DNS check across 30 stack___.com candidates returned NXDOMAIN cleanly for stackgazette.com, which also matches the broadsheet/editorial mood already specified in DESIGN.md sec 1. Changes (prototype only — live site, repo slug, content/, scripts/ all untouched; see prototype/README.md for the cutover open items): - Wordmark: "Stack Scout" -> "Stack Gazette" - Logo mark: 10px accent square + glow ring -> three stacked horizontal bars (narrowest top, full-width middle, medium bottom) in the accent colour. Inline SVG, scales cleanly. - Hover: second word now swaps to accent colour - Title, meta description, canonical, theme-color updated - Crumbs across all stub pages updated - localStorage key renamed (stackscout.mood.v1 -> stackgazette.mood.v1) - Footer wordmark updated Co-Authored-By: Claude Opus 4.7 --- prototype/README.md | 40 ++++++++++++++++++++++---- prototype/index.html | 67 +++++++++++++++++++++++++++++--------------- 2 files changed, 78 insertions(+), 29 deletions(-) diff --git a/prototype/README.md b/prototype/README.md index a04b6e9..3d61cb3 100644 --- a/prototype/README.md +++ b/prototype/README.md @@ -1,13 +1,13 @@ -# Stack Scout prototype +# Stack Gazette prototype -A self-contained vanilla port of `StackScout Prototype.html` from the May 2026 design pack. +A self-contained vanilla port of `StackScout Prototype.html` from the May 2026 design pack, renamed from "Stack Scout" → **Stack Gazette** because `stackscout.com` is owned by an active server-monitoring company. ## What this is A single-file static prototype demonstrating Phase 1 of [CLAUDE-HANDOFF-2026-05-zine.md](../CLAUDE-HANDOFF-2026-05-zine.md): - 5-mood palette toggle (graphite / midnight / obsidian / slate / carbon) with `localStorage` persistence -- Masthead with "Stack Scout" wordmark + accent dot (no issue number, no tagline) +- Masthead with "Stack Gazette" wordmark + three-bar stack mark (no issue number, no tagline in chrome) - Footer marquee + live UTC clock - Film grain overlay - Reveal / cycling-lead / sparkline / hover-stripe / magnetic-CTA / cursor-spotlight animations @@ -33,11 +33,29 @@ python -m http.server 4173 ## Source design pack -Staged at `W:\Websites\LOCAL-ONLY\stackscout\design-2026-05-19\` (private). The `DESIGN-2026-05-zine.md` and `CLAUDE-HANDOFF-2026-05-zine.md` files at the repo root are copies of the design pack's authoritative spec and build plan. +Staged at `W:\Websites\LOCAL-ONLY\stackscout\design-2026-05-19\` (private). The `DESIGN-2026-05-zine.md` and `CLAUDE-HANDOFF-2026-05-zine.md` files at the repo root are copies of the design pack's authoritative spec and build plan, kept under the original "Stack Scout" name as a historical record of the round 03 design. ## Domain -Recommendation: `stack-scout.com` (matches the two-word brand from DESIGN.md § 1; `stackscout.com` is already taken by a server-monitoring company). Update CNAME + canonical when confirmed. +**Recommended: `stackgazette.com`** — DNS check returned NXDOMAIN (the strongest signal that a .com is genuinely available rather than parked or owned). + +Why renamed from Stack Scout: + +- `stackscout.com` resolves to a Vercel-hosted server-monitoring product (in active use, not buyable) +- `stack-scout.com` was the dash-free alternative, but Kol's preference is no dashes +- User wanted a `stack___.com` that exists; "Gazette" matches the broadsheet/editorial mood already in DESIGN.md § 1 ("printed broadsheet at night") + +Other clean alternatives that came back NXDOMAIN if `gazette` doesn't land: `stackbulletin.com`, `stackpulse.com`, `stackdrop.com`. Avoid `stacklog.com`, `stackdaily.com`, `stackedge.com`, `stacktake.com` — all parked on Sedo (priced to extort). + +## Logo refresh + +The original wordmark was `[10px accent square] Stack Scout`. Refreshed to: + +- Three horizontal bars stacked, narrowest on top, full-width middle, medium bottom — literal "stack" mark in the accent colour +- Glow ring removed (the old `box-shadow` halo on the square is gone) +- Hover state: the second word ("Gazette") swaps to accent colour + +The mark scales cleanly because it's inline SVG. Light edit if you want a different stack shape — `.brand__mark svg rect` in the CSS. ## Phase 2-4 — outstanding @@ -47,4 +65,14 @@ Per the handoff doc, the remaining work is: - **Phase 3:** Filter pills read from query string and update DOM. - **Phase 4:** Real data hookup (Kol). -To be tracked in Linear as children of the Stack Scout launch parent. +To be tracked in Linear as children of the Stack Gazette launch parent (or KOL-533 if you want it under the same umbrella). + +## Naming-rename open items + +The repo itself is still `stackscout` (folder, GitHub repo, content/stackscout/, scripts/build-stackscout.js, manifests). Phase 2 should decide: + +- Rename the repo on GitHub: `koltregaskes/stackscout` → `koltregaskes/stack-gazette` (or keep the slug for repo continuity and only rename the public brand) +- Rename the content folder `content/stackscout/` → `content/stack-gazette/` and update the build script +- Update the legacy `DESIGN.md`, `SCOPE.md`, and `README.md` at the repo root with the new brand + +None of these affect the prototype — they're separate cutover work. Recommended: keep the repo slug as `stackscout` for git history, change only the visible brand. Cheap, low-risk. diff --git a/prototype/index.html b/prototype/index.html index 74bda8a..7944fd1 100644 --- a/prototype/index.html +++ b/prototype/index.html @@ -3,11 +3,11 @@ - Stack Scout — A field log for the AI stack - + Stack Gazette — A field log for the AI stack + - - + + /* ────────────────────────────────────────────────────────────────────── - Stack Scout · Zine prototype (vanilla port of StackScout Prototype.html) + Stack Gazette · Zine prototype (vanilla port of StackScout Prototype.html) Phase 1 of CLAUDE-HANDOFF-2026-05-zine.md Source design: DESIGN-2026-05-zine.md + Wordmark renamed from "Stack Scout" → "Stack Gazette" (stackscout.com + was taken; stackgazette.com matches the broadsheet mood in DESIGN.md § 1). + Logo refreshed: replaced the single accent square with three stacked + horizontal bars (literal "stack" mark, no glow ring). ────────────────────────────────────────────────────────────────────── */ /* Fixed cream/muted scale — never changes between moods */ @@ -152,17 +156,21 @@ padding: 0; cursor: pointer; display: inline-flex; - align-items: baseline; - gap: 12px; + align-items: center; + gap: 14px; } - .brand__dot { + /* Logo mark — three stacked horizontal bars, accent colour. + Reads as "stack" literally; sits flush with the wordmark baseline. */ + .brand__mark { display: inline-block; - width: 10px; height: 10px; - background: var(--accent); - border-radius: 2px; - box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 13%, transparent); - transform: translateY(-1px); - transition: background 400ms ease, box-shadow 400ms ease; + width: 18px; + height: 16px; + flex-shrink: 0; + transform: translateY(2px); + } + .brand__mark rect { + fill: var(--accent); + transition: fill 400ms ease; } .brand__word { font-family: 'Newsreader', serif; @@ -172,6 +180,14 @@ line-height: 1; color: var(--ink); } + /* Optional italic accent on the second word, used on hover */ + .brand:hover .brand__word-second { + color: var(--accent); + transition: color 240ms ease; + } + .brand__word-second { + transition: color 240ms ease; + } .nav-and-mood { display: inline-flex; align-items: center; gap: 28px; } .nav { display: inline-flex; gap: 22px; } .nav__btn { @@ -660,9 +676,14 @@
-
@@ -769,7 +790,7 @@

- Stack Scout / Releases + Stack Gazette / Releases
0Tracked 0Confirmed @@ -798,7 +819,7 @@

- Stack Scout / Wire + Stack Gazette / Wire
0Items 48h 0Indexed @@ -814,7 +835,7 @@

- Stack Scout / Top tools + Stack Gazette / Top tools Curated, not algorithmic.
@@ -827,7 +848,7 @@

- Stack Scout / Subscribe + Stack Gazette / Subscribe A field log for the AI stack.
@@ -848,7 +869,7 @@

- Stack Scout · independent · est. 2026 + Stack Gazette · independent · est. 2026
@@ -869,7 +890,7 @@

// ── Mood persistence ──────────────────────────────────────────── var MOODS = ['graphite', 'midnight', 'obsidian', 'slate', 'carbon']; - var STORAGE_KEY = 'stackscout.mood.v1'; + var STORAGE_KEY = 'stackgazette.mood.v1'; function setMood(id) { if (MOODS.indexOf(id) === -1) id = 'graphite'; From c80cdfb5a20d3a62bcd6543b1a75323b44b57753 Mon Sep 17 00:00:00 2001 From: Kol Tregaskes Date: Tue, 26 May 2026 00:21:30 +0100 Subject: [PATCH 3/4] chore(repo): keep design handoffs local-only --- .gitignore | 2 + CLAUDE-HANDOFF-2026-05-zine.md | 108 --------------------------------- 2 files changed, 2 insertions(+), 108 deletions(-) delete mode 100644 CLAUDE-HANDOFF-2026-05-zine.md diff --git a/.gitignore b/.gitignore index 4bfa471..39ac5e7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,12 @@ # Local planning and working notes .local/ local-hub/ +design/ PLAN.md TODO.local.md TASKS.local.md *.local.md +CLAUDE-HANDOFF-*.md notes-local/ planning-local/ .local-notes/ diff --git a/CLAUDE-HANDOFF-2026-05-zine.md b/CLAUDE-HANDOFF-2026-05-zine.md deleted file mode 100644 index feefe0e..0000000 --- a/CLAUDE-HANDOFF-2026-05-zine.md +++ /dev/null @@ -1,108 +0,0 @@ -# Stack Scout — Handoff to Claude Code - -This pack is for Claude Code to build the production site from. Read `DESIGN.md` first for the design spec; this file covers _how to ship it_. - -## What this is - -A complete, working HTML prototype at `StackScout Prototype.html` plus the design system in `DESIGN.md`. The prototype is build-with-Babel-in-browser React for iteration speed; production must be vanilla HTML/CSS + a thin JS layer, matching the existing `stackscout/` codebase pattern. - -## What you're replacing - -The existing `stackscout/` repo: -- builds a public site from `content/stackscout/site-source.json` + `tools-source.json` + `updates-source.json` -- via `scripts/build-stackscout.js` → static HTML in `index.html`, `catalog/`, `categories/`, etc. -- with `styles.css` + `app.js` providing the chrome -- targeting GitHub Pages - -Keep the shared source layer. Replace the chrome + page templates + IA with the design from this prototype. - -## Build order - -### Phase 1 · Shell + palette (~half day) - -1. Port `wireframes/zine-shell.jsx`'s palette + animation system to vanilla CSS custom properties + a tiny JS module. - - 5 palette presets are five CSS custom-property classes (`.mood-graphite`, `.mood-midnight`, etc.) on ``. - - Mood swap = swap class on ``. Persist to `localStorage`. Read on `DOMContentLoaded`. - - Pull `--ink`, `--muted`, `--rule`, `--rule-strong` to `:root`. Mood classes only set `--bg` and `--accent`. -2. Masthead: wordmark + dot + nav + mood toggle. No issue number, no tagline. Active page state via `data-page` attribute on ``. -3. Footer: live UTC clock chip + "Sources & method →" link to `/sources/`. Marquee with the 6 manifesto lines, CSS-only. -4. Page-header strip: breadcrumb on the left, configurable right slot. Becomes a partial in your template engine. -5. CSS keyframes: `ss-reveal-in`, `ss-rule-in`, `ss-pulse`, `ss-marquee-scroll`, `ss-text-cycle-in`, `ss-spark-rise`. All five live in one stylesheet block. - -### Phase 2 · Pages from source manifests (~1–2 days) - -Build templates for the 6 pages. Each page reads from the source layer and renders the markup the prototype shows. - -| Page | Source | Template should do | -|---|---|---| -| `index.html` (home) | `updates-source.json` (latest 4), `tools-source.json` (5 setlist + 5 list) | Cycling lead uses 4 most recent wire items. Setlist = next-90-days releases. Wire = last 48h. | -| `releases/index.html` | `tools-source.json` | Group by `releaseWindow` (week / month / quarter). Calendar view is a separate URL param or `#calendar` hash. | -| `wire/index.html` | `updates-source.json` | Paginated. Filter via query string (`?kind=funding`). | -| `list/index.html` | `tools-source.json` | Ranked list. Manual rank field; default order if missing. | -| `subscribe/index.html` | static + archive from `updates-source.json` grouped by week | Form posts to whatever subscribe endpoint Kol picks. | -| `sources/index.html` | new `sources-source.json` (Claude Code creates the schema) | Grouped Primary / Secondary / Aggregators + method explainer. | - -### Phase 3 · Filters and tags (~half day) - -The filter pills in the prototype are visual-only. Make them work. - -1. Reads from query string on load. -2. Updates query string + filters DOM on click (no router needed). -3. Tag chips on tool cards / wire items are anchor tags to the filtered URL. - -### Phase 4 · Real data hookup (Kol) - -The prototype uses placeholder data with intentionally fixed dates. Replace with: - -- `tools-source.json` entries — Claude 4.5, Cursor 2.5, GPT-5.5, Suno v5.5, Gemini 3.1 Pro/Flash, etc. -- `updates-source.json` — wire items from official changelogs only. -- `sources-source.json` — new file; see Sources page in prototype for shape. - -## Things to preserve from the prototype - -| Interaction | Where in prototype | -|---|---| -| Mood toggle (5 swatches) | `zine-shell.jsx` → `ColorToggle` | -| Cycling lead (4 headlines, blur-fade, hover-pause, click-to-jump dots) | `zine-extras.jsx` → `CyclingLead` | -| Magnetic CTA | `zine-extras.jsx` → `MagneticCta` | -| Sparkline | `zine-extras.jsx` → `Sparkline` | -| Count-up numbers | `zine-extras.jsx` → `CountUp` | -| Cursor spotlight on home hero | `zine-shell.jsx` → `Spotlight` | -| Hover stripes on rows | `zine-shell.jsx` → `HoverStripe` | -| Footer marquee, pause on hover | `zine-shell.jsx` → `FooterMarquee` | -| Live UTC clock | `zine-shell.jsx` → `useUtcClock` | -| Film grain overlay | `.ss-grain` class on `` | -| Page transitions | 200ms opacity + 4px translate on `
` swap | - -## Things to drop from the prototype - -- React + Babel — the prototype runs these in-browser for speed. Production is vanilla. -- The `ZineShell` state-machine routing — real URLs only. -- The hard-coded `DATA_HOME` / `DATA_RELEASES` / `DATA_WIRE` / `DATA_LIST` / `DATA_SOURCES` constants — read from the shared source layer. -- `Spotlight`'s mousemove handler attached to a ref — port as a one-line event listener on the home hero element. - -## Things to confirm with Kol before shipping - -See `DESIGN.md` § 7 "Open questions for Kol". - -In particular: - -- **Domain** for the wordmark. -- **List page ranking** — manual `rank` field in `tools-source.json` is the assumption. -- **Sources schema** — make a draft `content/stackscout/sources-source.json` based on the Sources page and let Kol fill it. - -## Acceptance checklist - -- [ ] 6 pages render from source manifests, no hard-coded content in templates. -- [ ] 5 palette moods work, persist across reloads. -- [ ] Filter pills filter (query string + DOM update). -- [ ] Calendar view of Releases works. -- [ ] Sources page renders Primary / Secondary / Aggregators with method explainer. -- [ ] All animations from the table above are intact. -- [ ] No 2px borders, no boxed cards (hairlines only). -- [ ] Every Wire and Release item shows a primary source. -- [ ] No fake decimal scores; verdict labels only. -- [ ] No "Issue 026" or "field log for the AI stack" in the masthead — these were design-round artefacts. -- [ ] Wordmark reads "Stack Scout" (two words), not "StackScout". -- [ ] Lighthouse desktop ≥ 95 perf, ≥ 95 a11y. -- [ ] Service worker + PWA install still works (already in `pwa.js`, `service-worker.js`). From 5df588aaa39fba7f647bf2be97dd84a7861d8385 Mon Sep 17 00:00:00 2001 From: Kol Tregaskes Date: Thu, 4 Jun 2026 05:22:37 +0100 Subject: [PATCH 4/4] fix: harden StackScout launch validation --- .env.example | 4 + .github/workflows/validate.yml | 22 +++ .gitignore | 2 + README.md | 22 ++- catalog/index.html | 4 +- categories/apis/index.html | 4 +- categories/clis/index.html | 4 +- categories/desktop-apps/index.html | 4 +- categories/index.html | 4 +- categories/mcps/index.html | 4 +- categories/web-apps/index.html | 4 +- categories/web-services/index.html | 4 +- categories/websites/index.html | 4 +- collections/index.html | 4 +- data/categories-manifest.json | 4 +- data/collections-manifest.json | 4 +- data/methodology-manifest.json | 4 +- data/page-registry.json | 2 +- data/radar-manifest.json | 4 +- data/tools-manifest.json | 4 +- data/updates-manifest.json | 4 +- index.html | 4 +- method/index.html | 4 +- package.json | 3 +- radar/index.html | 4 +- scripts/build-stackscout.js | 27 ++-- scripts/refresh-stackscout.ps1 | 38 +++--- scripts/verify-launch-safety.js | 208 +++++++++++++++++++++++++++++ service-worker.js | 2 +- tools/anthropic-api/index.html | 4 +- tools/canvas-planner/index.html | 4 +- tools/gh-cli/index.html | 4 +- tools/github-mcp-server/index.html | 4 +- tools/hugging-face/index.html | 4 +- tools/make/index.html | 4 +- tools/n8n/index.html | 4 +- tools/openai-api/index.html | 4 +- tools/perplexity/index.html | 4 +- tools/playwright-mcp/index.html | 4 +- tools/signal-stack/index.html | 4 +- tools/strudel-studio/index.html | 4 +- tools/syncpad/index.html | 4 +- tools/wrangler/index.html | 4 +- updates/index.html | 4 +- 44 files changed, 357 insertions(+), 109 deletions(-) create mode 100644 .env.example create mode 100644 .github/workflows/validate.yml create mode 100644 scripts/verify-launch-safety.js diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..419d8e3 --- /dev/null +++ b/.env.example @@ -0,0 +1,4 @@ +# Optional local-only export targets. +# Leave unset in public CI and ordinary GitHub Pages builds. +STACKSCOUT_PRIVATE_EXPORT_DIR= +STACKSCOUT_PRIVATE_STATUS_DIR= diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..27d4ace --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,22 @@ +name: Validate + +on: + pull_request: + push: + branches: + - main + - design/zine-prototype-2026-05 + workflow_dispatch: + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: '20' + + - run: npm run build:site + - run: npm run check diff --git a/.gitignore b/.gitignore index 39ac5e7..7cc533a 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,8 @@ planning-local/ .local-notes/ # Local screenshots and scratch files +.serve.log +.serve.err.log tmp-*.png tmp-*.jpg tmp-*.jpeg diff --git a/README.md b/README.md index 4fd00e8..db7fdc6 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,12 @@ `tools-hub` builds **StackScout**, the public-facing tools destination for curated builder tools, services, APIs, MCPs, and CLIs. -This repo remains the GitHub Pages implementation base, but the visible product is no longer a simple internal "Tools Hub" brochure. The private operational console stays separate in `W:\Repos\_local\surfaces\tools-hub-local`. +This repo remains the GitHub Pages implementation base, but the visible product is no longer a simple internal "Tools Hub" brochure. The private operational console stays outside this public repo. ## Public vs private - This repo is public-facing only. -- The local launcher, manager inbox, review evidence, session state, and leak-check operations belong in `tools-hub-local`. +- Local launchers, operations state, and review artefacts belong in the private local surface, not this repo. - Public content must stay safe for GitHub Pages and public browsing. - Do not rely on `.gitignore` alone to protect private data. Public output is generated from an allowlisted shared source layer. @@ -23,7 +23,7 @@ These source files drive: - public manifests in `data/` - generated static pages across the public site -- a private preview export written to `W:\Repos\_local\surfaces\tools-hub-local\data\stackscout-publishing.json` +- an optional private preview export when `STACKSCOUT_PRIVATE_EXPORT_DIR` or `STACKSCOUT_PRIVATE_EXPORT_FILE` is set locally ## Build @@ -50,15 +50,27 @@ This regenerates: npm run check ``` +`npm run check` also runs the no-publish launch-safety gate: + +```bash +npm run verify:launch +``` + +That gate scans generated public output for local Windows paths and private surface markers, confirms the public file set exists, checks `.gitignore` still excludes local notes and env files, and verifies the `service-worker.js` cache name is not older than the generated issue date. + +GitHub Pages does not support custom response headers such as a Netlify `_headers` file. Keep browser hardening inside static HTML, conservative client code, and dependency-free scripts unless the site moves to a host that can set CSP/HSTS-style headers. + +Before a public refresh, bump `CACHE_NAME` in `service-worker.js` when generated public content advances. The launch-safety gate fails if the cache date is older than the visible issue date. + ## Refresh ```bash npm run refresh:site ``` -This runs the site build, runs checks, and writes private refresh status to `W:\Repos\_local\surfaces\tools-hub-local\data\stackscout-refresh-status.json`. +This runs the site build, runs checks, and optionally writes private refresh status when `STACKSCOUT_PRIVATE_STATUS_DIR` is set locally. -For unattended Windows refreshes without visible terminal focus theft, use the local-only launcher at `W:\Repos\_My Tools\LOCAL-ONLY\stackscout-refresh\run-stackscout-refresh.cmd`. +For unattended Windows refreshes without visible terminal focus theft, use a local-only launcher outside this public repo and set the optional private export/status environment variables there. ## Site structure diff --git a/catalog/index.html b/catalog/index.html index 2d9c3e8..9f58d16 100644 --- a/catalog/index.html +++ b/catalog/index.html @@ -28,7 +28,7 @@

-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -637,7 +637,7 @@

SyncPad

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/apis/index.html b/categories/apis/index.html index 4d83e54..2dfa283 100644 --- a/categories/apis/index.html +++ b/categories/apis/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

Anthropic API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/clis/index.html b/categories/clis/index.html index 883eab2..1237cc8 100644 --- a/categories/clis/index.html +++ b/categories/clis/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

Wrangler

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/desktop-apps/index.html b/categories/desktop-apps/index.html index 9c5a59d..1be2b1e 100644 --- a/categories/desktop-apps/index.html +++ b/categories/desktop-apps/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -102,7 +102,7 @@

SyncPad

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/index.html b/categories/index.html index da0411d..6154107 100644 --- a/categories/index.html +++ b/categories/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -189,7 +189,7 @@

Desktop Apps

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/mcps/index.html b/categories/mcps/index.html index fc82736..37ebb41 100644 --- a/categories/mcps/index.html +++ b/categories/mcps/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

Playwright MCP

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/web-apps/index.html b/categories/web-apps/index.html index 2487a5e..721ea41 100644 --- a/categories/web-apps/index.html +++ b/categories/web-apps/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -170,7 +170,7 @@

Strudel Studio

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/web-services/index.html b/categories/web-services/index.html index 293e073..565fdd3 100644 --- a/categories/web-services/index.html +++ b/categories/web-services/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

Make

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/categories/websites/index.html b/categories/websites/index.html index 03d642b..35f906f 100644 --- a/categories/websites/index.html +++ b/categories/websites/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

Hugging Face

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/collections/index.html b/collections/index.html index 5867289..b4e9b70 100644 --- a/collections/index.html +++ b/collections/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -136,7 +136,7 @@

From the StackScout Lab

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/data/categories-manifest.json b/data/categories-manifest.json index c95c128..8051de5 100644 --- a/data/categories-manifest.json +++ b/data/categories-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Categories", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "categories": [ { "slug": "websites", diff --git a/data/collections-manifest.json b/data/collections-manifest.json index 2b33a0a..3b39eef 100644 --- a/data/collections-manifest.json +++ b/data/collections-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Collections", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "collections": [ { "slug": "creator-stack", diff --git a/data/methodology-manifest.json b/data/methodology-manifest.json index 815185c..3f8e1b4 100644 --- a/data/methodology-manifest.json +++ b/data/methodology-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Methodology", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "thesis": "StackScout is a public guide, not a benchmark lab. We badge selectively, update from official sources where possible, and avoid pretending every fast-moving tool deserves a fixed numeric score.", "principles": [ { diff --git a/data/page-registry.json b/data/page-registry.json index c9a1b85..d52aa73 100644 --- a/data/page-registry.json +++ b/data/page-registry.json @@ -1,6 +1,6 @@ { "title": "StackScout // Page Registry", - "generatedAt": "2026-04-25", + "generatedAt": "2026-06-04", "pages": [ { "key": "home", diff --git a/data/radar-manifest.json b/data/radar-manifest.json index 9c3b710..edd7d0f 100644 --- a/data/radar-manifest.json +++ b/data/radar-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Radar", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "items": [ { "title": "Azure MCP Server", diff --git a/data/tools-manifest.json b/data/tools-manifest.json index 9d4bbc9..620bd84 100644 --- a/data/tools-manifest.json +++ b/data/tools-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Tools Manifest", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "summary": "Public-safe catalog for StackScout.", "counts": { "total": 14, diff --git a/data/updates-manifest.json b/data/updates-manifest.json index dc7a94e..c632a68 100644 --- a/data/updates-manifest.json +++ b/data/updates-manifest.json @@ -1,7 +1,7 @@ { "title": "StackScout // Updates", - "generatedAt": "2026-04-25", - "updatedAt": "2026-04-25", + "generatedAt": "2026-06-04", + "updatedAt": "2026-06-04", "summary": "Public-safe activity stream seeded from official or first-party sources.", "items": [ { diff --git a/index.html b/index.html index df3e469..754b2ac 100644 --- a/index.html +++ b/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -794,7 +794,7 @@

From the StackScout Lab

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/method/index.html b/method/index.html index bdbfcd3..ad5da0c 100644 --- a/method/index.html +++ b/method/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -162,7 +162,7 @@

Verdict language

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/package.json b/package.json index 8e4d22d..a4ef155 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "scripts": { "build:site": "node scripts/build-stackscout.js", "refresh:site": "powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/refresh-stackscout.ps1", - "check": "node --check scripts/build-stackscout.js && node --check app.js && node --check pwa.js" + "check": "node --check scripts/build-stackscout.js && node --check app.js && node --check pwa.js && node --check service-worker.js && node --check scripts/verify-launch-safety.js && node scripts/verify-launch-safety.js", + "verify:launch": "node scripts/verify-launch-safety.js" } } diff --git a/radar/index.html b/radar/index.html index 8f2697e..09f4b2c 100644 --- a/radar/index.html +++ b/radar/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -125,7 +125,7 @@

GitHub skills ecosystem

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/scripts/build-stackscout.js b/scripts/build-stackscout.js index 7019eb2..c0e604e 100644 --- a/scripts/build-stackscout.js +++ b/scripts/build-stackscout.js @@ -4,10 +4,6 @@ const path = require('path') const ROOT_DIR = path.resolve(__dirname, '..') const SOURCE_DIR = path.join(ROOT_DIR, 'content', 'stackscout') const DATA_DIR = path.join(ROOT_DIR, 'data') -const PRIVATE_PREVIEW_EXPORT_CANDIDATES = [ - 'W:\\Repos\\_local\\surfaces\\tools-hub-local\\data\\stackscout-publishing.json', - '\\\\nas_storage_1\\Workspaces\\Repos\\_local\\surfaces\\tools-hub-local\\data\\stackscout-publishing.json', -] const BUILD_NOW = new Date() const GENERATED_AT = BUILD_NOW.toISOString().slice(0, 10) const GENERATED_AT_ISO = BUILD_NOW.toISOString() @@ -54,17 +50,16 @@ function writeExternalJson(absolutePath, value) { fs.writeFileSync(absolutePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8') } -function resolveWritableExternalPath(candidates) { - for (const candidate of candidates) { - try { - ensureParent(candidate) - return candidate - } catch (error) { - continue - } +function resolvePrivatePreviewExportPath() { + if (process.env.STACKSCOUT_PRIVATE_EXPORT_FILE) { + return path.resolve(process.env.STACKSCOUT_PRIVATE_EXPORT_FILE) } - throw new Error(`Unable to resolve writable external path from candidates: ${candidates.join(', ')}`) + if (process.env.STACKSCOUT_PRIVATE_EXPORT_DIR) { + return path.join(path.resolve(process.env.STACKSCOUT_PRIVATE_EXPORT_DIR), 'stackscout-publishing.json') + } + + return null } function escapeHtml(value) { @@ -1239,7 +1234,7 @@ ${routes.map((route) => ` ${PUBLIC_BASE_URL}${route}`).jo } function main() { - const privatePreviewExport = resolveWritableExternalPath(PRIVATE_PREVIEW_EXPORT_CANDIDATES) + const privatePreviewExport = resolvePrivatePreviewExportPath() const site = readJson('site-source.json') const tools = readJson('tools-source.json') const updates = readJson('updates-source.json').sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)) @@ -1254,7 +1249,9 @@ function main() { writeJson('data/methodology-manifest.json', buildMethodologyManifest(site)) writeJson('data/collections-manifest.json', buildCollectionsManifest(collections, toolIndex)) writeJson('data/radar-manifest.json', buildRadarManifest(site.radar)) - writeExternalJson(privatePreviewExport, buildPublishingPreview(tools, updates, categories)) + if (privatePreviewExport) { + writeExternalJson(privatePreviewExport, buildPublishingPreview(tools, updates, categories)) + } writeFile('index.html', renderHome(site, tools, updates, categories, collections, 'index.html')) writeFile('catalog/index.html', renderCatalog(tools, categories, 'catalog/index.html')) diff --git a/scripts/refresh-stackscout.ps1 b/scripts/refresh-stackscout.ps1 index 2ee63e4..8765129 100644 --- a/scripts/refresh-stackscout.ps1 +++ b/scripts/refresh-stackscout.ps1 @@ -6,29 +6,24 @@ param( $ErrorActionPreference = 'Stop' $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path -$privateDataDirCandidates = @( - 'W:\Repos\_local\surfaces\tools-hub-local\data', - '\\nas_storage_1\Workspaces\Repos\_local\surfaces\tools-hub-local\data' -) $privateDataDir = $null -foreach ($candidate in $privateDataDirCandidates) { - try { - if (-not (Test-Path $candidate)) { - New-Item -ItemType Directory -Path $candidate -Force | Out-Null - } +$privateDataDirInput = if ($env:STACKSCOUT_PRIVATE_STATUS_DIR) { + $env:STACKSCOUT_PRIVATE_STATUS_DIR +} elseif ($env:STACKSCOUT_PRIVATE_EXPORT_DIR) { + $env:STACKSCOUT_PRIVATE_EXPORT_DIR +} else { + $null +} - $privateDataDir = (Resolve-Path $candidate).Path - break - } catch { - continue +if ($privateDataDirInput) { + if (-not (Test-Path $privateDataDirInput)) { + New-Item -ItemType Directory -Path $privateDataDirInput -Force | Out-Null } -} -if (-not $privateDataDir) { - throw 'Unable to resolve a writable private data directory for StackScout refresh status.' + $privateDataDir = (Resolve-Path $privateDataDirInput).Path } -$statusFile = Join-Path $privateDataDir 'stackscout-refresh-status.json' +$statusFile = if ($privateDataDir) { Join-Path $privateDataDir 'stackscout-refresh-status.json' } else { $null } $toolsManifestFile = Join-Path $repoRoot 'data\tools-manifest.json' $updatesManifestFile = Join-Path $repoRoot 'data\updates-manifest.json' $categoriesManifestFile = Join-Path $repoRoot 'data\categories-manifest.json' @@ -38,10 +33,13 @@ $durationStopwatch = [System.Diagnostics.Stopwatch]::StartNew() function Read-JsonFile { param( - [Parameter(Mandatory = $true)] [string]$Path ) + if (-not $Path) { + return $null + } + if (-not (Test-Path $Path)) { return $null } @@ -82,6 +80,10 @@ function Write-RefreshStatus { $payload[$entry.Key] = $entry.Value } + if (-not $statusFile) { + return + } + $directory = Split-Path -Parent $statusFile if (-not (Test-Path $directory)) { New-Item -ItemType Directory -Path $directory -Force | Out-Null diff --git a/scripts/verify-launch-safety.js b/scripts/verify-launch-safety.js new file mode 100644 index 0000000..505473f --- /dev/null +++ b/scripts/verify-launch-safety.js @@ -0,0 +1,208 @@ +const fs = require('fs') +const path = require('path') + +const ROOT_DIR = path.resolve(__dirname, '..') +const PUBLIC_ENTRIES = [ + 'index.html', + 'catalog', + 'categories', + 'collections', + 'data', + 'method', + 'radar', + 'tools', + 'updates', + 'app.js', + 'pwa.js', + 'service-worker.js', + 'manifest.json', + 'styles.css', + 'sitemap.xml', + 'icon.svg', +] +const REQUIRED_PUBLIC_FILES = [ + 'index.html', + 'catalog/index.html', + 'categories/index.html', + 'collections/index.html', + 'data/page-registry.json', + 'data/tools-manifest.json', + 'data/updates-manifest.json', + 'data/categories-manifest.json', + 'data/methodology-manifest.json', + 'data/collections-manifest.json', + 'data/radar-manifest.json', + 'method/index.html', + 'radar/index.html', + 'updates/index.html', + 'app.js', + 'pwa.js', + 'service-worker.js', + 'manifest.json', + 'styles.css', + 'sitemap.xml', + 'icon.svg', +] +const TEXT_EXTENSIONS = new Set(['.css', '.html', '.js', '.json', '.svg', '.txt', '.xml']) +const PRIVATE_PATTERNS = [ + { label: 'Windows drive path', pattern: /\b[A-Z]:[\\/][^\s"'<>)]*/i }, + { label: 'UNC path', pattern: /\\\\[A-Za-z0-9._-]+[\\/][^\s"'<>)]*/i }, + { label: 'local-only surface marker', pattern: /\b(?:tools-hub-local|LOCAL-ONLY|_local)\b/i }, + { label: 'private operations wording', pattern: /\b(?:manager inbox|review evidence|session state)\b/i }, +] +const REQUIRED_GITIGNORE_PATTERNS = ['.env', '.env.*', '*.local.md', '.local/', 'local-hub/'] +const REQUIRED_APP_SHELL_ENTRIES = [ + '', + 'index.html', + 'catalog/', + 'categories/', + 'updates/', + 'radar/', + 'collections/', + 'method/', + 'styles.css', + 'app.js', + 'pwa.js', + 'manifest.json', + 'icon.svg', + 'data/page-registry.json', + 'data/tools-manifest.json', + 'data/updates-manifest.json', + 'data/categories-manifest.json', + 'data/methodology-manifest.json', + 'data/collections-manifest.json', + 'data/radar-manifest.json', +] + +function readText(relativePath) { + return fs.readFileSync(path.join(ROOT_DIR, relativePath), 'utf8') +} + +function exists(relativePath) { + return fs.existsSync(path.join(ROOT_DIR, relativePath)) +} + +function walk(relativePath) { + const absolutePath = path.join(ROOT_DIR, relativePath) + if (!fs.existsSync(absolutePath)) { + return [] + } + + const stat = fs.statSync(absolutePath) + if (stat.isDirectory()) { + return fs.readdirSync(absolutePath).flatMap((entry) => walk(path.join(relativePath, entry))) + } + + return [relativePath] +} + +function collectPublicTextFiles() { + return PUBLIC_ENTRIES.flatMap(walk).filter((file) => TEXT_EXTENSIONS.has(path.extname(file).toLowerCase())) +} + +function extractIssueDate() { + const indexHtml = readText('index.html') + const issueMatch = indexHtml.match(/Issue (\d{4}-\d{2}-\d{2})/) + if (!issueMatch) { + throw new Error('index.html does not contain a generated issue date.') + } + + return issueMatch[1] +} + +function extractCacheName() { + const serviceWorker = readText('service-worker.js') + const cacheMatch = serviceWorker.match(/const CACHE_NAME = ['"]([^'"]+)['"]/) + if (!cacheMatch) { + throw new Error('service-worker.js does not declare CACHE_NAME.') + } + + return cacheMatch[1] +} + +function assertNoPrivateLeaks(files) { + const leaks = [] + + for (const file of files) { + const text = readText(file) + for (const { label, pattern } of PRIVATE_PATTERNS) { + if (pattern.test(text)) { + leaks.push(`${file}: ${label}`) + } + } + } + + if (leaks.length) { + throw new Error(`Public output contains private/local markers:\n${leaks.join('\n')}`) + } +} + +function assertRequiredFiles() { + const missing = REQUIRED_PUBLIC_FILES.filter((file) => !exists(file)) + if (missing.length) { + throw new Error(`Missing required public files:\n${missing.join('\n')}`) + } +} + +function assertServiceWorkerFreshness() { + const serviceWorker = readText('service-worker.js') + const cacheName = extractCacheName() + const cacheDateMatch = cacheName.match(/^stackscout-(\d{4}-\d{2}-\d{2})$/) + if (!cacheDateMatch) { + throw new Error(`CACHE_NAME must use stackscout-YYYY-MM-DD format; found ${cacheName}.`) + } + + const issueDate = extractIssueDate() + const cacheDate = cacheDateMatch[1] + if (cacheDate < issueDate) { + throw new Error(`CACHE_NAME ${cacheName} is older than generated issue date ${issueDate}. Bump service-worker.js before refresh.`) + } + + const missingShellEntries = REQUIRED_APP_SHELL_ENTRIES.filter((entry) => !serviceWorker.includes(`'${entry}'`)) + if (missingShellEntries.length) { + throw new Error(`service-worker.js is missing app-shell entries:\n${missingShellEntries.join('\n')}`) + } + + return { cacheName, issueDate } +} + +function assertGitignoreKeepsPrivateNotesOut() { + const gitignore = readText('.gitignore') + const missing = REQUIRED_GITIGNORE_PATTERNS.filter((entry) => !gitignore.includes(entry)) + if (missing.length) { + throw new Error(`.gitignore is missing private/local exclusions:\n${missing.join('\n')}`) + } +} + +function assertReadmeDocumentsLaunchGate() { + const readme = readText('README.md') + const requiredPhrases = [ + 'npm run verify:launch', + 'GitHub Pages does not support custom response headers', + 'service-worker.js', + ] + const missing = requiredPhrases.filter((phrase) => !readme.includes(phrase)) + if (missing.length) { + throw new Error(`README.md is missing launch-safety guidance:\n${missing.join('\n')}`) + } +} + +function main() { + assertRequiredFiles() + const publicFiles = collectPublicTextFiles() + assertNoPrivateLeaks(publicFiles) + const freshness = assertServiceWorkerFreshness() + assertGitignoreKeepsPrivateNotesOut() + assertReadmeDocumentsLaunchGate() + + console.log( + `StackScout launch safety passed: ${publicFiles.length} public files scanned, CACHE_NAME=${freshness.cacheName}, issue=${freshness.issueDate}.`, + ) +} + +try { + main() +} catch (error) { + console.error(`StackScout launch safety failed: ${error.message}`) + process.exit(1) +} diff --git a/service-worker.js b/service-worker.js index b4064f1..9ff0fb2 100644 --- a/service-worker.js +++ b/service-worker.js @@ -1,4 +1,4 @@ -const CACHE_NAME = 'stackscout-v1' +const CACHE_NAME = 'stackscout-2026-06-04' const APP_SHELL = [ '', 'index.html', diff --git a/tools/anthropic-api/index.html b/tools/anthropic-api/index.html index 04c0cb6..6c325c3 100644 --- a/tools/anthropic-api/index.html +++ b/tools/anthropic-api/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

n8n

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/canvas-planner/index.html b/tools/canvas-planner/index.html index 55a6ab8..ae35bd4 100644 --- a/tools/canvas-planner/index.html +++ b/tools/canvas-planner/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -238,7 +238,7 @@

SyncPad

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/gh-cli/index.html b/tools/gh-cli/index.html index aaa32b4..5c1cfd6 100644 --- a/tools/gh-cli/index.html +++ b/tools/gh-cli/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -238,7 +238,7 @@

Wrangler

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/github-mcp-server/index.html b/tools/github-mcp-server/index.html index 9210494..02f9e15 100644 --- a/tools/github-mcp-server/index.html +++ b/tools/github-mcp-server/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

Wrangler

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/hugging-face/index.html b/tools/hugging-face/index.html index 2148d98..86dfd96 100644 --- a/tools/hugging-face/index.html +++ b/tools/hugging-face/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

GitHub MCP Server

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/make/index.html b/tools/make/index.html index 9237f3e..1fa84c1 100644 --- a/tools/make/index.html +++ b/tools/make/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

Anthropic API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/n8n/index.html b/tools/n8n/index.html index 2c19820..d0e28ca 100644 --- a/tools/n8n/index.html +++ b/tools/n8n/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

Anthropic API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/openai-api/index.html b/tools/openai-api/index.html index cc6fb3b..e1f2e5d 100644 --- a/tools/openai-api/index.html +++ b/tools/openai-api/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -306,7 +306,7 @@

Playwright MCP

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/perplexity/index.html b/tools/perplexity/index.html index 646703b..b08afcb 100644 --- a/tools/perplexity/index.html +++ b/tools/perplexity/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -238,7 +238,7 @@

OpenAI API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/playwright-mcp/index.html b/tools/playwright-mcp/index.html index 1e4bf30..462b6c3 100644 --- a/tools/playwright-mcp/index.html +++ b/tools/playwright-mcp/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -272,7 +272,7 @@

Anthropic API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/signal-stack/index.html b/tools/signal-stack/index.html index e1697fc..e942688 100644 --- a/tools/signal-stack/index.html +++ b/tools/signal-stack/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -216,7 +216,7 @@

Strudel Studio

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/strudel-studio/index.html b/tools/strudel-studio/index.html index e2544b5..992e2a4 100644 --- a/tools/strudel-studio/index.html +++ b/tools/strudel-studio/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -238,7 +238,7 @@

OpenAI API

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/syncpad/index.html b/tools/syncpad/index.html index e597110..b1e7bc2 100644 --- a/tools/syncpad/index.html +++ b/tools/syncpad/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -182,7 +182,7 @@

Canvas Planner

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/tools/wrangler/index.html b/tools/wrangler/index.html index 9de4afd..1695a79 100644 --- a/tools/wrangler/index.html +++ b/tools/wrangler/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -238,7 +238,7 @@

Playwright MCP

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.

diff --git a/updates/index.html b/updates/index.html index 3f33b57..e9d626f 100644 --- a/updates/index.html +++ b/updates/index.html @@ -28,7 +28,7 @@
-

Issue 2026-04-25 // Curated public signal for builders

+

Issue 2026-06-04 // Curated public signal for builders

No fake telemetry Official sources first @@ -325,7 +325,7 @@

Wrangler 4.58.0 improved command grouping and auth ergonomics

Public tool intelligence for builders, operators, and curious system nerds.

-

Updated 25 Apr 2026

+

Updated 4 Jun 2026

Public site generation from the StackScout shared source layer.