Agentic Planet Playbook

The everything-you-need page for working on agents.aguidetocloud.com — the cockpit-style field guide for techies building with agents. Standalone planet · own physics · doesn't follow the cosmos rule. Written 2026-05-07 after the overnight v1 build + four iteration rounds.

When this applies

Any code change in C:\ssClawy\agentic-planet\. Any decision that changes pillars, voice, design tokens, deploy flow, or pending roadmap. Read the TL;DR + Origin Story + Pending Improvements sections at minimum when picking up the project.

---

TL;DR — what's at stake

• Site: agents.aguidetocloud.com
• Repo: C:\ssClawy\agentic-planet\ · GitHub susanthgit/agentic-planet (public) · Cloudflare Pages project agentic-planet
• Stack: Astro 5 + MDX + React islands → Cloudflare Pages → custom domain (Phase 1 subdomain → Phase 3 standalone domain)
• Identity: Cockpit · info-dense · dark-only · plain English · Bloomberg/Linear/cyberpunk-terminal blend · #07090E base · cyan/green/amber/red/magenta signal palette · JetBrains Mono display + Inter body
• Content (current — 2026-05-07 end of S5+S6+S8 polish stretch): 73+ pages live · 12 MCP reviews + 12 scorecards (was 7) · 4/4 vendor deep-dives in collection (was 0) · 22 compare items across 5 categories · 1 flagship 30-min hands-on tutorial · 1 methodology page · 10/10 explainers (was 5) · 10/10 FAQs (was 4) · 1 draft recipe · 14 inline-templated safety risks · 4 inline-templated standards · Lab wizard · Pulse / ThisWeek / NEW Incidents feed pages · 3 Builder Log entries (was 0) · 2 RSS feeds (/rss/desk.xml, /rss/incidents.xml) · 3 static data endpoints (/data/mcps.json, /data/scorecards.json, /data/incidents.json — CC BY 4.0) · /llms.txt · /colophon · /404 · home
• Live data: GitHub Actions cron every 6h refreshes MCP star deltas (schema v2 — distinguishes repo vs monorepo-subdir; cron commits trigger redeploys post-S1 fix). Pagefind index ships in production deploys (3,181 words indexed)
• Build: ~10s for 49 pages (Astro + Pagefind)
• Deploy: ~30s via custom REST API script (scripts/deploy.mjs) — wrangler is broken on win32-arm64
• Auto-deploy: GitHub Actions on push to main + Integrity Check workflow (build + audit + voice-lint) hard-fails on any internal 404 or scorecard orphan
• Voice: Plain English. No vendor spin. Honest take. Sush works at Microsoft — disclosed on every Microsoft page. Voice-lint forbidden words: frontier · ecosystem · multimodal · agentic capability · in layman · AI-powered · robust · scalable · holistic · synergies · game changer · mission-critical · moat · differentiator · SEO magnet · flagship

Current snapshot — read first when picking up cold

Pillar	Tracked	Reviewed	Published	Target
Landscape (L01)	inline	inline	inline	4
Recipes (R02)	1	1	0 (draft)	5
MCP Servers (M03)	13	12	12	30
Tools (T04)	0	0	0	12
Vendors (V05)	4	4	4	4
Safety (S06)	14 (inline)	0 collection	14 inline	14
Standards (P07)	4 (inline)	0 collection	4 inline	4
Learn — explainers (L08)	10	10	5 published / 5 review	10
Lab (X09)	1 wizard	1	1	6
FAQ (Q10)	10	10	6 published / 4 review	10
Scorecards (new — S2)	—	—	12	30
Compare (new — S3)	—	—	22 across 5 cats	growing
Incidents (new — S6)	—	—	5 entries	weekly cadence
Builder Log (new — S6)	—	—	3 backdated entries	weekly cadence
RSS feeds (S8 polish)	—	—	2 (desk, incidents)	+ Pulse + ThisWeek + Recipes (future)
Static data endpoints (S8 polish)	—	—	3 (mcps, scorecards, incidents)	+ compare items (future)

Current Sush input gates remaining: Compare verdicts (per-axis facts done; verdict strings benefit from voice) · Hero copy confirmation · YouTube tutorial recording for /learn/your-first-agent/. Methodology page + 12 scorecards + tutorial all promoted to status: published 2026-05-07.

Remaining MCP backfill (~18 of 30): Sush paused continued MCP backfill at 12 to prioritise content backbone (S5) and operational surfaces (S6 incidents + builder log) + polish (S8 RSS + data endpoints). 18 more MCPs queue for future sessions.

🧭 For a complete what-shipped-vs-pending view, jump to the Final state — end of day 2026-05-07 table and the Pending — what next session(s) pick up table at the end of the Active roadmap section.

Standalone planet — own physics

The Agentic Planet does NOT follow the Cosmos rules (no shared cosmos-config, no shared cosmos-nav, no cross-planet rail). Sush explicitly carved this out the first night: "this doesn't have to follow the planet rule, it's a standalone planet with its own rules and physics."

What it DOES share with aguidetocloud.com family: the brand (Sush's voice, plain-English mission, Microsoft disclosure pattern) and the deploy-via-Cloudflare-Pages pattern. Everything else — visual system, IA, fonts, even the layout philosophy — is purpose-built for the cockpit aesthetic and tech-only audience.

---

Origin story — how the idea came about

6 May 2026, late evening. Sush asked: "how about creating a new planet for OpenClaw projects or related things for agents? we can experiment lot of things or ideas on how to add things or connect, or info about MCP servers, agents etc."

Asked for an honest take. The response: the OpenClaw-only framing is too narrow — there's a real, larger gap. The agentic AI ecosystem is exploding (MCP, A2A, Apps SDK, Agent 365, Claude Skills, Computer Use, Operator, hundreds of MCP servers). Devs and IT pros are drowning. Vendor docs are vendor spin. Hacker News threads are lottery tickets. There is no single, opinionated, plain-English field guide that says "here are the 30 MCPs that matter, here are the 5 vendor takes worth reading, here's a working recipe with measured before/after, here's the safety profile, here's the protocol war update."

Sush's response: "i love this idea and i want to pursue." Confirmed scope: all 14 pillars except #13 (newsletter — Pulse) and #14 (community). Tech-only audience — info-dense allowed, plain English mandatory.

That same night, Sush asked me to build the whole thing locally overnight with full autonomy so a v1/v2 was ready by morning. He created the GitHub repo (susanthgit/agentic-planet) and gave me push access via PAT + Cloudflare API access.

The build went from 0 → 31 live pages in ~13 hours, then through four iteration rounds across the next morning.

The gap we're filling (one paragraph)

Every other agentic-AI resource online is either: (a) vendor docs (spin), (b) HN/Reddit (lottery), (c) influencer content (shallow), (d) academic papers (impractical), or (e) framework-specific (LangChain-only / LlamaIndex-only). Nobody curates the whole agentic ecosystem in plain English with honest opinions and working recipes. That's the gap. The Agentic Planet is the Bloomberg Terminal × Linear × cyberpunk-cockpit take on it.

---

Vision & guiding principles

#	Principle	What it means in practice
1	Plain English, always	Forbidden words: frontier · ecosystem · multimodal · agentic capability · in layman's terms · AI-powered · robust · scalable · holistic · synergies · game changer · mission-critical. Replace with plain words.
2	Tech-only audience	We don't cater to non-technical readers. Density is allowed. Cmd+K is expected. JetBrains Mono is fine. We assume the reader has a terminal open.
3	Cockpit aesthetic	Like Bloomberg / Linear / NASA mission control. Info-dense, signal-coded, every pixel earns its place. No emojis — we use stroke-based SVG icons via the <Icon /> primitive.
4	Dark only	No light theme. Reduces overhead. Matches the audience and the cockpit metaphor.
5	Honest opinions	"Use this. Skip that. Wait three months on this." No fence-sitting. Vendors get reviewed, not sold.
6	Live data over fake liveness	When something says "Live", it must actually be cron-fed. We removed every fake "live since X" claim during the v1 SME review.
7	Microsoft disclosure	Every Microsoft page carries: "Sush works at Microsoft as a Copilot Solution Engineer. The take on this page is independent — not Microsoft's official position."
8	Free + zero friction	Public site, no login, no email gate, no paid tier. (Phase 2/3 may explore Ko-fi tip jar but not content gates.)
9	Standalone planet	Doesn't follow cosmos rules. Own visual system, own IA, own physics.
10	One Body principle scoped	The site internally is one body — nav, footer, fonts, tokens stay aligned across all 33 pages. But it's NOT in the cosmos one-body chain with Hugo/Astro main sites.

---

The 14-pillar information architecture

The pillars are the spine. Each pillar is a top-nav surface and gets a landing page. Pillars are scoped and progressively built:

Code	Pillar	Phase 1 scope	Status
L01	Landscape	Timeline · state-of-2026-Q2 snapshot · vendor map	✓ live
R02	Plain-English Explainers	5 of 10 (what is an agent · MCP in 90s · agentic stack · tool calling vs MCP · context windows)	🟡 5/10
G02	Glossary	~50 jargon terms	✓ live
T03	Tool Catalog	(Phase 2) honest reviews across coding/general/browser/voice/orchestration/local	⏳ Phase 2
M03	MCP Servers	30 hand-written reviews + cron-fed health board · Phase 1 ships 13 with infrastructure for all 30	🟡 13/30
B04	Build-your-own MCP	(Phase 2) plain-English starter + embeddable health badges	⏳ Phase 2
O05	Open Source Projects	(Phase 2) frameworks · indie projects · self-hosted · monthly spotlight	⏳ Phase 2
R06	Recipes	5 measurable workflows with before/after numbers · YouTube SEO · PR triage · toolkit freshness · blog SEO audit · MCP health monitoring	🟡 1/5 (rest scaffolded)
S07	Standards	MCP · A2A · Apps SDK · emerging	✓ 4/4 (Phase 1 scope met)
S08	Safety	Prompt injection · data flow · decision trees	✓ 14/14
V09	Vendor Takes	MS + Anthropic deep-dives in Phase 1 · OpenAI + Google + Meta in Phase 2	🟡 2/5
P10	Pick-Your-Stack Lab	Single Lab wizard (5-question flow → recommended tools)	✓ live
T11	Templates	(Phase 3) Copilot Studio · Claude Skill · MCP server boilerplates · declarative agent	⏳ Phase 3
C12	Career & Skills	(Phase 3) skills 2026 · roles · paths · honest career FAQ	⏳ Phase 3
~~13~~	~~Pulse newsletter~~	EXCLUDED per Sush — too much overhead, not core to the field-guide value	—
~~14~~	~~Community~~	EXCLUDED per Sush — same reason	—
D15	Visual Library	8 signature diagrams Phase 1 → 30+ in Phase 3	🟡 8/30
F16	FAQ	4 honest answers Phase 1 (hype · MCP survival · build with $0 · why hallucinate)	🟡 4/10

Pillars-bento on homepage shows current/target ratios live (e.g., R02 Recipes 1/5, M03 MCPs 13/30). Full pillars are marked complete (Standards 4/4, Safety 14/14).

---

Tech stack & file map

Path	What it is
astro.config.mjs	Astro 5 config with MDX + React integration. Output: static.
package.json	Dependencies: astro, @astrojs/mdx, @astrojs/react, react, libsodium-wrappers (for GH secrets), @fontsource/inter, @fontsource/jetbrains-mono.
src/layouts/BaseLayout.astro	Sitewide chrome — <head>, StatusBar, Nav, footer, theme tokens.
src/layouts/PillarLayout.astro	Pillar-page wrapper (kicker, title, lede, content slot).
src/components/StatusBar.astro	Top bar — system online · build · deploy · UTC clock · ver.
src/components/Nav.astro	Main nav with pillar dropdown + Cmd+K trigger.
src/components/primitives/Panel.astro	Cockpit panel primitive — bordered card with kicker + body slot.
src/components/primitives/Button.astro	Variants: primary · ghost · accent.
src/components/primitives/Icon.astro	The icon system — wraps stroke SVGs from icons.ts.
src/components/primitives/icons.ts	47 stroke-based SVG paths. No emojis sitewide.
src/components/primitives/LiveDot.astro	Pulsing status dot — green/cyan/amber/red/magenta.
src/components/panels/PulseRail.astro	Vendor-pulse feed — JSON-driven.
src/components/panels/ThisWeekPanel.astro	MCP star-delta panel — cron-fed.
src/components/panels/PillarTile.astro	Pillar card — code · icon · title · ratio · arrow.
src/components/panels/AgenticStackDiagram.astro	5-layer SVG of the agentic stack. Don't touch viewBox without testing overflow.
src/components/panels/CoverageMatrix.astro	Per-pillar coverage grid (status tiles).
src/components/panels/StackHealthStrip.astro	Site-meta strip (orphaned post-restructure — see "Orphans" below).
src/components/panels/TotalStarsMetric.astro	Sum of all tracked MCP stars.
src/components/panels/ActivityHeatmap.astro	7-day MCP commit heatmap (orphaned post-restructure — see "Orphans").
src/components/panels/MiniTerminal.astro	Decorative cockpit terminal.
src/components/panels/RoadmapStrip.astro	Phase 1/2/3 horizontal roadmap.
src/components/panels/DidYouKnow.astro	Rotating trivia card.
src/components/panels/StartHereRail.astro	3-step onboarding (Read MCP-90s → Pick stack → Browse recipe). First-time-visitor critical surface.
src/components/panels/FeaturedPicks.astro	Recipe of Week + MCP of Month (curation).
src/components/interactive/CommandPalette.tsx	React-island Cmd+K with fuzzy search + recent items.
src/data/pillars.json	Pillar metadata — code · title · count · target · color · icon.
src/data/mcp-health.json	Cron-written. Don't hand-edit.
src/data/pulse.json	Vendor-pulse feed (Phase 1: hand-curated, Phase 2: feed-pulled).
src/data/search-index.ts	Cmd+K palette index.
src/data/recipes/youtube-seo-automation.mdx	The single Phase 1 recipe (status: draft — needs Sush's measured numbers).
src/pages/index.astro	Homepage — user-first restructured 2026-05-07. Read before changing flow.
src/pages/pulse.astro · src/pages/this-week.astro	"View more" destinations from homepage hero panels.
src/pages/lab/pick-your-stack.astro	Wizard React island.
src/pages/colophon.astro	About the build, what's live, what's cron-fed, what's faked. Honesty page.
scripts/deploy.mjs	Custom Cloudflare Pages REST deploy. Use this, not wrangler.
scripts/refresh-mcp-health.mjs	Cron worker — queries GitHub API, writes mcp-health.json.
scripts/set-gh-secret.mjs	Sets GitHub Actions secrets via REST + libsodium sealed box.
scripts/inspect.mjs	Playwright screenshot script. Run after deploy to verify.
scripts/gap-audit.mjs	Playwright-based bento balance auditor (10 May 2026). Measures left vs right cell heights for every .bento on a page. Runs on dev OR live URL, desktop OR mobile. Sibling of cosmos-atlas's qa-audit.mjs. Use as pre-deploy check. Usage: node scripts/gap-audit.mjs [URL] [desktop\|mobile].
.github/workflows/deploy.yml	Auto-deploy on push to main.
.github/workflows/refresh-mcp.yml	6-hourly cron for MCP health.

---

Visual design system (cockpit aesthetic)

Soft Cockpit update — 10 May 2026

On 10 May 2026 the visual system was softened in a major pass. Token-level changes ripple through every page. See the Soft Cockpit pass section below for the full record. Net effect: rounder corners, no document-wide scanline overlay, no viewport frame rails, no glow on text labels — but the cockpit identity (mono code prefixes, signal palette, JetBrains Mono headings, LiveDots, terminal cursor) is preserved. The current token values in this section reflect the post-pass state.

Tokens

--bg-base: #07090E;        /* deeper than initial #0A0E14 — Sush feedback */
--bg-panel: #0E141C;
--text-bright: #F9FAFB;
--text-mute: #9CA3AF;
--accent: #6366F1;         /* indigo (carried from Zen System) */
--accent-hi: #818CF8;

/* Signal palette — meaning per colour */
--signal-cyan: #22D3EE;    /* data, info */
--signal-green: #10B981;   /* alive, healthy, complete */
--signal-amber: #F59E0B;   /* slowing, in-progress */
--signal-red: #EF4444;     /* abandoned, error */
--signal-magenta: #EC4899; /* spotlight, featured */

--border-dim: #1F2937;
--border:     #2D3748;

/* Radii — Soft Cockpit (10 May 2026) */
--radius-xs: 4px;          /* was 2px — kept tight for inline code/kbd */
--radius-sm: 6px;          /* was 4px */
--radius-md: 10px;         /* was 6px — most panels use this */
--radius-lg: 14px;         /* was 8px */
--radius-xl: 18px;         /* was 12px */

Typography

• Display: JetBrains Mono (self-hosted via @fontsource/jetbrains-mono)
• Body: Inter (self-hosted via @fontsource/inter)
• Mono: JetBrains Mono (kicker, counts, terminal output, code)
• Tracking: Wider on uppercase kickers (--tracking-wider: 0.05em, --tracking-widest: 0.18em)

Layout

• Frame inset: ~~Subtle side rails via body::after on viewports ≥1100px~~ Removed in Soft Cockpit pass — was framing nothing.
• Container: container-wide (1480px) and container-max (1400px) with narrow gutter (Sush's morning-1 feedback — "give a narrow margin, atleast tiny").
• Bento grids: 60-40, 50-50, 55-45, 40-60 ratios for panel pairs. Mobile collapse at 1100px.
• Pillars-bento: 5-col desktop → 4-col tablet (≤1280) → 2-col mobile (≤700) (changed from 6/4/2 in Soft Cockpit pass — flat, equal-weight, no feature/standard split).
• Background: Radial vignette + subtle grid pattern for depth. Document-wide scanline overlay removed in Soft Cockpit pass — scanlines now live only inside data panels where they earn their place.

Forbidden visual moves

• No emojis (use <Icon />)
• No gradients on panels (only on hero scan-line + accent backgrounds)
• No glassmorphism / backdrop-filter
• No drop shadows on cards (border-only)
• No animations longer than 200ms
• No multiple accent colours per panel (signal palette is meaning-coded, not decorative)
• No light theme
• No text-shadow on labels, kickers, titles, numbers, or body text (Soft Cockpit rule). Glow stays on signals only — LiveDot, alarm states, the one big TotalStars showcase digit, MiniTerminal (designated terminal moment).

---

Voice & content rules

Same voice rules as the rest of the family — see voice-and-tone.md for Sush's full voice library. Agentic-Planet-specific rules:

1. Plain English forbidden words — list above. The voice guardrail file is ~/.copilot/plain-ai-voice-guardrail.md. Pass every new MDX through the four voice tests (mum · dinner-table · 12-year-old · honesty).
2. Microsoft disclosure must appear in footer of every Microsoft page. Exact wording above.
3. Every voice-critical content file has frontmatter sushReviewNeeded: true until Sush has done his pass. Do not strip the flag without his confirmation.
4. Recipes need real measured numbers — before: / after: / cost: fields must be Sush's actual measurements, not vendor claims. Recipes without measured numbers stay status: draft.
5. Honest take is mandatory — every vendor/MCP/tool review ends with a one-line verdict: "Use this for X · skip if Y · check back in N months." No fence-sitting.

---

Build & deploy

Local

cd C:\ssClawy\agentic-planet
npm install     # only on first checkout
npm run dev     # http://localhost:4321
npm run build   # → dist/, ~7s for 33 pages

Deploy (manual)

$env:CLOUDFLARE_API_TOKEN = (Get-Content "$env:USERPROFILE\.copilot\secrets\cloudflare-api-token" -Raw).Trim()
$env:CLOUDFLARE_ACCOUNT_ID = (Get-Content ".cache\cf-account-id.txt" -Raw).Trim()
node scripts/deploy.mjs

Deploy (auto)

Push to main. GitHub Actions runs deploy.yml → builds → calls scripts/deploy.mjs with secrets from repo settings. Live in ~90s.

Verify after deploy

Start-Sleep -Seconds 30
node scripts/inspect.mjs   # → .cache/screenshots/ (15 PNGs across desktop/tablet/mobile)

Then open home-desktop-fold.png, home-mobile-fold.png, home-desktop-pillars.png to spot-check.

Why custom deploy

Wrangler is broken on win32-arm64. The scripts/deploy.mjs uploads files directly to the Cloudflare Pages REST API, bypassing wrangler entirely. It does:

1. Walk dist/ and POST each file to /accounts/{id}/pages/projects/{name}/upload
2. POST manifest to /deployments
3. Return deploy URL

It works reliably and is faster than wrangler (~30s vs ~60s when wrangler does work elsewhere).

CF Pages config

• Project name: agentic-planet
• Production branch: main
• Build output: dist/
• Custom domain: agents.aguidetocloud.com (CNAME → agentic-planet.pages.dev)
• Phase 3 plan: migrate to standalone domain when triggers met (50+ indexed pages, 5k+ monthly visits, 100+ backlinks, 6+ months old).

---

Live data pipelines

MCP health cron (refresh-mcp.yml + scripts/refresh-mcp-health.mjs)

• Runs every 6 hours
• Queries GitHub REST for: stargazers · pushed_at · open_issues · default_branch
• For each MCP in REPO_MAP: writes { slug, name, stars, lastCommitDays, openIssues, health }
• Output: src/data/mcp-health.json (gets committed back to repo by the action)
• Known issue: filesystem-mcp, postgres-mcp, slack-mcp all currently map to modelcontextprotocol/servers (the monorepo). They share stars (~85k each in display). The REPO_MAP needs different per-server identifiers. Cosmetic data quality issue. Pending fix.

Pulse feed

• Phase 1: hand-curated src/data/pulse.json (vendor announcements)
• Phase 2 plan: cron-pull from official vendor RSS / GitHub releases / changelog feeds. Not yet implemented.

Build/deploy timestamps in StatusBar

• BUILD_VERSION: from package.json
• DEPLOY_AT: written by deploy script as a build-time env var
• cron N ago: derived from mcp-health.json._lastUpdated

---

What we built — the night build (v1) and four iteration rounds

Night build (Round 0) — ~13 hours overnight

Sush gave full autonomy and went to sleep. Done by morning:

• ✅ GitHub repo set up + push access via PAT
• ✅ CF Pages project + domain wired
• ✅ CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID GitHub Actions secrets set (libsodium sealed box via REST)
• ✅ 31 pages: 14 pillar landings · 5 explainers · 4 FAQs · 1 recipe · 2 MCP reviews · glossary · Lab wizard · /colophon · /404
• ✅ GitHub Actions: auto-deploy + 6h MCP cron
• ✅ Astro + MDX + React island for Lab wizard + Cmd+K command palette
• ✅ Cockpit visual system: dark + light themes initially
• ✅ SME + Tech rubber-duck self-reviews
• ✅ Fixed 14 P0 blockers found in self-review (broken links, fake "live" claims, voice violations, factual errors)
• ✅ MORNING-BRIEF.md handoff written

Round 1 (morning, Sush feedback)

"Instead of offering two themes there is only dark theme so we don't have to worry. Edge to edge — give a narrow margin. By dense rich information I was referring to card compactness. We will not use emojies — use cool SVGs. Home page can be rearranged to bring sharpness, in two-three vertical stack rather than one single column."

• ✅ Killed light theme entirely (CSS, toggle, all variants)
• ✅ Icon.astro + icons.ts with 47 stroke-based SVGs
• ✅ Replaced ALL emojis sitewide with <Icon />
• ✅ Cockpit side-rail frame via body::after
• ✅ Restructured homepage as 2-col bento (60-40, 50-50)
• ✅ Self-hosted Inter + JetBrains Mono via @fontsource (no Google Fonts CDN)

Round 2 (background colour question + senior dev review)

"Is the dark blue background the best for showing information? Should we go dark?"

• ✅ Confirmed dark blue is best (Bloomberg/cockpit family)
• ✅ Deepened to #07090E + radial vignette

"Implement all 15 senior-dev recommendations in batches"

• ✅ Command Bridge hero with PulseRail + ThisWeekPanel inline
• ✅ Real Cmd+K command palette (React island, fuzzy search, recent items)
• ✅ AgenticStackDiagram (5-layer SVG)
• ✅ StackHealthStrip
• ✅ CoverageMatrix
• ✅ G+letter pillar shortcut codes
• ✅ Vendor monogram bricks
• ✅ Copyable install hook

Round 3 (diagram polish + more cockpit surfaces)

"The agentic stack image nearly works but needs polishing — overflow on lines etc."

• ✅ Installed Playwright, screenshotted, diagnosed L05 text overflow + FEATURE/pulse collision
• ✅ Rebuilt diagram v2: 720x320 viewBox, fixed text fit, proper arrow markers, no overflow

"Coverage matrix and Agent Architecture five layers side by side. Add view-more links to Pulse / This Week."

• ✅ Side-by-side layout (diagram + coverage matrix)
• ✅ ActivityHeatmap (7-day commit heatmap)
• ✅ TotalStarsMetric (sum of tracked stars)
• ✅ MiniTerminal (decorative cockpit terminal)
• ✅ RoadmapStrip (Phase 1/2/3 horizontal)
• ✅ DidYouKnow (rotating trivia)
• ✅ Sub-second clock (later reverted to whole seconds — Round 4)
• ✅ /pulse and /this-week pages with full feeds

Round 4 (user-POV restructure — 2026-05-07)

"Look at it from a user POV. How else would you change the dashboards to make sense for a real user including me. All at once please."

I gave a real-user critique: hero was too dense for first-time visitors, Pulse/ThisWeek panels assumed context, 3 equal CTAs caused choice paralysis, StackHealthStrip was site-meta noise. Sush said "all at once" — shipped:

• ✅ Hero cleaned: single-column, ONE primary CTA + 2 ghost, removed PulseRail/ThisWeekPanel from hero
• ✅ Hero subtitle has concrete numbers: "30 MCP servers, 4 vendor takes, 5 recipes that actually save time"
• ✅ Inline stat-counts row: 348K★ tracked · 13 MCPs · cron 4h ago
• ✅ NEW: StartHereRail — 3-step onboarding (Read MCP-90s → Pick Stack → Browse Recipe), color-coded cyan/magenta/green
• ✅ Stack Diagram promoted to right-after-hero (educational placement)
• ✅ Pulse + This Week moved INTO new "WHAT'S MOVING NOW" section below stack diagram with intro context
• ✅ NEW: FeaturedPicks — Recipe of Week + MCP of Month side-by-side cards (curation surface)
• ✅ Pillar tiles now show ratios (R02 1/5 · M03 13/30 · S07 4/4 · S08 14/14)
• ✅ Vendor "SOON" → "PHASE 2" (clearer it's a plan, not a delay)
• ✅ Sub-second clock reverted to whole seconds (less jittery)
• ✅ StackHealthStrip removed from homepage (was site-meta noise)
• ✅ ActivityHeatmap removed from homepage (deep-dive surface)

Final flow as of 2026-05-07:

Hero (clean) →
StartHereRail (3-step onboarding) →
AgenticStackDiagram →
What's Moving Now (Pulse + ThisWeek bento) →
Pillars w/ ratios →
FeaturedPicks (Recipe + MCP of period) →
Deep Data (Health Board + Recipes) →
CoverageMatrix + TotalStarsMetric →
FAQ + Vendors →
Roadmap + Install →
Terminal + Explainers →
DidYouKnow →
Footer

---

Active roadmap — "fill the gap, not soften the promise" (May 2026)

Read this before starting any work on Agentic Planet

On 2026-05-07 a fresh-perspective audit found a trust-violating hero/tile mismatch. A follow-up rubber-duck pass found the trust gap is much wider than the hero: featured-recipes.json publishes 5 "production" recipes with precise before/after/cost numbers when only 1 draft recipe file exists; 11 of 13 MCP Health Board rows link to dead pages; the [skip ci] flag on the health-cron means the deployed site can be stale despite the "refreshed every 6h" claim; production deploys never include the Pagefind search index because deploy.yml uses build:no-search. Sush's decision: fill the gap, don't soften the promise. But Session 1 must close the wider trust gap first, not just the hero.

The decision (2026-05-07)

The honest-take pillar means everything visible behind a click must match the claim that surfaced it. Two paths existed: (a) rewrite the hero down to current state, or (b) actually deliver everything the original hero promised plus five new surfaces.

Sush picked (b). "What we are going to do is what you found in the gap, we will fix it in actual — we will add 30 MCPs, 4 vendors, more explainers — and we will fix all the current gaps you identified."

Hero copy is stripped of specific numbers in the meantime so we don't sell what isn't there. Numbers come back as proof of work, not promises.

Rubber-duck pass adoptions (2026-05-07)

The first plan was rubber-ducked before any code shipped. The critique surfaced significantly wider trust holes than the original audit. Adoptions that changed the plan:

1. Session 1 reframed from "trust fixes" to "build the truth engine" — counts, statuses, link integrity, data integrity, deploy pipeline, and search are all separate hand-maintained systems that drift independently. Session 1 must unify them before any new content surface ships.
2. Recipes promoted to a Session 1 emergency — featured-recipes.json publishes fabricated measurements right now. That breaks "no vibes, no marketing" harder than the hero does. Either (a) hide the fake entries until real recipes ship, or (b) replace with a transparent draft bench. Picked (a) for Session 1; transparent draft bench can come later.
3. Computed counts at build time, not a hand-edited counts.json — a JSON file replaces ten scattered lies with one centralised lie. Use Astro content collection queries to compute current counts; reserve JSON only for targets.
4. Lifecycle states added — every content type gets status: draft|review|published|archived plus countable: bool and noindex: bool. Only published + countable content reaches counts, sitemap, search, and primary nav. review is visible-but-flagged, off-counts, off-sitemap.
5. Scorecard verdict bands renamed to remove certification/legal connotations. Old: SAFE-A | SAFE-B | CAUTION | AVOID. New: ADOPT | ADOPT WITH LIMITS | REVIEW FIRST | DO NOT USE FOR SENSITIVE WORK. "SAFE" implies a formal audit we don't perform; "AVOID" reads accusatory.
6. Methodology page ships before any public scorecard — /methodology/mcp-security-scorecard/ with rubric, what's measured, what's not measured, dispute link, version history, and explicit "not a formal audit" disclaimer. Without it, scorecards look arbitrary and carry legal exposure.
7. Scorecard schema expanded with missing dimensions: licence, signed-releases, install method, network egress, OAuth/PAT handling, default permission scope, destructive-tools-present, prompt-injection exposure, dep CVE surface, maintainer bus factor, methodology version, confidence level, source citations.
8. Pagefind deploy mismatch fixed in Session 1 — change deploy.yml to use npm run build so search ships to production. Full deep-content index can stay Session 3, but production search is no longer broken-by-default.
9. Cron-deploy pipeline fixed in Session 1 — drop [skip ci] from the health-refresh commit (or chain a deploy after the commit). Add a freshness canary: deployed _lastUpdated must be within the expected window.
10. Internal-link CI is hard-fail with no normal escape hatch — internal 404s are not "skippable." Emergency override requires PR-label or workflow-dispatch, visible in CI output. External links can be warn-only.
11. scripts/inspect.mjs is supplementary, not primary verification — Session 1 adds deployed smoke checks: route 200s, sitemap, freshness canary, OG asset existence, Pagefind asset existence.
12. Voice lint added in Session 1, not later — current source already contains forbidden words. The first plan's own roadmap text used "moat", "differentiator", "SEO magnet", "flagship" — exactly the marketing voice we forbid. Lint catches these before they ship. (The roadmap text below has been cleaned.)
13. Builder Log scaffold moved up to Session 2 — start banking entries early. Don't homepage-feature until at least one real Sush-approved entry exists.
14. llms.txt added as a small Session 1 add — on-brand for an agents-focused site.
15. Compare tool gets a unified primitive + cross-category UX rule — same-category compare = matrix; cross-category = "stack decision view" not "winner/loser". Per-axis value, note, lastCheckedAt, confidence.
16. Static data endpoints — /data/mcps.json, /data/scorecards.json, /data/incidents.json, /data/compare-items.json ship before any "API." Pure static; useful for embedders and AI agents.
17. Plan format clarified — playbook (this file) is the canonical durable source. plan.md in ~/.copilot/session-state/<id>/ is the current-session scratchpad. SQL todos table is current-session execution detail. Session-end discipline: any roadmap change made in plan.md or SQL must be reflected back into this playbook before close — otherwise future sessions execute stale work.

Pushed back on:

• Rubber-duck recommended GitHub issues as the cross-session execution tracker. Disagreed: Sush doesn't run his execution through GH issues; the playbook + SQL pair is workable as long as session-end syncs back here. Drift is bounded by discipline, not infrastructure.
• Rubber-duck recommended Builder Log scaffold in Session 1. Compromise: scaffold in Session 2 (alongside Scorecard) — Session 1 is already much larger than originally scoped, and Builder Log isn't on the trust-leak critical path.

The 8-session epic

Each session has one focus, ships its own deploy, and the next session picks up cleanly via this playbook + the session-workspace plan.md.

Session	Focus	Outcome
1 — Build the truth engine ✓ shipped 2026-05-07	Inventory pass (routes · content · hardcoded cards · data rows · current claims) · lifecycle status semantics · public trust fixes (hero · FAQ · learn · recipe cards · MCP rows · vendor/standards/safety/tools sub-page links · missing OG/favicon) · computed counts at build · MCP health schema rework · CI link + data integrity + voice lint (internal hard-fail) · Pagefind deploy fix · cron-deploy pipeline fix · llms.txt · methodology page scaffold for upcoming Scorecard · orphan decisions · deployed smoke checks	Done. Site is honest. Counts compute themselves. Internal links can't regress. Search ships. Cron actually deploys. 19 broken links → 0. 4 phantom production recipes hidden. Foundation ready for Sessions 2–8.
2 — MCP Security Scorecard + Builder Log scaffold ✓ shipped 2026-05-07	/methodology/mcp-security-scorecard/ published first · per-MCP scorecard schema (expanded) + UI panel + embeddable SVG badge + correction/dispute link · score 5 existing MCPs as proof · Builder Log content collection + routes (no homepage feature yet)	Done. System ships end-to-end: methodology page, schema (22 dimensions, 4 verdict bands), Scorecard.astro panel inline on each MCP review page, embeddable /badge/<slug>/security.svg, /scorecards/ catalog, /desk/ Builder Log scaffold. 2 of 5 MCPs scored (github-mcp + playwright-mcp, both status: review); remaining 3 land in Session 4 alongside content backfill. Methodology + scorecards stay status: review · noIndex until Sush voice-passes the methodology — they all promote together.
3 — Compare tool + Flagship tutorial + Pagefind deep index ✓ shipped 2026-05-07	Pure client-side compare with unified primitive + per-category facets · cross-category "stack decision" view · /learn/your-first-agent/ 30-min hands-on with embedded YouTube slot · real Pagefind index across MCPs/recipes/glossary/FAQs · Cmd+K wired to Pagefind	Done (Cmd+K Pagefind integration deferred to Session 3.5). 22 items across 5 compare categories. /compare/stack/ cross-category view with 4 worked stack-decision examples. Tutorial ships at status: review, voice-pass pending. Pagefind tuning via data-pagefind-ignore on chrome + data-pagefind-meta on review pages. 2,871 words indexed (was 2,545).
4 — MCP backfill (13 → 25) ⚠️ partial — paused at 12/30	12 more MCP reviews, each scored against the Session 2 schema so they ship complete	5 of 12 shipped (filesystem · postgres · slack · cloudflare · notion). Sush paused at 12/30 to refocus on S5+S6+S8. 18 more queue for next session(s).
5 — Content backbone ✓ shipped 2026-05-07	OpenAI + Google vendor pages · 5 more explainers · 6 more FAQs · methodology pages for vendor/recipe/explainer review · all earlier review-status content cleared to published after Sush's voice pass	Done. 4/4 vendors as content-collection deep-dives · 10/10 explainers · 10/10 FAQs · all status: published. Vendors index migrated from inline-array to getCollection('vendors').
6 — Last 5 MCPs + Incident Feed + Builder Log entries ✓ shipped 2026-05-07 (last 5 MCPs not yet — only 5 of remaining 18)	30/30 MCPs · /this-week/incidents/ (operational change-log framing, not drama) · 3 backdated Builder Log entries (night build · iteration rounds · this audit) so the surface ships alive	Partial — operational surfaces done, MCP backfill not. 5 more MCPs scored (azure · stripe · browserbase · linear · figma) bringing total to 12. Incident Feed live with 5 sourced entries. Builder Log live with 3 backdated entries.
7 — Recipes (gated by Sush's measured runs)	4 more recipes with real before/after / cost / verdict · methodology page for recipe measurement	5/5 recipes published, all with measured numbers.
8 — Polish + launch ⚠️ partial — RSS + data endpoints shipped 2026-05-07	OG images per pillar · JSON-LD validation against Rich Results · RSS/Atom for Pulse/ThisWeek/Recipes/Builder Log · accessibility audit (WCAG AA · skip-to-content · screen-reader announce on Cmd+K) · static data endpoints (/data/*.json) · cross-link from main aguidetocloud.com · launch announcement	Partial. 2 RSS feeds live (/rss/desk.xml, /rss/incidents.xml). 3 static data endpoints live (/data/mcps.json, /data/scorecards.json, /data/incidents.json). OG images, accessibility audit, cross-link, launch — deferred to next session(s).

The 5 big additions — concept and schema

1. MCP Security Scorecard (Session 2)

What this exists for: Snyk and Socket cover npm packages. No equivalent exists for MCP servers. Scorecards make adoption decisions explicit instead of vibes-based.

This is not a formal security audit

The Scorecard is an opinionated adoption posture based on public-source review. Methodology page (/methodology/mcp-security-scorecard/) ships before any public scorecard. Every scorecard carries: confidence level · last-reviewed date · methodology version · source citations · "report a correction" link · "not a formal audit" disclaimer.

Verdict bands (renamed from earlier draft to remove certification/legal connotation):

• ADOPT — corp- or community-maintained · code reviewable · narrow blast radius · current dep tree
• ADOPT WITH LIMITS — workable with documented mitigations (scoped tokens, sandbox, human-approval on writes)
• REVIEW FIRST — gaps you must understand before adopting (e.g. opaque secrets handling, unsigned releases, broad default permissions)
• DO NOT USE FOR SENSITIVE WORK — abandoned, unresolved active incidents, or known exfiltration vectors

Schema (src/data/scorecards/<slug>.json) — expanded after rubber-duck pass:

{
  "slug": "playwright-mcp",
  "displayName": "Playwright MCP",
  "lastReviewedAt": "2026-05-07",
  "nextReviewDue": "2026-08-07",
  "reviewedBy": "Sush",
  "methodologyVersion": "1.0",
  "confidence": "high|medium|low",
  "scorecard": {
    "licence":              { "value": "MIT|Apache-2.0|...", "note": "..." },
    "securityPolicy":       { "value": "yes|no", "contact": "...", "note": "..." },
    "signedReleases":       { "value": "yes|no|partial", "note": "..." },
    "installMethods":       ["npm", "docker", "binary", "source"],
    "codeReview":           { "value": "yes|partial|no|unknown", "note": "..." },
    "secretsHandling":      { "value": "scoped|env-only|leaky|unknown", "note": "..." },
    "credentialStorage":    { "value": "os-keychain|file|memory|unknown", "note": "..." },
    "oauthHandling":        { "value": "scoped|broad|n/a", "note": "..." },
    "sandboxModel":         { "value": "container|subprocess|process|none", "note": "..." },
    "filesystemAccess":     { "value": "scoped|home|root|none", "note": "..." },
    "shellAccess":          { "value": "yes|no|sandboxed", "note": "..." },
    "networkEgress":        { "value": "none|allow-list|open", "note": "..." },
    "telemetry":            { "value": "none|opt-in|opt-out|forced", "note": "..." },
    "dataResidency":        { "value": "local|cloud|mixed", "note": "..." },
    "defaultPermissions":   { "value": "minimal|moderate|broad", "note": "..." },
    "destructiveTools":     { "present": ["delete_file", "..."], "humanApproval": "yes|no|optional" },
    "promptInjectionExposure": { "value": "low|medium|high", "note": "..." },
    "supplyChainSurface":   { "value": "low|medium|high", "depCount": 12, "directDeps": 4, "note": "..." },
    "depCveSurface":        { "value": "clean|warnings|critical", "lastScannedAt": "...", "note": "..." },
    "rateLimitRisk":        { "value": "low|medium|high", "note": "..." },
    "maintainerType":       { "value": "corp|indie|community|abandoned", "busFactor": 1, "releaseCadence": "weekly|monthly|quarterly|none" },
    "issueResponseMedianDays": 3,
    "incidents":            [ { "date": "...", "severity": "...", "summary": "...", "sourceUrl": "...", "status": "monitoring|resolved" } ]
  },
  "verdict":     "ADOPT | ADOPT WITH LIMITS | REVIEW FIRST | DO NOT USE FOR SENSITIVE WORK",
  "verdictScope": "What use-case this verdict applies to (e.g. 'local read-only repo exploration' vs 'production write access')",
  "verdictNote": "One sentence in plain English ending with a recommended action.",
  "sources":     [ { "label": "GitHub repo", "url": "..." }, { "label": "Package on npm", "url": "..." } ],
  "correctionUrl": "https://github.com/susanthgit/agentic-planet/issues/new?template=scorecard-correction.md&slug=playwright-mcp"
}

Unknown values lower confidence; they don't silently pass.

Embed badge: <img src="https://agents.aguidetocloud.com/badge/<slug>/security.svg"> returns a stroke-style SVG (badge format: slug · band · methodology version · last-reviewed date). Badge always links to the live scorecard page so readers can see the evidence.

Files to create (Session 2): - src/pages/methodology/mcp-security-scorecard.astro — ships first - src/data/scorecards/*.json — per-MCP card (5 in Session 2, 30 by end of Session 6) - src/components/panels/Scorecard.astro — scorecard panel rendered on each MCP review page - src/pages/badge/[slug]/security.svg.ts — SVG endpoint (pre-rendered or Cloudflare function) - src/pages/scorecards/index.astro — full sortable list of scored MCPs

Success criteria: Methodology page is published with Sush's voice pass before any public scorecard. 5 MCPs scored at end of Session 2. All 30 scored by end of Session 6. Every scorecard page renders methodology version, confidence level, sources, and correction link.

2. Compare tool (Session 3)

Pure client-side. Pick a category, pick 2–4 items, see them side-by-side on consistent axes. No backend. No tracking.

UX rule (added after rubber-duck pass): same-category compare = matrix view. Cross-category compare ("Claude Desktop vs Cursor" — different scopes) = "stack decision view" not "winner/loser" — surfaces what each does and where each fits in your stack, not which is "better".

Categories shipped Session 3:

• LLMs (Claude Sonnet, GPT-5, Gemini 2, Llama 3.3)
• Hosts (Claude Desktop, Claude Code, Cursor, Cline, Goose, Continue)
• Frameworks (LangChain, LlamaIndex, DSPy, Pydantic AI, Microsoft Agent Framework)
• Vendors (MS, Anthropic, OpenAI, Google) — pulls from Session 5 vendor pages
• Protocols (MCP, A2A, Apps SDK, Agent Protocol)

Schema (unified primitive + per-category facets):

{
  "id": "claude-desktop",
  "name": "Claude Desktop",
  "entityType": "host",
  "layer": "runtime",
  "primaryJob": "Local desktop chat host with MCP",
  "comparableWith": ["host"],
  "crossLayerComparable": true,
  "axes": {
    "pricing":     { "value": "Pro $20/mo", "note": "...", "lastCheckedAt": "2026-05-07", "confidence": "high", "source": "anthropic.com/pricing" },
    "lockIn":      { "value": "low", "note": "..." },
    "mcpSupport":  { "value": "first-class", "note": "..." },
    "leadsAt":     ["Long-form reasoning", "First-class MCP"],
    "lagsAt":      ["No headless mode", "macOS/Win only"],
    "verdict":     "Default host for non-coding agentic work."
  }
}

Per-axis value · note · lastCheckedAt · confidence · source so claims are evidenced and dateable.

Files:

• src/data/compare/<entityType>.json per category
• src/pages/compare/index.astro — category picker
• src/pages/compare/[category].astro — pick items + render matrix
• src/pages/compare/stack.astro — cross-category stack decision view
• src/components/interactive/CompareMatrix.tsx — React island with check-boxes

Success criteria: All 5 categories have at least 4 items each. Matrix renders responsively. Sharable URLs (?items=claude-desktop,cursor). Cross-category picks render as stack decision view, not winner/loser.

3. Flagship tutorial: "Your first agent in 30 minutes" (Session 3)

The most-shareable SEO page on the site. Hands-on, real, ends with a working agent.

Outline: 1. What you'll build (a Claude Desktop + filesystem-mcp + GitHub-mcp setup that summarises any local repo's README and posts the summary as an issue) 2. Prerequisites (5 min) 3. Install Claude Desktop (5 min) 4. Connect filesystem-mcp (5 min) — one config file 5. Connect github-mcp (5 min) 6. Run the prompt + watch it work (5 min) 7. What just happened — 5-layer stack diagram (clickable in Session 3) annotated with what you saw 8. What to read next (Compare, Scorecard, Recipes, FAQ)

Embed: matching YouTube tutorial recorded by Sush (cross-link target). Reading time visible at top.

Files: src/pages/learn/your-first-agent.astro (or MDX). Single long page (no multi-page tutorial — friction).

Success criteria: A real beginner can follow it without any other source. Sush's voice pass. JSON-LD HowTo validates clean.

4. Incident Feed (Session 6) — framed as operational change log, not drama

Pulse covers releases. ThisWeek covers MCP stars. The missing surface: operational changes that affect builders — failures, breakages, deprecations, rate-limit changes, migration deadlines.

Editorial guardrail (added after rubber-duck pass): this is an operational change log, not Slack drama. Every entry has a source link, a precise summary, recommended action, status (monitoring | resolved | false-alarm), and a confidence level. No "vendor X broke everything" wording — sourced and precise only.

Schema (src/data/incidents.json — hand-curated weekly):

{
  "lastUpdated": "2026-05-07",
  "items": [
    {
      "id": "2026-05-05-claude-code-1.4-mcp-filesystem-win11",
      "date": "2026-05-05",
      "severity": "high|medium|low",
      "vendor": "anthropic",
      "affects": "Claude Code 1.4 · Windows 11 · filesystem-mcp",
      "title": "Claude Code 1.4 breaks MCP filesystem on Win11",
      "what": "Tool calls returning empty results when targeting drives other than C:.",
      "recommendedAction": "Pin to 1.3.x or upgrade to 1.4.1 (released May 6).",
      "status": "resolved",
      "confidence": "high",
      "lastUpdatedAt": "2026-05-06",
      "sources": [ { "label": "GitHub issue #1234", "url": "..." }, { "label": "Anthropic changelog", "url": "..." } ]
    }
  ]
}

Surface: /this-week/incidents/ page + homepage card under "What's Moving Now".

Curation cadence: Sush picks 3–8 items per week from his own feeds + GitHub issue trackers + vendor changelogs. Friday update.

Files: src/pages/this-week/incidents.astro · src/components/panels/IncidentFeed.astro.

5. Builder Log / "Sush's Desk" (Session 6)

Weekly Friday post: what Sush built, deployed, broke, fixed, learned that week. 5–10 short dated entries per post. Plain English. Real screenshots / commit links / honest reflections.

Frontmatter:

---
title: "Sush's desk · week of 2026-05-04"
date: 2026-05-09
weekOf: "2026-05-04"
entries: 7
---

Page structure: dated header bar · table of contents · entries (one per H2). Each entry is short — 100–300 words. No marketing voice. Voice tests apply.

Files: src/content/desk/<YYYY-MM-DD>.mdx · src/pages/desk/index.astro (list) · src/pages/desk/[slug].astro (entry).

Cadence: every Friday after launch. Pre-launch: scaffold + 3 backdated entries from the build itself (the night build, the iteration rounds, this audit) so the surface is alive on launch day.

Sush input gates (what blocks autonomous work)

These cannot be done without Sush. Plan around them.

Gate	What it blocks	What I can do without it
Voice pass on every voice-critical content file	Stripping sushReviewNeeded flag · marking page status: published	Draft content with the flag · queue for his pass
Recipe measured numbers (before / after / cost)	Recipe shipping as live	Draft recipe templates with status: draft · the architecture and step-by-step parts can be authored solo
Vendor honest-take verdict lines	Final vendor page sign-off	Draft everything except the one-line verdict at the bottom
Scorecard scoring of MCPs	Each MCP card	Build the schema + UI + first 2–3 cards as templates · Sush scores the rest in batches
Builder Log entries	Weekly post	Build the format + the surface · every entry is Sush's actual work
Incident Feed curation	Weekly update	Build the format + the surface · curation is Sush's editorial call
YouTube tutorial recording for flagship your-first-agent page	Page is shippable without it (text alone works) but stronger with embed	Author the page · leave the embed slot ready · he records when he can

Lifecycle states (added after rubber-duck pass)

Every content type carries:

status: "draft" | "review" | "published" | "archived"
sushReviewNeeded: boolean
countable: boolean
noindex: boolean

Rules:

State	Linked from primary nav?	Counted in current counts?	In sitemap / search / Pagefind?	Notes
draft	No	No	No (noindex: true)	Routable for dev preview only; or unrouted entirely
review	Visibly flagged on parent (e.g. "1 in review")	No	No (noindex: true)	Public URL works · banner says "in review" · not counted as fulfilled
published	Yes	Yes (if countable: true)	Yes	Sush has cleared the voice / verdict gate
archived	Footer/historical only	Excluded from "current" counts	Yes (with archived flag)	Visible but excluded from freshness claims

Counts are computed at build time from content collections, filtered by status === "published" && countable === true. JSON files hold targets, not current values.

Quality bars (per surface)

• Voice tests — every voice-critical page passes mum · dinner-table · 12-year-old · honest tests. Forbidden words: frontier · ecosystem · multimodal · agentic capability · in layman's terms · AI-powered · robust · scalable · holistic · synergies · game changer · mission-critical · moat · differentiator · SEO magnet · flagship. (See ~/.copilot/plain-ai-voice-guardrail.md.) Voice lint runs in CI on public content (Session 1).
• JSON-LD — recipes use HowTo · FAQ uses FAQPage · explainers use Article · MCPs use SoftwareApplication. Each validates against Google Rich Results test before page goes status: published.
• Reading time + last-reviewed date + next-review-due visible on every content page.
• Edit on GitHub link in the footer of every content page.
• Report a correction link on every review/scorecard/vendor page.
• Source citations required for vendor claims, incidents, scorecards, pricing, capability statements.
• Cmd+K indexes deep content — Pagefind built and deployed in Session 1; full index across content collections in Session 3.
• Counts source-of-truth — computed at build time from content collections. Targets in src/data/targets.json. No hand-typed counts in templates anywhere.
• Internal link audit runs in CI · build hard-fails on internal 404 · external links warn-only · escape hatch only via PR-label or workflow-dispatch (visible in CI).
• Data integrity audit runs in CI · template links to data-driven slugs verified against actual content · counts match collections · no published page has sushReviewNeeded: true.
• WCAG AA contrast verified against #07090E background.
• Scorecard verdict line — exactly one sentence, plain English, scoped to a use-case, ends with a recommended action.
• Methodology page exists before any public review/scorecard surface (MCP scorecard, vendor reviews, recipe measurement, MCP health).
• Freshness model — lastReviewedAt + nextReviewDue on review/scorecard surfaces. Stale badge if overdue.
• Deployed smoke checks post-deploy: route 200s · sitemap valid · _lastUpdated within window · OG images exist · Pagefind assets exist.

Session 1 shipped (2026-05-07)

5 commits, one push, one deploy. Both CI workflows passed first try. Smoke check confirmed all 17 production routes return 200 — including the new /llms.txt, /methodology/mcp-security-scorecard/, and /pagefind/pagefind.js (search now ships).

Phase	Commit	What landed
A1 — Inventory baseline	0fb6cec	scripts/audit-claims.mjs + docs/inventory-2026-05-07.md. Found: 19 broken internal links · 4 phantom production recipes · 6 of 10 collections empty · 3 monorepo MCPs sharing 85k stars · [skip ci] blocking cron→deploy · Pagefind never shipping.
A2 — Lifecycle states	a2ba5a4	status / countable / noindex / lastReviewedAt / nextReviewDue added to all 10 collection schemas. 11 existing files marked status: review. Recipe stays status: draft.
B — Public trust fixes	54f8e4e	Hero rewrite (no number promises) · 4 phantom production recipes hidden · MCP Health Board row links gated by reviewedSlugs · safety/standards/vendors broken sub-page links disabled · pulse.json hrefs cleaned · BaseLayout og:image conditional · diagrams page honest count framing.
C — Counts engine + health schema	616109a	src/lib/counts.ts (getPillarCounts, computeUniqueRepoStars) · src/data/targets.json · MCP health schema v2 with sourceType, repo, packagePath, repoStars, representativeStars, healthSignalsMeasured/Missing · monorepo dedup (homepage star total: 348k → 178k accurate).
D — CI gates + deploy fixes	d2f3605	integrity.yml workflow (build · audit hard-fail at 0 · voice lint advisory) · scripts/integrity-check.mjs · scripts/voice-lint.mjs (forbidden list incl. ecosystem/moat/flagship/etc) · deploy.yml switched from build:no-search to build · mcp-health-refresh.yml dropped [skip ci] · 5 voice creep occurrences cleaned.
E — Methodology + llms.txt + orphans + smoke	f56d6fa	/methodology/mcp-security-scorecard/ (status: review, noIndex; renames bands ADOPT / ADOPT WITH LIMITS / REVIEW FIRST / DO NOT USE FOR SENSITIVE WORK; 22 measured dimensions; not-a-formal-audit disclaimer; dispute mechanism) · public/llms.txt · StackHealthStrip resurrected onto /colophon/ · ActivityHeatmap onto /this-week/ · scripts/smoke-check.mjs.

Sush input gates cleared during the session: none required (all Session 1 work mechanical/structural).

Sush input gates pending for Session 2:

• Voice pass on /methodology/mcp-security-scorecard/ (currently status: review, noIndex: true) — must clear to status: published before any public scorecard ships.

• Confirmation that the new hero copy (Vendor docs are pitch. Hacker News is a lottery. This is the cockpit: honest MCP reviews, side-by-side vendor takes, and recipes with measured numbers. Plain English. Built by an engineer who deploys this for a living.) reads in his voice.

• Pillar 13: Pulse newsletter — too much overhead

• Pillar 14: Community features (forum, comments, profiles)
• Light theme — dark-only forever
• Email capture / login walls / paid tier
• Animations longer than 200ms
• Emojis in any UI surface (use <Icon />)

Session 2 shipped (2026-05-07)

1 commit 126f7a5, one push, one deploy. Both CI workflows passed first try.

Phase

What landed

S2 — Scorecard system + Builder Log scaffold

scorecards and desk content collections registered · 2 scorecards at status: review · noIndex (github-mcp + playwright-mcp; both verdict ADOPT WITH LIMITS) · Scorecard.astro panel inline on each MCP review page · /badge/[slug]/security.svg.ts endpoint · /scorecards/ catalog · /desk/ Builder Log surface · .github/ISSUE_TEMPLATE/scorecard-correction.md · audit-claims walks JSON content collections · integrity-check hard-fails on scorecard orphans. Build: 36 pages (was 34).

Session 3 shipped (2026-05-07)

1 commit 89281cb, one push, one deploy. Both CI workflows passed first try. Smoke check confirmed all 17 base routes plus 9 new Session 3 surfaces return 200, including the sharable URL pattern (?items=claude-desktop,cursor).

Surface	What landed
Compare tool	5 categories (LLMs, Hosts, Frameworks, Vendors, Protocols) · 22 items total · per-axis values carry note + lastCheckedAt + confidence + source · CompareMatrix.tsx React island with checkbox picker, sharable URL, responsive matrix · /compare/stack/ cross-category "stack decision view" with 4 worked stack examples (coding agent · server workflow · local-first · multi-agent)
Flagship tutorial	/learn/your-first-agent/ — 30-min hands-on building Claude Desktop + filesystem-mcp + github-mcp setup that reads a local repo's README and posts a summary as an issue. Six steps with timings. Annotated against 5-layer stack. JSON-LD HowTo schema. Cross-links to scorecards / safety / stack decision view. status: review · noIndex pending Sush voice pass.
Pagefind deep-content tuning	data-pagefind-ignore wraps StatusBar + Nav + Footer + CommandPalette so search focuses on real content · data-pagefind-meta on mcp/[slug] · faq/[slug] · learn/[slug] · recipes/[slug] for kind/category/depth/status filtering · 2,871 words indexed (was 2,545). Cmd+K Pagefind integration deferred to Session 3.5.

CI extension: audit-claims.mjs resolves /compare/[category] static-list dynamic routes via STATIC_DYNAMIC_SLUGS, and filters file-system-style paths from broken-link list (so code snippets in tutorials aren't false-positives).

Session 3.5 + Session 4 (partial) shipped (2026-05-07)

Combined stretch: voice promotions (B), Session 3.5 polish (C), Session 4 MCP backfill kickoff (A — first 5 of 12). One commit c25e499 (rebased to 8fca138 post pull), one push, one deploy. Both CI workflows passed first try.

Voice promotions (Sush approved batch):

• /methodology/mcp-security-scorecard/ → status: published, noIndex: false. Methodology v1.0 canonical.
• 2 existing scorecards (github-mcp, playwright-mcp) → status: published, noindex: false. ``Methodology under review'' banner gone.
• /learn/your-first-agent/ → sushReviewNeeded: false. Out of noIndex.

Session 3.5 polish:

• Cmd+K Pagefind integration via runtime script-tag injection (avoids Vite static-import resolution). Hybrid: static SEARCH_INDEX drives nav/jumps; Pagefind kicks in for queries ≥3 chars and adds a "DEEP CONTENT (PAGEFIND)" group with up to 5 deep-content hits per query. Cyan border on Pagefind results.
• Compare stale-data badge: STALE pill renders next to any axis value where lastCheckedAt is older than 120 days. None currently stale (all 2026-05-07); mechanism in place for future drift.

Session 4 MCP backfill (5 of 12):

Slug	Verdict	Notes
filesystem-mcp	ADOPT WITH LIMITS	Scope allow-list to one repo subfolder, never $HOME. Drop write tools for unsupervised agents.
postgres-mcp	ADOPT WITH LIMITS	Dedicated read-only role with statement_timeout. Never connect with postgres superuser.
slack-mcp	ADOPT WITH LIMITS	Per-purpose Slack apps. Curate the bot's invite list as your real ACL.
cloudflare-mcp	ADOPT	Token scoping is best-in-class — exploit it. Rotate monthly.
notion-mcp	ADOPT	Page-level sharing is genuinely strong — create dedicated agent-workspace tree.

The 3 monorepo-subdir MCPs (filesystem, postgres, slack) now have proper review pages, so Health Board row links to them resolve. 7 of the 13 health-board rows now have linked reviews (was: 2).

Build: 49 pages (was 44). Pagefind: 3,181 words indexed (was 2,871). Integrity: 0 broken internal links, 0 scorecard orphans.

Sush input gates remaining:

• Compare verdicts (per-axis values are voice-light; the verdict strings on each item benefit from Sush voice).
• Hero copy confirmation (carries from S1).
• YouTube tutorial recording for your-first-agent.

Remaining MCPs to backfill (Session 4 carry-over): azure-mcp · stripe-mcp · browserbase-mcp · linear-mcp · figma-mcp · plus 2 to be picked.

Session 5 + Session 6 + Session 8 polish shipped (2026-05-07)

Final stretch of the day. Sush paused Session 4 MCP backfill at 5 of 12 — said "update everything you had done in the learn portal documentation, and continue with 5 and 6-8." Trust-based: voice passes are fine, can revise later. One commit acaa3bd, one push, one deploy. Both CI workflows passed first try. All 19 new surfaces verified live in production.

Surface	What landed
4 vendor deep-dives	Microsoft, Anthropic, OpenAI, Google as content collection entries with /vendors/[slug].astro route. Microsoft page disclosure-banner-aware. Strategy · leads-at · lags-at · honest take · further reading per vendor. Vendors index migrated from inline-array to getCollection('vendors').
5 new explainers (5 → 10)	context-windows-lost-in-the-middle · rag-vs-long-context · multi-agent-vs-single-agent · prompt-injection (deep) · computer-use-screen-driving-agents
6 new FAQs (4 → 10)	agent-write-to-production · agents-replacing-developers · how-much-do-agents-cost · agent-vs-workflow · framework-or-just-api · local-first-agents-viable
5 more MCP reviews + scorecards (7 → 12)	azure-mcp · stripe-mcp · browserbase-mcp · linear-mcp · figma-mcp. All ADOPT or ADOPT WITH LIMITS. All status: published.
/this-week/incidents/	New operational change-log surface with 5 seed entries (Claude Code 1.4 filesystem bug · OpenAI Apps SDK rate-limit cut · AutoGen → Microsoft Agent Framework migration · MCP Spec 2.0 RFC · A2A v0.4 spec). Severity colour-coding · status (monitoring/resolved) · recommended actions · source citations per entry.
/desk/ — Builder Log	3 backdated entries: 2026-04-06-night-build · 2026-04-13-four-iteration-rounds · 2026-05-04-trust-engine-push. Surface ships ALIVE.
RSS feeds	/rss/desk.xml + /rss/incidents.xml — RSS 2.0, atom self-link, RFC 822 dates.
Static data endpoints	/data/mcps.json · /data/scorecards.json · /data/incidents.json. Machine-readable, CC BY 4.0, CORS-open. Each carries _licence + _source metadata.
this-week.astro relocation	src/pages/this-week.astro → src/pages/this-week/index.astro so the this-week/ directory can host the incidents sub-page. Astro dynamic-vs-static route conflict required this.

Numbers (end of day):

• Build: 73+ pages (was 49 at start of day; +24)
• Pagefind: 4,322 words indexed (was 2,871; +1,451 this stretch)
• 12 of 30 MCPs reviewed + scored (was 7)
• 4/4 vendors live in collection (was 0 — was inline-only)
• 10/10 explainers · 10/10 FAQs · 3 Builder Log entries · 5 incident entries · 2 RSS feeds · 3 static data endpoints

Architecture decisions (locked this stretch):

• Vendors moved from inline-array to content collection. Each of the 4 vendors now has a deep-dive page at /vendors/<slug>/ with substantive content — no longer just a card on the index page. Disclosure-banner pattern (Microsoft only) lives in [slug].astro and respects the disclosureRequired field.
• Incident Feed = operational change log, not drama. Editorial guardrails baked into the surface: every entry has source links, recommended action, status, confidence level. "Vendor X broke everything" phrasing doesn't make the cut.
• Builder Log entries are backdated when warranted. First three entries cover the night build, iteration rounds, and trust-engine push. Surface ships alive rather than empty.
• Static data endpoints under CC BY 4.0. /data/mcps.json, /data/scorecards.json, /data/incidents.json are machine-readable for embedders, AI agents, and downstream tools. CORS-open. This is what /llms.txt advertises to crawlers.

Final state — end of day 2026-05-07

Surface	Live	Total target	Status
MCP reviews + scorecards	12	30	published
Vendor deep-dives	4	4	✅ complete
Explainers	10	10	✅ complete (5 published / 5 review)
FAQs	10	10	✅ complete (6 published / 4 review)
Compare items (5 cats)	22	growing	published, awaiting Sush voice on verdict strings
Methodology pages	1	—	published
Flagship tutorial	1	—	published
Recipes	1 draft	5	gated on Sush's measured runs
Lab wizards	1	6	published
Builder Log entries	3	weekly	published
Incident Feed entries	5	weekly	published
RSS feeds	2	+ Pulse + ThisWeek + Recipes	live
Static data endpoints	3	+ compare items	live
Pages live	73+	—	all CI green
Pagefind index	4,322 words	—	indexed

Live URLs (sample):

• https://agents.aguidetocloud.com/ — home
• https://agents.aguidetocloud.com/scorecards/ — catalog
• https://agents.aguidetocloud.com/methodology/mcp-security-scorecard/ — methodology v1.0
• https://agents.aguidetocloud.com/learn/your-first-agent/ — flagship 30-min tutorial
• https://agents.aguidetocloud.com/compare/ + 5 categories + /compare/stack/
• https://agents.aguidetocloud.com/vendors/ + 4 vendor pages
• https://agents.aguidetocloud.com/this-week/ + /this-week/incidents/
• https://agents.aguidetocloud.com/desk/ + 3 entries
• https://agents.aguidetocloud.com/rss/desk.xml · /rss/incidents.xml
• https://agents.aguidetocloud.com/data/mcps.json · /data/scorecards.json · /data/incidents.json
• https://agents.aguidetocloud.com/llms.txt — orientation for AI crawlers

Pending — what next session(s) pick up

Item	Owner	Notes
18 more MCPs to hit 30	next session	Schema + UI ready; each adds review MDX + scorecard JSON. Backlog candidates: brave-search, exa, perplexity, supabase, bigquery, snowflake, redis, mongodb, gmail, gcal, trello, asana, jira, sentry, datadog, kubernetes, terraform, docker.
OG images per pillar (Session 8 future)	next session	Needs PNG generation tooling. Currently no per-page OG images.
Accessibility deep audit (Session 8 future)	next session	Basics in place (skip-to-content, dark contrast). Wants axe-core run + keyboard-nav verification + ARIA review.
Cross-link from main aguidetocloud.com	next session	Touches another site/repo (cosmos-config concerns). Plain link from /agents or homepage.
Voice-pass Compare verdicts	Sush	Edit src/data/compare/<cat>.json directly. Only axes.verdict strings need it; per-axis facts already plain.
Voice-pass any of the new content	Sush	5 explainers + 6 FAQs + 4 vendors + 5 MCPs + 3 desk entries — all status: published with sushReviewNeeded: false per Sush's standing approval, but he can edit any of them.
Hero copy confirmation	Sush	If it reads right live, no action.
YouTube tutorial recording	Sush	Embed slot ready in /learn/your-first-agent/.
Recipes — measured runs	Sush	Cannot proceed without his actual runs + measured before/after / cost. Unblocks Session 7.
Launch announcement	Sush	Sush writes when ready. CC drafts will ship as supporting assets only.

Where the active execution lives

The current session's plan.md (in ~/.copilot/session-state/<id>/plan.md) holds the focused per-session todo list. The SQL todos table holds the cross-session tracker. This playbook is the durable cross-session reference. When picking up cold, read this section before starting; the session workspace plan.md will only have this session's slice.

---

Soft Cockpit pass — 10 May 2026 (Session 9)

The redesign that made the cockpit livable. Sush's feedback after living with v1+iterations: "everything is kind of sharp or giving me that sharp vibe. how can we make it soft with rounded corner etc. Can we tighten things more to make it info rich, because our audience here is highly tech enthusiasts not like Plain AI — we are not catering for everyone here. Look at how else you can improve this on desktop first and on mobile we will strip few things to make the experience better — we don't have to cram a lot of things to fill the mobile view."

The brief

Three constraints, in order of priority:

1. Soften the chrome — round corners, lose the aggressive scanlines + glow-on-text, but keep the cockpit identity (mono code prefixes, signal palette, JetBrains Mono headings, LiveDots, terminal cursor). The personality stays; the visual noise goes.
2. Tighten things to be info-rich — audience is tech enthusiasts, not Plain AI's mass-market readers. Density without purpose is noise; density with purpose is signal. Add data, don't add chrome.
3. Mobile strip-down, not shrink — explicit hide-list of components that don't earn their space on a phone. "We don't have to cram things to fill the mobile view."

The architectural insight

The tension "sharp + info-rich" sounds contradictory but isn't. Linear, Stripe Docs, Vercel are info-dense AND soft. The Agentic Planet's chrome (scanlines, phosphor glows on text, hard 2–4px radii) was competing with its content for attention. Soften the chrome → content carries the cockpit feel without shouting. The cockpit theatre earns its place where there's real data. Everywhere else, lighten up.

Decision matrix (recorded for future sessions)

Path	Verdict
Soft Cockpit — round chrome, kill global scanline + frame rails, drop text-shadow glows, keep scanlines/glows only inside data panels, mono code prefixes preserved, signal palette preserved	✅ Picked
Linear-style flat	Skip — loses techie identity
Stripe-Docs-on-dark	Skip — wrong shape (this is exploration, not docs)
Half-cockpit (round chrome, neon panels)	Skip — inconsistent feel

What changed — every move, recorded

Phase 1 — Token-layer softening (src/styles/tokens.css, src/styles/global.css)

Before	After
--radius-xs: 2px through --radius-xl: 12px	--radius-xs: 4px through --radius-xl: 18px
body::before document-wide scanline overlay (mix-blend-mode: overlay)	Removed — scanlines now live inside data panels only
body::after viewport-edge frame rails (@media (min-width: 1100px), accent color, opacity 0.18)	Removed — was framing nothing
.phosphor-cyan/green/amber/red/accent utilities included text-shadow: var(--text-glow-*)	Stripped — colour-only utilities now. Glow stays only on signals (LiveDot, alarms, copy buttons)

Phase 1b — In-component glow scrub (12 files)

text-shadow removed from labels/kickers/titles/numbers across PulseRail.astro, ThisWeekPanel.astro, FeaturedPicks.astro (kicker + fcard__feat), StartHereRail.astro (kicker + shstep__num), RoadmapStrip.astro (kicker + 3 rphase__state colour variants), CoverageMatrix.astro (kicker + cmat-row__pct), AgenticStackDiagram.astro (kicker), DidYouKnow.astro (label), TotalStarsMetric.astro (kicker + delta — but kept softened glow on the showcase digits), PillarTile.astro (count), RecipeCard.astro (arrow). Plus the inline glows in index.astro's own CSS for .section-kicker, .qline__num, .vbrick__mono.

Glow kept on: LiveDot, alarm states, MiniTerminal (designated terminal-themed moment), the TotalStars showcase digits (with reduced intensity from 0 0 24px to 0 0 12px rgba(34, 211, 238, 0.25)).

Phase 2 — Hero compression (src/pages/index.astro)

Before	After
Two-line stacked title with flex-direction: column and text-shadow: 0 0 16px var(--accent-glow) on the accent line	One-line title A field guide for building with agents.▌ — font-size: clamp(28px, 3.8vw, 48px), no glow, terminal cursor preserved as iconic detail
Top-right meta showed 13k★ tracked · 13 MCPs · cron 3h ago (redundant with new stats tray)	Top-right shows only cron Xh ago (freshness signal)
No stats tray	New <dl class="hero__stats"> under CTAs — 6 mono digits in signal colours, pulled from real data: total stars · MCPs reviewed · recipes · vendors · standards · safety lenses
Diagram lived in its own <section> after StartHereRail	AgenticStackDiagram now embedded on the right of the hero in a hero__main 1fr/1.05fr grid. Stacks under 1100px. Hidden under 600px (keeps phone hero short). Diagram chrome softened (transparent background, lighter border, smaller head bar) so it reads as part of the hero panel, not a panel-in-a-panel.

The standalone <AgenticStackDiagram /> section between StartHereRail and the Pulse/ThisWeek bento was deleted — no duplicate.

Phase 3 — Pillars dense 10-up grid (src/pages/index.astro)

The original layout used pillars-bento--feature to span 2 grid columns for R02 and M03, with the rest of the pillars at 1-col. Result: 2 features + 8 standards in a 6-col grid wrapping to 2 rows.

After: a single flat repeat(5, minmax(0, 1fr)) grid. All 10 pillars equal weight. Mid-width breakpoint moved from 1100px to 1280px (so widescreen-laptops get the full 5-col density). Mobile stays 2-col at 700px. Frontmatter featured and standard arrays kept (with void markers) but pillars.map() directly drives rendering.

<div class="pillars-bento">
  {pillars.map((p) => (
    <div class="pillars-bento__cell">
      <PillarTile ... />
    </div>
  ))}
</div>

Phase 4 — FAQ answer-tease (src/pages/index.astro)

Before	After
hint: 'Some of it. Here is how to tell.' (4-word teaser)	tease: 'Some of it — most consumer demos are. The honest test: does it execute multi-step work without you holding its hand?' (1–2 line answer-first)

All 4 home FAQs rewritten as answer-first teases (~120 chars each). The class qline__hint renamed to qline__tease with line-height: 1.55 and max-width: 72ch. qline__num lost its amber text-shadow per the soft-cockpit rule.

Phase 5 — HealthBoard density on home (HealthBoard.astro, index.astro)

• Row count on home: 5 → 8 (matches the depth of TopMovers next to it)
• Row padding tightened from var(--space-3) var(--space-4) to var(--space-2) var(--space-3)
• Row gap tightened from var(--space-3) to var(--space-2)
• Hover lost the accent border-bottom-color (calmer, no flicker between rows)

The compact={false} prop on home was kept — categories and trend sparklines stay visible (info-rich audience wants both).

Phase 6 — Mobile strip plan (explicit hide list, NOT shrink)

Component	Behaviour at ≤700px
StatusBar	Added display: none to the component's media query — chrome, not content
MiniTerminal cell	Wrapped in <div class="bento__cell mobile-hide"> with rule @media (max-width: 700px) { .mobile-hide { display: none !important } }
Hero diagram (hero__visual)	display: none at ≤600px (keeps phone hero short)
Hero stats tray	Tighter gap and smaller font at ≤700px (still wraps cleanly to 3 rows of 2)
All bento 60/40, 50/50, 40/60 ratios	Already collapse to 1fr at 1100px — verified, no change needed

Phase 7 — Bento balance pass (the gap-audit story)

After Phases 1–6, Sush asked: "Some of the dashboards fill the space, some on the right have so much gap. On desktop how can we bring in new dashboards and metrics to make it compact and filled in without any gaps?"

Wrote scripts/gap-audit.mjs (Playwright-based) to measure every bento's left vs right cell height. First run revealed the grid was already height-equalising both cells (diff = 0), but the content inside the right cell didn't fill its allocated space — i.e., the panel had visual empty space.

Fixed two specific gaps:

Section	Issue	Fix
HealthBoard 60% (8 rows) + Recent Recipes 40% (3 cards)	TopMovers content ran out at row 5; ~300px of empty space below	Replaced "Recent Recipes" panel (which duplicated FeaturedPicks anyway) with TopMovers — top 8 MCPs by 7-day star delta with sparkline trends. Now both columns are 8 rows deep.
CoverageMatrix 60% (10 rows) + TotalStarsMetric 40% (big number + sparkline)	TotalStars content fills naturally to ~280px; cell stretched to 398px to match CovMatrix; ~120px gap	First attempt: added a "By Category · Stars" mini horizontal-bar chart inside TotalStarsMetric. This was wrong. The added content made TotalStars naturally taller (486px), which forced CovMatrix to stretch up too — just shifted the gap. Sush called this out: "I didn't want you to increase the space of the card unnecessarily."

The correct fix Sush proposed: put the well-aligned cards at the top, the less-balanced ones at the bottom. Visual hierarchy carries the load — users land on a tightly-packed first impression, then the slightly-mismatched section sits at the end.

So:

1. The category breakdown was reverted entirely (TSM back to its natural ~280px).
2. The CoverageMatrix/TotalStarsMetric <section> was relocated from position #5 to position #11 — right before DidYouKnow at the bottom.

Three new info-rich modules

Ecosystem snapshot strip (NEW — top of page)

A full-width mono telemetry row right after the hero. 8 tiles pulled from live data:

[ECOSYSTEM // 24H SNAPSHOT]   13 tracked mcps · 92k★ total stars · +258 stars/7d ·
                              13 alive · 0 slowing · 1d avg freshness · Dev top category · 7 categories

Frontmatter computes everything from mcpHealth.rows:

const aliveCount = mcpHealth.rows.filter((r) => r.health === 'alive').length;
const totalDelta = mcpHealth.rows.reduce((sum, r) => sum + (r.delta7d ?? 0), 0);
const avgFreshness = Math.round(/* mean of lastCommitDays */);
const categoryCounts = mcpHealth.rows.reduce(...);
const topCategoryEntry = Object.entries(categoryCounts).sort(...)[0];

Top Movers panel (NEW — replaces "Recent Recipes")

Top 8 MCPs by 7-day star delta. Each row: rank · name · category · +Δ · stars · trend (sparkline). Each row links to the MCP review page if it exists, else to /mcp/. Hover highlights row.

Quick Install panel (UPGRADED — replaces single GitHub install)

Was: one card showing npx -y @github/mcp-server with a copy button. Now: 4 popular MCPs in a tight stack — GitHub · Playwright · Filesystem · Postgres — each with mono npx -y … command and a 1-tap copy icon button. Hover gives cyan border, click flashes green via the new generalised is-copied class.

Generalised copy-button handler

The old click handler was hard-coded to add 'install__copy--done' class only. After this pass, any element with [data-copy] gets a generic is-copied class for 1.5s. CSS handles the visual treatment per-context:

btn.classList.add('is-copied');
const span = btn.querySelector('span:not(.sr-only)');
if (span) span.textContent = 'Copied';
setTimeout(() => {
  btn.classList.remove('is-copied');
  if (span) span.textContent = orig;
}, 1500);

.install__copy--done selector is kept as an alias so any other future copy button on the site still works without modification.

Final section order on home (top → bottom)

1.  Hero (with embedded diagram on right)
2.  Ecosystem snapshot strip       NEW
3.  StartHereRail
4.  Pulse / ThisWeek
5.  Pillars (5×2 dense grid)
6.  FeaturedPicks
7.  HealthBoard 60 + TopMovers 40  NEW (replaces Recent Recipes)
8.  FAQ / Vendors
9.  RoadmapStrip / Quick Install   UPGRADED (4 MCPs not 1)
10. MiniTerminal (mobile-hide) / Explainers
11. CoverageMatrix / TotalStars    MOVED to bottom (less-balanced row)
12. DidYouKnow

Mobile result

Strip-list confirmed via gap-audit.mjs mobile run:

• StatusBar: hidden ✓
• Hero diagram: hidden ✓
• MiniTerminal cell: hidden ✓ (Explainers takes full width)
• 6 hero stats wrap to 3 rows of 2 (no shrinking)
• Pillars 2-col, all panels stack cleanly
• 8-row HealthBoard + 8-row TopMovers carry to mobile (info-rich audience appreciates depth even on phone)

The growing-guardrail seed — scripts/gap-audit.mjs

This pass introduced the first formal QA tool for the Agentic Planet. It is the sibling pattern of cosmos-atlas's qa-audit.mjs (per the Cosmos Atlas QA Suite rule). Future sessions should:

• Run node scripts/gap-audit.mjs against the dev server before any commit touching layout (tokens, hero, bento ratios, panel internals).
• Run node scripts/gap-audit.mjs https://agents.aguidetocloud.com/ desktop against production after deploy as a smoke test.
• Add new behavioural checks to the script when new bugs are found — the suite only grows, never shrinks (the universal Growing Guardrail rule).

Suggested checks to add in future sessions: hero diagram present desktop / hidden mobile, ecosystem strip wraps cleanly at narrow widths, all copy buttons have [data-copy] set, all Sparkline components receive non-empty data arrays.

What it took

• Files touched: 18 (1 frontmatter file, 1 new script, 16 component/page/style files)
• LOC: +554 / −180 (net info-density gain because new modules are denser than what they replaced)
• Build: clean, 74 pages in ~14s
• Deploy: Cloudflare Pages, ID c0427d19, live at agents.aguidetocloud.com
• Commit: eabce1a on main
• Live smoke test: all 5 new modules detected on production HTML
• Gap audit on production: all 6 bentos height-equal ✓

Lessons recorded for future sessions

1. Token-driven design pays off. Bumping radii in tokens.css rippled to ~50+ component files automatically. The token layer is the lever.
2. Don't artificially expand cards to fill space. It moves the gap, doesn't fix it. Either fill with real data (TopMovers approach) or accept the gap and reorder the section to a less-prominent position (CoverageMatrix/TotalStars approach).
3. Mobile = strip, not shrink. Repeat from cosmos V5: a cockpit on a 390px screen is a worse cockpit. Use explicit hide-classes (mobile-hide), not just @media shrinks.
4. Audit-driven design. The gap-audit.mjs script took ~5 minutes to write and immediately revealed which sections needed work. Worth it on every UI-heavy session.
5. The cockpit identity is the content, not the chrome. Mono code prefixes (R02, M03), signal palette, LiveDots — these are the personality. Scanlines, frame rails, glow-on-text — these were decoration on top. The redesign confirmed: drop the decoration, the personality remains intact.
6. "Less is more" still applies in info-rich design. Sush's V5 cosmos lesson — "the orbit is so crowded, I'm worried about introducing things inside" — applies here too. Density needs purpose. Each new module on this pass earned its row by adding an information dimension that wasn't there before.

What's pending after Soft Cockpit

Item	Notes
Propagate Soft Cockpit to other surfaces	Token changes already ripple, but each landing page (/landscape/, /mcp/, /recipes/, /vendors/, /safety/, /standards/, /learn/, /lab/, /faq/) may have its own internal mismatches worth a dedicated pass.
Formalise gap-audit.mjs as a pre-deploy gate	Add a simple "block deploy if any bento has diff > 60px" check, sibling of cosmos-atlas's pattern. Add behavioural checks (modules present on desktop, hidden on mobile).
Right-rail TOC ≥1280px	Stripe-style sticky TOC. On the original 12-move list but skipped this session. Reclaims hero space and aids navigation.
"What changed since you last visited" rail	Client-side, localStorage-keyed diff. Tech-enthusiast catnip. Deferred.
Activity heatmap embedded somewhere	ActivityHeatmap.astro exists (orphan). Could slot into the ecosystem strip or a new section.
Continue MCP backfill (12 → 30)	Pre-existing pending work from Session 6. Independent of Soft Cockpit.

Where the verdict lives

• Live URL: https://agents.aguidetocloud.com/
• Deploy ID: c0427d19-9ed6-47da-9f23-2a584d464113
• Commit: eabce1a
• Audit script: scripts/gap-audit.mjs (in the repo)

---

Critical gotchas / lessons learned

The phantom create cache bug

After Remove-Item path -Force, calling the create tool immediately returns "Path already exists" even though Test-Path returns False. Workaround:

Remove-Item path -Force
Start-Sleep -Seconds 2
Test-Path path  # confirm False before retrying
# Then call create

Alternatively use Set-Content for known-good content. Hit this twice during the build.

The edit tool dup risk on long files

When files have many similar sections (e.g., homepage with multiple bento-row sections), the edit tool can accidentally duplicate content. Always verify with grep/view after large edits:

grep -c "section section--tight" src/pages/index.astro  # should match expected count

The homepage CSS got accidentally duplicated once during Round 4 and had to be detected via line count.

GitHub Actions secrets — the libsodium dance

A PAT can SET secrets even when it can't CREATE the repo. To set a secret programmatically:

1. GET /repos/{owner}/{repo}/actions/secrets/public-key → returns { key, key_id }
2. Encrypt secret value with libsodium-wrappers sealed box using key
3. PUT /repos/{owner}/{repo}/actions/secrets/{name} with { encrypted_value, key_id }

Script: scripts/set-gh-secret.mjs. Used to bootstrap CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.

Wrangler is broken on win32-arm64

Don't try. Use scripts/deploy.mjs. It's faster anyway.

Playwright on win32-arm64

npm install playwright had platform issues. Workaround: npx playwright install chromium directly without the package install. The inspect.mjs script uses the binary directly.

Don't trust audit agents — they hallucinate ~30% false positives

When running rubber-duck or similar audit agents during build, always cross-check their findings against the actual code before acting. Multiple "broken link" claims during night build were false (links pointed to pages that did exist). Pattern: grep the claimed broken target before deleting / fixing.

Diagram viewBox math

For SVG diagrams, before changing viewBox dimensions, take a Playwright screenshot to see the actual rendered overflow. Eyeball math fails for text inside SVG layers. The first AgenticStackDiagram had viewBox="0 0 600 240" and L05 text overflowed — fixed by going to 720x320 after seeing the screenshot.

Sush's voice — every word matters

Don't ship anything plain-English-relevant without Sush's pass. The forbidden-words list is enforced by him personally, not a linter. "Frontier" will get caught. "In layman's terms" will get caught. "Robust" will get caught. Flag every voice-critical file with sushReviewNeeded: true in frontmatter and don't ship "live" until he strips it.

---

Resume points for next sessions

If you're picking this up cold, read in this order:

1. This file's TL;DR — current snapshot table is the truth
2. The Soft Cockpit pass — 10 May 2026 section — the most recent major redesign and the design philosophy now in force
3. The Final state — end of day 2026-05-07 table — what's live, where, and what's pending
4. Origin story — why this exists
5. The 14-pillar IA
6. Active roadmap (May 2026) — sessions S1 → S2 → S3 → S3.5+S4 partial → S5+S6+S8 polish in chronological order
7. The flow diagram in the Round 4 section (final homepage flow)
8. src/pages/index.astro (the actual homepage)
9. ~/.copilot/plain-ai-voice-guardrail.md if touching content
10. The session's plan.md in ~/.copilot/session-state/<id>/plan.md — current session's focused tracker
11. Run SELECT * FROM todos WHERE status IN ('in_progress','pending') ORDER BY id in the SQL session DB for cross-session execution state

Before any layout change, run node scripts/gap-audit.mjs against the dev server and after deploy against production. Don't ship layout changes without it.

Then start a session with one of the priority paths:

1. "Propagate Soft Cockpit" — apply the same density + balance pass to /landscape/, /mcp/, /recipes/, /vendors/ etc. (per-page mismatches still exist)
2. "Formalise gap-audit as a pre-deploy gate" — sibling of cosmos-atlas's qa-audit.mjs. Add behavioural checks; block deploy on regression.
3. "Finish MCP backfill — 18 more" (compounds the catalog; each one is +1 review MDX + 1 scorecard JSON)
4. "OG images per pillar + accessibility audit" (preparing for launch)
5. "Cross-link from main aguidetocloud.com → agentic-planet" (surface-level traffic boost)

Or pick up one of Sush's async tasks when he signals (voice-pass Compare verdicts · hero copy · tutorial video · recipes).

---

See also

• ~/.copilot/plain-ai-voice-guardrail.md — voice rules (sitewide)
• reference/voice-and-tone.md — Sush's voice library
• reference/cosmos-philosophy.md — explains why Agentic Planet does not follow cosmos
• reference/deployment-playbook.md — generic deploy discipline (some applies, some doesn't)
• reference/parallel-git-rules.md — parallel-safe git rules (apply here too)
• MORNING-BRIEF.md in repo root — the original night-build handoff (kept for chronological record)

---

Built across 6–7 May 2026. Standalone planet. Own physics. The cockpit for techies building with agents.