@sinoia/hubdoc-tools 1.12.0 → 1.13.0

package/docs/llm-usage.md

@@ -408,6 +408,68 @@ 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 — handled server-side, no client state** :
+
+Each write action executes on the server as a single load-blob → mutate
+→ save-blob → `publish Documents::FileContentUpdated` cycle. Two agents
+running `hubdoc md insert` in parallel serialise at the Rails +
+ActiveStorage level; the second one loads the first one's result before
+applying its own. No client-side coordination or CRDT to maintain.
+
+Cross-modal coordination (agent + human on the web UI): every write
+broadcasts `content_refresh` over `DocumentEditingChannel`, which the
+frontend's Y.js session reloads from server content. Cf. the corex
+design `.claude/context/designs/y-rb-implementation.md`.
+
+**Inter-agent coordination via events** :
+
+```bash
+# Agent B watches for edits on the file, reacts.
+hubdoc events watch \
+    --type Documents::FileContentUpdated \
+    --timeout 900 --json \
+    | jq -r '.items[-1].data.file_id'
+# → returns as soon as another agent (or the human) touches the file.
+```
+
+**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.0",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {