🌌 Cosmos Audit & Resume Doc¶
Read me first. This page exists because unifying voice, docs, and navigation across 7 planets is a multi-session project. If a session ends with work in flight, the next session reads this file to know where we are and what's next.
How to use this page
- Read top to bottom on first encounter.
- Glance at the Status Table to see which planets are current and which still drift.
- Run
SELECT id, title, status FROM todos ORDER BY status, idagainst the session DB to see the live task list. - Pick the first
pendingtodo whose dependencies are alldone. - Update this doc when something material changes — every session must leave this page accurate.
Established: 8 May 2026 — session "Unify Planet Voice And Docs".
The mission, in one sentence¶
Bring relation and voice parity across all the planets we build, even when each planet keeps its own visual atmosphere and internal rules — because the belief is the same across the whole universe.
What's stable (don't relitigate)¶
These are the foundations. Future sessions inherit them; do not redesign without Sush.
| Foundation | Where it lives | What it says |
|---|---|---|
| Cosmos Philosophy | reference/cosmos-philosophy.md | Earth + Moon + planets + stars + nebulae metaphor. Universal laws (quality, value, usability, honesty, don't-collide, no-paid-content-on-free-pathways). Each planet picks its own atmosphere. |
| Cosmos Nav Playbook | reference/cosmos-nav-playbook.md | The cross-planet navigation rail. 4-icon shared masthead contract. How to render a planet's icon in another planet's atmosphere. |
| Cosmos Config Manifest | reference/cosmos-config-manifest.md | The [cosmos] block in planets.toml/json — newsletter URL, feedback link, parent site. Single-source-of-truth pattern. 5 mirror files. |
| Voice & Tone (Sush) | reference/voice-and-tone.md | Sush's belief-led voice. Honesty over charm. No gatekeeping. Plain English. Brag-allergy. Phrasing fingerprints. This is the belief language all planets must echo even in their own dialect. |
The 7 planets (current truth as of 8 May 2026)¶
| # | Planet | Identity | Domain | Status | Overview doc | Playbook |
|---|---|---|---|---|---|---|
| 1 | 🌍 Earth | A Guide to Cloud — the home, soft, patient, giving | aguidetocloud.com |
LIVE | ✅ cosmos/earth/index.md | (no separate playbook — cosmos-philosophy + voice-and-tone are the de-facto Earth playbook) |
| 1a | 🌑 Moon (Guided) | The paid moon — accessibility-priced cert prep, $9 | aguidetocloud.com/guided/ (integrated into Earth) |
LIVE | ✅ cosmos/earth/guided.md | playground/guided/ |
| 2 | 🪐 CMD (formerly Brain Bar) | Microsoft jargon AND error code decoder — $_ launcher, terminal atmosphere |
cmd.aguidetocloud.com |
LIVE | ✅ cosmos/cmd/index.md (migrated from brain-bar/ with rebrand applied) |
reference/brain-bar-lessons.md (file kept under legacy name — content current) |
| 3 | 🪐 Shift | The AI job-change wire — newspaper atmosphere, cream paper | shift.aguidetocloud.com |
LIVE | ✅ cosmos/shift/index.md | reference/shift-playbook.md |
| 4 | 🪐 Plain AI (formerly working name "AI for Grandma") | AI explained plainly, for everyone — dark-default, gradient-mesh covers | plainai.aguidetocloud.com |
LIVE | ✅ cosmos/plain-ai/index.md | reference/plain-ai-playbook.md |
| 5 | 🪐 Agentic (standalone — own physics) | The agent cockpit field-guide for techies | agents.aguidetocloud.com |
LIVE | ✅ cosmos/agentic/index.md | reference/agentic-planet-playbook.md |
| 6 | 🪐 Claw (standalone — own physics) | Plain-English study reference for OpenClaw | claw.aguidetocloud.com |
LIVE under noindex |
✅ cosmos/claw/index.md | reference/claw-planet-playbook.md |
| 7 | ⭐ MCP Move (invisible star) | MCP server exposing the universe to AI agents | mcp.aguidetocloud.com/mcp |
LIVE | (no human surface — see CMD docs) | (lives inside CMD's playbook) |
| 8 | 🌌 Cosmos Atlas (meta-layer planet) | Bold living solar system map of the cosmos | cosmos.aguidetocloud.com |
LIVE 8 May 2026 | ✅ cosmos/atlas/index.md | cosmos/atlas/v1-shipped.md + deploy-playbook.md |
Locked decisions (8 May 2026 session)¶
These were resolved with Sush this session and must not be reopened without him.
- CMD is the official brand. Brain Bar is the legacy/working name and is preserved only as history. The folder
learn-docs/brain-bar/is being renamed tolearn-docs/cosmos/cmd/. The slugbrainbarinplanets.tomlis kept for now to avoid breaking skip-self filter logic on each planet's nav code. The user-facingnamefield has been updated "Brain Bar" → "CMD" across all 5 manifest mirrors. A future session should audit the slug usage and migrate tocmdwhen safe. - Guided is Earth's Moon — integrated chrome, distinct identity. Per One Body Two Organs rule, Guided shares Zen tokens, nav, footer, and theme with Earth. BUT for cross-planet referencing, Guided gets its own logo/icon and its own entry in the cosmos manifest. This is a navigation-and-attribution decision, not a code structure change.
- Doc structure standard going forward. All planet docs follow this layout:
learn-docs/docs/cosmos/<slug>/index.md— overview / planet identity / what it is in one screenlearn-docs/docs/cosmos/<slug>/playbook.md— deep operational doc (extend / audit / deploy / voice / gotchas)learn-docs/docs/cosmos/<slug>/status.md(optional) — current production state, pending steps, pipelinelearn-docs/docs/cosmos/<slug>/<other>.md(optional) — roadmap, lessons, content-review, etc.- All planet-specific docs live under
cosmos/<slug>/. Cosmos-wide docs (philosophy, nav playbook, config manifest, audit, voice-and-tone) stay inreference/. - Earth gets its own playbook-shaped overview so its belief, voice anchors, and brand promise are documented the same way every other planet's are.
- Cloud Café is NOT a planet. It will be explicitly listed in the "Common confusions" section below.
- 🆕 Universal manifest rule (8 May, second exchange). Sush decided: every planet joins
planets.toml— including Earth, Guided (the moon), CMD, Shift, Plain AI, Agentic, Claw, and any future planet. The "standalone — own physics — doesn't follow cosmos rules" framing in the original Agentic and Claw playbooks is partially overridden: their visual atmosphere autonomy stays (own fonts, colours, layout, voice register) but their manifest participation is now mandatory. Manifest membership ≠ visual conformity. - 8 of 8 planet-specific reference files moved. All planet playbooks, lessons, roadmaps, and curriculum kickoff prompts have been moved from
reference/<slug>-...mdintocosmos/<slug>/<file>.md. Redirect stubs left at the old paths so livelearn.aguidetocloud.com/reference/...URLs keep resolving for old links.
🛡️ The GUARDRAIL — for every future session¶
Every future Copilot CLI session that does any planet doc work must obey these rules. Print them in the session journal entry if you change anything in the cosmos.
| # | Rule | Why |
|---|---|---|
| 1 | Read cosmos-audit.md first when picking up planet work cold |
This is the resume artefact; it tells you what's done and what drifts |
| 2 | All planet-specific docs live under learning-docs/docs/cosmos/<slug>/ |
One canonical place per planet. Don't scatter into reference/. |
| 3 | Cosmos-wide docs stay in learning-docs/docs/reference/ |
Philosophy, nav playbook, config manifest, voice-and-tone, audit. These govern the universe, not one planet. |
| 4 | Every planet joins planets.toml |
New planet = add to all 5 manifest mirror files in same commit. Even standalone-physics planets (Agentic, Claw) participate in the manifest. |
| 5 | Atmosphere autonomy is preserved | A planet's own fonts, colours, layout, voice register stay its own. Manifest participation is data-shaped, not visual conformity. |
| 6 | Don't move existing playbooks again | They were moved 8 May 2026. The redirect stubs in reference/ keep old URLs alive. Future moves break things. |
| 7 | Update cosmos-audit.md when material state changes |
The Status Table and Locked Decisions must stay accurate. If you don't update this file, you owe the next session an apology. |
| 8 | Never weaken the SLA discipline on Earth's paid products | Practice exam SLA is non-negotiable. Cosmos law #6 (no paid content via free pathways) is non-negotiable. |
| 9 | mkdocs build --strict must exit 0 before committing any cosmos doc change |
If it fails, fix before pushing. |
| 10 | 5-file mirror commit discipline | Any change to [cosmos] config or [[planets]] entries must update all 5 manifest files (aguidetocloud-revamp/data/planets.toml, aguidetocloud-revamp/brainbar/data/planets.toml, guided/src/data/planets.json, shift/src/data/planets.json, plainai/content/planets.json) in the same commit. Phase 4 will add agentic + claw mirrors as planet 6 and 7. |
If you violate any of these rules without a written exception by Sush, revert your change.
Status table — by phase¶
Source of truth for live status: SQL
todostable in this session's database. This table is a snapshot for human reading.
Phase 1 — Structural docs cleanup (this session)¶
| Todo ID | Title | Status |
|---|---|---|
| p1-resume-doc | Create master resume doc | done |
| p1-cosmos-folder | Create cosmos/ folder + index hub | done |
| p1-earth-overview | Earth planet overview doc | done |
| p1-guided-moon-doc | Guided moon doc | done |
| p1-cmd-rename | CMD rename — folder + content | done |
| p1-shift-overview | Shift overview doc | done |
| p1-plain-ai-link | Plain AI overview reorganised | done |
| p1-agentic-overview | Agentic overview doc | done |
| p1-claw-overview | Claw overview doc | done |
| p1-openclaw-retire | Retire openclaw placeholder | done |
| p1-mkdocs-nav | Update mkdocs.yml Cosmos nav | done |
| p1-cloud-cafe-note | Document Cloud Café is not a planet | done (in cosmos-audit + cosmos/index.md) |
| p1-planets-toml-add | Add Agentic + Claw to planets.toml | deferred — needs Sush decision (see Open Questions below) |
| p1-build-verify | Build mkdocs strict + verify | done — mkdocs build --strict exits 0 as of 8 May 2026 |
Phase 1 SHIPPED — 13 of 14 todos done, 1 deferred for Sush. Site builds clean. No deploy yet (intentional — content review first).
Phase 4a — Logo audit¶
| Todo ID | Title | Status |
|---|---|---|
| p4a-walk-planets | Walk every planet for brand mark inventory | done |
| p4a-test-hypothesis | Test family-signal hypothesis (mark = working interface element) | done |
| p4a-write-audit | Write cosmos/logo-audit-2026-05-08.md |
done |
| p4a-mkdocs | Add audit to mkdocs Cosmos nav | done |
| p4a-update-cosmos-audit | Update this Status Table → Phase 4a ✅ DONE | done |
| p4a-update-voice-drift | Update voice-drift Phase 4 inputs to point at audit | done |
| p4a-strict-build | mkdocs build --strict exits 0 |
(this session — runs after edits) |
Phase 4a SHIPPED — 8 May 2026. Inputs ready for Phase 4b (logo design — Sush direction needed on Agentic redesign + Guided crescent decision + Earth refine decision) and Phase 4c (cosmos-rail expansion from 4 to 7 slugs across 5 mirrors).
Phase 4b — Logo design (8 May 2026)¶
| Todo ID | Title | Status |
|---|---|---|
| p4b-decision-agentic | Sush picks cockpit-class direction | done — Option B Signal LED |
| p4b-decision-guided | Sush picks crescent / refine / Moon-class | done — Option A keep crescent for rail/atlas; Lotus for tab+masthead per Universal Law #7 |
| p4b-decision-earth | Sush picks lotus / refine | done — Option A keep lotus emblem |
| p4b-decision-plainai | Sush picks fill / outline | done — Option A fill everywhere |
| p4b-design-agentic | Design Signal LED SVG | done (commit da9da14 agentic-planet) |
| p4b-design-guided | Refine crescent (only if needed) | done — no new design, adopt existing kit |
| p4b-refine-earth | Refine lotus (only if needed) | done — no refinement, lotus stays |
| p4b-harmonise-plainai-fav | Harmonise fill/outline | done — fill everywhere |
Phase 4b SHIPPED — Sush mockup decisions delivered as phase4b-mockups.html in session-state files; picks reduced to 3 letters (B/A/A); Universal Cosmos Law #7 (lotus-as-default) codified into cosmos-philosophy.md from Sush's brand-rule call.
Phase 4c — Cosmos rail implementation (8 May 2026)¶
| Todo ID | Title | Status |
|---|---|---|
| p4c-add-3-icons-5-mirrors | Add guided/agentic/claw to all 5 mirrors | done — 4c.1 + 4c.2 (commits a296596 cd71094 0135e16b c0170eb) |
| p4c-update-typed-unions | Astro typed unions 4-slug → 7-slug | done (in same commit set) |
| p4c-wire-guided-masthead | Replace lotus img with crescent | done — RESOLVED no-op per Universal Law #7 (lotus IS correct on host-identity surfaces; crescent is rail/atlas only) |
| p4c-update-nav-playbook | Update playbook 4-icon → 7-icon | done — prepended dated update section (commit 7b1743f) |
| p4c2-plainai-mirror | Plain AI build-shared.mjs (deferred from 4c.1) | done — 5th mirror landed (commit c0170eb) |
| quickwin-guided-fav-swap | Guided Astro placeholder → lotus | done (commit e065588) |
| quickwin-earth-fav-swap | Earth ☁️ → lotus | done (commit 1cdab7b8) |
| quickwin-plainai-labels | Delete PLAINAI_PLANET_LABELS drift surface |
done — bundled with 4c.2 (commit c0170eb) |
Phase 4c SHIPPED — 8 May 2026. All 5 cosmos icon palette mirrors handle 7 slugs. Brand-mark surfaces unified across favicons + mastheads + cosmos rails per Universal Law #7. Drift score: was 15 (14 icon gaps + 1 label), now 0.
Phase 5 — Manifest expansion + governance (8 May 2026)¶
| Todo ID | Title | Status |
|---|---|---|
| p5-drift-audit-script | Cosmos-wide drift audit script | done (commit aad449c) — learning-docs/scripts/cosmos-drift-audit.mjs |
| p5-onboarding-checklist | New-planet onboarding checklist in cosmos-audit | done — 10-step checklist added (commit 7b1743f) |
| pre-mkdocs-anchors | Fix 5 mkdocs --strict anchor warnings | done — all 5 cleared (commit 03be532) |
Phase 5 SHIPPED — 8 May 2026. Governance guardrail in place. New-planet onboarding checklist published. Mkdocs strict zero anchor warnings. Future cosmos sessions inherit these guardrails by default.
🟢 COSMOS UNIFICATION COMPLETE — 8 May 2026. 19/19 todos shipped across Phases 1, 1.5, 1.6, 2, 3, 4a, 4b, 4c.1, 4c.2, 5. Drift score 0. Universe is data-shaped + visually-shaped + voice-shaped + governance-shaped.
Phase 6+ — what's next (the roadmap from here)¶
Read cosmos/next-up-from-2026-05-08.md first when picking up cosmos work after 8 May 2026.
Sush flagged 7 workstreams to build on top of the unified foundation:
| # | Workstream | Status | Cheapest first step |
|---|---|---|---|
| A | 🌌 Cosmos Atlas — interactive map page rendering all 7 planets | 🟡 in flight (parallel session, Phase 0+1 shipped) | Pick up parallel session's atlas/ folder; use drift audit as parity check |
| B | 🪐 Phase 4d — Agentic + Claw two-way cosmos rail | 🔴 not started | Vendor sibling icon palette into both repos + add cosmos rail UI to their mastheads |
| C | 🔗 Cross-planet About cross-linking (deeper) | 🟢 baseline shipped (Phase 3 prose); next: persistent footer/sidebar with named chips | Pick a surface (footer vs sidebar); render 6 sibling chips on every planet |
| D | 🔍 SEO across the cosmos | 🔴 per-planet exists; cosmos-as-family does not | Sitemap cross-linking + JSON-LD Organization schema (cheapest, biggest win) |
| E | 🌐 New custom domain purchase | 🟡 Sush decision pending | Pick candidate planet + domain; check Universal Cosmos Law #7 for Earth-family vs graduated planet semantics |
| F | 🎙️ Voice re-audit (cycle 2) | 🟢 cycle 1 shipped 8 May; defer until post-atlas/4d/footer content has landed | Re-run the voice-drift-2026-05-08.md audit pattern, save as voice-drift-2026-MM-DD.md |
| G | 🪶 Misc + tooling polish | 🔴 backlog (apple-touch SVGs · OG generators · drift audit CI cron · cosmos SVG sprite sheet · cosmos-index.json star) |
Pick whichever fits the session's slack |
The next-up doc has each workstream's foundation, scope, file pointers, and recommended next steps. It's the canonical "what would I do if I were a future Copilot session picking up cold?" answer.
Files created:
- docs/reference/cosmos-audit.md (this file — the resume artefact)
- docs/cosmos/index.md (the planet hub)
- docs/cosmos/earth/index.md + guided.md (Earth + the Moon)
- docs/cosmos/cmd/index.md + status.md (CMD, migrated from brain-bar/ with full rebrand applied)
- docs/cosmos/shift/index.md, cosmos/plain-ai/index.md, cosmos/agentic/index.md, cosmos/claw/index.md
Files updated:
- docs/brain-bar/index.md + status.md → redirect stubs
- docs/plain-ai/index.md → redirect stub (status.md kept in place under old folder)
- docs/openclaw/index.md → disambiguation page (OpenClaw runtime ≠ Claw Planet)
- mkdocs.yml → Cosmos nav rewritten with full ordered list of 7 worlds; cosmos-audit.md added to Reference section
Open questions (need Sush)¶
(All previously open questions resolved as of 8 May 2026. Recorded here for history.)
✅ RESOLVED 8 May 2026 — Should Agentic + Claw join the cosmos manifest?¶
Answer: YES. Sush's lock: "yes and for guided and any new planets too."
Implementation (done this session):
- planets.toml and 4 JSON mirrors now contain 7 entries: earth, guided, brainbar (display name "CMD"), shift, plainai, agentic, claw.
- Visual atmosphere autonomy of standalone-physics planets (Agentic, Claw) is preserved per Cosmos Philosophy.
- Phase 4 will add agentic and claw mirrors of the manifest when those planets start rendering the masthead rail back. Until then the rail is one-way (cosmos-bound planets render the full 7; agentic + claw don't render the rail).
- Universal rule now formalised: see GUARDRAIL #4 above.
Phase 2 — Voice parity audit (NEW SESSION)¶
Goal: identify drift from Earth's belief language across each live planet's homepage + about page. Each planet keeps its own register (terminal-blunt for CMD, plain-English-explainer for Plain AI, newspaper for Shift, etc.) but the underlying belief (no gatekeeping, plain English, honesty, "for people like us") must show through.
✅ DONE — 8 May 2026. Audit shipped at cosmos/voice-drift-2026-05-08.md.
Headline findings:
- Hero copy is on-brand across all 7 planets. Drift is concentrated in 3 places.
- 🔴 Agentic + Claw lack
/about/pages. Phase 3 P0. - 🟡 CMD About has a TODO placeholder + stale cosmos map (still mentions "ai for grandma" as a future planet). Phase 3 P0.
- 🟡 Plain AI About still says "Brain Bar" (rebrand happened only in manifest, not in About prose) and mischaracterises Shift. Phase 3 P0.
- 🟡 Shift About cosmos map hardcodes 4 of 7 planets (manifest expansion left 3 with default emoji). Phase 3 P1.
- 🟡 Guided FAQ entries 1, 9, 12 drift toward corporate-feature-list voice. Includes gamification language (XP / streaks / badges) that contradicts brand position. Phase 3 P1.
The audit doc has the full per-planet breakdown, specific quote-level drift symptoms, and recommended edit lists ready for Phase 3 to pick up directly.
Phase 3 — Cross-planet About blocks¶
Goal: every planet's About page references other planets in the universe with: logo + one-liner + URL + "why this belongs here". A visitor on any planet can discover the whole cosmos.
✅ DONE — 8 May 2026 (same session as Phase 1+1.5+1.6+2).
What shipped (all local edits, no Cloudflare deploy this session):
- 🪐 Agentic — new
/about/page (cockpit register) with 6 Panels: gap, what-we-publish, editorial rules, who-built-this, cosmos map, disagree (agentic-planet/src/pages/about.astro) - 🪐 Claw — new
/about/page (study-reference register) with 8 §-numbered sections matching home pattern, including verification states legend (claw-planet/src/pages/about.astro) - 🪐 CMD — TODO placeholder replaced with personal voice paragraph; cosmos ASCII map updated to 7 worlds; title corrected to include "AND error code" (
aguidetocloud-revamp/brainbar/layouts/_default/about.html) - 🪐 Plain AI — "A Guide to Cloud family" paragraph rewritten — Brain Bar → CMD, Shift mischaracterisation fixed, Agentic + Claw added (
plainai/content/pages/about.json) - 🌑 Guided — homepage FAQ entries 1, 9, 12 rewritten in Sush's voice; gamification language stripped; "Sutheesh" → "Sush" (
guided/src/pages/index.astro— SLA-light data edit only, no PracticeQuiz/build/env touched) - 🪐 Shift — cosmos map
PLANET_EMOJI+PLANET_TAGLINES_LOCALexpanded from 4 to 7 entries; Earth's local tagline tightened; CMD's local tagline revised (shift/src/pages/about.astro)
Full audit report: cosmos/voice-drift-2026-05-08.md
Phase 4 — NAV + logos (NEW SESSION)¶
Goal: masthead planet rail extended from 4 to 7 planets, with each planet carrying a logo that's true to its name AND signals family.
This phase splits into three sub-phases:
Phase 4a — Logo audit. Walk every planet (Earth, Guided-as-moon, CMD, Shift, Plain AI, Agentic, Claw) and document the current logo state.
✅ DONE — 8 May 2026. Audit shipped at cosmos/logo-audit-2026-05-08.md.
Headline findings (full detail in audit doc):
- 5 purpose-built marks confirmed: CMD
$_, Shift dial, Plain AI speech bubble (NOT "P-square" as voice-drift had it), Claw[*], and Guided crescent moon kit (designed but unwired). - 🔴 Guided has a complete brand kit on disk (
public/brand/guided-mark.svg+ 7 sister files including OG image, lockup, mono, on-dark) — but the masthead renders Earth's lotus webp andpublic/favicon.svgis the default Astro framework placeholder. Major Phase 4c gap. - 🔴 Agentic has only a generic stroke planet+orbit mark — no cockpit-register signal, doesn't carry agents/MCP/honest-take semantics. Phase 4b primary target.
- 🌍 Earth's lotus is emblem-class, not interface-class. Sits in a different family from the 5 planet-class marks. Plus Earth's favicon is
☁️(cloud emoji), not lotus — tab/masthead inconsistency. Phase 4b decision. - 🔴 Cosmos rail wired for 4 slugs only. All 5 mirror files (
planet-icon.html× 2,PlanetIcon.astro× 2,build-shared.mjs× 1) handle exactly: earth, brainbar, shift, plainai. Adding guided/agentic/claw renders nothing today. Phase 4c work item. - 🟡 Plain AI's
PLAINAI_PLANET_LABELSoverrides manifest — live cosmos chip aria-label still says "Brain Bar" even thoughplanets.jsonsays"name": "CMD". Data wiring fix for Phase 4c.
Family-signal hypothesis tested. The proposed rule — "the brand mark IS a working interface element from that planet's own UI" — holds for 4 of 5 confirmed purpose-built marks (CMD, Shift, Plain AI, Claw). Guided's crescent and Earth's lotus need carve-outs (Moon-class metaphor + Earth-as-home emblem). Agentic must be redesigned to fit. See audit doc for the full restated rule.
Phase 4b — Logo design + family signal. Design or refine each logo so:
- It is true to the name of its planet (CMD's $_ is exemplary — it IS the brand)
- It carries a subtle family signal — some shared geometry, weight, motif, stroke language — that whispers "part of the A Guide to Cloud cosmos" without forcing visual conformity
- It survives the masthead-icon contract per Cosmos Nav Playbook
Per cosmos philosophy: each planet's atmosphere and visual register stays independent. Only the masthead-icon contract is shared. The family signal lives in the icon set, not in fonts or colours.
Phase 4c — Implementation. Implement masthead 7-planet rail across all planet mastheads. SVGs ship per-planet so each can render in its own atmosphere (paper for Shift, dark for Plain AI, terminal for CMD, cockpit for Agentic, study-reference for Claw).
Phase 5 — Manifest expansion + governance (NEW SESSION)¶
Goal: all 5+ mirror manifest files include all 7 planets. Document a one-page "new-planet onboarding checklist" inside this doc.
Common confusions (resolve once, stop repeating)¶
These are references that have surfaced in past agent answers but are NOT planets. Future sessions must not treat them as such.
❌ Cloud Café — NOT a planet¶
- Lives at
C:\ssClawy\cloud-cafe\AGENTS.md(1.7 KB) - A Copilot Studio sample agent for a hypothetical Auckland café — menu, scheduling, inventory, customer feedback
- Not deployed, not on a domain, not part of the cosmos. It's a demo asset.
- If an agent surfaces it as a planet → wrong. Correct it: "Cloud Café is a Copilot Studio demo file, not a published product."
❌ AI for Grandma — NOT a current planet (it's the working name that became Plain AI)¶
- The session that built it (
67262696-a1cd-4774-bdf7-00bf18d887c2, 4 May 2026) called it "AI for Grandma" - It pivoted to Plain AI before launch. Plain AI is the live planet (
plainai.aguidetocloud.com). - The pivot history is documented inside cosmos/plain-ai/playbook.md
- If an agent says "AI for Grandma" → wrong. Correct it: "That was the working name; the live planet is Plain AI."
❌ OpenClaw — NOT the same as Claw Planet¶
- OpenClaw is the open-source AI agent project Sush is exploring as a learning topic. The placeholder doc at
learn-docs/openclaw/index.mdis from before. - Claw Planet is
claw.aguidetocloud.com— the live plain-English study reference for OpenClaw. - The two are related (Claw Planet teaches OpenClaw) but they are not the same artefact. Future docs must not conflate them.
❌ Brain Bar — the OLD name for CMD¶
- Sush rebranded the planet from Brain Bar → CMD. Domain stayed
cmd.aguidetocloud.com. - Many internal references still use "brainbar" (slug, folder paths,
.tomldata files insideaguidetocloud-revamp/brainbar/). - New rule: in user-facing copy always say "CMD" (with "(formerly Brain Bar)" allowed only as a one-time history note). In internal code paths, the slug
brainbarmay persist where renaming would break too much — that's tech debt, not a brand decision.
Doc structure standard (for future planet additions)¶
When a new planet enters the cosmos, this is the minimum doc layout:
learn-docs/docs/
├── cosmos/
│ └── <slug>/
│ ├── index.md # Overview / what it is in one screen / atmosphere / cosmos contracts
│ └── status.md # (optional) current production state, pending steps, pipeline
├── reference/
│ └── <slug>-playbook.md # Deep operational doc — extend, audit, deploy, voice, gotchas
The index.md overview is for first-encounter humans + future agents. It must answer: what is it, who is it for, what's its atmosphere, where does it sit in the cosmos, where do I go next.
The playbook.md is for the next session that has to work on it. It must answer: how do I extend / audit / deploy this planet without breaking it.
Voice belief — the universal anchor¶
Every planet's hero copy and About page must echo these (in its own dialect):
- No gatekeeping. Most things free. "For people like us — not power users."
- Plain English. Almost a religion on Earth and Plain AI. Allowed to bend (CMD is terminal-blunt, Shift is newspaper-tight) but the underlying anti-jargon stance must show through.
- Honest take. Hard truth > polite deflection. No fake confidence.
- Curious learner posture. Sush built this for himself first. Then it overflowed. Avoid expert-pulpit framing.
- No brag. Self-stat blocks ("100K subs", "X years experience") are out. Voices (testimonials with handles) and day-job framing are in.
- Quality over speed. Don't ship sloppy. Don't break the SLA.
Drift symptoms to watch for in Phase 2:
- "AI-powered" / "frontier" / "ecosystem" / "agentic" used as marketing words (banned by plain-ai-voice-guardrail.md)
- "Used by 2M+ developers" or any boasting number
- "Game-changer" / "robust" / "scalable" / "cutting-edge"
- "Unlock" + abstract noun
- Forced enthusiasm ("Get started today!" "Don't wait!")
New planet onboarding checklist¶
Phase 5 governance — added 8 May 2026. The one-page step-by-step for adding the 8th (or 80th) planet to the cosmos. Run through every step in order. The drift audit script (
learning-docs/scripts/cosmos-drift-audit.mjs) is the final gate.
0. Decide it's actually a planet¶
Read Cosmos Philosophy § How to decide: Earth or new planet?. 3+ "yes" on the checklist → new planet. Otherwise it's a feature inside Earth.
1. Pick the four manifest fields¶
| Field | Rule | Example |
|---|---|---|
slug |
Lowercase, no spaces, stable forever (don't rename — code paths depend on it). Match folder names where you can. | agentic |
name |
Display name. Updates here flow to every cosmos rail aria-label. Once shipped, prefer not to rename. | Agentic |
url |
Canonical homepage URL. MUST end with /. |
https://agents.aguidetocloud.com/ |
tagline |
One sentence positioning. No marketing voice. Plain English. | MCP reviews, recipes, vendor takes — for techies building with agents |
2. Add the entry to all 5 manifest mirrors (same commit)¶
| File | Format | Repo |
|---|---|---|
aguidetocloud-revamp/data/planets.toml |
TOML, [[planets]] block |
aguidetocloud-revamp |
aguidetocloud-revamp/brainbar/data/planets.toml |
TOML, [[planets]] block |
aguidetocloud-revamp |
guided/src/data/planets.json |
JSON, planets array |
guided |
shift/src/data/planets.json |
JSON, planets array |
shift |
plainai/content/planets.json |
JSON, planets array |
plainai |
The order in the array matters for visual order in cosmos rails. New planets typically go at the end, BUT keep Earth first and Guided second (Moon-of-Earth contract).
3. Design the planet's mark per Universal Law #7¶
Read Cosmos Philosophy Universal Law #7. Two surfaces:
- Tab favicon + masthead = host identity. Lotus (Earth-family) OR purpose-built mark.
- Cosmos rail + atlas = cosmic role. Each planet's purpose-built mark.
Mark must satisfy the family-signal rule: the brand mark IS a working interface element from that planet's UI (CMD's $_ IS the launcher, Shift's dial IS the gauge, Plain AI's bubble IS the conversation, Claw's [*] IS the dispute marker, Agentic's LED IS the status indicator).
Allowed carve-outs: Earth (lotus = home emblem-class), Guided (crescent = Moon-class metaphor).
Frame: 32×32 viewBox is the canonical favicon size; 24×24 the canonical cosmos-rail render size. Use currentColor for parts that should inherit text color; hardcode brand-accent colors only.
4. Add the icon to all 5 cosmos-rail palette mirrors (same commit)¶
| File | Repo | What to edit |
|---|---|---|
aguidetocloud-revamp/layouts/partials/planet-icon.html |
aguidetocloud-revamp | Add {{ else if eq $slug "<new-slug>" }} branch |
aguidetocloud-revamp/brainbar/layouts/partials/planet-icon.html |
aguidetocloud-revamp | Same |
guided/src/components/layout/PlanetIcon.astro |
guided | Add {slug === '<new-slug>' && (...)} block + expand TypeScript Props.slug union |
shift/src/components/PlanetIcon.astro |
shift | Same |
plainai/build-shared.mjs planetIcon() |
plainai | Add case '<new-slug>' to the switch |
Update the doc-comment "expected: ..." in each file. Update the warnf/console.warn message.
5. The new planet's own brand surfaces¶
Per Universal Law #7 — never ship a framework default. If purpose-built mark isn't ready, ship the lotus.
| File | Required? | Note |
|---|---|---|
public/favicon.svg |
YES | Purpose-built mark OR lotus self-contained SVG (see Earth/Guided commits 1cdab7b8 / e065588 for lotus pattern) |
public/favicon.ico |
YES | Multi-resolution (16/32/48). Replace any framework default. |
public/apple-touch-icon.png |
recommended | 180×180 PNG. iOS auto-discovers at root. |
public/images/logo_agtc_dark_1.webp |
for Earth-family | Vendor copy of lotus if your planet's masthead points at /images/logo_agtc... |
Masthead inline SVG in Header.astro / Nav.astro / baseof.html |
YES | The brand mark next to the wordmark. |
| OG image (1200×630) | recommended | Per-page generation OK; static fallback at minimum. |
6. About-page cross-references¶
Update each existing planet's About page to mention the new one:
- Earth (
aguidetocloud-revamp/layouts/about/single.html) — typically auto-renders from manifest; verify - CMD (
brainbar/layouts/_default/about.html) — has cosmos ASCII map; add the new planet line - Shift (
shift/src/pages/about.astro) —PLANET_EMOJI+PLANET_TAGLINES_LOCALdictionaries (add entries) - Plain AI (
plainai/content/pages/about.json) — "A Guide to Cloud family" paragraph (add the new planet to the prose list) - Agentic (
agentic-planet/src/pages/about.astro) — cosmos map block - Claw (
claw-planet/src/pages/about.astro) — cosmos map block
7. Docs scaffolding¶
| Path | Required? | Purpose |
|---|---|---|
learning-docs/docs/cosmos/<slug>/index.md |
YES | Overview / planet identity / what it is in one screen |
learning-docs/docs/cosmos/<slug>/playbook.md |
YES | Deep operational doc (extend / audit / deploy / voice / gotchas) |
learning-docs/docs/cosmos/<slug>/status.md |
optional | Current production state, pending steps, pipeline |
Add to mkdocs.yml Cosmos section |
YES | New nav block under Cosmos: |
8. Voice + drift audit gates (mandatory before commit)¶
cd learning-docs
# Mkdocs strict build — no broken links/anchors
mkdocs build --strict # exit 0 required
# Cosmos drift audit — manifest/icon/label parity
node scripts/cosmos-drift-audit.mjs # exit 0 required
Voice spot-check: hero copy + About page must echo Sush's belief language (no gatekeeping, plain English, honest take, no brag). Forbidden words list in plain-ai-voice-guardrail.md (frontier · ecosystem · agentic capability · AI-powered · robust · scalable · holistic · synergies · game changer · in layman's terms · etc.).
9. Deploy + verify¶
- SLA-protected planets (Guided): pre-change + post-deploy 3-curl smoke test (questions, checkout, practice).
- All planets: pull-rebase before push (parallel-safe; never
git add .). - Post-deploy verify live: cosmos rail aria-labels, OG image fetch, favicon byte size sanity (lotus = ~4.5 KB, framework defaults vary).
10. Update this audit doc¶
- Add the new planet row to the Status Table
- Increment the planet count in the title (currently "7 planets" — bump to "8 planets")
- Update the cosmos-philosophy.md "Other planets" table
- Update mkdocs.yml Cosmos nav
If you skip step 10, the next session that picks up cold doesn't know your planet exists. Don't owe them an apology.
🌌 Cosmos Atlas (Planet #8) — physics gotchas for future sessions¶
Added 12 May 2026 after R3 polish. The Atlas is a single planet in the manifest, but its interactive code has its own physics quirks that bite every session that touches orbit / lens / focus logic. Captured here (not in a code guide) because future sessions read
cosmos-audit.mdfirst when picking up cosmos work cold.
Source files for everything below: cosmos-atlas/src/scripts/cosmos.ts (physics + lenses + interactions) · cosmos-atlas/src/data/atlas.json (orbital data) · cosmos-atlas/src/styles/cosmos.css (chrome + ambient player + left-stack) · cosmos-atlas/scripts/qa-audit.mjs (growing-guardrail suite — add a test for every new bug, never delete).
1. Moon orbit scale ≠ planet orbit scale¶
A planet's orbital radius is multiplied by scaleFactor (~0.27 on iPhone 390px, 1.0 on desktop ≥720px breakpoint where the outer ring fits the viewport). A moon's sub-orbit radius is multiplied by an independent moonScale = max(0.5, cw / 720) (~0.541 on iPhone, 1.0 on desktop). See moonOrbitPos() at cosmos.ts:624. Why two scales: planet orbits compress hard on phones so the whole ring fits; moons need to stay visibly close to their parent, so they compress less.
The trap: tightening a moon's sub-orbit to ease a moon-vs-other-planet sweep collision can simultaneously push the moon INSIDE its parent body's silhouette on iPhone, because the moon doesn't shrink the same way the planet ring does. 12 May 2026 attempt: pulled curriculum sub-orbit 70 → 58 to gain 2px margin on the curriculum-vs-shift iPhone sweep — it broke curriculum-vs-parent (dist 31.4 vs minSafe 37 on iPhone). Reverted same session.
Before changing any sub-orbit, run the iPhone math both ways:
- Moon-vs-parent screen distance = subOrbitRadius * moonScale → must exceed (parent.width + moon.width)/2 + 8
- Moon-vs-neighbour radial gap = (parentOrbit - neighbourOrbit) * scaleFactor − subOrbitRadius * moonScale → must exceed (neighbour.width + moon.width)/2 + 6 after considering eccentricity + phase
2. The curriculum-vs-shift sweep is flaky, not deterministic¶
The qa-audit.mjs moon-time-sweep samples 6 timepoints over ~15s (sampleInterval=2500ms × 6). The worst-case angular alignment of curriculum (moon of plainai) and shift (neighbour planet) doesn't always fall inside the sample window — so the test passes on most runs, fails occasionally at 29.7-29.8px vs minSafe 31.8-32.1px. It is pre-existing, low-amplitude, customer-invisible. Don't fix it by moving curriculum's sub-orbit (see #1). Real fix would be re-spacing the planet ring (brainbar 920 and shift 950 are only 30px apart in planet-space → ~8px raw on iPhone, surviving only by 80° phase offset). That's a multi-session redesign, not a one-orbit-bump.
3. Sun-occlusion fade hides deliberately-placed bodies in alt-lenses¶
applyBodyTransforms() drops a body's opacity to 0.15 when its screen position falls inside the sun's halo (radius ≈ sun.size × 3.8 × cameraZoom). In cosmos lens this is correct — bodies legitimately pass behind the sun. In constellation / timeline / audience lenses bodies are placed deliberately, often AT canvas centre (sun's position). Skip sunOcclusionFade in non-cosmos lenses. R2 session bug: Earth was placed at canvas centre in constellation lens and was invisible. QA guardrail (added R2): every planet + moon body in constellation / timeline / audience must have opacity ≥ 0.5, non-zero rect, and centre within viewport.
4. Focus-scroll trap on programmatic card open¶
.cosmos { overflow: hidden } has scrollWidth > clientWidth because .card-panel rests at translateX(100%) (480px past the right edge). When card-name h2 receives focus after openSlug(), the browser auto-scrolls .cosmos to bring it into view, leaving scrollLeft = 480. All absolute-positioned .bodies then appear shifted 480px to the left in every lens render after that. Fix: heading?.focus({ preventScroll: true }) — preserves screen-reader announcement, prevents the silent scroll. Caught R2 session. The interaction (perspective + transform + overflow:hidden + .focus() = auto-scroll) is a generic browser behaviour; any future fullscreen-overlay UI on cosmos that focuses an element inside an overflow-hidden ancestor must use preventScroll: true.
5. Audience lens col 0 collides with .left-stack¶
computeAudiencePosition() distributed bodies across cw / 4 columns with col 0 centre at cw / 8 (~180px on a 1440px viewport). .ambient-player (inside .left-stack) sits at left: 20px; width: 240px → right edge ~260px. Result: Earth, BrainBar, PlainAI, Curriculum (column 0 of audience lens) overlapped the ambient player widget visually. R3 session fix: leftPad = 280 on desktop, 40 on mobile (same 720px breakpoint that hides .left-stack in CSS), rightPad = 40, usable = cw − leftPad − rightPad, colWidth = usable / 4. QA guardrail (added R3): in audience lens at desktop viewports, no planet/moon body bounding rect may intersect .ambient-player's bounding rect.
6. Screensaver fade rule needs per-element control, not a bulk selector¶
The button that toggles screensaver mode lives inside .hud-orientation. A bulk selector like body[data-screensaver="active"] .cosmos > :not(.canvas-stage) propagates opacity: 0 to all children of .cosmos, including the screensaver toggle itself — children can't override parent opacity, so the toggle goes invisible and unclickable. Fix: enumerate the fade list (.hud-tools, .hud-attribution, .left-stack, .lens-legend, .lens-audience-cols, .cosmos-coach, plus .hud-orientation > :not(#screensaver-toggle)). Caught by rubber-duck pass R2 session before any code shipped. QA guardrail (added R2): screensaver toggle opacity ≥ 0.95 while screensaver is active.
7. Camera retargeting + body scale lerp during card-open warp¶
Older code (pre R2) layered three effects on click: (1) camera retarget toward the focused body, (2) zoom to 1.85×, (3) body scale + opacity snap from 1.0 → target instantly. Felt jerky. R2 fix: zoom NEVER changes on focus (stays at userZoomMul = 1.0), focus-lerp slowed 4.5 / sec → 1.5 / sec, per-body currentScale + currentOpacity lerp toward target (exponential, 8/sec scale, 6/sec opacity). Also removed the filter: blur(1.6px) on body icons during the warp (the dominant visual jerk source). QA guardrail (added R2): smooth-card-open probe asserts no blur() filter on .planet-body__icon during the 280ms warp window.
Pattern for every future Atlas physics session¶
- Read this section before touching
cosmos.ts,atlas.json,PlanetIcon.astro, orindex.astro. - Rubber-duck the plan before coding — physics changes ripple (one orbit change cascades through lens projections, sweep collisions, click clamps). R2 + R3 sessions both caught blocking design issues in rubber-duck review.
- Local QA:
node scripts/qa-audit.mjsmust pass before push (45+ checks, ~30s, see Cosmos Atlas QA Suite blocking rule in copilot-instructions.md). - Deploy → re-run audit against live (
node scripts/qa-audit.mjs https://cosmos.aguidetocloud.com/) before declaring the session shipped. - Every prod bug fixed adds a guardrail test. The suite only grows — never shrinks. Find bug → write test that catches it → fix bug → verify test passes → deploy.
Resume pointer (when picking this up cold)¶
- Read this whole page.
- Read
voice-and-tone.mdandcosmos-philosophy.mdonce. - Run
SELECT id, title, status FROM todos ORDER BY status, id;against the session-state DB. - Pick the first
pendingtodo with nopendingdeps. Mark itin_progress. - When done, mark it
done, update the Status Table on this page, and proceed. - If the SQL DB doesn't exist (new session in a different folder), create todos by reading the Phase 1-5 sections above.
If you can't find this file's SQL state, the table at the top of the page is the next-best snapshot. Update it by hand.
What this doc is NOT¶
- Not a brand book. Voice is in
voice-and-tone.md. - Not a code guide. Each planet's playbook owns its own code rules.
- Not a deploy doc. That's
deployment-playbook.md. - Not a Zen design doc. Earth's design system is in
zen-system/.
This is just the map of the cosmos — what exists, where it's documented, what's drifting, what's next.
Update discipline: every session that does work captured by this doc must leave the Status Table and the planet table accurate before checkpointing. If you don't update this file, you owe the next session an apology.