• The PDF is the only source of concepts. If a concept is not explicitly named or clearly introduced in the

  pdftotext

  output, it does NOT become a note — no matter how canonical, standard, or "obviously related" it is to the lecture topic. See Do not invent concepts below.
• General knowledge is for explaining, not extending. You may use your own knowledge to flesh out an explanation, add an illustrative example, or phrase a definition clearly — but only for concepts the PDF already introduces.
• One concept per note. Never dump a whole lecture into one file.
• Group notes by lecture topic. Every concept from a lecture goes inside a folder named after that lecture's hub concept — never at the course root. See the path convention below.
• Link aggressively — within the verified set. Use

  [[wikilinks]]

  for every concept that has (or should have) its own note, but never wikilink to a concept the PDF doesn't mention. Forward-links to future lectures are fine only if the current PDF explicitly names the future concept.
• Stay within the course. Do not link across course folders.
• Merge, don't overwrite. If a note exists, integrate new material and preserve existing structure.
• Cite the PDF, not slide numbers. E.g.

  CS101 Lecture — 03_DesignByContract.pdf

  .
• Ask before you assume inputs. If the user didn't specify a PDF path, a vault location, or a canvas file, ask — do not invent defaults. See Inputs below.

Completeness means what the lecture covered, not what the topic canonically includes.

• "What are the standard sub-topics under X?"
• "To be complete I should add…"
• "This lecture briefly mentioned Y, and Y is usually explained alongside Z, so Z should have a note too."
• Writing a note whose body relies on details the PDF doesn't contain.
• Adding a wikilink to a concept name that never appeared in the

  pdftotext

  output.

• User gives one or more PDF paths and asks for notes.
• User references lecture slides in the vault and wants them processed.
• User asks for "study notes from these slides" or similar.

• A file path (one PDF).
• A directory path — list every

  .pdf

  inside, show the user the list, and confirm the processing order before starting.
• A glob (e.g.

  ~/slides/*.pdf

  ).

Which lecture PDF(s) should I process? Give me a file path, a directory containing PDFs, or a glob.

1. If the current working directory contains

   .obsidian/

   , offer it as a suggestion.
2. Otherwise ask: "Which Obsidian vault should I add notes to?"

• If the user provides an existing canvas (e.g.

  architecture-map.canvas

  ), use that file — load, mutate, save.
• Otherwise default to

  <Vault>/<Course>.canvas

  . Create if absent, as an empty

  {"nodes":[],"edges":[]}

  .

• 1–3 PDFs → single-agent mode. The main agent does everything. Simpler; keeps full context for cross-lecture linking.
• 4+ PDFs → subagent-per-PDF mode. For each PDF, dispatch a subagent (via the

  Agent

  tool) to do steps 1–4 only: survey, plan, extract visuals, draft note contents. The subagent returns a compact structured result — do NOT have it write files or touch the canvas. The main agent then performs the merge into existing notes (step 4 write) and the canvas update (step 5) serially, so shared state (existing notes, canvas positions) stays consistent.

{
  "course": "CS101",
  "topic": "Design by Contract",
  "concepts": [
    {
      "name": "Preconditions",
      "path": "CS101/Content/Design by Contract/Preconditions.md",
      "tier_hint": "leaf",
      "parents": ["Design by Contract"],
      "wikilinks": ["Design by Contract", "Assertions"],
      "pdf_evidence": "A pre-condition must be true before the method executes — the caller's obligation.",
      "body": "<full markdown body, including ## References footer>"
    }
  ],
  "pdf_filename": "03_DesignByContract.pdf"
}

pdf_evidence

pdftotext

pdf_evidence

pdftotext

pdftotext <path> -

• Course (confirmed with the user, or inferred from the PDF path — e.g.

  CS101

  )
• Lecture topic (hub concept, e.g. "Design by Contract") — this becomes both the hub note name AND the topic folder name.
• Candidate concepts — distinct ideas the PDF explicitly names or introduces. For each, record a short verbatim quote from the

  pdftotext

  output that introduces the concept. This becomes the

  pdf_evidence

  field.
• Slide ranges where each concept lives (for the next step)

pdftotext

pdftotext <path> - | grep -iE "concept name|obvious paraphrase"

• Zero hits and no obvious paraphrase present → delete the candidate. It is hallucinated.
• One passing mention inside an example/diagram caption → not enough. The PDF must introduce the concept (define, describe, list as a bullet, or give it a section heading). Delete the candidate if it only appears inside a worked example's body.
• Multiple references, clearly introduced → keep.

pdf_evidence

<Vault>/<Course>/Content/<Topic>/<Concept>.md

• <Vault>/CS101/Content/Design by Contract/Design by Contract.md

  ← hub

• <Vault>/CS101/Content/Design by Contract/Preconditions.md

• <Vault>/CS101/Content/Design by Contract/Postconditions.md

• <Vault>/CS101/Content/Design by Contract/Class Invariants.md

<Course>/

<Course>/Content/

• If a precondition is violated, the effect becomes undefined.
• ...

• CS101 Lecture —

  03_DesignByContract.pdf

Style rules:

- Opening sentence defines the concept and wikilinks to parent/related ideas.
- Use `**bold**` for emphasis on key terms.
- Section headings (`##`) are topical (`Key points`, `Example`, `In inheritance`, etc.) — do NOT include slide numbers.
- Code blocks use fenced syntax with the right language.
- Footer is a `## References` section naming the PDF file only.
- Every concept name that has (or could have) its own note — **and is present in the verified concept list for this or a previous lecture** — becomes a `[[wikilink]]`. Never wikilink to a concept that no PDF has introduced.

**Using general knowledge for explanation (allowed):**

- Fleshing out a definition the PDF states tersely.
- Providing an extra illustrative example that matches the lecture's framing.
- Rephrasing for clarity while preserving the PDF's meaning.

**Using general knowledge for extension (forbidden):**

- Introducing related sub-concepts the PDF doesn't name (even as a sub-bullet).
- Adding a `##` section about a topic the PDF doesn't cover.
- Citing mechanisms, patterns, or examples that pull in new terminology not in the PDF.
- Expanding a brief slide into a multi-section deep dive that goes beyond what was taught.

If a `##` section in your draft can't be traced back to specific PDF content, delete it.

**Merging:** when a note exists, read it first. Add new bullets/sections at the natural place, add missing wikilinks, extend the `## References` footer with the new PDF if different. Preserve the author's existing wording. The same no-extension rule applies to merges — new material must come from the current PDF.

1. User-provided canvas path — use it directly. Read, mutate, save.
2. Otherwise — use

   <Vault>/<Course>.canvas

   .
3. If the file doesn't exist — create it, initialised as

   {"nodes":[],"edges":[]}

   .

{
  "nodes": [
    {"id": "<16-hex>", "type": "file", "file": "<Course>/Content/<Topic>/<Name>.md",
     "x": 0, "y": 0, "width": 400, "height": 400, "color": "5"}
  ],
  "edges": [
    {"id": "<16-hex>", "fromNode": "<id>", "fromSide": "top",
     "toNode": "<id>", "toSide": "bottom"}
  ]
}

• Preserve existing node positions. Only place/resize new nodes; never move existing ones.
• Generate

  id

  as a random 16-char hex string.
• Write valid JSON (Obsidian is strict — no trailing commas, no comments).

"5"

"4"

1. Place the hub at its existing position, or ≥1200 px from the nearest existing hub if new.
2. For a parent's children, pick a broad angular region (e.g. 120°–180° arc) on the side facing away from the rest of the graph. Within that arc, distribute children at varied radii (roughly 700–1000 px for core nodes, 450–650 px for leaves off a core) and uneven angular gaps — don't snap to equal spacing. Small jitter (±10–15%) is better than clockwork.
3. Follow the natural branching: a core node's leaves should fan out beyond it, continuing the flow outward rather than curling back toward the hub.
4. Minimum spacing: 120 px gap between any two node bounding boxes. If a candidate position overlaps, nudge outward or sideways until clear — keep the nudge small so the flow isn't disrupted.
5. Arrow routing: pick

   fromSide

   /

   toSide

   based on relative position:
   • child above parent →

     fromSide: "top"

     ,

     toSide: "bottom"

   • child below →

     "bottom"

     /

     "top"

   • child left/right →

     "left"

     /

     "right"

     symmetrically Choose whichever axis (horizontal vs vertical) has the greater displacement. This prevents arrows cutting diagonally across nodes.
6. Add edges: parent hub → each direct sub-concept, plus edges between already-placed concepts wherever wikilinks exist between them.

• Hallucinating canonical concepts not in the PDF. The #1 failure mode. If you're adding standard topic-X concepts because "lectures on X usually cover them", STOP — grep the pdftotext output, confirm zero hits, delete the concept. Applies to every topic.
• Deep-diving a concept the PDF only names briefly. A one-line slide mention doesn't justify a multi-section note. Match the note's depth to the PDF's depth; use general knowledge only for phrasing and one short illustrative example.
• Wikilinking to concepts the PDF doesn't mention. Forward-links to future-lecture concepts are allowed only if the current PDF explicitly names them (e.g. a slide listing upcoming lectures).
• Dumping every concept at the course root. Every lecture's concepts belong inside a topic folder named after the lecture — never

  <Course>/Concept.md

  . See Step 2.
• Processing PDFs you weren't given. If the user didn't specify which files to process, ask — don't glob the current directory.
• Writing to a canvas you weren't asked to touch. Use the user-provided canvas if given; otherwise the course default. Don't pick a third file.
• Writing one giant note per lecture. Split by concept.
• Citing slide numbers. PDF filename only.
• Linking across courses. Stay within the course folder.
• Overwriting existing notes. Always merge.
• Processing all PDFs in parallel. Go one at a time.
• Reading the whole PDF as images. Use

  pdftotext

  first, then targeted page reads.
• Dropping existing canvas nodes or moving them. Only add/position new ones.
• Invalid canvas JSON (trailing commas, missing

  id

  ). Obsidian silently fails to load.
• Uniform node sizes. A concept that ten others link to should look different from a leaf — resize and recolour by degree.
• Arrows slicing through nodes. Pick

  fromSide

  /

  toSide

  from relative position (step 5). If an arrow still crosses a node, nudge the new child further out.
• Clustering new nodes on one side. Distribute around the parent — but in a flowing arc, not a strict ring.
• Over-regular layout. Equal spacing and matched radii look mechanical. Vary distances and angles slightly so the graph reads as organic.