margin 0.2.1__tar.gz

margin-0.2.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,95 @@
+# 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/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "margin"
+version = "0.2.1"
+description = "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"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Konstantinos Georgiou" }]
+dependencies = []
+keywords = ["outline", "markdown", "comments", "claude", "claude-code", "agents", "documentation"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Documentation", "Topic :: Utilities"]
+
+[project.urls]
+Homepage = "https://github.com/drkostas/margin"
+
+[project.scripts]
+margin = "margin.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+margin = ["skills/*/SKILL.md"]

margin-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

margin-0.2.1/src/margin/batch.py

@@ -0,0 +1,41 @@
+"""When to tell the agent about comments: a settle window, so a burst becomes one message.
+
+A route (one repo's chat) has a batch open from its first undelivered comment. The batch is ready
+when the person has been quiet for `quiet` seconds, or `cap` seconds after its first comment so a
+long reading session still gets answers, or at once when a comment mentions the agent.
+
+Times are this machine's receive times (seconds since the epoch), never the server's timestamps,
+so a clock or timezone difference between the two cannot hold a batch back or release it early.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+
+def ready(rows, now: float, quiet: float, cap: float) -> dict[str, list]:
+    by_route: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_route[r["route"]].append(r)
+    out = {}
+    for route, rs in by_route.items():
+        first = min(r["received_at"] for r in rs)
+        last = max(r["received_at"] for r in rs)
+        if any(r["mentions_agent"] for r in rs) or now - last >= quiet or now - first >= cap:
+            out[route] = sorted(rs, key=lambda r: r["received_at"])
+    return out
+
+
+def due_in(rows, now: float, quiet: float, cap: float) -> float | None:
+    """Seconds until the next batch becomes ready, for a status line. None when nothing waits."""
+    if not rows:
+        return None
+    best = None
+    by_route: dict[str, list] = defaultdict(list)
+    for r in rows:
+        by_route[r["route"]].append(r)
+    for rs in by_route.values():
+        first = min(r["received_at"] for r in rs)
+        last = max(r["received_at"] for r in rs)
+        t = max(0.0, min(last + quiet, first + cap) - now)
+        best = t if best is None else min(best, t)
+    return best

margin-0.2.1/src/margin/claude.py

@@ -0,0 +1,89 @@
+"""`margin setup-claude`: wire margin and Outline into Claude Code, idempotently.
+
+Three things, each safe to run again:
+
+1. the margin skill, linked into ~/.claude/skills/margin from this package, so it updates with it;
+2. Outline's own MCP server registered in ~/.claude.json, with the agent's key supplied at connect
+   time by a small headers script that runs `api_key_command`, so the key is never written into
+   a config file;
+3. Outline's destructive MCP tools denied in ~/.claude/settings.json. An agent that deletes or
+   moves a document, or changes a collection, would break the folder structure margin mirrors.
+
+Both JSON files are backed up once per run before they are rewritten, atomically.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+from .config import Config
+
+DENY = ["delete_document", "delete_collection", "update_collection", "create_collection",
+        "move_document"]
+
+
+def _rewrite(path: Path, change) -> bool:
+    data = json.loads(path.read_text()) if path.exists() else {}
+    before = json.dumps(data, sort_keys=True)
+    change(data)
+    if json.dumps(data, sort_keys=True) == before:
+        return False
+    if path.exists():
+        shutil.copy2(path, path.with_name(path.name + f".bak-margin-{time.strftime('%Y%m%d%H%M%S')}"))
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent))
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, path)
+    return True
+
+
+def setup(cfg: Config, home: Path | None = None, name: str = "outline") -> list[str]:
+    home = home or Path.home()
+    done = []
+
+    # 1. the skill
+    skill_src = Path(__file__).parent / "skills" / "margin"
+    skills = home / ".claude" / "skills"
+    skills.mkdir(parents=True, exist_ok=True)
+    link = skills / "margin"
+    if link.is_symlink() or not link.exists():
+        if not (link.is_symlink() and Path(os.readlink(link)) == skill_src):
+            if link.is_symlink():
+                link.unlink()
+            link.symlink_to(skill_src)
+            done.append(f"skill linked: {link} -> {skill_src}")
+    else:
+        done.append(f"skill left alone: {link} exists and is not a link")
+
+    # 2. the MCP server and its headers script
+    helper = home / ".config" / "margin" / "outline-mcp-headers.sh"
+    helper.parent.mkdir(parents=True, exist_ok=True)
+    body = ("#!/bin/sh\n# written by margin setup-claude: the agent's Outline key, read at connect time\n"
+            f"k=$({shlex.join(cfg.api_key_command)}) || exit 1\n"
+            "printf '{\"Authorization\": \"Bearer %s\"}\\n' \"$k\"\n")
+    if not helper.exists() or helper.read_text() != body:
+        helper.write_text(body)
+        done.append(f"headers script written: {helper}")
+    helper.chmod(0o700)
+    url = cfg.mcp_url or cfg.url.rstrip("/") + "/mcp"
+
+    def add_server(d):
+        d.setdefault("mcpServers", {})[name] = {"type": "http", "url": url,
+                                               "headersHelper": str(helper)}
+    if _rewrite(home / ".claude.json", add_server):
+        done.append(f"MCP server '{name}' registered at {url}")
+
+    # 3. deny the destructive tools
+    def deny(d):
+        lst = d.setdefault("permissions", {}).setdefault("deny", [])
+        for t in DENY:
+            if f"mcp__{name}__{t}" not in lst:
+                lst.append(f"mcp__{name}__{t}")
+    if _rewrite(home / ".claude" / "settings.json", deny):
+        done.append("destructive Outline tools denied: " + ", ".join(DENY))
+    return done or ["already set up"]