docs(notion-writer): document engines + file uploads (v1.3.0)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

custom-skills/32-notion-writer/SKILL.md

@@ -139,6 +139,19 @@ python notion_writer.py -d DATABASE_URL -t "Entry Title" -f content.md
 | `---` | Divider |
 | Paragraphs | Paragraph |
 
+### Engines and image uploads
+
+Two write engines via `--engine {blocks,markdown}` (default: `blocks`).
+
+The **blocks engine** (default) converts markdown locally to Notion block objects. Local images (`![alt](./file.png)`) are auto-uploaded via the `ntn` CLI and embedded at their original position in the page. Requires `ntn` installed and `ntn login`.
+
+The **markdown engine** (`--engine markdown`) posts the document through Notion's native enhanced-markdown API (`Notion-Version: 2026-03-11`, set automatically; override with `--notion-version`). The skill's authoring dialect — GitHub alerts (`[!NOTE]`), Pandoc columns (`::: columns`), `<details>` toggles, and `@[mention]` — is auto-translated before posting. Note: local images are appended at the end of the page rather than inline with this engine; use `--engine blocks` when image position matters. Pass `--allow-deleting-content` when `--replace` needs to remove child pages or databases.
+
+```bash
+# Markdown engine — create a DB row from a doc with callouts or columns
+python notion_writer.py -d DB_URL -t "Notes" --engine markdown -f notes.md
+```
+
 ## Workflow Example
 
 Integrate with Jamie YouTube Manager to log video info:

custom-skills/32-notion-writer/code/CLAUDE.md

@@ -189,6 +189,53 @@ print("Hello")
 
 Notion's URL validator requires absolute URLs for link annotations. The parser converts TOC-style anchor links to bold to preserve navigation intent and silently strips relative paths.
 
+### File uploads
+
+Standalone local-image lines (`![alt](./image.png)`) are auto-uploaded to Notion and embedded as `file_upload` image blocks. Remote images (`![](https://...)`) are left as external links unchanged.
+
+**Requirements:**
+- `ntn` CLI installed: `curl -fsSL https://ntn.dev | bash`
+- Logged in: `ntn login`
+
+Uploads are workspace-scoped — the file lands in whichever workspace the `ntn` CLI is authenticated to. Ensure this matches the workspace the Notion API token targets, or the image block will not attach.
+
+### Engines
+
+Two write engines, selected with `--engine {blocks,markdown}`. Default is `blocks`.
+
+| Engine | Flag | When to use |
+|--------|------|-------------|
+| **blocks** (default) | `--engine blocks` | General use; images embed at their exact position; full table + container support |
+| **markdown** | `--engine markdown` | Richer Notion-native formatting via enhanced-markdown endpoints |
+
+**blocks engine** converts markdown to Notion block objects locally (via `markdown_to_notion_blocks`). Local images are uploaded via `ntn` and embedded at their exact position in the document.
+
+**markdown engine** posts the document through Notion's native enhanced-markdown endpoints (`Notion-Version: 2026-03-11`, set automatically). The skill's authoring dialect is auto-translated before posting:
+
+| Skill dialect | Translated to |
+|---------------|---------------|
+| `> [!NOTE]` / `[!TIP]` / `[!IMPORTANT]` / `[!WARNING]` / `[!CAUTION]` | `<callout icon="..." color="...">` |
+| `::: columns` / `::: column` / `:::` | `<columns><column>...</column></columns>` |
+| `<details><summary>...</summary>` | `<details>` (Notion toggle) |
+| `@[Title](id-or-url)` | `<mention-page url="...">` |
+
+**Local image limitation with `--engine markdown`**: local images cannot be placed inline via the enhanced-markdown API. They are appended at the end of the page as a second write pass. Use `--engine blocks` when image placement matters.
+
+**`--notion-version`**: Override the API version for the markdown engine (default: `2026-03-11`).
+
+**`--allow-deleting-content`**: Required when `--replace` needs to delete child pages or databases under the target page; the Notion API refuses such deletions unless this flag is present.
+
+```bash
+# Markdown engine, create a row from a doc with callouts/columns
+python notion_writer.py -d DB_URL -t "Notes" --engine markdown -f notes.md
+
+# Blocks engine with a local image (auto-uploaded via ntn)
+python notion_writer.py -p PAGE_URL -f post.md   # post.md contains ![chart](./chart.png)
+
+# Markdown engine, replace page allowing child deletion
+python notion_writer.py -p PAGE_URL -f doc.md --replace --engine markdown --allow-deleting-content
+```
+
 ---
 
 ## Examples
@@ -398,9 +445,10 @@ python notion_writer.py -d DB_URL -t "Title" --upsert-by "Name" -f content.md
 
 ---
 
-*Version 1.2.0 | Claude Code | 2026-04-27*
+*Version 1.3.0 | Claude Code | 2026-06-27*
 
 Changelog:
+- 1.3.0 — Local file/image uploads via the `ntn` CLI (`![](local)` → file_upload image blocks). New `--engine markdown` path writing through Notion's native enhanced-markdown endpoints with a dialect translator. Added `--notion-version` and `--allow-deleting-content`.
 - 1.2.0 — Extended block coverage: GitHub-alert callouts, HTML5 `<details>` toggles, Pandoc `::: columns` fenced div, inline `@[Title](id-or-url)` page mentions. Parser made reentrant to support full recursion inside container blocks.
 - 1.1.0 — Migrated to Notion API 2025-09-03 (multi-source databases). Added `--properties` JSON flag, `--upsert-by` for idempotency, anchor-link parser fix, friendlier API error messages.
 - 1.0.0 — Initial release with markdown→Notion block conversion.