Folder / notebook tree of the live Noteful library (iCloud sync, same as the iPad).

Each notebook shows its page count and a 'live:<id>' ref usable by every read tool.
query: optional case-insensitive filter on folder path or title.
Without Noteful for Mac it lists exported .noteful files instead.

Search the live library's indexed text: pdf text, typed text boxes, outlines, bookmarks.

Handwriting is not indexed; to read it use render_page on the hits' notebooks.

List .noteful notebooks (with folder paths from archive.json when present).

root: folder to scan (default: configured roots, e.g. iCloud Drive/Downloads backups
and the MCP output folder). query: optional case-insensitive filter on title/path.

Folder / notebook tree from a Noteful export's archive.json.

Title, dates, folder and per-page details (background, ink stroke count, images).

Render a page (1-based) as PNG so you can read the handwriting and drawings.

scale 0.9 gives ~980px wide; use 1.5+ to zoom into small writing. Covered tapes are drawn
striped as on the iPad; reveal_tapes=True outlines them so the hidden content shows.

Zoomed crop of a page. Coordinates are page units (A4 page = 1091 x 1543).

Ink statistics of a page: stroke count, colours, pen widths, written area.

Highlighter and tape marks of a page (1-based).

highlights: highlighter strokes and ruler lines grouped into regions (colour, bbox).
tapes: Noteful tape strips/bands with bbox and state; "covered" tape hides what is under
it (study mode), "revealed" was tapped open. render_page/render_region with
reveal_tapes=True shows the hidden content.
crops=True also returns zoomed crops of each region (up to 12), tapes revealed.

Where the handwriting is: the page's ink grouped into numbered items (words and phrases on one line) with bounding boxes in page units, in reading order.

Use it before write_on_page to aim marks: read the numbered image, find the item you mean
(a quiz option, a wrong result, a heading), then place a check, ellipse, arrow, highlight or
note relative to its bbox [x0, y0, x1, y1] (e.g. a check at x1 + 20, (y0 + y1) / 2).

Render the whole notebook (backgrounds + ink + images) into a PDF.

Save embedded PDFs and images (backgrounds, pasted pictures) to a folder.

Create a new notebook whose pages are written in natural handwriting ink. look: 'study' (default: composed study notes, docs/STYLE.md) or 'classic' (plain notebook). theme: light (ivory page) for summaries | dark (black page, neon) for question/tree pages. Study markdown, one block per line: '# THE CARDIAC CYCLE' thick title with shadow, the ** word in colour (add ':heart:' / sun, star, atom, drop, bolt, cloud, leaf for a doodle); '# SOLAR & TERRESTRIAL // RADIATION' two-line title on a marker band; 'subtitle' line; '## Section' or '## SMOOTH muscle' coloured caps on a rule (next accent each time); '### Label'; body is mixed case: 'term' colour, '==phrase==' highlighter ('=={pink}..=='), '[[tag]]' pill, '((detail))' grey; items '- ', '* ' star, '-> ' arrow, '1. ' circled; '> [sky] TITLE: text ((detail))' card; '>> A: text || B: text' cards side by side; '!columns 55' ... '!col' ... '!end' two columns (put a !draw on one side); '!zone [sky]' ... '!end' pale full-width band; '!sticky [yellow] TITLE: text'; '!stat 30 reflected (albedo)'; '!map TOPIC | question?' then '- BRANCH.' and indented ' - leaf' lines (tree, best on dark); '!draw [width]' '!end'; '---'; '\pagebreak'. Colours: coral, amber, sky, purple, teal, pink; keep 2-3 per page. Fill the page (~90 %): a diagram + text in columns, cards, a zone with stats and a sticky. Classic markdown: '# ' '## ' headings, '- ' bullets, '[ ] ' checkboxes, '> ' box, '{color:red} ' line colour, '==text==', '!tape mint'. paper: dot|grid|ruled|blank. font: patrick (default), caveat, readability, felix, allure, elfin, nixish. hand: neat | natural | messy. pen: fineliner (study default) | ballpoint. Science: Greek letters, T^4, m^{-2}, CO_2, → ⇄ ≈ ± ° work. Read an example first: example_pages. Drawings (organs, cells, models, circuits, graphs): write a plain SVG with a viewBox 400-650 wide. It is scaled to the width given ('!draw 480' = 480 page units, the page is 1091 wide; inside '!columns' it is capped by the column), so labels need font-size 18-22 in that viewBox to stay readable. Outlines: stroke="#1f2233" stroke-width="2" become hand-drawn ink. Fills become pastel highlighter colouring, even dark ones, so separate stacked parts with outlines, not with darker fills; later shapes cover earlier ones (draw the organ, then its parts). Labels: become handwriting, placed outside the drawing and joined to the part with a . Use curves (C/Q/A) for organic shapes; keep it schematic like a textbook sketch. See the drawing examples.

Copy a notebook and add handwritten pages (at the end, or after page N, 1-based). look: 'study' (default: composed study notes, docs/STYLE.md) or 'classic' (plain notebook). theme: light (ivory page) for summaries | dark (black page, neon) for question/tree pages. Study markdown, one block per line: '# THE CARDIAC CYCLE' thick title with shadow, the ** word in colour (add ':heart:' / sun, star, atom, drop, bolt, cloud, leaf for a doodle); '# SOLAR & TERRESTRIAL // RADIATION' two-line title on a marker band; 'subtitle' line; '## Section' or '## SMOOTH muscle' coloured caps on a rule (next accent each time); '### Label'; body is mixed case: 'term' colour, '==phrase==' highlighter ('=={pink}..=='), '[[tag]]' pill, '((detail))' grey; items '- ', '* ' star, '-> ' arrow, '1. ' circled; '> [sky] TITLE: text ((detail))' card; '>> A: text || B: text' cards side by side; '!columns 55' ... '!col' ... '!end' two columns (put a !draw on one side); '!zone [sky]' ... '!end' pale full-width band; '!sticky [yellow] TITLE: text'; '!stat 30 reflected (albedo)'; '!map TOPIC | question?' then '- BRANCH.' and indented ' - leaf' lines (tree, best on dark); '!draw [width]' '!end'; '---'; '\pagebreak'. Colours: coral, amber, sky, purple, teal, pink; keep 2-3 per page. Fill the page (~90 %): a diagram + text in columns, cards, a zone with stats and a sticky. Classic markdown: '# ' '## ' headings, '- ' bullets, '[ ] ' checkboxes, '> ' box, '{color:red} ' line colour, '==text==', '!tape mint'. paper: dot|grid|ruled|blank. font: patrick (default), caveat, readability, felix, allure, elfin, nixish. hand: neat | natural | messy. pen: fineliner (study default) | ballpoint. Science: Greek letters, T^4, m^{-2}, CO_2, → ⇄ ≈ ± ° work. Read an example first: example_pages. Drawings (organs, cells, models, circuits, graphs): write a plain SVG with a viewBox 400-650 wide. It is scaled to the width given ('!draw 480' = 480 page units, the page is 1091 wide; inside '!columns' it is capped by the column), so labels need font-size 18-22 in that viewBox to stay readable. Outlines: stroke="#1f2233" stroke-width="2" become hand-drawn ink. Fills become pastel highlighter colouring, even dark ones, so separate stacked parts with outlines, not with darker fills; later shapes cover earlier ones (draw the organ, then its parts). Labels: become handwriting, placed outside the drawing and joined to the part with a . Use curves (C/Q/A) for organic shapes; keep it schematic like a textbook sketch. See the drawing examples.

Clean copy: insert a neat handwritten rewrite right after the given page. First call render_page and read the messy page yourself; then pass the cleaned, well structured content as markdown. look: 'study' (default: composed study notes, docs/STYLE.md) or 'classic' (plain notebook). theme: light (ivory page) for summaries | dark (black page, neon) for question/tree pages. Study markdown, one block per line: '# THE CARDIAC CYCLE' thick title with shadow, the ** word in colour (add ':heart:' / sun, star, atom, drop, bolt, cloud, leaf for a doodle); '# SOLAR & TERRESTRIAL // RADIATION' two-line title on a marker band; 'subtitle' line; '## Section' or '## SMOOTH muscle' coloured caps on a rule (next accent each time); '### Label'; body is mixed case: 'term' colour, '==phrase==' highlighter ('=={pink}..=='), '[[tag]]' pill, '((detail))' grey; items '- ', '* ' star, '-> ' arrow, '1. ' circled; '> [sky] TITLE: text ((detail))' card; '>> A: text || B: text' cards side by side; '!columns 55' ... '!col' ... '!end' two columns (put a !draw on one side); '!zone [sky]' ... '!end' pale full-width band; '!sticky [yellow] TITLE: text'; '!stat 30 reflected (albedo)'; '!map TOPIC | question?' then '- BRANCH.' and indented ' - leaf' lines (tree, best on dark); '!draw [width]' '!end'; '---'; '\pagebreak'. Colours: coral, amber, sky, purple, teal, pink; keep 2-3 per page. Fill the page (~90 %): a diagram + text in columns, cards, a zone with stats and a sticky. Classic markdown: '# ' '## ' headings, '- ' bullets, '[ ] ' checkboxes, '> ' box, '{color:red} ' line colour, '==text==', '!tape mint'. paper: dot|grid|ruled|blank. font: patrick (default), caveat, readability, felix, allure, elfin, nixish. hand: neat | natural | messy. pen: fineliner (study default) | ballpoint. Science: Greek letters, T^4, m^{-2}, CO_2, → ⇄ ≈ ± ° work. Read an example first: example_pages. Drawings (organs, cells, models, circuits, graphs): write a plain SVG with a viewBox 400-650 wide. It is scaled to the width given ('!draw 480' = 480 page units, the page is 1091 wide; inside '!columns' it is capped by the column), so labels need font-size 18-22 in that viewBox to stay readable. Outlines: stroke="#1f2233" stroke-width="2" become hand-drawn ink. Fills become pastel highlighter colouring, even dark ones, so separate stacked parts with outlines, not with darker fills; later shapes cover earlier ones (draw the organ, then its parts). Labels: become handwriting, placed outside the drawing and joined to the part with a . Use curves (C/Q/A) for organic shapes; keep it schematic like a textbook sketch. See the drawing examples.

Copy a notebook and draw on an existing page (1-based) in handwriting ink.

items is a list of objects, coordinates in page units (A4 = 1091 x 1543, origin top-left):
  {"type":"text","text":"...","x":100,"y":300,"width":800,"color":"red","size":11,"font":"patrick",
   "hand":"natural","pen":"ballpoint"}
    (y = first baseline; wraps inside width)
  {"type":"markdown","text":"...","x":100,"y":300,"width":800}
  {"type":"line"|"arrow","from":[x,y],"to":[x,y],"color":"blue"}
  {"type":"rect","x":..,"y":..,"w":..,"h":..,"color":"green","radius":0}
  {"type":"ellipse","cx":..,"cy":..,"rx":..,"ry":..,"color":"red"}
  {"type":"underline","x0":..,"x1":..,"y":..,"double":false}
  {"type":"check"|"star","x":..,"y":..,"size":18}
  {"type":"tape","x":..,"y":..,"w":230,"h":40,"angle":0.05,"palette":"mint","pattern":"stripes|dots|grid"}
  {"type":"highlight","x":..,"y":..,"w":..,"h":24,"color":"yellow"}  covers a box (e.g. a line
    of existing writing: y = top of the letters, h ~ 24 per line)
  {"type":"highlight_line","from":[x,y],"to":[x,y],"width":24,"color":"pink"}
    highlighter colours: yellow, pink, mint, lavender, peach, blue (Turkish names work) or #hex.
    These are real Noteful highlighter strokes, drawn translucent under the ink.
  {"type":"drawing","svg":"<svg viewBox=...>...</svg>","x":..,"y":..,"width":400}
    a diagram drawn by you; see the drawing notes below.
Aim with page_layout: it numbers the handwriting on the page and gives each item's bbox, so
a tick goes at x1 + 30, a circle around the bbox, the right answer gets a highlight. To grade
a quiz: render_page to read the answers, page_layout to find the options, then one
write_on_page call with every mark (and a score near the title).
The result is opened in Noteful for Mac when it is installed; the reply says which option to
pick in Noteful's dialog. Notebooks of the live library are never modified.
Drawings (organs, cells, models, circuits, graphs): write a plain SVG with a viewBox 400-650 wide. It is scaled to the width given ('!draw 480' = 480 page units, the page is 1091 wide; inside '!columns' it is capped by the column), so labels need font-size 18-22 in that viewBox to stay readable. Outlines: stroke="#1f2233" stroke-width="2" become hand-drawn ink. Fills become pastel highlighter colouring, even dark ones, so separate stacked parts with outlines, not with darker fills; later shapes cover earlier ones (draw the organ, then its parts). Labels: <text x y font-size text-anchor> become handwriting, placed outside the drawing and joined to the part with a <line>. Use curves (C/Q/A) for organic shapes; keep it schematic like a textbook sketch. See the drawing examples.

Draw a picture of a study page with an image model on the user's own Google account (GEMINI_API_KEY or NOTEFUL_VERTEX_PROJECT; see imagegen.py), to copy into ink with design_page. content: what the page holds and roughly where (title, sections, a drawing, cards, a zone...), quoting the exact title and labels. look: 'calm' (default: ordinary notes, one pen, underlined headings, a little highlighter) or 'rich' (only for a visual summary page: cards, a drawing, a sticky note). Most pages, course notes and worked problems included, are calm; a notebook full of rich pages looks overdone. theme: light | dark. reference: a gallery example name to imitate (default: clean-copy for rich light, answers-tree for dark, none for calm) or the path of the previous page's mockup, which keeps a multi-page note consistent. Returns the mockup's path, the mockup and a grid.

A mockup (or any page picture) with a labelled pixel grid, to read the coordinates a design_page spec needs. region [x, y, w, h] zooms in with a finer grid.

Write pages that copy page designs (mockups) in real ink. pages: one spec per page. Either title (a new notebook) or path (add to that notebook after after_page, 1-based; live notebooks too). Copy a page design into real ink. Workflow: design_mockup (or any picture of a page the user gives) -> mockup_grid to read coordinates -> design_page with one spec per page -> render_page to compare with the mockup and fix what is off. In the spec list every block of the mockup in its own pixels: text lines with the CORRECT words (image models garble body text; the layout, sizes and colours are what you copy), cards, bands, highlighter, sticky notes, arrows, circled numbers; trace the drawings straight from the mockup (erase their labels and write the labels as text). Match each text's 'h' (cap height) and 'w' (line length) to the mockup. Spec format: Copy a page design (an image model's mockup) into real Noteful ink.

The agent looks at the mockup and lists what is on it, in the mockup's own pixels; this module draws each item at the same place and size: text as handwriting (the agent supplies the correct words, so the mockup's typos never reach the page), cards, colour bands, highlighter, sticky notes, arrows and circled numbers as pen and highlighter strokes, and drawings traced straight out of the mockup (trace.py) so they keep its quality.

Spec (JSON): {"size": [896, 1200], "theme": "light", "mockup": "", "items": [ {...}, ... ]} items are drawn in order; colours are "#rrggbb" or "auto" (sampled from the mockup at that spot) text {"t": "text", "x", "y" (baseline), "h" (cap height), "text", "color", "pen" (line weight, default 1.15), "w" (fit width), "align": left|center|right, "lh" (line spacing, for several lines split by \n), "wmax" (shrink only if wider)} inline: {#e9573f:PHOT} colours a run, ==ATP== highlights it ({hl:#ffd27a} first to pick the colour), CO_2 and C_6H_{12} are subscripts, T^4 superscripts rect {"t": "rect", "x", "y", "w", "h", "fill", "stroke", "r" (corner radius), "pen", "dots" (dotted inner border colour), "angle" (degrees)} band {"t": "band", "y", "h", "fill"} full-width colour zone hl {"t": "hl", "x", "y", "w", "h", "color"} highlighter swipe sticky {"t": "sticky", "x", "y", "w", "h", "fill", "angle", "tape": "#c9b9a0", "text": [text items, placed relative to the page as usual]} line {"t": "line", "pts": [[x, y], ...], "color", "pen", "head": none|open|hollow|block, "size" (head length), "width" (block arrow)} circle {"t": "circle", "cx", "cy", "r", "color", "pen", "fill", "text", "h"}; "rx"/"ry" make it an ellipse (around a chosen answer) any item may carry "g": the group its strokes belong to (design_groups) lines {"t": "lines", "x", "y" (first baseline), "h", "lh" (baseline step), "lines": [...], plus any text keys} a paragraph or list, one text item per line trace {"t": "trace", "box": [x, y, w, h], "erase": [[x, y, w, h], ...] (labels to drop, in mockup pixels), "colors": 8}

Copy a notebook under a new title.

Where written notebooks go (import them in Noteful via Files).

Example pages and drawings to imitate, with their source and how they look.

Without a name: the list of examples and the style guide. With a name: its source (study
Markdown or SVG) and a preview image. Read the matching example before create_notebook,
add_pages, clean_copy or a write_on_page drawing, and follow its structure.