From 8f8a0fcc52c6caa20baf8eff1c84060fea64819d Mon Sep 17 00:00:00 2001 From: Grit77 <305451418+Grit-77@users.noreply.github.com> Date: Thu, 22 Oct 2026 23:01:49 +0300 Subject: [PATCH 1/2] Document an isolated local mailbox first use --- README.md | 13 ++++++-- docs/LOCAL-DEMO.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 docs/LOCAL-DEMO.md diff --git a/README.md b/README.md index fedd658..cb9a137 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,14 @@ flowchart LR R -->|HTTPS polling| D ``` +## Try the mailbox locally first + +[Send, claim and answer a synthetic message without connecting either agent →](docs/LOCAL-DEMO.md) + +The isolated PowerShell walkthrough uses a separate virtual environment and +mailbox on loopback. You supply the reply manually; it tests the protocol, not +native ChatGPT/Claude integration. Then connect your actual coding session below. + ## Quickstart: three steps 1. **Install and initialize on the computer running Claude Code.** @@ -34,8 +42,9 @@ flowchart LR dotline init ``` - Or run commands without a persistent install: `uvx --from . dotline init`. - Use `uvx --from . dotline ...` in place of `dotline ...` throughout this guide. + If you already cloned this repository, run `uvx --from . dotline init` + **from the clone's root** for a non-persistent alternative. In that checkout, + use `uvx --from . dotline ...` in place of `dotline ...` throughout this guide. For hooks and MCP, install with pipx so `dotline` is on the session's PATH. Init prints only the token file path. It preserves existing settings and the token. diff --git a/docs/LOCAL-DEMO.md b/docs/LOCAL-DEMO.md new file mode 100644 index 0000000..afab9ac --- /dev/null +++ b/docs/LOCAL-DEMO.md @@ -0,0 +1,77 @@ +# Try the mailbox without an agent + +Use this local manual demo to try send → claim → reply → readback before +connecting a ChatGPT dot or Claude Code. The second terminal plays the consumer. +No agent session, model API key or public tunnel is needed for this protocol demo. + +This is a **synthetic local exchange**, not a native agent integration test. +The recorded rehearsal used Windows, Python 3.12 and source revision +`71b3c8f9e32585ef2d48fb7ecb14fc3a7084e3ec`. Python 3.10+ and Git must already +be installed. Installation may download build tooling. + +## Terminal A: install and start an isolated mailbox + +Use a new empty directory and keep both terminals in that directory. The commands +below use PowerShell. Choose another unused loopback port if 18790 is occupied. + +```powershell +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install git+https://github.com/Grit-77/dotline@71b3c8f9e32585ef2d48fb7ecb14fc3a7084e3ec +$env:DOTLINE_HOME = Join-Path $PWD 'mailbox' +$env:DOTLINE_URL = 'http://127.0.0.1:18790' +Remove-Item Env:DOTLINE_TOKEN_FILE -ErrorAction SilentlyContinue +.\.venv\Scripts\dotline.exe init +.\.venv\Scripts\dotline.exe serve --host 127.0.0.1 --port 18790 +``` + +The separate virtual environment and `DOTLINE_HOME` keep this demo's runtime and +mailbox away from an existing dotline setup. `init` prints the token file path; +do not print or share its contents. The server stays in the foreground and binds +to loopback. It does not expose your computer to the public internet. + +## Terminal B: send, claim and answer + +Open another PowerShell terminal in the same demo directory. If you selected a +different port, use that same value here. + +```powershell +$env:DOTLINE_HOME = Join-Path $PWD 'mailbox' +$env:DOTLINE_URL = 'http://127.0.0.1:18790' +Remove-Item Env:DOTLINE_TOKEN_FILE -ErrorAction SilentlyContinue +.\.venv\Scripts\dotline.exe health +.\.venv\Scripts\dotline.exe send 'Synthetic local demo request' --topic demo +.\.venv\Scripts\dotline.exe pending --json +# Use the ID printed by send in place of 1: +.\.venv\Scripts\dotline.exe claim 1 --by manual-demo +.\.venv\Scripts\dotline.exe reply 1 --by manual-demo 'Synthetic local demo reply' +.\.venv\Scripts\dotline.exe wait 1 --minutes 0.1 +.\.venv\Scripts\dotline.exe replies +``` + +Check that `wait` returns the reply you wrote and that `replies` associates it +with the sent message. Health alone does not test authenticated mailbox access. +Reusing this mailbox can produce IDs other than 1; use the actual ID throughout. + +## Stop and decide what to try next + +Stop the server with Ctrl+C in Terminal A and close the demo terminals. The +virtual environment and mailbox remain in the demo directory. Mailbox data and +the bearer are plaintext: keep that directory private and remove it when you +no longer need the synthetic data. + +The local rehearsal also exercised file input, a repeated `client_id`, a refused +conflicting claim and an unanswered wait. The same 90 selected CLI, HTTP and +integration tests passed in researcher and manager runs on the pinned source; +these are repeated runs of 90 tests, not 180 distinct tests. No real messages, +owner settings or external agent sessions were used. + +Those observations do not establish that a dot or Claude follows its trust +instructions. To connect your actual session, return to the +[Claude-side setup](../README.md#claude-side) and +[dot connection choices](../README.md#talking-from-a-dot). Native integration +and remote HTTPS need their own checks. Retain the +[trust and security limits](../README.md#trust-and-security). + +If you get stuck, report the source revision, operating system, command stage +and redacted error in an [issue](https://github.com/Grit-77/dotline/issues). +Do not include bearer values or private message contents. From 0fd4d1faf3fec1471747a46ef107a7670bcfcd76 Mon Sep 17 00:00:00 2001 From: Grit77 <305451418+Grit-77@users.noreply.github.com> Date: Thu, 22 Oct 2026 23:13:56 +0300 Subject: [PATCH 2/2] Use portable reply argument ordering in examples --- README.md | 2 +- docs/LOCAL-DEMO.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cb9a137..43bb2f5 100644 --- a/README.md +++ b/README.md @@ -288,7 +288,7 @@ an invalid claim instead of replacing it or treating it as unclaimed. Inspect and repair the file with the sessions stopped before trying again. For Monitor, always claim before working. Optionally use -`dotline reply --by "answer"` to require the matching claim. +`dotline reply "answer" --by ` to require the matching claim. The default reply command trusts cooperating local sessions; local file access is not a security boundary. Long work can outlive the 30-minute lease: check ownership and avoid duplicate side effects. Expiry does not undo work. diff --git a/docs/LOCAL-DEMO.md b/docs/LOCAL-DEMO.md index afab9ac..e5f54df 100644 --- a/docs/LOCAL-DEMO.md +++ b/docs/LOCAL-DEMO.md @@ -43,7 +43,7 @@ Remove-Item Env:DOTLINE_TOKEN_FILE -ErrorAction SilentlyContinue .\.venv\Scripts\dotline.exe pending --json # Use the ID printed by send in place of 1: .\.venv\Scripts\dotline.exe claim 1 --by manual-demo -.\.venv\Scripts\dotline.exe reply 1 --by manual-demo 'Synthetic local demo reply' +.\.venv\Scripts\dotline.exe reply 1 'Synthetic local demo reply' --by manual-demo .\.venv\Scripts\dotline.exe wait 1 --minutes 0.1 .\.venv\Scripts\dotline.exe replies ```