feat(export): export a page to Word (DOCX) and OpenDocument (ODT)

.claude/skills/knot-api/SKILL.md

@@ -64,6 +64,8 @@ Keep the password in an env var, never in argv/history. Failed logins are thrott
 | Workspace export | `GET /api/workspace/export` → zip (markdown + manifest) |
 | Workspace import | `POST /api/workspace/import` (multipart zip upload) |
 | Single-doc export | `GET /api/docs/{id}/export` |
+| **Export doc as Word / OpenDocument** | `POST /api/docs/{id}/export/docx` or `…/export/odt` → the file; body empty, or multipart with one PNG per diagram key (≤ 10 MiB total, ≤ 2 MiB and ≤ 100 parts). Header `X-Knot-Export-Fallbacks: diagrams=…, images=…, unknown=…` counts what was left out. Viewer+ |
+| Diagrams to render for that export | `GET /api/docs/{id}/export/diagrams` → `{"limits":{…}, "diagrams":[{"key","kind":"mermaid","source"} \| {"key","kind":"board","board_id","label"}]}` |
 | Upload attachment | `POST /api/docs/{id}/blobs` · fetch: `GET /api/blobs/{id}` |
 | Workspace info | `GET /api/workspace` · templates: `GET /api/workspace/templates` |
 
@@ -90,6 +92,11 @@ kmut -X PATCH "$KNOT/api/docs/$DOC_ID/tasks/2" \
 
 # Full workspace backup
 kget /api/workspace/export > knot-backup.zip
+
+# Export a doc as Word (or …/export/odt). An empty body means no diagram
+# pictures: Mermaid blocks and boards become "(not included)" placeholders.
+kmut -X POST "$KNOT/api/docs/$DOC_ID/export/docx" -D headers.txt -o page.docx
+grep -i '^x-knot-export-fallbacks' headers.txt
 ```
 
 ## Gotchas
@@ -99,5 +106,6 @@ kget /api/workspace/export > knot-backup.zip
 - `403 {"code":"auth.csrf","message":"missing or mismatched CSRF token"}` on POST/PUT/PATCH/DELETE → `X-CSRF-Token` header missing or ≠ `csrf` cookie value.
 - `403 {"code":"acl.editor_required"}` → the user is a workspace Viewer; writes need Editor+.
 - Search returns `{"results":[]}` silently for queries < 2 chars; `limit` is clamped to 20 server-side.
+- Word/OpenDocument export: `503 export.busy` (with `Retry-After: 5`) when two exports already run on that pod — wait and retry; `413 export.too_large` when the multipart body passes 10 MiB — resend with smaller or no pictures. A picture part over 2 MiB, past the 100th part, or named after no diagram on the page is ignored, not an error.
 - Real-time editing runs over a WebSocket CRDT protocol (yrs) — not curl territory; use the markdown endpoints instead.
 - First-run bootstrap / break-glass admin (no HTTP): `knot-server admin create --email … --display-name …` (password via stdin) directly against the DB (`KNOT_DATABASE_URL`).

ARCHITECTURE.md

@@ -38,6 +38,7 @@ There is **no Redis**. Cross-pod CRDT update fan-out and ACL revocation both rid
 | `knot-crdt`       | yrs `Engine`, `Rooms` registry, `Room` actor, `PgBus` over LISTEN/NOTIFY |
 | `knot-docs`       | ACL evaluation engine + ACL invalidation listener |
 | `knot-markdown`   | Markdown ↔ ProseMirror round-trip (canonical schema) |
+| `knot-export`     | Page → DOCX/ODT (pure; walks the Y.Doc) |
 | `knot-obs`        | structured logging, OTLP traces, Prometheus exporter, well-known metric describes |
 | `knot-test-support` | `fresh_db()` against the dev-compose Postgres (NEVER testcontainers) |
 | `tools/schemagen` | generates `schema.rs` (server) + `schema.ts` (client) from `tools/schema.json` |

CHANGELOG.md

@@ -23,6 +23,9 @@ so this log can be regenerated from history (e.g. with `git-cliff`).
   the card hides it until the next upgrade, on every device. New users start
   caught up, and development builds never show it. `GET /api/whats-new`,
   `POST /api/whats-new/seen`. (#45)
+- Word (DOCX) and OpenDocument (ODT) export from the page header's download
+  menu, with diagrams as pictures. `GET /api/docs/{id}/export/diagrams`,
+  `POST /api/docs/{id}/export/{docx|odt}`. (#46)
 
 ### Security
 - `ctutils` 0.4.5 fixes RUSTSEC-2026-0385: its constant-time helpers could

Cargo.toml

@@ -6,6 +6,7 @@ members = [
     "crates/knot-config",
     "crates/knot-crdt",
     "crates/knot-docs",
+    "crates/knot-export",
     "crates/knot-markdown",
     "crates/knot-obs",
     "crates/knot-storage",

crates/knot-export/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "knot-export"
+version = "0.0.0"
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[dependencies]
+yrs.workspace = true
+sha2.workspace = true
+url.workspace = true
+thiserror.workspace = true
+uuid.workspace = true
+zip = { version = "8", default-features = false, features = ["deflate"] }
+image-webp = "0.2"
+png = "0.18"
+imagesize = { version = "0.15", default-features = false, features = ["png", "jpeg", "gif", "webp"] }
+
+[dev-dependencies]
+roxmltree = "0.20"