You asked: when I say "put it in the frontmatter," WHICH file? The chat itself? The handoff? The session JSON? Answer: a chat creates a bunch of different files, and they each handle metadata differently. Here's the map.
You probably think of "a chat" as one thing — the conversation that happens in your VS Code sidebar. But every chat actually has at least four different files connected to it. Each one stores different information.
Two of these files (handoff + status-back) are markdown — you write them. Two of them are not — Claude Code writes them. Same chat. Very different files.
When I say "frontmatter" I always mean the YAML block at the very top of a markdown file. It looks like a list of key: value pairs, fenced by three dashes above and below. Then comes the actual document.
Everything between the two --- lines is the frontmatter. The highlighted lines above are where all our naming-related stuff lives: chat_name, audience, standing, etc.
The bit AFTER the closing --- is the actual document body — the brief, the writeup, whatever the file is for.
YAML is just a simple way to write key-value pairs in plain text. It's not a programming language — no logic, no expressions. Just labels and values. The whole reason markdown files use a YAML block at the top is to attach a few labels to the document without polluting the prose.
Before you start a new chat, you write a handoff file — a markdown file in your ~/lab/handoffs/active/ folder that says "here's what this new chat is supposed to do." It's the brief.
That handoff file has frontmatter at the top. This is where the chat's tag, audience, standing-status, etc. all live. When I say "Q9 sets standing: true in frontmatter," I mean: in the YAML block at the top of the handoff file that launched that chat.
The status-back file (the writeup after the chat finishes) follows the same pattern. Same shape. Same frontmatter style. Just describes the chat's outputs instead of its plans.
So when I say "put it in frontmatter," I mean the handoff file's YAML block. Every time. That's the only "frontmatter" we're touching.
Behind the scenes, every Claude chat you start gets stored in a file at ~/.claude/projects/<encoded-path>/<uuid>.jsonl. That's Claude Code's internal record of the conversation — every message you send, every tool I call, every result.
That file is JSONL, not markdown. JSONL means "one JSON object per line." There's no YAML frontmatter block at the top; the whole file is structured JSON throughout.
When you run /rename inside a chat, it writes a special line into this session JSONL file: {"type":"custom-title","customTitle":"AL-1.3"}. That's how the /resume picker knows what to show.
So the JSONL file does hold a name — but it's stored as JSON, not as YAML frontmatter. Two different file formats. Two different storage mechanisms.
You don't write this file by hand. You don't edit it directly. Claude Code manages it for you. The most you do is run /rename inside the chat, and Claude Code updates the JSONL.
What you and I type at each other right now — that's the conversation. It's not really a file at all (well, it's logged into the JSONL above, but the live conversation is a stream, not a settings sheet).
The conversation has no frontmatter. No metadata. No labels. Just back-and-forth.
If you need to attach a "this chat is called SL-0.6" label to the conversation itself, you can't. You either (a) write it into the handoff file's frontmatter (where it lives properly), or (b) run /rename SL-0.6 to write it into the JSONL session storage.
Five rows. Read once. Bookmark.
| Where | What is it | Frontmatter? |
|---|---|---|
| handoff-*.md | The brief — written before the chat starts. Tells the chat what to do. | ✓ YES (the main one) |
| status-back-*.md | The writeup — written after the chat finishes. Tells you what got done. | ✓ YES (mirrors handoff) |
| research/*.md, ideas/*.md | Other markdown the chat produces. | ✓ YES |
| <uuid>.jsonl | Claude Code's internal record of the chat. JSON, not markdown. | ~ kind of (JSON, not YAML) |
| (the chat itself) | What we type. Live conversation. No file at all. | ✗ NO |
When this course (or any chat) says "add it to frontmatter", we mean: the handoff file's YAML block. The session JSONL handles its own metadata internally and you almost never touch it directly.
chat_name, audience, standing, etc./rename writes to this file.