--- name: ingest-textbooks description: Ingest a folder of textbooks (PDFs and/or Jupyter-notebook repos) and generate an AGENTS.md study index — a self-index for the AI tutor with a resource inventory, page-offset navigation table, per-book tables of contents cross-referenced to real PDF pages, a topic→best-source map, and tutoring conventions. Use when the user wants to set up a new subject for tutoring, add textbooks to an existing index, or regenerate/refresh AGENTS.md. --- # Ingest Textbooks → AGENTS.md Turn a directory of learning resources into a single `AGENTS.md` that an AI tutor reads at the start of each session. The goal is an index that lets the tutor (a) name every resource and its character, (b) jump to any section by real PDF page, and (c) pick the best source for any topic. The reference output is the discrete-math `AGENTS.md` at the project root — match its structure and tone. This skill generalizes that process to any subject and any book set. ## Inputs - A resources folder (default `textbooks/`; may be a symlink). Ask the user if absent. - Optionally, a seed/intent prompt (e.g. `prompts/init_agents.md`) describing the subject, the course tag, and how the user wants to be taught. Read it first if present. - The subject name and any course tag (e.g. "Discrete Mathematics", tag "TMU"). If regenerating an existing `AGENTS.md`, read it first and **preserve** any accumulated notes/conventions the user added — never discard them. ## Tools available Extract text with what this machine actually has — probe first, never guess. In order: **1. MCP PDF tools (preferred — e.g. the "PDF Utilities" VS Code extension exposes `read_pdf` / `get_pdf_info`; self-contained JavaScript, no Python needed):** - If your environment has MCP tools, call `get_pdf_info` for the page count and `read_pdf` with an absolute path for the text. **2. pypdf / pdfplumber (pure Python — the toolchain the official OpenAI `pdf` skill installs; Codex users install that skill first):** - Page count: `python -c "import pypdf; print(len(pypdf.PdfReader('.pdf').pages))"` - Page range: `python -c "import pypdf; r=pypdf.PdfReader('.pdf'); [print(f'--- PDF page {i+1} ---'); print(r.pages[i].extract_text()) for i in range(-1, )]"` Probe once at the start: check for a `read_pdf` MCP tool → `python -c "import pypdf"`. If NOTHING works, stop and tell the user the one-line fixes — install the OpenAI `pdf` skill (Codex) or the "PDF Utilities" VS Code extension (Copilot) — and never fabricate page contents. Neither extractor preserves print layout: columns and ToC page numbers may reflow, so match ToC titles to page numbers deliberately instead of trusting the text order. Notebook repos are plain `.ipynb` under chapter folders — list dirs, open the files as text. ## Process Work one resource at a time. Do **not** read whole books — only front matter, the ToC, and a few verification pages. ### 1. Inventory the folder List the resources folder. Classify each entry: PDF textbook, notebook repo (a dir of `Chapter NN …/*.ipynb`), or data/zip to ignore. For each PDF get the page count (MCP `get_pdf_info`, or the pypdf one-liner in "Tools available"). Note filenames are often generic — you'll identify the actual book in step 3. ### 2. Locate each PDF's table of contents The ToC is usually a few pages into the front matter. Extract a generous front range (the first ~40 pages: `read_pdf`, or the pypdf page-range one-liner) and search it for "contents"/"目錄". Then extract the ToC pages themselves. Capture **printed** section numbers and the **printed page numbers** the book lists (e.g. "3.3 Complexity of Algorithms 231"). ### 3. Identify the book (title, author, edition) Read the title page if present. If the filename is generic and no clean title page exists, **infer** author/edition from distinctive structure (signature chapter titles, special features, ornaments) and **say so explicitly** in the inventory — mark it "author inferred, not read off a title page." Never assert an identity you didn't verify; flag the inference. ### 4. Compute the printed→PDF page offset, then VERIFY it Printed page numbers are the canonical reference, but the PDF is shifted by front matter. Estimate the offset, then confirm by extracting the expected pages and searching for a known section title (e.g. expecting printed p.1 at PDF p.25 → offset +24: extract PDF pages 24–30 and check the first section actually starts there) so the table is trustworthy. Record the **verified anchor** (e.g. "printed p.1 = PDF p.25") and note that offsets drift ±1–2 pages around part-openers, so precise jumps should re-search by title rather than trust the offset blindly. ### 5. Transcribe tables of contents For each book, list chapters with their sections and **printed** page numbers, exactly as the book prints them. Keep it dense (one line per chapter, sections inline). Include appendices and answer-key locations. For notebook repos, list chapter folders and the Python/stack used; flag any chapter missing from the repo. ### 6. Build the topic → best-source map This is the highest-value section. For each major topic in the subject, recommend a **primary** source (the clearest/deepest for that topic) and **supplements**, using "→" for primary and "+" for supplements. Base recommendations on each book's character (e.g. one is gentlest for proofs, another is the CS-depth reference, another is concise review). Cover every topic that appears across the books. ### 7. Write AGENTS.md Assemble the file with these sections (adapt headings to the subject): 1. **Header + Purpose** — one-paragraph note that this is the tutor's self-index, read at session start; restate the subject, course tag, and tutoring posture from the seed prompt. 2. **Resource Inventory** — table: Tag | Resource (path) | Type | Character | Pages. The "Character" cell is a sentence on what each source is best for. 3. **How to Navigate the PDFs** — the offset table (Book | offset | verified anchor) plus the extraction recipes (`read_pdf` / pypdf) and the "verify by search when precision matters" warning. 4. **Tables of Contents** — per §5, printed page numbers. 5. **Topic → Best-Source Map** — per §6. 6. **Tutoring Conventions** — how the tutor should behave (default to explanation over lookup; cite sources as `[Tag §x.y, p.N]`; adapt level; etc.). Carry over anything from the seed prompt. Use printed page numbers throughout as the canonical citation; the offset table is how the tutor turns those into PDF pages. ## Quality bar - Every offset has a **verified** anchor, not just an estimate. - Every inferred book identity is flagged as inferred. - The topic map names a primary source for every topic and is internally consistent with each book's stated character. - Page numbers are the book's printed numbers, transcribed accurately from the ToC. - On regeneration, user notes and conventions survive. ## After writing Tell the user what was indexed (N books, page counts, any inferred identities or missing chapters) and offer to start tutoring or to spot-check a couple of the verified anchors.