sheafmd 1.0.0__tar.gz

sheafmd-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+# SPEC 18. A pull request, a push to main and the nightly run run on ubuntu only, and macOS runs only when someone
+# starts the workflow by hand with `macos` ticked: a macOS minute counts ten times.
+# tests/test_ci_workflow.py holds these triggers.
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  # paths-ignore filters push and pull_request only; a scheduled run always starts.
+  schedule:
+    - cron: '0 1 * * *'
+  workflow_dispatch:
+    inputs:
+      macos:
+        description: Add the macOS jobs (a macOS minute counts ten times)
+        type: boolean
+        default: false
+      python:
+        description: Python version to test (all is every version of the matrix)
+        type: choice
+        options: [all, "3.11", "3.13", "3.14"]
+        default: all
+
+# A new push to a pull request cancels its earlier run. A run on main is never cancelled once it has
+# started, so every merge to main gets a full verdict. Each run on main has a
+# group of its own, because a group holds one running and one waiting run, and a newer waiting run
+# would replace an older one even with cancel-in-progress false. Merges in a burst therefore run side
+# by side, one job each, and a 3.11 or 3.14 regression shows in the nightly run, not in a merge.
+concurrency:
+  group: ci-${{ github.ref == 'refs/heads/main' && github.run_id || github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    # A run takes about 25 minutes; 45 still stops a hang.
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJSON(github.event_name == 'workflow_dispatch' && inputs.macos && '["ubuntu-latest","macos-latest"]' || '["ubuntu-latest"]') }}
+        python: ${{ fromJSON(github.event_name == 'workflow_dispatch' && inputs.python != 'all' && format('["{0}"]', inputs.python) || (github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && '["3.11","3.13","3.14"]' || '["3.13"]') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # A pull request's checkout is its merge commit; two commits give the base as its first parent.
+          fetch-depth: 2
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install from the lock
+        run: uv sync --locked
+
+      # -v names every test in the log, and tools/ci/stall_watch.py dumps
+      # the process table and the pytest process's thread stacks when the output stops for six
+      # minutes, then ends the run after ten, so a hung job names itself instead of being cancelled.
+      - name: Tests
+        run: uv run --no-sync python tools/ci/stall_watch.py -- uv run --no-sync pytest -v --durations=25 -m "not page"
+
+      # The page tests drive Chromium through Playwright (tests/page) and take about half of a pull
+      # request's run. A pull request that changes no path they load skips them, and says so here
+      # (tools/ci/page_paths.py holds the list). A push to main, the nightly run and a manual run
+      # always run them. Until tests/page exists on main there is nothing to run.
+      - name: Decide whether the page tests run
+        id: page
+        run: uv run --no-sync python tools/ci/page_paths.py
+
+      - name: Cache the Playwright browsers
+        if: hashFiles('tests/page/**') != '' && steps.page.outputs.run == 'true'
+        uses: actions/cache@v4
+        with:
+          path: ${{ runner.os == 'macOS' && '~/Library/Caches/ms-playwright' || '~/.cache/ms-playwright' }}
+          key: playwright-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+
+      - name: Page tests (Playwright, Chromium)
+        if: hashFiles('tests/page/**') != '' && steps.page.outputs.run == 'true'
+        shell: bash
+        run: |
+          set -o pipefail
+          # --with-deps installs Chromium's system packages through sudo, which GitHub's runners have.
+          deps=""
+          if [ "$RUNNER_OS" = "Linux" ] && command -v sudo >/dev/null; then deps="--with-deps"; fi
+          uv run --no-sync playwright install $deps chromium
+          uv run --no-sync python tools/ci/stall_watch.py -- uv run --no-sync pytest -v --durations=25 -m page -rs 2>&1 | tee page-tests.txt
+          # A page test that cannot start its browser skips with a reason. Here that is a failure.
+          if grep -Eq '[0-9]+ skipped' page-tests.txt; then
+            echo "::error::page tests were skipped, so Chromium did not run them"
+            exit 1
+          fi
+
+      # A Chromium has closed with no word on a runner. The runner is a container
+      # with no dmesg (kernel.dmesg_restrict) and a memory cap of its own, so this reads what it can: the cgroup's
+      # own count of OOM kills, the memory and load, and /dev/shm. Nothing here changes the result of the job.
+      - name: Host state after a failure
+        if: failure() && runner.os == 'Linux'
+        shell: bash
+        run: |
+          free -m || true
+          uptime || true
+          cat /sys/fs/cgroup/memory.max /sys/fs/cgroup/memory.current /sys/fs/cgroup/memory.events 2>/dev/null || true
+          df -h /dev/shm || true
+          dmesg 2>/dev/null | tail -50 || true
+          journalctl -k --no-pager -n 50 2>/dev/null || true
+
+      - name: Wheel smoke (build, uv tool install, sheaf version, --share, init cursor, a hub)
+        run: uv run --no-sync python tools/wheel_smoke.py
+
+      # These two install a real user service on the runner. They refuse to run anywhere else.
+      - name: User service, systemd
+        if: runner.os == 'Linux'
+        run: PATH="$PWD/.venv/bin:$PATH" .venv/bin/python tools/ci/service_linux.py
+
+      - name: User service, launchd
+        if: runner.os == 'macOS'
+        run: PATH="$PWD/.venv/bin:$PATH" .venv/bin/python tools/ci/service_macos.py

sheafmd-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

sheafmd-1.0.0/GLOSSARY.md

@@ -0,0 +1,105 @@
+# sheaf
+
+A local working page for a markdown document, shared between a person and their agent. The `.md` stays the source; everything done on the page lands back in it.
+
+## Language
+
+**Hub**:
+The one local process that serves every document.
+_Avoid_: server, per-document server
+
+**Root**:
+A git repo (or a folder outside git) whose documents the hub serves, named after its folder.
+_Avoid_: project, collection
+
+**Core**:
+What every sheaf user gets: rendering, editing, comments, the agent adapter, the plain theme.
+
+**Layer**:
+An organisation's additions on top of the core, made of a theme, a root config, and separate programs that use sheaf as a library.
+_Avoid_: plugin, extension
+
+**Theme**:
+A folder of data that gives pages their look: stylesheet, fonts, wordmark, PDF footer. `plain` is built in.
+_Avoid_: skin, brand
+
+**Root config**:
+The `.sheaf.toml` file at the top of a root, checked in, that sets the root's theme, its "prepared for" name and its link rule.
+_Avoid_: settings, project config
+
+**Share copy**:
+A read-only render of a document with every comment removed, for someone outside the conversation.
+_Avoid_: client render, client version, public copy
+
+**Link rule**:
+The standard that every page, article, tool or document a text names is a link to its URL. It is checked when a page is rendered and told to the agent.
+
+**Diagnostics log**:
+The local record of everything that went wrong on a page or the hub, kept for bug reports.
+_Avoid_: incident log
+
+**Comment**:
+A threaded note a person or an agent leaves on a passage, stored in the `.md` right after that passage. Written as `sheaf-comment`; the older `rd-comment` is read as the same thing.
+_Avoid_: annotation, note, marker
+
+**Foreign comment**:
+Any HTML comment in the `.md` that sheaf did not write, such as another review tool's comments or a table-of-contents directive. sheaf never changes, moves or drops one, and does not show it as a Comment.
+
+**Hub key**:
+The one secret that proves a caller is the person whose hub it is. A browser holds a cookie derived from it, swapped for once; the CLI and the stdio MCP door read it from disk.
+_Avoid_: token, edit token, password
+
+**Sign-in nonce**:
+A value the hub makes for the key holder that signs one browser in, once, within 30 seconds. `sheaf open` hands the browser this instead of the hub key.
+_Avoid_: sign-in token, key URL
+
+**Loopback mode**:
+The hub as it runs by default: reached on 127.0.0.1 only, by the hub key, a browser cookie or an MCP token.
+
+**Remote seat**:
+A person working on the hub's machine over ssh, with no display there, so a browser on their own machine reaches the hub only through a tunnel. Not proxy mode: the hub is the same, only the way to it differs.
+_Avoid_: remote mode, remote host
+
+**Proxy mode**:
+The hub served on the origin of another web application, the front, through a reverse proxy on the same machine, with the front's sign-in saying who is asking. Off unless the hub's config switches it on.
+_Avoid_: hosted mode, remote mode
+
+**Front**:
+The web application whose origin the hub's pages share in proxy mode, and whose sign-in says who the member is.
+_Avoid_: host app, parent app
+
+**Verifier**:
+The small service the reverse proxy asks, in proxy mode, whether a request carries a session of the front, and which member it is. Not part of the hub.
+
+**Member**:
+A user of the front whom the hub's config lets in through proxy mode, with the roots they see and the name they sign with. A member has no account on the machine.
+_Avoid_: account, login
+
+**Agent adapter**:
+How the hub reaches an agent session: ask it a question, deliver a Tell, read its state, stop it. Each agent offers only what it can really do.
+
+**MCP door**:
+How an agent reaches the hub: read a document's threads and its text, reply, resolve, and, with the right to write, make a page and change its text. Any agent that speaks MCP can use it, whether the hub runs on the same machine or on a box it connects to.
+_Avoid_: MCP server, plugin
+
+**MCP token**:
+A named, revocable secret that lets one agent use the hub's HTTP MCP door, and nothing else. A token made with `--write` may also read, make and change pages through the door.
+_Avoid_: API key, hub key
+
+**Target session**:
+The agent session a document's Ask and Tell reach: the last one that rendered it from an agent.
+
+**Ask**:
+A question on a comment thread, answered in the thread by a fork of the target session, which changes nothing.
+
+**Tell**:
+A comment sent into the running target session, which acts on it and replies in the thread.
+_Avoid_: send, push
+
+**Role**:
+What a reply is, recorded apart from who wrote it: `answer` for an Ask, `action` for what a session did after a Tell.
+_Avoid_: reply type, magic author name
+
+**Pin**:
+A version of a document that the hub keeps beside the newest because a page holds its reload on it (`POST /_/pin`), so what the page sends later against that version is still taken. It is not the popover a page fixes on screen.
+_Avoid_: lock, snapshot

sheafmd-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tiroir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sheafmd-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: sheafmd
+Version: 1.0.0
+Summary: A working page for a markdown document, shared between a person and their agent.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: fonttools[woff]>=4.50
+Requires-Dist: pillow>=10
+Requires-Dist: pypandoc-binary==1.17
+Description-Content-Type: text/markdown
+
+# sheaf
+
+A working page for a markdown document, shared between a person and their agent.
+The `.md` stays the source; everything done on the page lands back in it.
+
+You read the document in your browser, edit it in place, and comment on passages. Press **Ask** on a
+comment and a copy of the agent session that wrote the document answers in the thread; press
+**Tell** and the running session acts on it and replies. Every edit and every comment is written
+into the `.md`, so the agent reads the same file you do, and `git diff` shows what happened.
+
+Three things set it apart:
+
+- **A save made against an older file is merged, not refused.** If the agent changed the file
+  while you were editing, your save is lined up with it paragraph by paragraph. Only the same
+  paragraph changed on both sides is a conflict, and even then nothing is lost.
+- **A share copy with the comments taken out.** `sheaf plan.md --share` writes one self-contained
+  HTML file (and, with `--pdf`, a PDF) that you can send to someone outside the conversation.
+- **Ask and Tell from the page, at any time.** The agent does not have to be waiting.
+
+## Install
+
+    uv tool install sheafmd
+
+`pipx install sheafmd` works too. It needs Python 3.11 or later; pandoc comes with it. The command
+is `sheaf`.
+
+## Quick start
+
+    sheaf plan.md
+
+This starts the hub if none runs, opens the page in your browser and prints its address. Select
+text on the page and press **Comment**; edit a paragraph and it is saved to `plan.md`. The hub
+serves every document you open from one local address, `http://127.0.0.1:27419`, and its index
+page lists them.
+
+The commands that work on the file alone need no hub:
+
+    sheaf comments plan.md                       # the open comments, with their threads
+    sheaf reply plan.md c3 "Done." --resolve     # answer a comment and resolve it
+    sheaf plan.md --share                        # plan-share.html, no comments, no script
+
+`sheaf --help` lists every command.
+
+## Agents
+
+    sheaf init claude      # or codex, gemini, cursor
+
+`init` registers sheaf's MCP door with that agent, using the agent's own command (`claude mcp add`,
+`codex mcp add`, `gemini mcp add`; for Cursor it adds an entry to `~/.cursor/mcp.json`). The agent
+can then list the documents with open comments, read a thread, reply and resolve. For Claude Code
+it also installs a skill in `~/.claude/skills/sheaf`. `init` never replaces what it did not write:
+a server called `sheaf` that is set up differently, a skill file of your own, or a file it cannot
+read is left as it is, and it says why and what to do.
+
+Ask and Tell from the page work with Claude Code. The other agents reach sheaf through the MCP
+door; adapters for them come later.
+
+For an agent that has no skills, or a project that wants the instruction in the repository, put
+this in the project's `AGENTS.md` (sheaf never writes that file):
+
+```
+This project keeps documents in markdown and uses sheaf: `sheaf FILE.md` opens a page for the person and prints its URL, which you give them. Do not render text meant for pasting somewhere else (an email, a post, a commit message, a prompt, a config file): put it in the conversation.
+Before you revise a document, read its comments with `sheaf comments FILE.md`.
+After you handle a comment, reply with `sheaf reply FILE.md ID "what you did" --resolve`; never delete a comment. A message that starts "Tell from sheaf" is a comment to act on: do it, then reply with `--role action`.
+Record what goes wrong with `sheaf diag note "what went wrong"`. Never run `sheaf signin-url` yourself: it prints the hub's key; ask the person to run it.
+Every page, article, tool or document you name is a markdown link to its URL, checked with curl that it answers.
+```
+
+An agent that reaches the hub over HTTP instead gets a named token: `sheaf token add NAME`
+prints it once. A token can read and answer comments. A token made with
+`sheaf token add NAME --write` can also read a page's text, make a page and change its text; it
+keeps every comment in the text, and a change made against an older text is refused.
+
+## Platforms
+
+- **Linux** is tested: CI runs the whole test suite on every pull request and every merge to main, on x86-64, with Python
+  3.13, and with Python 3.11, 3.13 and 3.14 every night. On aarch64 sheaf was tried once, by hand, with Python 3.14: the failures it
+  showed were fixed, and the whole suite has not been run there again.
+- **macOS** is not tested yet. The code has launchd and `~/Library` paths; nobody has run sheaf on a
+  Mac of their own.
+- **Windows** is not supported: use WSL2 (untested). Natively, only `--share`, `comments`,
+  `comment`, `reply`, `resolve`, `reopen` and `version` run.
+
+## Keep the hub running
+
+The hub starts by itself the first time a command needs it. To keep it running across logins and
+reboots, install it as a user service (never done for you):
+
+    sheaf service install      # systemd on Linux, launchd on macOS
+    sheaf service uninstall
+
+With the service installed, `sheaf start` and `sheaf restart` go through it. If the hub crashes the
+service starts it again after a growing delay (2 s, up to 60 s on systemd 254 and later) and gives
+up after five starts in five minutes. `sheaf diag` lists every `hub-start`, `hub-exit` and
+`unclean-exit`. Linux is the tested platform. CI installs the service for real on a Linux runner
+and checks that it restarts the hub after a `kill -9` and after an upgrade. The launchd job is
+checked only by tests that pretend to be a Mac: nobody has run it on a Mac of their own yet.
+
+After you upgrade sheaf, the next `sheaf` command restarts an idle hub on the new version and open
+pages reload by themselves. If an Ask or Tell is running, it says so and leaves the hub alone: run
+`sheaf restart` when it is done. A page with edits you have not saved, or a comment half written,
+is never reloaded; it tells you instead.
+
+## A hub on a remote box
+
+The hub listens on `127.0.0.1` only. To use one on a box you reach over ssh:
+
+1. On the box, install sheaf and run `sheaf service install`. A user service stops when its owner
+   logs out unless the admin runs `loginctl enable-linger <you>` once.
+2. On your machine forward the hub's port to the same port number:
+   `ssh -L 27419:127.0.0.1:27419 box`. VS Code Remote-SSH forwards it for you. In an ssh session
+   with no display, `sheaf open` prints this command, with your port, user and address, above the
+   URL and starts no browser on the box.
+3. On the box run `sheaf signin-url` and open what it prints in your own browser. That URL holds the
+   hub key: open it yourself, never paste it to an agent.
+
+Two people on one box each set their own port in `~/.config/sheaf/config.toml` (`port = 27420`) and
+forward their own. The sign-in cookie is named after the hub's port, so a local hub and a
+forwarded one on the same port number would overwrite each other's.
+
+## Signing in again
+
+`sheaf rotate` replaces the hub key. Every browser is signed out at once: an open page shows the
+sign-in page (or, with unsaved edits on it, keeps them and says how to sign in again). Sign in
+again with `sheaf open FILE.md`, or with `sheaf signin-url` for a browser on another machine. MCP
+tokens are not affected.
+
+## Security
+
+The trust line is your operating-system user: any process running as you is trusted. sheaf defends
+against other websites in your browser, other users on the machine, and hostile content in a
+document you render. The hub listens on loopback only, checks the `Host` and `Origin` of every
+request, and talks only to a browser that holds its key; the key is never in a page, and another
+local user without it gets nothing but the hub's name and version. The sign-in link that
+`sheaf open` hands your browser works once, and on Linux only for a browser of your own user: another
+user who reads it from the process list is refused (macOS cannot check that). Raw HTML in a document is
+sanitised and every page carries a content security policy, also for a page an agent wrote. An
+agent's token reaches the door's tools and nothing else: it cannot use the page's routes, run Ask
+or Tell, or add a folder, and it reads, makes and changes pages only when it was made with
+`--write`. sheaf collects nothing and opens no connection to another machine: its commands, your
+browser and the hub talk over `127.0.0.1`, and Ask and Tell go through your own agent.
+
+---
+
+Made by tiroir. A hosted version is coming.
+
+## Licence
+
+MIT. The pandoc binary comes from the separate `pypandoc-binary` wheel (GPL); sheaf itself stays
+MIT.

sheafmd-1.0.0/README.md

@@ -0,0 +1,150 @@
+# sheaf
+
+A working page for a markdown document, shared between a person and their agent.
+The `.md` stays the source; everything done on the page lands back in it.
+
+You read the document in your browser, edit it in place, and comment on passages. Press **Ask** on a
+comment and a copy of the agent session that wrote the document answers in the thread; press
+**Tell** and the running session acts on it and replies. Every edit and every comment is written
+into the `.md`, so the agent reads the same file you do, and `git diff` shows what happened.
+
+Three things set it apart:
+
+- **A save made against an older file is merged, not refused.** If the agent changed the file
+  while you were editing, your save is lined up with it paragraph by paragraph. Only the same
+  paragraph changed on both sides is a conflict, and even then nothing is lost.
+- **A share copy with the comments taken out.** `sheaf plan.md --share` writes one self-contained
+  HTML file (and, with `--pdf`, a PDF) that you can send to someone outside the conversation.
+- **Ask and Tell from the page, at any time.** The agent does not have to be waiting.
+
+## Install
+
+    uv tool install sheafmd
+
+`pipx install sheafmd` works too. It needs Python 3.11 or later; pandoc comes with it. The command
+is `sheaf`.
+
+## Quick start
+
+    sheaf plan.md
+
+This starts the hub if none runs, opens the page in your browser and prints its address. Select
+text on the page and press **Comment**; edit a paragraph and it is saved to `plan.md`. The hub
+serves every document you open from one local address, `http://127.0.0.1:27419`, and its index
+page lists them.
+
+The commands that work on the file alone need no hub:
+
+    sheaf comments plan.md                       # the open comments, with their threads
+    sheaf reply plan.md c3 "Done." --resolve     # answer a comment and resolve it
+    sheaf plan.md --share                        # plan-share.html, no comments, no script
+
+`sheaf --help` lists every command.
+
+## Agents
+
+    sheaf init claude      # or codex, gemini, cursor
+
+`init` registers sheaf's MCP door with that agent, using the agent's own command (`claude mcp add`,
+`codex mcp add`, `gemini mcp add`; for Cursor it adds an entry to `~/.cursor/mcp.json`). The agent
+can then list the documents with open comments, read a thread, reply and resolve. For Claude Code
+it also installs a skill in `~/.claude/skills/sheaf`. `init` never replaces what it did not write:
+a server called `sheaf` that is set up differently, a skill file of your own, or a file it cannot
+read is left as it is, and it says why and what to do.
+
+Ask and Tell from the page work with Claude Code. The other agents reach sheaf through the MCP
+door; adapters for them come later.
+
+For an agent that has no skills, or a project that wants the instruction in the repository, put
+this in the project's `AGENTS.md` (sheaf never writes that file):
+
+```
+This project keeps documents in markdown and uses sheaf: `sheaf FILE.md` opens a page for the person and prints its URL, which you give them. Do not render text meant for pasting somewhere else (an email, a post, a commit message, a prompt, a config file): put it in the conversation.
+Before you revise a document, read its comments with `sheaf comments FILE.md`.
+After you handle a comment, reply with `sheaf reply FILE.md ID "what you did" --resolve`; never delete a comment. A message that starts "Tell from sheaf" is a comment to act on: do it, then reply with `--role action`.
+Record what goes wrong with `sheaf diag note "what went wrong"`. Never run `sheaf signin-url` yourself: it prints the hub's key; ask the person to run it.
+Every page, article, tool or document you name is a markdown link to its URL, checked with curl that it answers.
+```
+
+An agent that reaches the hub over HTTP instead gets a named token: `sheaf token add NAME`
+prints it once. A token can read and answer comments. A token made with
+`sheaf token add NAME --write` can also read a page's text, make a page and change its text; it
+keeps every comment in the text, and a change made against an older text is refused.
+
+## Platforms
+
+- **Linux** is tested: CI runs the whole test suite on every pull request and every merge to main, on x86-64, with Python
+  3.13, and with Python 3.11, 3.13 and 3.14 every night. On aarch64 sheaf was tried once, by hand, with Python 3.14: the failures it
+  showed were fixed, and the whole suite has not been run there again.
+- **macOS** is not tested yet. The code has launchd and `~/Library` paths; nobody has run sheaf on a
+  Mac of their own.
+- **Windows** is not supported: use WSL2 (untested). Natively, only `--share`, `comments`,
+  `comment`, `reply`, `resolve`, `reopen` and `version` run.
+
+## Keep the hub running
+
+The hub starts by itself the first time a command needs it. To keep it running across logins and
+reboots, install it as a user service (never done for you):
+
+    sheaf service install      # systemd on Linux, launchd on macOS
+    sheaf service uninstall
+
+With the service installed, `sheaf start` and `sheaf restart` go through it. If the hub crashes the
+service starts it again after a growing delay (2 s, up to 60 s on systemd 254 and later) and gives
+up after five starts in five minutes. `sheaf diag` lists every `hub-start`, `hub-exit` and
+`unclean-exit`. Linux is the tested platform. CI installs the service for real on a Linux runner
+and checks that it restarts the hub after a `kill -9` and after an upgrade. The launchd job is
+checked only by tests that pretend to be a Mac: nobody has run it on a Mac of their own yet.
+
+After you upgrade sheaf, the next `sheaf` command restarts an idle hub on the new version and open
+pages reload by themselves. If an Ask or Tell is running, it says so and leaves the hub alone: run
+`sheaf restart` when it is done. A page with edits you have not saved, or a comment half written,
+is never reloaded; it tells you instead.
+
+## A hub on a remote box
+
+The hub listens on `127.0.0.1` only. To use one on a box you reach over ssh:
+
+1. On the box, install sheaf and run `sheaf service install`. A user service stops when its owner
+   logs out unless the admin runs `loginctl enable-linger <you>` once.
+2. On your machine forward the hub's port to the same port number:
+   `ssh -L 27419:127.0.0.1:27419 box`. VS Code Remote-SSH forwards it for you. In an ssh session
+   with no display, `sheaf open` prints this command, with your port, user and address, above the
+   URL and starts no browser on the box.
+3. On the box run `sheaf signin-url` and open what it prints in your own browser. That URL holds the
+   hub key: open it yourself, never paste it to an agent.
+
+Two people on one box each set their own port in `~/.config/sheaf/config.toml` (`port = 27420`) and
+forward their own. The sign-in cookie is named after the hub's port, so a local hub and a
+forwarded one on the same port number would overwrite each other's.
+
+## Signing in again
+
+`sheaf rotate` replaces the hub key. Every browser is signed out at once: an open page shows the
+sign-in page (or, with unsaved edits on it, keeps them and says how to sign in again). Sign in
+again with `sheaf open FILE.md`, or with `sheaf signin-url` for a browser on another machine. MCP
+tokens are not affected.
+
+## Security
+
+The trust line is your operating-system user: any process running as you is trusted. sheaf defends
+against other websites in your browser, other users on the machine, and hostile content in a
+document you render. The hub listens on loopback only, checks the `Host` and `Origin` of every
+request, and talks only to a browser that holds its key; the key is never in a page, and another
+local user without it gets nothing but the hub's name and version. The sign-in link that
+`sheaf open` hands your browser works once, and on Linux only for a browser of your own user: another
+user who reads it from the process list is refused (macOS cannot check that). Raw HTML in a document is
+sanitised and every page carries a content security policy, also for a page an agent wrote. An
+agent's token reaches the door's tools and nothing else: it cannot use the page's routes, run Ask
+or Tell, or add a folder, and it reads, makes and changes pages only when it was made with
+`--write`. sheaf collects nothing and opens no connection to another machine: its commands, your
+browser and the hub talk over `127.0.0.1`, and Ask and Tell go through your own agent.
+
+---
+
+Made by tiroir. A hosted version is coming.
+
+## Licence
+
+MIT. The pandoc binary comes from the separate `pypandoc-binary` wheel (GPL); sheaf itself stays
+MIT.