@sinoia/hubdoc-tools 1.12.0 → 1.13.1

package/docs/llm-usage.md

@@ -408,6 +408,71 @@ without going through a workspace-scoped ACL. Example:
 `hubdoc permissions grant --to <user-id> --to-type user --on <project-id>
 --on-type project --level admin`.
 
+### Concurrent markdown editing (`hubdoc md`, corex#594)
+
+`hubdoc md` exposes the corex `Tools::Documents::MarkdownEditor` (the
+same tool internal Ruby agents use) through a single HTTP endpoint
+(`POST /api/v1/documents/files/:id/markdown_editor`). Eleven surgical
+actions, one HTTP round-trip each:
+
+- **Discovery** : `structure` (outline + line numbers), `stats` (word
+  counts, section sizes, TODOs), `search --pattern <regex> [--context N]`.
+- **Read** : `read [--from-line N --to-line M | --offset N --limit M]`,
+  `read-section --heading "…" [--level N] [--index N]`.
+- **Write** : `write-section --heading "…" (--content <text> |
+  --content-file <path>)`, `append`, `insert (--at-line N | --at-offset
+  N)`, `delete (--from-line/--to-line | --from-offset/--to-offset)`,
+  `replace --find "…" (--replace-with "…" | --replace-with-file <path>)
+  [--all]`.
+- **Save** : `save [--create-version] [--version-comment "…"]` — the
+  content is auto-saved by every write; `save` is just for the explicit
+  version snapshot.
+
+**Concurrency & merge — server-side, current limitations** :
+
+Each write action executes on the server as a single load-blob → mutate
+→ save-blob → `publish Documents::FileContentUpdated` cycle. Cross-modal
+broadcasts still work: every server-side write broadcasts
+`content_refresh` over `DocumentEditingChannel`, and the web UI's Y.js
+session reloads from server content. Cf. the corex design
+`.claude/context/designs/y-rb-implementation.md`.
+
+> ⚠️ **Known limitation — lost-update race on concurrent writes**
+> (tracked in [corex#595](https://code.plugandwork.net/sinoia/corex/-/issues/595)):
+> two `hubdoc md insert`/`replace`/`write-section` calls firing in
+> parallel on the **same file** may silently drop one of the writes —
+> the load→save cycle is not yet atomic. Until corex ships a PG advisory
+> lock on `MarkdownEditor#execute`, treat writes on any given file as
+> **sequential**: chain your CLI calls with `await`, or coordinate via
+> an out-of-band lock. Writes on *different* files stay safe.
+
+> ⚠️ **Known limitation — `Documents::*` events not yet on `/api/v1/events`**
+> (tracked in [corex#596](https://code.plugandwork.net/sinoia/corex/-/issues/596)):
+> the events API was initially scoped to `Projects::*` types (corex#593).
+> `hubdoc events watch --type Documents::FileContentUpdated` returns
+> nothing today — agent-to-agent coordination on markdown edits is on
+> hold until that scope is opened. In the meantime, coordinate via the
+> ticket the file belongs to (`ticket.updated`, `ticket.comment`) or via
+> an external channel.
+
+**Typical agent workflow — build a section incrementally without racing** :
+
+```bash
+# 1. Discover current structure (10 KB, no side effects).
+hubdoc md structure "$FID" --json
+
+# 2. Read just the section we care about.
+hubdoc md read-section "$FID" --heading "Analyse" --json > current.md
+
+# 3. Regenerate its body locally, push atomically.
+llm-generate-analysis > new-analysis.md
+hubdoc md write-section "$FID" --heading "Analyse" \
+    --content-file new-analysis.md --json
+
+# 4. Snapshot when done.
+hubdoc md save "$FID" --create-version --version-comment "Analyse v2" --json
+```
+
 ### Events — react to what's happening (corex#593)
 
 `hubdoc events ls` and `hubdoc events watch` sit on top of the Rails

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinoia/hubdoc-tools",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {