portable-agent-layer 0.31.0 → 0.33.0

package/assets/skills/consulting-report/template/app/page.tsx

@@ -1,13 +1,28 @@
 import { AlertTriangle, CheckCircle2, Lightbulb, Target } from "lucide-react";
 import { Callout } from "@/components/callout";
+import { ComparisonTable } from "@/components/comparison-table";
 import { CoverPage } from "@/components/cover-page";
 import { Exhibit } from "@/components/exhibit";
 import { FindingCard } from "@/components/finding-card";
 import { RecommendationCard } from "@/components/recommendation-card";
 import { Section } from "@/components/section";
+import { StatGrid } from "@/components/stat-grid";
+import { TableOfContents } from "@/components/table-of-contents";
 import { Timeline } from "@/components/timeline";
 import { reportData } from "@/lib/report-data";
 
+const sections = [
+  { id: "executive-summary", title: "Executive Summary" },
+  { id: "situation-assessment", title: "Situation Assessment" },
+  { id: "key-findings", title: "Key Findings" },
+  { id: "risk-analysis", title: "Risk Analysis" },
+  { id: "strategic-opportunity", title: "Strategic Opportunity" },
+  { id: "recommendations", title: "Strategic Recommendations" },
+  { id: "target-state", title: "Target State Vision" },
+  { id: "roadmap", title: "Implementation Roadmap" },
+  { id: "call-to-action", title: "Call to Action" },
+];
+
 export default function ReportPage() {
   const data = reportData;
 
@@ -23,29 +38,29 @@ export default function ReportPage() {
       />
 
       <div className="report-container">
-        <Section title="Executive Summary">
+        <TableOfContents items={sections} />
+
+        <Section id="executive-summary" title="Executive Summary">
           <p className="text-lg mb-6">{data.executiveSummary.context}</p>
 
-          <Exhibit number={1} title="Assessment Methodology">
-            <div className="flex items-start gap-8">
-              <div>
-                <p className="text-3xl font-bold text-primary">
-                  {data.executiveSummary.methodology.interviewCount}
-                </p>
-                <p className="text-sm text-muted">Interviews Conducted</p>
-              </div>
-              <div className="flex-1">
-                <p className="text-sm font-semibold text-foreground mb-2">
-                  Roles Interviewed:
+          <StatGrid
+            stats={[
+              {
+                value: String(data.executiveSummary.methodology.interviewCount),
+                label: "Interviews",
+              },
+              { value: "—", label: "Headline metric", caption: "replace with your own" },
+              { value: "—", label: "Headline metric", caption: "replace with your own" },
+            ]}
+          />
+
+          <Exhibit number={1} title="Roles Interviewed">
+            <div className="grid grid-cols-2 gap-1">
+              {data.executiveSummary.methodology.roles.map((role) => (
+                <p key={role} className="text-sm text-muted">
+                  {role}
                 </p>
-                <div className="grid grid-cols-2 gap-1">
-                  {data.executiveSummary.methodology.roles.map((role) => (
-                    <p key={role} className="text-sm text-muted">
-                      {role}
-                    </p>
-                  ))}
-                </div>
-              </div>
+              ))}
             </div>
           </Exhibit>
 
@@ -75,7 +90,7 @@ export default function ReportPage() {
           </ul>
         </Section>
 
-        <Section title="Situation Assessment">
+        <Section id="situation-assessment" title="Situation Assessment">
           <div className="grid gap-6">
             <div>
               <h3 className="text-lg font-semibold mb-2 flex items-center gap-2">
@@ -95,7 +110,7 @@ export default function ReportPage() {
           </div>
         </Section>
 
-        <Section title="Key Findings">
+        <Section id="key-findings" title="Key Findings">
           <p className="text-muted mb-6">
             Our analysis identified {data.findings.length} significant findings that
             require attention. Each finding is supported by evidence gathered during our
@@ -108,7 +123,7 @@ export default function ReportPage() {
           </div>
         </Section>
 
-        <Section title="Risk Analysis">
+        <Section id="risk-analysis" title="Risk Analysis">
           <div className="grid gap-6">
             <Exhibit number={3} title="Existential Risks">
               <div className="space-y-3">
@@ -142,7 +157,7 @@ export default function ReportPage() {
           </div>
         </Section>
 
-        <Section title="Strategic Opportunity">
+        <Section id="strategic-opportunity" title="Strategic Opportunity">
           <Callout label="The Path Forward">{data.strategicOpportunity.goodNews}</Callout>
 
           <h3 className="text-lg font-semibold mt-6 mb-3 flex items-center gap-2">
@@ -162,7 +177,7 @@ export default function ReportPage() {
           </ul>
         </Section>
 
-        <Section title="Strategic Recommendations">
+        <Section id="recommendations" title="Strategic Recommendations">
           <p className="text-muted mb-6">
             Recommendations are prioritized by urgency and impact.
           </p>
@@ -173,9 +188,21 @@ export default function ReportPage() {
           </div>
         </Section>
 
-        <Section title="Target State Vision">
+        <Section id="target-state" title="Target State Vision">
           <p className="text-lg mb-6">{data.targetState.description}</p>
 
+          <ComparisonTable
+            leftLabel="Today"
+            rightLabel="Target"
+            rows={[
+              {
+                metric: "Replace with metric",
+                left: "Current state value",
+                right: "Target state value",
+              },
+            ]}
+          />
+
           <Exhibit number={5} title="Key Capabilities Enabled">
             <div className="grid md:grid-cols-3 gap-4">
               {data.targetState.keyCapabilities.map((capability) => (
@@ -201,7 +228,7 @@ export default function ReportPage() {
           </ul>
         </Section>
 
-        <Section title="Implementation Roadmap">
+        <Section id="roadmap" title="Implementation Roadmap">
           <p className="text-muted mb-6">
             The transformation should be executed in phases, with clear milestones and
             decision points.
@@ -211,7 +238,7 @@ export default function ReportPage() {
           </Exhibit>
         </Section>
 
-        <Section title="Call to Action">
+        <Section id="call-to-action" title="Call to Action">
           <div className="bg-primary/5 rounded-2xl p-8 border border-primary/20">
             <h3 className="text-xl font-semibold mb-4">Immediate Next Steps</h3>
             <ol className="space-y-3 mb-6">

package/assets/skills/consulting-report/template/components/comparison-table.tsx

@@ -0,0 +1,40 @@
+interface ComparisonRow {
+  metric: string;
+  left: string;
+  right: string;
+}
+
+interface ComparisonTableProps {
+  leftLabel: string;
+  rightLabel: string;
+  rows: ComparisonRow[];
+  metricLabel?: string;
+}
+
+export function ComparisonTable({
+  leftLabel,
+  rightLabel,
+  rows,
+  metricLabel = "Metric",
+}: ComparisonTableProps) {
+  return (
+    <table className="comparison-table">
+      <thead>
+        <tr>
+          <th>{metricLabel}</th>
+          <th>{leftLabel}</th>
+          <th>{rightLabel}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={row.metric}>
+            <td className="metric">{row.metric}</td>
+            <td>{row.left}</td>
+            <td>{row.right}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/assets/skills/consulting-report/template/components/section.tsx

@@ -1,14 +1,15 @@
 import { cn } from "@/lib/utils";
 
 interface SectionProps {
+  id?: string;
   title: string;
   children: React.ReactNode;
   className?: string;
 }
 
-export function Section({ title, children, className }: SectionProps) {
+export function Section({ id, title, children, className }: SectionProps) {
   return (
-    <section className={cn("report-section", className)}>
+    <section id={id} className={cn("report-section", className)}>
       <h2>{title}</h2>
       {children}
     </section>

package/assets/skills/consulting-report/template/components/stat-grid.tsx

@@ -0,0 +1,26 @@
+interface Stat {
+  value: string;
+  label: string;
+  caption?: string;
+}
+
+interface StatGridProps {
+  stats: Stat[];
+}
+
+export function StatGrid({ stats }: StatGridProps) {
+  return (
+    <div
+      className="stat-grid"
+      style={{ gridTemplateColumns: `repeat(${stats.length}, minmax(0, 1fr))` }}
+    >
+      {stats.map((s) => (
+        <div key={s.label} className="stat">
+          <div className="stat-value">{s.value}</div>
+          <div className="stat-label">{s.label}</div>
+          {s.caption && <div className="stat-caption">{s.caption}</div>}
+        </div>
+      ))}
+    </div>
+  );
+}

package/assets/skills/consulting-report/template/components/table-of-contents.tsx

@@ -0,0 +1,27 @@
+interface TocItem {
+  id: string;
+  title: string;
+}
+
+interface TableOfContentsProps {
+  items: TocItem[];
+  title?: string;
+}
+
+export function TableOfContents({ items, title = "Contents" }: TableOfContentsProps) {
+  return (
+    <nav className="toc">
+      <h2>{title}</h2>
+      <ol>
+        {items.map((item, i) => (
+          <li key={item.id}>
+            <a href={`#${item.id}`}>
+              <span className="toc-number">{(i + 1).toString().padStart(2, "0")}</span>
+              <span className="toc-title">{item.title}</span>
+            </a>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}

package/assets/skills/presentation/SKILL.md

@@ -59,9 +59,10 @@ Authoring this way means: a malformed edit only takes down its own slide, slides
 Per-slide conventions (inside each file):
 - Speaker notes: lines starting with `Note:`.
 - Layout directive: `<!-- .slide: data-layout="..." -->` at the top.
+- Image references: `![alt](../assets/foo.png)` — the natural relative path from `slides/*.md` to the deck's `assets/` folder. The build rewrites this to `assets/foo.png` in the concatenated `<deck-name>.md` (which sits at the deck root, so the path stays valid for direct preview), and inlines the image bytes as a `data:` URI in the HTML so the output is truly self-contained (emailable, USB-stickable). Remote refs (`https://…`) and `data:` URIs pass through untouched.
 - See "Layouts" below for the available layout names.
 
-Backwards compatible: if `slides/` doesn't exist, the build falls back to a single `<deck-dir>/content.md` with `---` separators between slides.
+Backwards compatible: if `slides/` doesn't exist, the build falls back to a single `<deck-dir>/content.md` with `---` separators between slides. Image refs there should use `assets/foo.png` (root-relative), since `content.md` already lives at the deck root.
 
 ### Step 3: Build
 
@@ -69,12 +70,14 @@ Backwards compatible: if `slides/` doesn't exist, the build falls back to a sing
 bun ~/.pal/skills/presentation/tools/build.ts <deck-dir> [--out <dir>] [--force]
 ```
 
-Output goes to `<out>/<deck-name>/`, where `<deck-name>` = the basename of `<deck-dir>`:
+Output files (where `<deck-name>` = basename of `<deck-dir>`):
 
 - `<deck-name>.md` — the concatenated source (all `slides/*.md` joined with `---` separators), written to disk **first** so you can inspect, diff, or feed it into other tooling.
 - `<deck-name>.html` — the self-contained presentation (CSS, JS, fonts, logo all inlined). Email it, USB-stick it, host it anywhere.
 
-Defaults: `--out` defaults to the current working directory. The `<deck-name>/` subdir is always created — even when `--out` is explicit — so multiple decks can coexist in one folder.
+Default location: `--out` defaults to the **deck-dir itself**, and the files land flat at `<deck-dir>/<deck-name>.{html,md}` — next to your slides, regardless of where you ran the build from. The scaffolder's `.gitignore` already covers them.
+
+Override: pass `--out <dir>` to redirect elsewhere. When `--out` is *not* the deck-dir, a `<deck-name>/` subdir is created under it so multiple decks can coexist in one collection folder.
 
 `--force` overwrites an existing build. Without it, the build refuses to clobber `<deck-name>.{md,html}`.
 
@@ -90,7 +93,8 @@ Catches authoring failures before you ever open the browser:
 - Title or subtitle exceeding the visual budget (h1 > 60 chars, h2 > 100).
 - Layout-content mismatch — `comparison` without a `<div class="compare">`, `metric-grid` without `<div class="metrics">`, `two-column` missing column wrappers, etc.
 - Overflow heuristics — `agenda` > 10 items, `content` > 7 bullets, `code` block > 25 lines, `table` > 10 rows, `metric-grid` ≠ 3 metrics.
-- Image referenced via `![](assets/...)` but the file is missing.
+- **Visual-line budget**: any bullet-bearing slide (`content`, `agenda`, `comparison`, `two-column`) with > 10 flattened list lines (top-level + sub-bullets combined). 10 fits cleanly; 11+ overflows even when each line is short.
+- Image referenced via `![](../assets/...)` (slide-relative) or `![](assets/...)` (root-relative, for legacy `content.md` decks) but the file is missing.
 - Layout requirements — `big-stat` without an h1, `quote` / `pull-quote` without a `> blockquote`.
 
 Exit codes: `0` = clean, `1` = errors found (or warnings under `--strict`), `2` = usage error. Run before each build in your iteration loop, or wire it into a pre-commit hook.
@@ -112,10 +116,105 @@ Open `<out>/<deck-name>/<deck-name>.html` in your browser. Iterate by editing a
 └── assets/                 # images / videos referenced from slides/*.md
 ```
 
-Build output is **never** written inside `<deck-dir>` — it lands in `<out>/<deck-name>/` (default `<cwd>/<deck-name>/`). The scaffolder's `.gitignore` covers the case of running build from inside the deck-dir.
+Build output lands flat inside the deck-dir by default (`<deck-dir>/<deck-name>.{html,md}`), or under `<out>/<deck-name>/` when `--out` is explicit. Both shapes are covered by the scaffolder's `.gitignore`.
 
 (Legacy: a single `content.md` at the deck root still works — see Step 2.)
 
+## Content principles
+
+The doctor enforces *structural* discipline (slide budgets, layout-content match, missing assets). These rules are about *content* — what goes on the slide and in the notes. They apply to every deck regardless of type. For type-specific rules, see the "see also" links at the bottom of this section.
+
+### Core rules
+
+- **A slide carries what the *learner* takes away — never what happens in the room.** "We will discuss CI/CD agents" is not a slide; "CodeRabbit and CodeAnt cost ~$15/dev/mo at this scale" is.
+- **Less is more on bullets.** The doctor caps `content` at 7 bullets; the content rule is stricter — 3–5 is usually right. One bullet is not a slide; either expand or fold into the previous one.
+- **Two ideas → two slides.** If a slide carries two takeaways, split.
+- **No sentences on slides or in notes.** Exceptions: quotes, code comments, single callout sentences. Everything else is bullets, including notes.
+- **A title-only slide is valid only as a `section` divider.** Single-word slides and single-bullet slides are not valid — split or expand.
+- **Vocabulary consistency.** Pick one word per concept ("agent" vs "assistant", "tool" vs "capability") and use it everywhere. Drift confuses the audience.
+- **Layout choice = content choice, not decoration.** `big-stat` says "this number *is* the point." `comparison` says "you have to choose between these." `quote` says "someone earned the right to say this." Wrong layout muddies the message.
+- **Define jargon before using it.** First use of a non-obvious term gets a parenthesized gloss or its own glossary slide. After that, no.
+
+### Bullet & sub-bullet structure
+
+- **Top-level bullet = one fact or one claim.** 6–12 words. If you need more, split or use a sub-bullet.
+- **Sub-bullets = elaboration of the parent.** A list, an example, a clarification. 2–8 words each. Don't start a new claim at a sub-bullet — that's a top-level bullet.
+- **Never use em-dash continuations to extend a bullet.** `- Foo — bar — baz` is prose pretending to be a bullet. Convert to:
+  ```markdown
+  - Foo
+    - bar
+    - baz
+  ```
+  Em-dash is reserved for: title qualifiers ("Block 4 — Landscape"), and anticipated Q&A in notes (`"Question?" — short answer`).
+- **Stable parallel structure inside a bullet group.** If bullet 1 starts with a verb, bullets 2–N start with verbs. If bullet 1 is `Name: description`, the rest match.
+- **Concrete over abstract.** Show paths, file names, numbers, command snippets in backticks. "the project file" is weaker than `./CLAUDE.md`.
+
+### Notes structure
+
+Notes are the speaker's working surface during delivery. They must be scannable, not readable. Strict format:
+
+1. **Source links first**, one per line, before any explanation. Multiple links are fine if the slide cites multiple sources. The speaker should never scroll to find a link they're about to open in the browser.
+2. **Named beats as top-level bullets.** A "beat" is a named chunk of context — `Eval setup`, `Headline numbers`, `Why X wins`, `Common output`, `Anticipated questions`. The beat name lets the speaker jump.
+3. **Sub-bullets under each beat.** Same 2–8 word budget. Lists, edge cases, examples. No prose.
+4. **Quotes nest under a `- Quote` beat** as a markdown blockquote (`>`). Quotes are the only place full sentences are allowed in notes.
+5. **Anticipated Q&A near the end.** Format: `- "Question?" — short answer`. The em-dash here separates the quote from the answer; this is the legal use.
+6. **Forward references are terse.** "more in Day 2 when you build your own", "see Block 2 for X". Not "we'll discuss this later" prose.
+
+### Voice
+
+- **Declarative, not hedging.** "Anthropic's holdout" beats "Anthropic has chosen a different approach." If you mean it, say it; if you don't, cut it.
+- **Opinionated where the room expects opinion.** Workshops are taught, not narrated. State which option you'd pick and why.
+- **Concrete identifiers visible.** File paths, version numbers, URLs, exact tool names. The audience should be able to type what's on the slide and have it work.
+
+### Examples
+
+**Bad slide — describes the room, not the takeaway:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Code Review Agents
+
+- We will look at three vendors
+- Pricing comparison
+- Live demo of CodeRabbit
+```
+
+**Good slide — what the learner walks away with:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Code review agents — when each wins
+
+- CodeRabbit: best for large PRs, weakest at C# specifics
+- CodeAnt: tightest C# rules, no PR summary
+- Custom (Claude Code in CI): controllable, you pay per token
+```
+
+**Bad notes — prose, no source link:**
+
+```markdown
+Note: We should talk about EchoLeak here. It was a vulnerability in Microsoft 365 Copilot discovered in 2025 that allowed prompt injection through email content. The attack worked by sending a crafted email that the Copilot assistant would later read and execute instructions from. This is a good example of why we need to think about prompt injection in agentic systems.
+```
+
+**Good notes — link first, bullets, anticipated questions:**
+
+```markdown
+Note:
+- [EchoLeak (CVE-2025-32711) — Microsoft writeup](https://msrc.microsoft.com/...)
+- Zero-click prompt injection in M365 Copilot via crafted email
+- Attack surface: any agent that reads attacker-controlled content
+- Mitigations
+  - Tool allowlists, not denylists
+  - Human-in-loop on data exfil tools
+- "Could this happen with Claude Code?" — yes, via any tool that reads external text (web fetch, MCP server, log file)
+```
+
+### See also (type-specific rules)
+
+- **Workshops, training, hands-on sessions:** [`WORKSHOP.md`](WORKSHOP.md)
+
+(Future: `PITCH.md`, `LECTURE.md`, `INTERNAL_REVIEW.md` — coming soon.)
+
 ## Content conventions
 
 ```markdown
@@ -188,6 +287,26 @@ Composable on any `<img>` or wrapper element:
 | `image-duotone` | Brand-tinted monochrome via filter chain |
 | `image-overlay` | Adds a brand-gradient scrim from transparent → primary at 75% bottom |
 
+## Text-alignment utilities
+
+Composable on any block element. Use these instead of inline `style="text-align: …"` — Reveal's print stylesheet forces `text-align: left !important` on every `div`/`p`/`ol`/`ul`, which silently kills inline alignment styles in print (the on-screen view looks fine, the printed PDF lands left-aligned).
+
+| Class | Effect |
+|---|---|
+| `text-center` | Center inline content (typical use: wrapping a centered `<img>` or caption) |
+| `text-right` | Right-align inline content |
+| `text-left` | Left-align inline content (rarely needed; default) |
+
+Example — centering an image on a `content` slide:
+
+```markdown
+<div class="text-center">
+
+![Waldo](../assets/waldo.png)
+
+</div>
+```
+
 ## Design tokens
 
 The skill ships a token system in `theme-base/base.css`. Templates only declare two anchors (`--brand-primary`, `--brand-accent`); the rest derives via `color-mix(in oklch, …)`.

package/assets/skills/presentation/WORKSHOP.md

@@ -0,0 +1,128 @@
+# Workshop-specific content rules
+
+Read [`SKILL.md`](SKILL.md) first — the general content principles apply unchanged. This file only adds the rules that are specific to workshops, training sessions, and hands-on formats.
+
+A workshop is not a talk. The deck is scaffolding for the room's work, not the work itself. If the slides could be read alone and convey the value, it isn't a workshop — it's a recorded lecture.
+
+## Rules
+
+- **Block arc: opener → core → demo/exercise → synthesis.** Every block follows this shape.
+  - **Opener** — one slide that earns the block: a stat, a story, a failure case. "Why should you care for the next 45 minutes?"
+  - **Core** — the actual material. The teaching slides.
+  - **Demo or exercise** — the participants do something or watch something done. Live, not recorded.
+  - **Synthesis** — one slide that closes the loop: "what you now know" or "what you can do tomorrow."
+  - Skip a beat and the block falls flat. Especially the opener.
+- **Topic shape inside a block — preferred, not required: what → proof → mechanics → advanced → exercise.** A useful default ordering for depth topics. Skip any beat that doesn't fit the topic. Reorder if a different sequence teaches better. Variability is expected; this is the shape to fall back to when nothing better suggests itself.
+  - **What** — what it is + landscape framing (who built it, who supports it, who doesn't), if it matters.
+  - **Proof** — only if you have a *genuinely* interesting stat, eval, or incident. See the big-stat rule below.
+  - **Mechanics** — how it actually works: scopes, locations, semantics, limits.
+  - **Advanced** — patterns, extensions, teaser hooks for later blocks/days.
+  - **Exercise** — bullets are *principles* (learner takeaway), notes carry facilitation.
+- **Big-stat is for genuinely interesting numbers, not a checkbox.** Use the `big-stat` layout when you have a stat that *changes the room's mind* — a real eval result, a striking incident metric, a non-obvious cost number. Don't manufacture one. A topic without a strong stat skips the proof slide; a generic stat dilutes every later one. Format when used: h1 = the number with `<em class="unit">`, h2 = the comparison-with-context (named alternatives, named source).
+- **~50% slides / ~50% hands-on.** If deck-time exceeds half the block's runtime, cut slides — not exercise time.
+- **Recall check at every block boundary.** A question slide between blocks: "Before we move on — what would you do if X?" One question, no answer, deliberate silence. Forces consolidation.
+- **Question slides as discussion prompts.** Bold question, no answer, no bullets. Use sparingly (2–3 per day max) — overuse breaks the room's trust that you have answers.
+- **Energy curve matters.**
+  - Hardest cognitive lift in the morning, before lunch.
+  - Live coding right after lunch is malpractice (post-meal energy crash).
+  - Demos and discussion in the afternoon.
+  - End each day on synthesis or a payoff demo, never on dense content.
+- **Buffer / reserve slides per block.** Every block has 1–2 slides marked optional (in the deck, not separate) used only if pace allows. Lets you stretch comfortably without scrambling. Marker convention: filename suffix `-reserve` (e.g., `045-reserve-extra-eval-example.md`) and a `<!-- reserve -->` comment at the top of the slide so the doctor can flag if any are still flagged at build time.
+- **Exercise slides follow a strict template.**
+  - **Title prefix `Exercise — `** so the room sees the mode change.
+  - **Bullets = principles, not procedure.** What the learner *takes away* by doing the exercise. Procedure ("5 minutes solo, then we compare two") goes in notes.
+  - **Standard note beats, in order:** `Facilitation`, `Common output`, `Common mistakes`, `Anticipated questions`. Use these names verbatim — the speaker scans by them.
+  - **Keep principles transferable.** A bullet that only makes sense in the context of this specific repo isn't a principle; demote it to a note example.
+
+## Examples
+
+**Bad opener — describes the agenda instead of earning the block:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Security block
+
+- Prompt injection
+- Tool aliasing
+- Credential exposure
+- Hook-based guardrails
+```
+
+**Good opener — a real incident earns the next 90 minutes:**
+
+```markdown
+<!-- .slide: data-layout="big-stat" -->
+# 9 seconds
+## Replit production database, deleted by an agent
+
+Note:
+- [Replit prod-DB deletion — postmortem](https://...)
+- Agent had unscoped DB credentials in its environment
+- "Drop the dev tables" → matched against prod by mistake
+- This is the failure mode the next 90 minutes prevent
+- "Could Claude Code do this?" — yes, if you give it `.env` with prod creds
+```
+
+**Bad recall slide — gives the answer:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Recap
+
+- Tier 1 = enterprise sanctioned
+- Tier 2 = paid + settings off
+- Tier 3 = prohibited
+```
+
+**Good recall slide — forces the room to retrieve:**
+
+```markdown
+<!-- .slide: data-layout="quote" -->
+> Your colleague asks if she can paste a 20-line C# snippet
+> from our payment service into ChatGPT Plus. What do you say?
+
+Note:
+- Let the room answer first, ~30 seconds of silence is fine
+- Correct: depends on classification — if Confidential, no; if Internal, sanitize and yes (settings off)
+- Don't give the answer until at least one person tries
+```
+
+**Bad exercise slide — procedure on the slide, no transferable principle:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Write a CLAUDE.md
+
+- Open your favorite repo
+- Spend 5 minutes writing CLAUDE.md
+- We'll pick 2 to share
+- Discuss what worked
+```
+
+**Good exercise slide — principles on the slide, procedure in notes:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Exercise — write your CLAUDE.md
+
+- Capture conventions, not procedures (procedures belong in skills)
+- One fact per line, no prose paragraphs
+- Glossary entries earn their place — only project-specific terms
+- Order matters — most-violated rules first, model reads top-down
+- Commit it; use `.local.md` only for personal overrides
+
+Note:
+- Facilitation
+  - 5 min solo on a repo they know
+  - 2 volunteers show on screen
+  - group critiques against the failure modes from prior slides
+- Common output
+  - "Use Polly for retries, not custom code"
+  - "Tests live in `tests/Unit/`, not `src/__tests__/`"
+- Common mistakes
+  - writing instructions that should be skills
+  - copying a generic style guide instead of capturing real violations
+- Anticipated questions
+  - "Should this be in AGENTS.md or CLAUDE.md?" — symlink and stop choosing
+  - "What if there's already one?" — diff against it; usually adds 30%
+```