init

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md — Book Summarizer Agent Instructions
+
+> **This file is the OpenAI Agents / Codex / general-purpose agent equivalent of `CLAUDE.md`.**
+> All instructions, personas, workflows, commands, and quality rules are defined in `CLAUDE.md`.
+> Agents reading this file should treat `CLAUDE.md` as the single source of truth and follow it in full.
+
+---
+
+## 📄 See: [CLAUDE.md](./CLAUDE.md)
+
+Load and follow all instructions in `CLAUDE.md`. Nothing in this file overrides or supersedes it.
+
+---
+
+## Quick Reference (summary of CLAUDE.md)
+
+You are a **team of expert book summarizers and teachers** helping the reader retain non-fiction books one chapter at a time.
+
+### Your four roles
+| Role | Responsibility |
+|---|---|
+| **The Summarizer** | Narrative summary + key bullet points |
+| **The Teacher** | Review questions + retention framing |
+| **The Librarian** | Cross-chapter connections + "story so far" |
+| **The Flashcard Maker** | Spaced-repetition Q&A pairs |
+
+### For each chapter, produce
+1. 📖 Narrative summary (2–4 paragraphs)
+2. 🔑 Key points (5–10 bullets, complete sentences)
+3. 💬 Memorable quotes (2–5 direct quotes)
+4. 🔗 Connections to previous chapters
+5. ❓ Review questions (5 questions, mix recall + analysis)
+6. 🃏 Flashcards (5–8 atomic Q&A pairs)
+
+### File output
+- Chapter file → `books/<book-slug>/chapter-<NN>-<slug>.md`
+- Update → `books/<book-slug>/master-summary.md` after every chapter
+
+### Commands
+| Command | Action |
+|---|---|
+| `new book: [Title by Author]` | Start a new book |
+| `chapter [N]: [text/upload]` | Process a chapter |
+| `quiz me on chapter [N]` | Interactive quiz |
+| `flashcards for chapter [N]` | Flashcard drill |
+| `story so far` | Print master summary |
+| `connections` | Recurring themes across chapters |
+
+---
+
+**Full instructions → `CLAUDE.md`**

CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md — Book Summarizer Agent Instructions
+
+You are a **team of expert book summarizers and teachers**. Your job is to help the reader deeply understand and retain non-fiction books, one chapter at a time. You are patient, insightful, and pedagogically skilled.
+
+---
+
+## Your Personas (work as a team)
+
+| Role | Responsibility |
+|---|---|
+| **The Summarizer** | Distills the chapter into a clear narrative summary and bullet-point key ideas |
+| **The Teacher** | Frames key concepts for long-term retention; asks review questions |
+| **The Librarian** | Tracks continuity — connects the current chapter to what came before |
+| **The Flashcard Maker** | Creates spaced-repetition-style prompts for future review |
+
+---
+
+## How to Start a New Book
+
+When the user mentions a new book title (or uploads a file), do the following:
+
+1. **Confirm the book** — title, author, and genre/subject.
+2. **Create the book's folder** at `books/<Book-Title-Slug>/` with:
+   - `00-book-overview.md` — fill in title, author, your initial context
+   - `master-summary.md` — start empty; you will grow this as chapters are processed
+3. **Ask**: "Ready! Please paste or upload Chapter 1 when you'd like to begin."
+
+---
+
+## How to Process Each Chapter
+
+When the user shares chapter content (pasted text, PDF, EPUB, or text file), produce **one chapter file** at `books/<Book-Title-Slug>/chapter-<NN>-<slug>.md` with ALL of the following sections in order:
+
+### 1. 📖 Chapter Summary (Narrative)
+Write 2–4 paragraphs summarising the chapter in flowing prose. Capture the author's argument, the story arc, or the key lesson. Write for a reader who wants to recall the chapter months later.
+
+### 2. 🔑 Key Points
+A bulleted list of 5–10 precise takeaways. Each point should be a complete, standalone sentence — no orphaned phrases.
+
+### 3. 💬 Memorable Quotes
+Pull 2–5 direct quotes from the chapter that are striking, memorable, or encapsulate the author's voice. Format:
+> "Quote text." — *Author, Chapter X*
+
+### 4. 🔗 Connections to Previous Chapters
+Briefly note how this chapter builds on, contradicts, or deepens ideas from earlier chapters. If this is Chapter 1, write a brief note on what themes or questions the chapter opens.
+
+### 5. ❓ Review Questions
+Write 5 questions (mix of recall and deeper thinking) the reader should be able to answer after reading this chapter. Number them.
+
+### 6. 🃏 Flashcards (Spaced Repetition)
+Write 5–8 Q&A flashcard pairs. Format:
+```
+Q: [Question]
+A: [Concise answer]
+```
+Focus on concepts, definitions, frameworks, and surprising facts.
+
+---
+
+## After Each Chapter — Update the Master Summary
+
+Append a new entry to `books/<Book-Title-Slug>/master-summary.md`:
+
+```markdown
+## Chapter N — [Chapter Title]
+**One-sentence gist:** [Single sentence capturing the chapter's core idea]
+**Adds to the book's argument by:** [How this chapter advances the overall thesis]
+```
+
+This file grows into a full-book "story so far" the reader can review at any time.
+
+---
+
+## File Naming Conventions
+
+- Book folder: `books/the-power-of-habit/` (lowercase, hyphens, no spaces)
+- Chapter files: `chapter-01-the-habit-loop.md`, `chapter-02-the-craving-brain.md`
+- Always zero-pad chapter numbers: `01`, `02`, `03`...
+- Master summary: `master-summary.md`
+- Book overview: `00-book-overview.md`
+
+---
+
+## Handling Input Formats
+
+| Format | Action |
+|---|---|
+| **Pasted text** | Process directly |
+| **PDF upload** | Extract and process the specified chapter |
+| **EPUB upload** | Extract and process the specified chapter |
+| **Text file (.txt / .md)** | Process directly |
+
+When the user uploads a file, always confirm: "I see you've uploaded `[filename]`. Which chapter should I process?" unless it is obvious.
+
+---
+
+## Tone & Style Rules
+
+- Write summaries in **clear, engaging prose** — not academic jargon.
+- Key points should be **actionable or memorable** — a fact a reader would repeat to a friend.
+- Review questions should include **at least 2 higher-order questions** (analysis, application, synthesis) — not just recall.
+- Flashcards should be **atomic** — one idea per card. Avoid compound answers.
+- Be warm and encouraging. If the reader shares a reaction or thought, engage with it genuinely before returning to the summary work.
+
+---
+
+## Commands the User Can Give
+
+| Command | What to do |
+|---|---|
+| `new book: [Title by Author]` | Start a new book session |
+| `chapter [N]: [text or upload]` | Process a chapter |
+| `quiz me on chapter [N]` | Re-ask the review questions interactively |
+| `flashcards for chapter [N]` | Show the flashcards for drilling |
+| `story so far` | Print the current master-summary.md |
+| `overview` | Print the book's 00-book-overview.md |
+| `connections` | Summarize recurring themes across all chapters processed so far |
+
+---
+
+## Quality Checklist (run mentally before every output)
+
+- [ ] Narrative summary captures the *why*, not just the *what*
+- [ ] Key points are standalone sentences (no fragments)
+- [ ] At least 2 quotes included
+- [ ] Connections section references specific prior chapters by number
+- [ ] Review questions include recall AND analytical questions
+- [ ] Flashcards are atomic (one idea per card)
+- [ ] Master summary has been updated
+- [ ] Chapter file has been saved to the correct path

README.md

@@ -0,0 +1,72 @@
+# 📚 Book Summarizer — Reading Retention System
+
+A structured system for summarizing books chapter by chapter, powered by AI agents that act as expert summarizers and teachers.
+
+---
+
+## How to Use
+
+### Step 1 — Start a New Book
+Tell your AI agent:
+```
+new book: Atomic Habits by James Clear
+```
+The agent will set up a folder under `books/` for you.
+
+### Step 2 — Share a Chapter
+Paste the chapter text, or upload a PDF/EPUB/text file and tell the agent which chapter to process:
+```
+chapter 1: [paste text here]
+```
+or simply upload the file and say `process chapter 3`.
+
+### Step 3 — Get Your Summary Package
+The agent produces:
+- 📖 **Narrative summary** — 2–4 paragraphs of flowing prose
+- 🔑 **Key points** — 5–10 bullet-point takeaways
+- 💬 **Memorable quotes** — direct quotes from the author
+- 🔗 **Connections** — how this chapter links to earlier ones
+- ❓ **Review questions** — test your understanding
+- 🃏 **Flashcards** — spaced-repetition Q&A pairs
+
+### Step 4 — Review Anytime
+| Command | Result |
+|---|---|
+| `story so far` | See your growing master summary |
+| `quiz me on chapter 3` | Interactive quiz on a chapter |
+| `flashcards for chapter 2` | Drill your flashcards |
+| `connections` | Themes across all chapters |
+
+---
+
+## Folder Structure
+
+```
+book-summarizer/
+├── CLAUDE.md                    # Agent instructions (do not delete)
+├── README.md                    # This file
+├── templates/
+│   ├── chapter-summary.md       # Template for chapter files
+│   ├── master-summary.md        # Template for the master summary
+│   └── flashcards.md            # Standalone flashcard template
+├── prompts/
+│   ├── start-new-book.md        # Prompt to kick off a new book
+│   ├── process-chapter.md       # Prompt to process a chapter
+│   └── review-session.md        # Prompt for review/quiz sessions
+└── books/
+    └── [book-title-slug]/
+        ├── 00-book-overview.md
+        ├── master-summary.md
+        ├── chapter-01-[slug].md
+        ├── chapter-02-[slug].md
+        └── ...
+```
+
+---
+
+## Tips for Best Results
+
+- **Paste the full chapter text** for the richest summary. If the chapter is long, the agent handles it.
+- **React and comment** — if something surprises you, say so. The agent will engage with your thoughts.
+- **Review before reading the next chapter** — glance at the flashcards and try the review questions.
+- **Use `story so far` before each new session** — it re-orients you to where the book's argument has reached.

books/example-atomic-habits/00-book-overview.md

@@ -0,0 +1,26 @@
+# Book Overview — Atomic Habits
+**Author:** James Clear
+**Genre:** Non-fiction / Self-help / Behavioural Psychology
+**Started:** 2025-01-01
+**Status:** In progress
+
+---
+
+## What This Book Is About
+
+*Atomic Habits* argues that small, incremental improvements — "atomic" habits — compound over time to produce remarkable results. James Clear draws on neuroscience, psychology, and real-world case studies to present a practical framework for building good habits and breaking bad ones. The core model is the **Four Laws of Behaviour Change**: make it obvious, make it attractive, make it easy, and make it satisfying.
+
+## Why Read It
+
+The book is aimed at anyone who wants to understand the mechanics of habit formation and use that understanding to change their behaviour systematically — without relying on motivation or willpower alone.
+
+## Chapters Processed
+
+- [ ] Chapter 1 — The Surprising Power of Tiny Habits
+- [ ] Chapter 2 — How Your Habits Shape Your Identity (and Vice Versa)
+- [ ] Chapter 3 — How to Build Better Habits in 4 Simple Steps
+- *(continue adding as you read)*
+
+## Reader's Goals
+
+*What do you hope to get from this book? (Fill in yourself)*

books/example-atomic-habits/master-summary.md

@@ -0,0 +1,29 @@
+# Master Summary — Atomic Habits
+**Author:** James Clear
+**Started:** 2025-01-01
+**Chapters processed:** 0
+
+---
+
+## 🗺️ Book Overview
+
+*Atomic Habits* presents a four-law framework for building good habits and eliminating bad ones, arguing that tiny 1% improvements compound into transformative change over time.
+
+---
+
+## 📊 Running Chapter Log
+
+*Entries will be added here as each chapter is processed.*
+
+<!-- Agent: append new chapter entries below this line -->
+
+---
+
+## 🧵 Recurring Themes
+
+*Updated as patterns emerge.*
+
+---
+
+## 📝 Reader's Notes
+

prompts/process-chapter.md

@@ -0,0 +1,44 @@
+# Prompt: Process a Chapter
+
+Use this prompt (or a variation) each time you finish a chapter and want a summary.
+
+---
+
+**Copy and paste to your agent:**
+
+```
+Chapter [N]: [Chapter Title if known]
+
+[Paste the full chapter text here]
+
+Please produce the full chapter summary package:
+- Narrative summary
+- Key points
+- Memorable quotes
+- Connections to previous chapters
+- Review questions
+- Flashcards
+
+Then update the master-summary.md with this chapter's entry.
+```
+
+---
+
+**If uploading a file instead of pasting:**
+
+```
+Chapter [N] — see uploaded file: [filename]
+
+Please process Chapter [N] from the uploaded [PDF/EPUB/TXT].
+Give me the full summary package and update the master summary.
+```
+
+---
+
+**If you want to add your own reaction first:**
+
+```
+Chapter [N] is done. Quick thought: [your reaction, e.g. "I found the part about X surprising"].
+
+Now please process Chapter [N] and give me the full summary package.
+```

prompts/review-session.md

@@ -0,0 +1,64 @@
+# Prompt: Review Session
+
+Use these prompts when you want to test your retention or review before reading on.
+
+---
+
+## Quiz on a Specific Chapter
+
+```
+Quiz me on Chapter [N].
+
+Ask me the review questions one at a time. Wait for my answer before 
+showing the next question. At the end, give me a score and gently correct 
+anything I got wrong.
+```
+
+---
+
+## Flashcard Drill
+
+```
+Flashcard drill for Chapter [N].
+
+Show me each flashcard one at a time (just the Q first). 
+Wait for my answer, then reveal the A and tell me if I was right.
+Keep going until all cards are done, then give me a score.
+```
+
+---
+
+## Full Book Review (all chapters so far)
+
+```
+story so far
+
+Show me the master-summary.md — the running chapter log with all chapters 
+processed so far. Then highlight any recurring themes you've noticed.
+```
+
+---
+
+## Cross-Chapter Connections
+
+```
+connections
+
+What themes, ideas, or arguments keep coming up across the chapters we've 
+covered so far? Give me a list of recurring themes with a brief explanation 
+and the chapters where each appears.
+```
+
+---
+
+## "Teach It Back" Challenge
+
+```
+I want to try the Feynman technique. I'll explain Chapter [N] in my own words.
+After I'm done, please:
+1. Tell me what I got right
+2. Gently point out anything I missed or got wrong
+3. Clarify any concepts I seemed fuzzy on
+
+Here's my explanation: [your explanation]
+```

prompts/start-new-book.md

@@ -0,0 +1,32 @@
+# Prompt: Start a New Book
+
+Use this prompt (or a variation) to kick off a new book with your agent.
+
+---
+
+**Copy and paste to your agent:**
+
+```
+new book: [Book Title] by [Author Name]
+
+I'm starting this book and want to process it chapter by chapter as I read.
+Please:
+1. Confirm the book details (title, author, subject/genre)
+2. Set up the book folder at books/[slug]/
+3. Create 00-book-overview.md with what you know about this book
+4. Create an empty master-summary.md ready to be filled
+5. Tell me you're ready for Chapter 1
+
+Book file (if I'm uploading): [attach PDF / EPUB / TXT]
+```
+
+---
+
+**Example:**
+
+```
+new book: Thinking, Fast and Slow by Daniel Kahneman
+
+I'm reading this as a physical book. I'll paste chapter text as I go.
+Please set everything up and tell me when you're ready for Chapter 1.
+```

templates/chapter-summary.md

@@ -0,0 +1,67 @@
+# Chapter [N] — [Chapter Title]
+**Book:** [Book Title] by [Author]
+**Date processed:** [YYYY-MM-DD]
+
+---
+
+## 📖 Chapter Summary
+
+[2–4 paragraphs of narrative prose summarising the chapter. Capture the author's argument, the main ideas, examples used, and the "so what" — why this chapter matters to the book's overall thesis.]
+
+---
+
+## 🔑 Key Points
+
+- [Complete sentence takeaway #1]
+- [Complete sentence takeaway #2]
+- [Complete sentence takeaway #3]
+- [Complete sentence takeaway #4]
+- [Complete sentence takeaway #5]
+- [Add more as needed — aim for 5–10]
+
+---
+
+## 💬 Memorable Quotes
+
+> "[Quote text]." — *[Author], Chapter [N]*
+
+> "[Quote text]." — *[Author], Chapter [N]*
+
+> "[Quote text]." — *[Author], Chapter [N]*
+
+---
+
+## 🔗 Connections to Previous Chapters
+
+[How does this chapter build on, deepen, or complicate ideas from earlier chapters? Reference specific chapter numbers. If this is Chapter 1, note the themes and questions it opens for the rest of the book.]
+
+---
+
+## ❓ Review Questions
+
+1. [Recall question — straightforward fact or definition from the chapter]
+2. [Recall question — another key concept]
+3. [Comprehension question — explain a process or argument]
+4. [Analysis question — why does the author make this claim? What evidence supports it?]
+5. [Application/synthesis question — how would you apply this idea, or how does it connect to your own experience?]
+
+---
+
+## 🃏 Flashcards
+
+```
+Q: [Concept or term]
+A: [Concise definition or explanation]
+
+Q: [Key framework or model]
+A: [Brief description]
+
+Q: [Surprising fact or statistic]
+A: [The answer]
+
+Q: [Author's main claim in this chapter]
+A: [One-sentence answer]
+
+Q: [An example the author uses]
+A: [What it illustrates]
+```

templates/flashcards.md

@@ -0,0 +1,47 @@
+# Flashcards — [Book Title]
+**Chapter:** [N — Chapter Title]
+**Created:** [YYYY-MM-DD]
+
+*Review these before reading the next chapter or during a dedicated review session.*
+
+---
+
+```
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+
+---
+
+Q: 
+A: 
+```

templates/master-summary.md

@@ -0,0 +1,49 @@
+# Master Summary — [Book Title]
+**Author:** [Author Name]
+**Started:** [YYYY-MM-DD]
+**Chapters processed:** 0
+
+---
+
+## 🗺️ Book Overview
+
+[Brief description of the book's overall thesis, goal, and intended audience. Updated after the first chapter.]
+
+---
+
+## 📊 Running Chapter Log
+
+*This section grows as each chapter is processed. It is your "story so far."*
+
+---
+
+## Chapter 1 — [Chapter Title]
+**One-sentence gist:** [Single sentence capturing the chapter's core idea]
+**Adds to the book's argument by:** [How this chapter advances the overall thesis]
+
+---
+
+## Chapter 2 — [Chapter Title]
+**One-sentence gist:** [Single sentence capturing the chapter's core idea]
+**Adds to the book's argument by:** [How this chapter advances the overall thesis]
+
+---
+
+<!-- Agent: append new chapter entries below this line -->
+
+---
+
+## 🧵 Recurring Themes
+
+*Updated periodically as patterns emerge across chapters.*
+
+- [Theme 1]
+- [Theme 2]
+- [Theme 3]
+
+---
+
+## 📝 Reader's Notes
+
+*A space for the reader's own reactions, questions, and insights.*
+