margin 0.2.1__py3-none-any.whl

margin-0.2.1.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: margin
+Version: 0.2.1
+Summary: Publish a repo's markdown to a self-hosted Outline, keep comments anchored, and bring each new comment back to an AI agent in batches
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/margin
+Keywords: outline,markdown,comments,claude,claude-code,agents,documentation
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# margin
+
+margin publishes the markdown files of your repositories to a self-hosted [Outline](https://github.com/outline/outline) wiki, and brings every comment you leave there back to an AI agent such as Claude Code. You read your docs in a browser or on your phone, select a sentence and comment on it, and the agent answers in the thread and changes the file.
+
+Each repository becomes one Outline collection. Folders become parent documents, and a folder's `README.md` is that folder's page.
+
+## What it does
+
+- **Publishes changes as small patches.** A comment in Outline is attached to a piece of text. Replacing a whole document through Outline's API removes every one of those attachments, so margin never does that. It works out the smallest changes, applies them one at a time, and checks each result against what it expected.
+- **Publishes the pictures a file shows.** A local image referenced by a relative path (`![The settings page](shots/settings.png)`) is uploaded once as an attachment of its document, so everyone who can read the document sees it. The file keeps its relative path. A changed picture counts as a changed file.
+- **Never settles a disagreement by "newest wins".** margin keeps both sides' text from the last sync. If only the file changed, it patches Outline. If someone edited the document in Outline, or both changed, it leaves both alone and reports the document.
+- **Collects comments two ways.** Outline sends a signed webhook for each new comment. A catch-up poll every few minutes finds anything the webhook missed, for example while the machine was asleep. A comment that arrives both ways is recorded once.
+- **Sends comments in batches.** A burst of comments becomes one message. A batch is delivered after a quiet period (3 minutes by default), never later than a cap after its first comment (15 minutes), and at once when a comment mentions the agent's user.
+- **Keeps the agent out of its own inbox.** Comments written by the agent's user are never recorded, so its replies cannot wake it.
+
+## Install
+
+```bash
+pip install margin
+```
+
+margin needs Python 3.11 or newer and has no dependencies outside the standard library. You also need an Outline server that you can reach, with two users, yourself and the agent. [`examples/outline`](examples/outline) has a Docker Compose setup for Outline, Redis and a small sign-in provider.
+
+## Configure
+
+margin reads `~/.config/margin/config.toml`. Secrets are never written in it. Each secret is the output of a command, for example a password manager or the macOS keychain.
+
+```toml
+[outline]
+url = "https://docs.example.com"
+api_key_command = ["pass", "outline/agent-api-key"]      # the agent's key, a normal member
+admin_key_command = ["pass", "outline/admin-api-key"]    # used only to create the webhook
+
+[intake]
+listen = "127.0.0.1:8771"
+webhook_url = "http://host.docker.internal:8771/outline" # the address Outline posts to
+secret_command = ["pass", "outline/webhook-secret"]
+poll_seconds = 600
+
+[batch]
+quiet_seconds = 180
+cap_seconds = 900
+
+[notify]
+command = ["my-notifier", "{route}"]     # receives each batch as JSON on stdin; {text}, {repo} and {repo_path} are filled in
+
+[[repo]]
+name = "my-project"                      # the Outline collection
+path = "~/code/my-project"
+exclude = ["vendor/**"]
+route = "my-project"                     # passed to the notifier as {route}
+```
+
+When `[notify]` has no command, margin prints each batch.
+
+Outline refuses to send webhooks to private addresses. If margin runs on the same machine as an Outline container, add the container's host gateway address to Outline's `ALLOWED_PRIVATE_IP_ADDRESSES` setting.
+
+## Use
+
+```bash
+margin sync                  # publish what changed, in every configured repo
+margin sync my-project --full
+margin serve                 # webhook receiver, catch-up poll, batching and a sync every minute
+margin status                # documents that need attention, comments waiting
+margin reply <comment-id> "Changed to five minutes, see the Lifetime section."
+margin resolve <comment-id>
+margin thread <comment-id>
+margin link docs/plan.md     # publish these files now and print a Markdown link to each
+margin setup-claude          # link the skill, register Outline's MCP, deny its destructive tools
+```
+
+A batch looks like this.
+
+```text
+2 new comment(s) in Outline.
+
+### Cache design
+my-project/docs/cache.md  https://docs.example.com/doc/cache-design-pbS4AcgGK0
+- [393bdced-...] Alex on "least recently used first":
+  Please also say what happens when memory is full.
+- [819aea0e-...] Alex on "The cache holds entries":
+  Is ten minutes measured from write or from last read?
+```
+
+The notifier also receives every comment as structured JSON, with the document's title, link and repository path.
+
+## Limits
+
+- A comment attached to text that the agent then rewrites loses its attachment. The thread stays, with no highlighted text. margin keeps its patches small so that this happens only to text that really changed.
+- Outline re-parses a whole list or quote when a patch has to cross into the next block. Comments inside that block lose their attachment the same way. New content at the end of a document is appended and touches nothing.
+- Edits made in Outline are reported, not copied back to the file. That direction is planned.
+
+## Licence
+
+MIT

margin-0.2.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+margin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+margin/batch.py,sha256=el8bHtPY0TPz1xllKcaqy7_SgXKijpvtEx2jMSDXnoE,1748
+margin/claude.py,sha256=gZhRE07r9wxKO7LQZQwrvAaEFZfZBlJBcbT5e_0HxcU,3577
+margin/cli.py,sha256=6I-9jZ1ZqhmaX34-TNsmzRrCkoCcGAUGEz-Y1gMqtVQ,13788
+margin/config.py,sha256=ijQ98rl4KycYYIHGxKmRpQ77oUmxt3AKrnSSswl1_R4,8389
+margin/fold.py,sha256=QWwMOzw6T0EFSi8z8Pf78fUjt32DoJhMa2UGepgv-BI,38426
+margin/images.py,sha256=A9c8dqQlAOA4ycV8PU_t6S2rfkb3BZvYkBpJrw-uq4E,3156
+margin/inbox.py,sha256=WeIakbR5wvj9BYmCFt3r2oleuVFVV_AmBgwboYvDa4Y,15312
+margin/outline.py,sha256=85sUXQXBSBwp_hTs_Pkh0w0r-HI3xI7pSwfyKlp4dro,12232
+margin/patches.py,sha256=4GSqKevQkJM6nf-Xi2_rffmqGp-cqPsEOyQSIWeMebk,11837
+margin/pinch_check.py,sha256=zij6y4TpAvalMkbfG5nK8KkadfYPBszXMHiiJ_9vRJ4,18177
+margin/store.py,sha256=B6Ozo5oJZXsI6r7fw5NcdwH7UYPiXLPul13lLhApJa0,8757
+margin/sync.py,sha256=ocPWRPkU8oPSQy_njxsRFxnLhJpqLMWyYsWPgtgRe2o,35710
+margin/skills/margin/SKILL.md,sha256=eXvX5l-SBVsbG7im5AZEX_GiYRlJMZlrv3-V-dv03gE,6279
+margin-0.2.1.dist-info/licenses/LICENSE,sha256=y2yT4XOJ5hjMzENqKJShtqLiwI-IE1PnWqMxbhhL5r8,1078
+margin-0.2.1.dist-info/METADATA,sha256=8rMHTJfTNu0PdY8h1OxbyjiNh0FNqK2epp-wGF6dpbM,5995
+margin-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+margin-0.2.1.dist-info/entry_points.txt,sha256=-5w3KEPp-au9A_bOPxtQGR67B9egA10Me2jOSRbXoDs,43
+margin-0.2.1.dist-info/top_level.txt,sha256=u21cuPWaJENEWAYmCFNkRU86jsBUCoVDmgkRuy2U1SY,7
+margin-0.2.1.dist-info/RECORD,,

margin-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

margin-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+margin = margin.cli:main

margin-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+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.

margin-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+margin