Reference¶
This section is the working memory annex for Copilot CLI sessions. Anything that is reference (look up on demand) rather than rule (must be followed every session) lives here, so the ~/.copilot/copilot-instructions.md file can stay focused on rules.
Two purposes share this folder (set 31 May 2026)
The portal serves two distinct uses:
- Atlas Brain Extended — Atlas's working-memory storehouse. Docs Atlas reaches for to make decisions, run a playbook, surface a rule's provenance, propose architecture, draft in Sush's voice. Atlas operates these; they're written for Atlas's retrieval patterns. Front door:
atlas-brain-extended.md. - Sush-authored sacred content — Sush's philosophy, voice library, founding principles (in
~/.copilot/plain-ai-*.md). Atlas READS but doesn't OWN. Edits proposed before commit.
Both coexist in this folder. The distinction is who edits, not where it lives. The 31 May 2026 trim cycle named what was already true — see trim-2026-05-cycle.md for the rationale + Rule #9 (Portal-First Retrieval) origin.
How this section is used
Future Copilot sessions read these pages as plain markdown via the filesystem, not over the web. The website is a rendered viewer for Sush. The canonical source of truth is C:\ssClawy\learning-docs\docs\reference\*.md.
copilot-instructions.md contains pointers to file paths in this folder, e.g.:
For the full deployment playbook, read
C:\ssClawy\learning-docs\docs\reference\deployment-playbook.md
The router at ~/.copilot/scripts/portal-router.ps1 reads cwd + recent file changes + prompt and recommends the right docs. Atlas runs it before any non-trivial response (per 🚨 Rule #9 in copilot-instructions.md).
What lives here¶
| Page | What's in it |
|---|---|
| Atlas Brain Extended (front door) | Atlas's working-memory taxonomy — grouped by retrieval situation. When Atlas needs memory grounding / proposes architecture / deploys / drafts content / integrates a tool / handles an incident — this is the per-situation table. Read this if you want to scan how Atlas thinks. Set 31 May 2026 during the trim cycle. |
| Trim 2026-05 cycle | May 2026 brain trim methodology + outcomes. Protected-content floor calc · brain regression test suite · per-critic synthesis · Y/X net-KB equation · Rule #9 (Portal-First Retrieval) origin · in-context manifest design. Read this for the canonical trim methodology future cycles should follow. |
| Triggers — keyword → learn-doc routing | Read this when you don't know which playbook to load. Maps keywords (Cosmos, Plain AI, deploy, etc.) and implicit triggers (about to touch a practice exam file → read SLA) to the playbook(s) you should read. Lifted out of copilot-instructions.md 22 May 2026 so the always-loaded soul file stays small. |
| Memory System Evolution | Honest evaluation of external memory-system patterns (notably obsidian-memory-for-ai v3.1) and the case for what we adopted (Promote-on-2+ rule, triggers.md), what we rejected (bi-temporal frontmatter, _inbox/, atomic-facts reorg), and why. Read first if Sush surfaces another memory-system idea — it explains what we already evaluated and the reasoning. |
| Architecture Gate + Data-First Playbook | The deep version of soul-file Rules #5 (Architecture Gate) and #6 (Data-First Sequence). The atlas-portfolio 4-day case study (3 failed attempts vs the 80-minute success). The probe-script pattern. The 12-step checklist for the next big tool/dashboard build. Read first when starting a new tool or dashboard, OR when Atlas catches itself skipping either rule. Set 25 May 2026 with Sush's express authority to interrupt execution. |
| Deployment Playbook | The 19-step pre-push checklist. CSS, JS, build, cache, smoke-test discipline. |
| Cert Tracker Playbook | 🔴 Read before touching cert retirement status, cert page content, or the /cert-tracker/ index. The trap that drove it: exam status lives in TWO independent sources — Hugo front matter exam_status (single pages) and cert-tracker/scripts/exams.json → latest.json (the index, fetched client-side, so curl proves nothing). Fixing one is a silent half-fix that looks verified. Also: manual: true is the only thing stopping the weekly bot from reverting hand-edited content/cert-tracker/*.md; why exams.json edits are durable (EXAMS_CONFIG, read-only; bot only commits site/); the monthly "has any retiring cert already retired?" check with runnable commands; and the pending-actions table (AZ-500/AZ-800/AZ-801 retire 2026-09-30). Born 30 Aug 2026 after 6 cert pages spent 1–2 months telling visitors an exam was "Retiring" when it had already retired. |
| Cert Vendor Demand Ranking | 🔴 Read first when asked "why are we building this vendor next?" or when reordering the Guided build queue. The durable record of WHY the queue is ordered as it is: Sush's two rulings (order by student popularity/interest, and past Stripe sales are an invalid input — circular), the certified-population evidence table with a source + confidence on every figure (ITIL ~5M · PMP 1.4M+ · PSM I 772,305 · Salesforce ~170k + 20M Trailblazers · r/oscp ~110k · Red Hat: none found), and the finding that contradicted the original request — Sush asked to front-load the lab certs as "most student-popular"; the evidence put ITIL/PMP an order of magnitude ahead. Also records that bucket 3 was never actually blocked (CKA/CKAD/CKS already ship live at $9 for 100%-lab exams) and that the documented Stripe blocker is factually wrong (metadata is not customer-visible). Carries the UNKNOWN that matters: no evidence found in either direction that lab-cert students want question banks. Excluded from the public site — competitive build strategy. Born 13 Sep 2026. |
| Phase D Playbook (guided question-bank cleanup) | Read first when picking up Phase D / mashup cleanup / cert QA work on guided.aguidetocloud.com. State, priorities (P1 prevention hook is highest ROI), canonical per-cert workflow, triage rules per heuristic (H1/H2/H3/H4 + FP categories), discovered_bugs persistence model (git-tracked JSON ↔ session SQLite), self-learning protocol (build a scanner when you see a bug class 2+ times), stop criteria, resume one-liner. Self-updating doc — bumped at the end of every Phase D session. Born 3 Jun 2026 in session 9e5cc23f after 3 commits + parallel session 89327d9c shipped scanner v2 + B-Lite strip on juniper-jncis-ent. |
| Parallel-Safe Git Rules | The M-flag detection, worktree pattern, the May 2026 incident that drove the rules. |
| Voice & Tone | Sush's core values, the brag-allergy, phrasing fingerprints. How to write as him without flattening him. |
| Blog Voice Guide & Story Worlds | 🔴 THE voice gate for aguidetocloud-revamp/content/blog/ — read before writing or editing any post. Part 1 (Sush-authored, sacred — don't change without his sign-off): the USP ("we simplify hard concepts for people like us" — not power users, not developers), first-person coffee-chat voice, the 3 Story Worlds (Your Phone 📱 = features/tiers/settings · The Hotel 🏨 = security/governance/access · Moving House 🏠 = deployment/migration/adoption) with full mapping tables and worked examples, the 4-beat section rhythm (Hook → Simple explanation → Detail → Action), and the "What NOT to Do" list (bans leverage · utilize · implement · facilitate · stakeholders, passive voice, definition-openers, >4-sentence paragraphs). Part 2 — anti-AI-writing gate (added 21 Aug 2026), validated against the external standard conorbronsdon/avoid-ai-writing after a measured audit of all 71 posts / 247k words. Headline finding: the vocabulary was already clean (Tier 1B = 0, Tier 2 clusters = 0, Tier 3 = 0.02% vs a 3% threshold) but the formatting was the tell — bold at 30.1/1k and em dashes at 20.3/1k against a hard max of 1. Five rules: (1) bold is a budget, not a highlighter — max one emphasis per line, structural **Label:** lead-ins exempt, never bold a clause >5 words, first mention only, tables/headings/callouts exempt; (2) earn the em dash — prose splices are the single most recognisable AI habit, — as list/heading typography is fine; ⚠️ NOT yet remediated, needs its own Gate A before anyone bulk-edits; (3) banned Tier 1A/1B words + hollow intensifiers, including the genuinely nuance (keep before a threshold/contrast — "only when developers genuinely need control"; cut before a plain evaluative adjective — "genuinely impressive"); (4) sentence-case headings, no em dash in headings; (5) list shape — no runs of 5+ bare noun-phrase bullets, **Label:** not **Label.**, avoid the rule of three. Tools: scripts/ai-writing-audit.mjs (detect only, never rewrites) and scripts/debold-propose.mjs (--cap=1 --apply). Quotes the standard's own caveat: signals, not proof — these fire more on second-language writers and technical genres. Promoted into the portal 21 Aug 2026 from a dead session-state folder where it had been invisible for months (Rule #14b). |
| Zen Design System Quickref | One-page lookup for tokens, guardrails, and the parity-file map between Hugo and Astro. Now includes the hub Zen pattern + voice library + Layer 2 cert-landing pattern. |
| Blog Notebook System | The Field Notebook layout for /blog/. Architecture, design tokens, frontmatter conventions, shortcodes, the "handwritten over emoji" principle, deployment history (8 May 2026), known issues. Read first if picking up blog work cold. |
| What's New Copilot Pack Playbook | Canonical monthly "What's New in M365 Copilot" blog + PowerPoint workflow (the whats-new-copilot-pack skill): official-source matrix across Learn release notes, roadmap, Work IQ and the Tech Community monthly roundup; late-publication/modified-date rechecks; screenshot harvest; premium deck design/engine; SME + vision QA; and clean deployment. Born 25 Jun 2026; monthly-roundup guardrail added 24 Jul 2026. |
| MRC Roadmap MCP Playbook | The free, no-auth Microsoft Release Communications MCP server that exposes the M365 roadmap and Azure updates as queryable tools (https://www.microsoft.com/releasecommunications/mcp). Read before any monthly What's New research pass or "what shipped / what's coming" question. Covers: connection facts and the two-tool allowlist; the four live tool names and why tools/list always beats the Learn doc (the doc names two tools that don't exist); the items-not-value results-array trap that silently returns nothing while totalCount reads fine; the created vs generalAvailabilityDate split that quietly corrupts a monthly sweep; a tested OData filter + PowerShell SSE harness (verified 14/14 items for Aug 2026); pagination, cost discipline, the multiword-search defect; and why this is a query interface over the same corpus as the existing daily REST pipeline, not a second source. Set 2026-08-24. |
| Copilot Monthly Blog Screenshots Playbook | Read before capturing/placing screenshots for any monthly What's New in M365 Copilot recap blog. Section-by-section workflow, Rule #8 filename-lies discipline, annotation house style (red boxes + composites for tiny taskbar shots), PII masking, what to do when a feature isn't in the tenant (search internal → official image → honest disclaimer, reject 3rd-party copyright), accuracy reconciliation (UI vs release-note names; verify is-it-coming via roadmap), the fade-off reorder + anchor updates, and validation. Born 23 Jul 2026 (July recap, ~40 images). |
| Blog Notebook Follow-ups Prompt | Self-contained starter prompt for the next session that tackles the 3 flagged items from the 8 May SME audit (JSON-LD nested-quote bug, SEO content lengths, Clarity CSP decision). |
| Hugo Build Wrapper | Why never to run bare hugo. The wrapper script, why builds take ~100s, and the lock-file recovery flow. |
| Windows Developer Config — adoption playbook | Read first when picking up Build-2026 Windows dev environment unification work. Microsoft's microsoft/WindowsDeveloperConfig GA analysis: what's actually inside dev-config.winget (14 packages + ~30 scripts), W7080 probe (ARM64 Surface · Node 24 already matches LTS · zero WSL), 14 gotchas (4 brand-new from a CDX VM dry-run — including the killer WinGet-per-user-MSIX trap that breaks every cloud automation path), Path A adoption design (vendor + atlas-overlay.winget + post-bootstrap scripts), unification of Cosmos + Atlas + AGTC dev workstreams. Set 3 Jun 2026 session 7d91c294. Living doc — bump on every milestone. |
| Tool Integration Checklist | The 12 mandatory touch points when adding a new free tool to the public site. |
| Context7 Research Playbook | Context7 (Upstash) — what it's actually good for and what it must never be used for. Verified head-to-head against Microsoft Learn MCP: Context7 returns paraphrased summaries, Learn MCP returns verbatim doc text — so Learn is always the authority for Microsoft product facts, and Context7 is never a source for the paid practice-exam or blog claims. Its genuine unique value is GitHub repos + non-Microsoft vendors (copilotstudiosamples, Agents Toolkit, pnp/copilot-prompts, Graph docs-contrib) which Learn MCP structurally cannot index. Deliberately NOT installed as an MCP server — on-demand HTTPS only, to avoid prompt-injection into a shell-capable agent and auto-routing of work queries to a US third party. Includes ready-to-run curl/PowerShell snippets, verified library IDs, the 6 hard usage rules, and the Rule #16 Gate A verdicts. Read before using Context7 or before anyone proposes adding it to mcp-config.json. Built 18 Aug 2026. |
| Production Incident Log | Every production bug + the guardrail that was added because of it. The "growing test suite" principle. |
| Site Audit & Cleanup Log (May 2026) | Working memory for the periodic site cleanup audit. What's been deleted, what's kept-but-redundant (and why), what's pending. The Cloudflare _redirects gotcha lives here too. |
| May 2026 Zen Shipping Log | Full chronological log of the Layer 1 + Layer 2 Zen redesign, OG/SEO push, paid-product loop fix. Read this first if you're picking up Layer 2 or Practice page work. |
| Shift Playbook | How to extend, audit, and deploy shift.aguidetocloud.com. Voice rules, Three Dials framework, deploy gotchas, audit personas, deferred backlog. |
| Plain AI Playbook | How to extend, audit, and deploy plainai.aguidetocloud.com. Content model, visual rules, the cache trap, the pivot history (AI for grandma → Plain AI), and the wrangler-on-arm64 workaround. |
| Agentic Planet Playbook | How to extend, audit, and deploy agents.aguidetocloud.com — the cockpit field-guide for techies building with agents. Origin story, the 14-pillar IA (minus 13/14), four iteration rounds, full pending-improvements roadmap, gotchas. Read first if picking up the project cold. |
| Claw Planet Playbook | How to extend, audit, and deploy claw.aguidetocloud.com — the plain-English study reference for OpenClaw. Origin story, the 10-§-section IA, locked visual decisions (B3 reference layout, OpenClaw red, Bracket Mark logo), voice guardrails, verification states, batch-by-batch workflow. Read first if picking up Claw Planet cold. Updated 14 May 2026 with the v0b multi-vendor expansion admonition — Claw now covers OpenClaw + Anthropic + OpenAI + Google + Microsoft. |
| Planet Pivot Playbook | Meta-playbook for repurposing an existing planet when its scope no longer matches what Sush wants to learn out loud about. Captured 14 May 2026 from the Claw v0a → v0b multi-vendor expansion. Six patterns: (A) multi-turn requirements gathering ("creative-juice arc") · (B) when to call the rubber-duck · (C) sourced-seed content lifecycle · (D) Cat A vs Cat B problem (dev infrastructure vs hosted product) · (E) Microsoft slice + data classification discipline · (F) Batch 0 migration phases in safe order. Includes anti-patterns, lessons learned, full file map, and a checklist for the next planet pivot. Read first if Sush proposes a new planet OR a scope expansion of an existing one. |
| Claw v0b Follow-ups Prompt | Self-contained kickoff for the next session that picks up Claw v0b after Batch 0 shipped (14 May 2026). What's live, what's queued (Batch 0b URL migration + Batch A Anthropic content), required reading, working pattern reminders, SQL todo state, full file map. |
| Cosmos Philosophy | The metaphor that governs how the universe expands. Universal laws, planet-internal laws, inter-planet contracts. Read first before any new-planet work. |
| Cosmos Nav Playbook | How the cross-planet navigation rail works across all 5 worlds. Schema, file map, per-planet renderings, how to add a new planet, SLA guardrails. Built 5 May 2026. |
| Cosmos Config Manifest | The [cosmos] block — newsletter URL, feedback link, parent site. How to swap newsletter platform in 5 file edits, no code. Brainstorm of what else could use this pattern. |
| Cosmos Audit & Resume Doc | The universe-wide coordination map — 8-planet status table, locked decisions, the 10-rule GUARDRAIL for every future cosmos session, doc structure standard, new-planet onboarding checklist, resume pointer. Now also houses the Cosmos Atlas (Planet #8) physics gotchas section — moonScale ≠ scaleFactor on iPhone, sun-occlusion fade trap in alt-lenses, focus-scroll trap on programmatic card open, audience lens col 0 overlap with ambient player, screensaver fade per-element control, smooth-card-open layered fix. Read first when picking up universe-wide work cold OR when touching cosmos-atlas/src/scripts/cosmos.ts, atlas.json, orbit logic, lenses, or interaction physics. Grew R3 (12 May 2026). |
| Brain Bar Lessons | What worked + what to do differently from the first planet build. Patterns to reuse for the next planets. |
| Memory Instrumentation System | 🔴 The first measured view of Atlas's own behaviour — built 13 Aug 2026. The two corpora and which answers what (events.jsonl = tool-level but only ~5 days / 66 sessions; session-store.db = 12,386 turns over 5 months). The headline finding: Atlas claims completion in 33% of all turns; claims paired with "go test it yourself" are 3.1× more likely to be refuted in the very next turn (7.4% vs 2.4%) — with verbatim ground-truth cases. Also: the fail-closed preToolUse trap (a crashing hook denies every tool call; timeouts fail open, so no QA suite can run in-hook), detector-precision failures (first-pass detectors scored 0–25% precision — subagent briefs and scraped data pollute everything), the prose→gate graduation rule (deterministic / uncontested / safe-if-wrong), and what was deliberately NOT built and why (no vector DB, no fine-tuning, no episode→fact compression, no vendor-benchmark citations). Read FIRST before adding any rule, guardrail, or hook — or before proposing another memory redesign. |
| Constitution Rule Provenance | 🔴 The war stories behind the constitution's rules — origin incidents, sightings, evidence, retired companion specs. Built 14 Aug 2026 to get narrative out of the always-injected copilot-instructions.md without touching a single obligation. Nothing normative lives here: every MUST / NEVER / trigger / bypass / boundary stays in the constitution, and the move is gated by a contract — obligation count and HARD count must be identical before and after (build-registry-v3.mjs), plus zero regressions from test-rule-firing.ps1 -Compare. Read when asking why a rule exists, whether it can be retired, or before trimming the constitution. |
| Memory System Architecture | One-page Mermaid map of the 6 memory tiers (constitution · reference · journal · annex · archive · session-store SQL). When each tier gets read, what triggers loads, what NOT to add. Read this if asked to "explain the memory system" — answer in seconds instead of composing from scratch. Built 10 May 2026. |
| Skills Strategy | The agentskills.io spec digested + our build list + the four meta-gates (voice / quality / last-used / meta-review). Captures: existing skills audit (14 found at ~/.copilot/skills/, mostly unused), why they don't trigger (description fit, not infrastructure), Category B priority list (voice-review + connect-classify P0), Category C script-wrap list (gsc/stripe/realtime weekly trio P0), Atlas extensions to the metadata field (last_used, voice_critical, surface), the skills-meta self-policing skill, build order, and the open questions for Sush. Read first when picking up any skill work — new build, retire decision, eval design, or "why isn't this skill triggering?". Built 21 May 2026 in session 09a04d64. |
| SEO Sweep Phase 2 Prompt | Earth-only sweep, ✅ SHIPPED Mon 11 May 2026. 845 failing → 50 failing across all Tier 1+2 surfaces. 818 page rewrites in 7 commits. 8 sibling scripts in aguidetocloud-revamp/scripts/. Full results table inside. |
| SEO Sweep Phase 3 Prompt | Cosmos-wide SEO sweep — Phase 3 hand-off. Per-planet audit (Brain Bar, Guided, Shift, Plain AI, Cosmos Atlas, Agentic Planet, Claw Planet), live homepage state, SLA touch-points, recommended commit order (lowest risk → SLA-touched last). ~100-170 pages to rewrite across 7 planets. Read first when picking up cosmos SEO work cold. |
| Stripe Payment Playbook | Everything Copilot needs to know about the aguidetocloud.com Stripe setup. What's possible via API, what isn't (Radar Rules API doesn't exist; Cash App/Klarna/Affirm aren't region-available), what's already shipped (11 May 2026 baseline: 3 commits to checkout.ts), the wallet discovery (Apple/Google/Link work under card automatically), the Payment Method Configuration landscape, the pre-test pattern for checkout.ts changes, fraud cluster handling via Radar value lists, common pitfalls. Read first if picking up Stripe / paid product work cold. Built 11 May 2026 alongside ~/.copilot/scripts/stripe-weekly.py. |
| Blog Cover Prompt Template | Reusable recipe for OG / LinkedIn cover images for /blog/ posts. Locked palette · medium · composition rules · mood. Reusable prompt template + 3 example scene prompts (Copilot CLI / monthly updates / licensing). Modelled on Darren Johns's "Teaching an Old Dog New Tricks" article cover (4 May 2026). Paste-into-Designer-or-ChatGPT workflow; the "Future: programmatic generation" section is now real and points to og-image-system.md. Read first when writing a new blog post and need to generate its cover image manually. Built 11 May 2026, updated 12 May 2026. |
| Copilot Monthly Blog QA Playbook | Read before QA-ing or publishing any monthly What's New in M365 Copilot issue. The deterministic system that replaced eyeballing: scripts/monthly-blog-qa.py offline invariants (roadmap ID exists in the bot-committed feed · link label matches its own href · *For:* line · source URL · image on disk with alt text · zero-sections-is-never-a-pass), exceptions.json for genuine Microsoft roadmap withdrawals (3 of 220 IDs, measured), 15 self-tests including a regression lock on a real false positive, the pre-push hook (fails open without Python) plus the CI backstop (doesn't), and the Rule #8 image-observation workflow. Born 21 Aug 2026 after the August issue (59 sections, 60 images). |
| OG Image System | The locked two-tier OG cover system for aguidetocloud.com. Tier 1a — cert study guide + practice exam ✅ SHIPPED 13 May 2026 PM — V3 programmatic SVG (dark #0F0F10 BG + Inter ExtraBold cert code + indigo accent + family-coloured band + ink-lotus + wordmark), 149 study guide covers + 125 live practice exam covers, Microsoft 5-family palette (AZ peach · MS pink · AI lavender · SC periwinkle · MB teal) + DEFAULT neutral for AWS/Cisco/CompTIA/GCP/etc. Generator at aguidetocloud-revamp/scripts/og-generator-cert/, in-place atomic replacement (no baseof.html change). Practice mode reads guided/src/content/certs/*.toml as strictly READ-ONLY. Tier 1b — blog covers ✅ SHIPPED 13 May 2026 PM — V3-blog "B2 Editorial-Light" — warm-white #FAFAF8 BG + Inter ExtraBold headline left + tiny line-art glyph corner-right (calendar / compare / layers / list) + lotus+wordmark bottom-left. 18 covers live at static/images/og/blog/, generator at scripts/og-generator-blog/. 🔴 Universal format lock — JPG @ q=85 with mozjpeg encoder + 4:4:4 chroma subsampling + stripped metadata (§ 6.11.3) — apply to ALL OG generators (Node V3 cert, V3-blog, legacy Python next time touched). Yields ~22-31 KB per cover, sharp text edges on coloured accents. Tier 2 Azure Foundry gpt-image-2 watercolour path is ARCHIVED. Peer-set audit (Linear/Vercel/Stripe/Cloudflare/MS Learn — 11 reference covers in session-state), v1→v4 iteration history, family-palette lock, adaptive font-sizing rules, frontmatter contract (og_headline + og_glyph), in-place vs /v3/ route trade-off, guided-repo read-only contract, pre-existing SEO guardrail follow-up. 🆕 § 6.16 (19 May 2026) — operational hardening documents the two-generator clobber trap (Python clobbers V3-blog when both write to same path), silent og_glyph fallback, and the three new check-seo-lengths.ps1 checks (strict-fail on missing og_headline · warn on invalid glyph · warn on OG >50 KB legacy-format heuristic). Read first if picking up OG image work cold OR if asked to "make a cover image". Built 12 May 2026, V3 locked 12 May PM, V3-blog SHIPPED 13 May PM, V3 cert+practice SHIPPED 13 May PM, ops hardening 19 May. |
| Cosmos Intelligence Playbook | The cosmos-wide live counter + private analytics dashboard. GA4 single property + cosmos_planet event-scoped custom dim → public pill on every planet via cosmos-bar + gated 🌌 Cosmos tab in Command Centre + nightly summary worker with KV stale-while-revalidate. Full architecture, auth model (CC SHA-256 hash + plaintext Bearer + constant-time compare), file map across 8 repos, NZT week math, GA4 gotchas, signals engine, Phase B roadmap (outcome events, journey, GSC, LLM memo), 13 gotchas-with-cost. Read first if extending cosmos analytics, adding a new planet to the counter, or touching /api/cosmos-summary or /api/stats?realtime=cosmos. Built 12 May 2026 — two rubber-duck passes + one SME code review + 14 commits across 8 repos. |
| LinkedIn Advisor Playbook | Thought-advisor mode — turning customer sessions into LinkedIn posts that push existing blogs without feeling promotional. The formula (hook → context → reframe → visual → link → 2 hashtags), three hook variants (customer-question · honest-admission · T3-pattern), voice guardrails (extends Voice & Tone), sizing rules (~80 words), visual rules per topic shape, cadence (1/fortnight, trigger-based not date-based), the trigger system (what I scan for at end of each customer-session journal entry), a queue of blog posts ready to push with their trigger conditions, posted log, and what NOT to post. Read at the end of every customer or T3 session to scan for a moment worth posting. Built 12 May 2026 alongside the brand-kit decision-tree post. |
| Realtime Counter Playbook | The live "people in cosmos" pill + Site Analytics tile + tool-counter + CC "Live Now" — architecture, file map, operational runbook. Captures the 4-incident history (13/14/16 May 2026) and the permanent fix shipped 16 May (commit 6a9f6b7b, Option A+ "decouple public realtime from GA4 quota via scheduled KV refresh"). Architecture: GHA cron → handleRealtimeRefresh → realtime:active + realtime:pages KV keys → public handlers read KV only (fail closed, never fall back to GA4). GA4 calls/hour: O(visitors × poll_rate × N_pops) → constant ~60. Includes a 10-row "the pill is broken again" troubleshooting table, the ~/.copilot/secrets/guided-admin-password ≠ CC admin password gotcha, and the cross-quota-dimension lesson (per-hour vs per-day GA4 limits, different reset windows). Read first if the live counter shows nothing OR before touching functions/api/stats.js realtime paths OR .github/workflows/realtime-refresh.yml. Built 16 May 2026. |
| Cowork Cost Calculator Playbook | The /cowork-cost-calculator/ tool — cost model + the calibration story (numbers were ~6× too low until pinned to Microsoft's public estimator), the "meter" design, the credit-check widget + /cost slash-command integration, Zen-template gotchas (zen-migrated body class · --accent-strong for active pills), QA traps (lazy-load naturalWidth=0, count-up timing, data-theme toggle), and the blog↔tool cross-link map. Constants: CREDIT_COST=0.01, SEAT=$30 (enterprise — ignore the recurring $19.99 consumer flag), USAGE bands light/balanced/heavy. Read first before touching any Cowork costing number on the site. Built 18 Jun 2026, session ce18cacd. |
| MSFT Gold Explore Queue | Curated triage of 20 internal mcaps-microsoft repos discovered in the 21 May 2026 second-pass scan (817 repos scanned, 195 name-matches). Tiered: 5 install-this-week (mcp-gateway, MSX-MCP, iq-core, MSX-Milestones-Skill, clawpilot-seismic-bridge) · 4 try-and-compare (CSA-Sherpa-Agent vs Connect tracking, Frontier-Fast-Start vs Frontier SE, copilot-account-research, MSXelerate) · 4 ANZ-relevant learn-from (belux-clawpilot as anz-clawpilot template, uspro-se-toolbox governance pattern, clawpilot-skills marketplace pattern, Cooking-with-Cowork inner-source framework) · 10 know-it-exists. Includes install order, why-now for each, decision criteria for the try-and-compare set, and a draft spec for PAC's future "Scout" tab (weekly auto-scan + LLM-scored digest — none of the existing internal tools do this, so it's PAC's defensible differentiator). Read first when picking install priorities for Sush's CLI/MCP fleet, or when designing PAC's Scout tab. Built 21 May 2026. |
| OpenClaw Companion + CDX Foundry Playbook | The execute-only recipe for installing the OpenClaw Companion (Molty) Windows tray app pointed at a Microsoft Foundry resource in Sush's CDX tenant, PLUS the canonical recipe for adding messaging channels (WhatsApp, Telegram, Signal etc.) to atlas-gw. Built 4 Jun 2026 in session f69e1571. Major expansion 5 Jun 2026 PM (session 786f4f8c): § 12 NEW — WhatsApp via Baileys (NOT Chromium!) + Atlas identity files (IDENTITY.md / USER.md / SOUL.md / FAMILY.md / GROUPS.md pattern + BOOTSTRAP.md deletion trap) + lockdown config (allowFrom, groupAllowFrom, per-JID systemPrompt) + family-group integration template + Sush's 2-WhatsApp-account model (personal vs Business as Atlas identity). 22 named gotchas with cost (G18: @openclaw/whatsapp uses Baileys not Puppeteer; G19: channels are process-local not satellite-node; G20: BOOTSTRAP.md makes agent ask "who am I" forever until deleted; G21: tools.profile="coding" filters out whatsapp_login + message + 4 others; G22: probe truncation hides full schema for mentionPatterns/ackReaction; CDX disables local-auth on every Cognitive Services resource — Entra-ID only; data-plane RBAC is separate from sub Owner + needs 3-5 min propagation; SP can do ARM but not Graph; az account clear while user is AFK is destructive; the Companion installer cert NotAfter is 6 Jun 2026 but Authenticode-timestamped through Oct 2026; etc.), the architecture diagram (Companion ↔ WSL gateway ↔ Foundry ↔ optional MXC sandbox + the cloud atlas-gw VM via CF tunnel), full reusable PowerShell + bash invocation snippets, the 6-step wizard onboarding walk-through, the 13-step atlas-gw deploy recipe, the 7-step WhatsApp Baileys recipe, resume one-liners, and the append-only execution log. Read first when installing OpenClaw on a new device, troubleshooting Companion ↔ gateway ↔ Foundry chain, adding more model deployments, adding ANY messaging channel (Telegram/WhatsApp/Signal/Discord/etc.), seeding Atlas's identity files, or when any new Cognitive Services / AOAI / Foundry work in the CDX tenant comes up. Living doc — append to Section 6 (gotchas) and the timeline log as you go. Cross-references the MXC handoff for the deferred enterprise-sandbox path. |
| atlas-gw Reliability Playbook | Read first when aunty goes silent overnight, OR when any work touches vm-atlas-gw-01 lifecycle, the openclaw-gateway systemd unit, the Resource Health alerts, the Action Group, or the Automation Runbook. Built 7 Jun 2026 in session 23ef0e09 after 2 nights of family-group silence caused by CDX-tenant auto-shutdown of the VM + a systemd LoadCredential= boot race. Two complementary layers deployed: (1) Azure-side auto-restart via Resource Health alert → Action Group → Automation Runbook (Start-AtlasGw) → Start-AzVM — octowatch pattern, $0/mo within free tier, 3-7 min recovery; (2) In-guest systemd boot-resilience drop-in extending retry budget from 10/5min to 20/30min for KV-warmup race. CRITICAL Rule #5 retrospective in § 7 — the session that built this fix initially proposed a custom Windows watcher on Sush's laptop; rubber-duck + GPT-5.5 + research-agent all converged on the correct answer (the Azure-native pattern in this playbook) only after Sush invoked the architecture gate manually. Future Atlas: if you find yourself building a custom PowerShell/cron/script on the user's machine to auto-restart an Azure VM, STOP and read this playbook first. Includes diagnose-silent-aunty probes, idempotent test recipe, common failure modes, backlog (belt-and-braces deallocate alert + scheduled fallback runbook + KV warmup retry in fetch-openclaw-token.sh). |
| PAC Architecture & Conventions (ARCHIVED) | [ARCHIVED 2026-05-24] PAC v0.2.1 architecture (22 May 2026 cut). PAC was paused and the codebase archived to pac-archive @ v0.6.1. Kept here for the transferable patterns: why MSAL was ripped out (CA-blocked twice); the WorkIQ MCP + Copilot-CLI---acp internal-first replacement; Electron process model + IPC surface; env-scrub discipline; ACP read-only tool defaults. Reach for these patterns in future Electron / desktop-shell work — not as a PAC-specific guide. |
| PAC v0.8 Second-Brain (ARCHIVED) | [ARCHIVED 2026-05-24] PAC v0.8 architecture (22 May 2026 overnight cut). PAC was paused and archived to pac-archive @ v0.6.1. Kept here for the transferable patterns: Triage/Calendar/Threads three-tab workspace over a flat-JSON store fed by workiq.cmd; threading heuristic (Jaro-Winkler + 3× prefix normalisation); draft-delivery Option C (voice-aware drafts to ~/.copilot/drafts/*.md); 168 QA gates + 86 unit tests pattern. Reach for these patterns in atlas-portfolio / atlas HELM or any second-brain work — not as a PAC-specific guide. |
| M365 + Clawpilot Playbook | The canonical answer for wiring M365 (email / chat / calendar) into Atlas without building a new app. Set 27 May 2026 from Issy peer-AI knowledge transfer. The auth recipe (MSAL acquireTokenInteractive in embedded browser, scopes against /me user-delegated — no admin consent wall): Mail.Read/Send/ReadWrite, Chat.Read/ReadWrite, People.Read, Calendars.ReadWrite. Direct Graph vs WorkIQ routing (Graph for nouns, WorkIQ for verbs). Skills pattern (markdown files, LLM is the renderer). MSX probe-before-render skill pattern. Path C Helm + Clawpilot connector (Clawpilot owns M365, Helm sidebar asks Clawpilot via ACP when customer context demands). Failure-mode matrix mapping every PAC + atlas-portfolio bump to the alternative. Execution checklist for the next session that acts on this. Read first when wiring M365 into anything — this is the canonical answer. |
| atlas-portfolio Architecture | Successor to PAC + Atlas CC (both paused 2026-05-24). Static HTML + node script + msx-mcp stdio subprocess — third time's the charm. Why Path B (static HTML, NO Electron) won the architecture gate; the az login auth pattern (NO MSAL) lifted from Frontier SE / msx-mcp; the canonical MCP SDK Client subprocess pattern; right-anchored markdown parsing (defensive default — opp names contain pipes); VPN profile gotcha (MSFT-AzVPN-Manual not MSFTVPN-Manual for prod MSX IP allowlist); upstream msx-mcp Node 24 + Windows execFile patch (PR #431 on mcaps-microsoft/msx-mcp); M365 filter heuristic; snapshot schema v2 with per-customer opps embedded; PAC Atlas Console v3 design DNA (Inter + JetBrains Mono, #fbbf24 amber, #06b6d4 cyan, typewriter // XX · UPPERCASE section labels, tilde ~ markers). Two standing rules: NEVER load mock data (real MSX only) · scope is M365 / Copilot / Agent 365 only (NO ACR / NO MACC). v0.1 shipped 4 phases in 5 hours on 2026-05-24. Read first when resuming any atlas-portfolio work. |
| Clawpilot Embed Research | Parked 2026-05-27. v2.2.0 attempted, reverted to v2.1.10 baseline. Phase 0 source-read findings (no external API, mini-mode architecture, single-instance lock, Teams Relay path, identity model); decompiled app.asar location; what's possible vs not for external integration; why rc1 SetParent+positioning failed (multi-monitor + DPI + Z-order race + diag-logging blind spot); why rc2 Path B "side-by-side launcher" felt insufficient (Sush's emotional test failed: visible seam, two-windows pretending to be one); 7 concrete recommendations for the next attempt (read MS-internal gim-home/m source first; run a hardware-specific SetParent spike; investigate inverse "Clawpilot embeds HELM" direction; consider Teams app embedding; fork as last resort); artifacts preserved in session 591b6a54-1de9-4542-a77a-079ba239d967/files/ including the extracted asar (~505 MB), the working PowerShell bridge code, and the Playwright self-test. Read first when picking up Clawpilot embed work cold. |
| atlas-portfolio Data Pipeline | The operational counterpart to atlas-portfolio-architecture.md. What gets scraped, in what order, into what file, and how to verify the result. Source-of-truth map covering MSX (msx-mcp → snapshot-customers---c360 → PRU/AVD/agreements) + Lynx home (one-off, tenant map) + Lynx /reports/your-tenants (portfolio rollup) + Lynx per-tenant page (per-app MAU/WAU/DAU) + Lynx admin (cohort search OR Admin Configs tab — both kept, loader prefers tab). Execution DAG, dependency table, weekly tracker template Atlas copies into the session journal each refresh. Concrete QA sentinels (ASB Anthropic=Enabled, customerCount 50-60, etc.) — scripts/refresh-qa.mjs automates them and exits non-zero on red flags. READ BEFORE any atlas-portfolio scrape/refresh work; run refresh-qa.mjs after every refresh. Set 2026-05-25 in v1.0.1. |
Susanth FY27 Dashboard — susanth-fy27-dashboard-playbook.md (internal, not published) |
Internal working notes — not published to this site. Operational playbook for the FY27 customer adoption dashboard: data sources, build script, the frozen day-one baseline used for all deltas, refresh recipe, sections and backlog. Read the local file for detail. Set 2026-07-01. |
Signal Cockpit — signal-cockpit-playbook.md (internal, not published) |
Internal working notes — not published to this site. Canonical playbook for the signal-driven mode of the dashboard: architecture, locked decisions, the never-list, file map, commands and current state. Read the local file for detail. Set 2026-07-02. |
Mission Tab Playbook — mission-tab-playbook.md (internal, not published) |
Internal working notes — not published to this site. Playbook for the dashboard's attainment-tracking mode: scorecards, focus band, deal board, per-tab sync indicators, refresh schedule, data schema and guardrails. Read the local file for detail. Built 23–24 Jul 2026. |
Backup & Recovery Architecture — backup-and-recovery-architecture.md (internal, not published) |
🔴 CANONICAL for backup, restore and disaster recovery. Read FIRST before ANY backup work, and before answering any question about what would survive losing the machine. Consolidates what used to be scattered across six places. Covers: the one-sentence entry point that starts a recovery from any agent on any machine (and its 4 independent copies) · the four channels and which of them has rollback / is reachable on a bare machine · what is and is NOT backed up (and why locally-committed-but-unpushed work does not survive) · the ten scheduled jobs and five health beacons · a recovery decision tree · an alarm→meaning→action table · honest weak points · 12 hard-won rules · and a pointer map declaring which doc is authoritative for every other backup mention. Read the local file for detail. Set 2026-08-28. |
| atlas-portfolio OneDrive Backup | ⚰️ RETIRED, and NOT the Copilot CLI backup — do not act on this for disaster recovery. Historical playbook for a different system: the retired atlas-portfolio repo's local working data mirrored weekly to corp OneDrive. Kept only for transferable robocopy//MIR patterns. For anything about backing up or restoring this machine, see backup-and-recovery-architecture.md. Set 2026-05-25, retired 2026-07-04. |
| Atlas HELM Design Philosophy | 🎨 THE LIVING CONSTITUTION for HELM visual design. Read first before ANY phase that touches a HELM visual surface (today-tab, overview-tab, customer cards, scout cards, etc). Set 2026-05-29 (session 386fd1f6) from Sush's "make each card tell its own story" directive — bento mosaic principle (cards have shape-fit-to-content, not stacked uniform rectangles), 5-second cold-user test, story-shape mapping table for Today cards (hero=2×2 anchor · timeline=4×1 strip · top-3=1×3 tall · hot pipeline=3 squares · atlas brief=2×3 serif narrative · scout=3×1 strip), IBM Plex Sans + JetBrains Mono + IBM Plex Serif typography plan (replaces HELM's current Inter, matches what PAC actually uses), amber/cyan discipline (amber reserved for STAKES only — money/customer/time at risk), 8 better-than-asked queued moves (sticky hero, freshness ink, growable cards, sparklines, pinning, hover halos, two-state cards, quiet-day creative space), Path A grid-template-areas skeleton with mobile collapse, risks + guardrails + change log. Intentionally FLUID — expect v2/v3/v10. Each session may EDIT this doc. Phase 200 series in ~/.copilot/atlas-portfolio-phases.md carries the multi-session execution plan. |
| Work IQ Two-Track Playbook | 🔴 The non-negotiable operational pattern for ALL Work IQ API work — MSFT corp tenant (HELM/CLI internal productivity) and CDX tenant (public blog/learning content) are STRICTLY SEPARATE parallel sessions. Neither Atlas may ever read/render/log/screenshot/summarise data from the other tenant. Set 2026-06-10 from Sush's direct instruction ("please don't ever mix both together — both world are separate") during the Work IQ API GA prep session 078b16de. Formalises the operational pattern that enforces the existing 🔒 Internal Data Classification rule. Covers: the two-track tenant + auth + destination matrix, the hard symmetric rule (corp Atlas never touches CDX paths; CDX Atlas never logs in as *@microsoft.com), Track A scope (HELM Mail tab, Copilot CLI WorkIQ plugin, customer-360 context, drafts-only per Rule #2), Track B scope (CDX exploration, screenshot-for-blog, Day-1 GA blog draft, billing experiments post-Jun-16), how sessions hand off (no cross-tenant messages; shared brain via 3-file system + portal but never shared data; journal entries labelled [Track A — corp internal] vs [Track B — CDX public]), the firing conditions (when this rule fires vs when it doesn't), and the kickoff prompt pattern for spawning the Track B parallel session. Read first BEFORE starting any Work IQ session, OR when picking up an existing one cold and deciding which tenant it's against. |
What does NOT live here¶
- Rules that must be followed every session — those stay in
copilot-instructions.md - Sensitive operational details — internal tenant info, customer-specific paths, anything Microsoft-confidential
- Secrets, tokens, passwords — never in either file. They live in
~/.copilot/secrets/ - Calendar items (self-reminders with dates) — those stay in
copilot-instructions.mdso they fire on session start
Editing rules¶
When future-Copilot adds a new entry here:
- Use a focused, scannable format — tables, bullet lists,
!!! noteadmonitions - Lead with the answer, then why, then examples
- Cross-link liberally between pages
- If a rule emerges that must apply every session, copy the rule line into
copilot-instructions.mdand leave the depth here - Run
mkdocs build --strictbefore committing to catch broken links - Add a row to the table above when creating a new file. The table is the directory; the playbooks are the books. (Set 10 May 2026 alongside the Learn-Doc-First Rule.)
- Naming:
<topic>-playbook.md(ongoing) ·<topic>-system.md(design system) ·<area>-quickref.md(cheat sheet) ·<event>-incident.md(post-mortem) ·<topic>-followups-prompt.md(kickoff prompt for next session)
Why this section exists¶
Sush asked for it. Direct quote from May 2026:
"make sure my study sections are intact and create a new memory section for you and move all things related to you there. and reorganise everything as it makes sense, and rebuild things as it makes sense. You have full creative freedom and control and I trust you."
The design intent: shrink copilot-instructions.md to the minimum set of cross-cutting rules, and offload everything else here so future-Copilot can grow this annex over time without fattening the always-loaded instructions file.