superbee 0.4.0-pre.2 → 0.4.0-pre.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.0-pre.2",
+  "version": "0.4.0-pre.3",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [

package/references/hosted-checkout.md

@@ -141,6 +141,20 @@ doc history <id> --seq <n>` shows version `n` (add `--json` for its whole conten
 created in the folder has history once `superbee sync` sends it. To compare-and-swap, use the
 folder's own version from `doc read`, not the host's newest version.
 
+## Large documents
+
+A host accepts documents up to the size it states (on current hosts 983,040 bytes as sent, about
+950 KiB of Markdown, since each newline, quote or backslash counts twice; 64 KiB on older ones).
+Sync holds a larger one with reason `too_large` and sends nothing: split it, or keep the edit until
+the host accepts it. Never shorten someone else's document just to make it sync.
+
+Read a large document a page at a time instead of pulling it whole into context: `superbee doc read
+<id> --offset 0 --json` answers `body` as one page of about 32 KiB with `range` (`complete`,
+`next_offset`); continue with `--offset <next_offset> --expected-version <head_version>` until
+`complete` is true. A page is not the document: never write it back as the body. To edit, use `doc
+read <id> --body-out <path-outside-bundle>`, edit that file, then `doc update <id> --body-file
+<path> --expected-version <version>`.
+
 ## Host reads with no verb yet: `op list` and `op run`
 
 Typed verbs come first: `doc read`, `doc history`, `list`, `query` and `status`. When the host
@@ -207,6 +221,32 @@ with a `held` row, reason `unsafe_id`, and the rest of the bundle syncs. A host
 differs only in letter case from another is held as `case_collision`. Both are renamed in the
 Superbee app, by the person.
 
+## The bundle's front page (the root `index.md`)
+
+The root `index.md` syncs as one file of its own when the host lets you change the bundle's front
+page (anyone who may write the bundle may). An edit to it is sent with the next `superbee sync`
+against the host's version the folder last had, and a front page changed on the host replaces an
+unedited file. If both changed, the receipt has a `conflict` row for `index.md`, and nothing is
+sent:
+
+```sh
+superbee sync --inspect --doc index.md          # base, your front page, the host's
+superbee sync --resolve take --doc index.md     # use the host's
+superbee sync --resolve keep --doc index.md     # the next sync sends yours over the inspected host version
+```
+
+- `keep` needs an `--inspect` first, as for a document. It sends the file as it is at that next
+  sync, so edit it to the combined result first if you want both. `revise` does the same.
+- A front page over 64 KiB as a request is held (`too_large`), and one that is not plain UTF-8
+  text (or starts with a byte-order mark) is held (`not_sendable`). The host refuses one that
+  changes the bundle's `okf_version` (`refused`, `validation_failed`).
+- A lost answer is settled by the host's front page itself: the next sync never sends it twice.
+- Where the host does not take front-page changes from you (an older host, or no write access), an
+  edited root `index.md` is held (`reserved_file`): change it in the Superbee app.
+- A root `index.md` that is a symbolic link (`symlink`) or a folder (`unsafe_path`) is held: sync
+  never reads, sends or replaces through it.
+- A subdirectory `index.md` and every `log.md` are always held (`reserved_file`).
+
 ## Refusals that belong to the person
 
 Some commands are refused in a hosted checkout with "do this in the Superbee app". Examples: