backdraft 0.4.0__tar.gz → 0.4.1__tar.gz

backdraft-0.4.1/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "backdraft",
+  "owner": {
+    "name": "Spencer Braun",
+    "url": "https://github.com/spencerbraun"
+  },
+  "description": "Self-hosting marketplace for the backdraft plugin: agent skills for writing documents whose factual claims carry verifiable citations.",
+  "plugins": [
+    {
+      "name": "backdraft",
+      "source": "./",
+      "description": "Drop-in provenance for factual claims: one click from any claim to the evidence behind it. Ships the backdraft writing, backfill, and artifact-reading skills; the CLI installs separately (uv tool install backdraft).",
+      "category": "productivity"
+    }
+  ]
+}

backdraft-0.4.1/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "backdraft",
+  "displayName": "Backdraft",
+  "version": "0.4.1",
+  "description": "Drop-in provenance for factual claims: one click from any claim to the evidence behind it. Ships the backdraft writing, backfill, and artifact-reading skills; the CLI installs separately (uv tool install backdraft).",
+  "author": {
+    "name": "Spencer Braun",
+    "url": "https://github.com/spencerbraun"
+  },
+  "homepage": "https://backdraft.dev",
+  "repository": "https://github.com/spencerbraun/backdraft",
+  "license": "MIT",
+  "keywords": ["citations", "provenance", "sources", "evidence", "documents", "pdf", "xlsx", "writing"]
+}

{backdraft-0.4.0 → backdraft-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backdraft
-Version: 0.4.0
+Version: 0.4.1
 Summary: Drop-in provenance for factual claims: one click from any claim to the evidence behind it.
 Project-URL: Homepage, https://backdraft.dev
 Project-URL: Documentation, https://backdraft.dev/docs.html
@@ -232,13 +232,7 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship inside the package, and the CLI installs them:
-
-```bash
-backdraft skill install          # the writing skill, into ~/.claude/skills/
-backdraft skill install --all    # plus backfill and artifact-reading
-backdraft skill install --project  # into this repo's .claude/skills/
-```
+Three agent skills ship inside the package and in this repo:
 
 | Skill | For |
 |---|---|
@@ -247,7 +241,51 @@ backdraft skill install --project  # into this repo's .claude/skills/
 | [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
 
 The CLI is the system; a skill is one page telling an agent to use it. Nothing in
-the skills is required to use backdraft by hand.
+the skills is required to use backdraft by hand. How the skills reach your agent
+depends on the harness:
+
+**Claude Code.** The repo is its own plugin marketplace, so the plugin route
+tracks releases:
+
+```text
+/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft
+```
+
+Or have the CLI copy the skills into your skills directory:
+
+```bash
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
+```
+
+**Claude Cowork.** Once the plugin is listed in Anthropic's community
+directory, it installs from Cowork's built-in skills directory. Until then,
+zip a skill folder from `skills/` and upload it under Customize > Skills.
+Inside a Cowork session the CLI itself runs per-command as
+`uvx backdraft ...`, since installs do not persist between sessions.
+
+**Codex, Cursor, Copilot.** Agents in this family read skills from
+`~/.agents/skills`:
+
+```bash
+backdraft skill install --agent codex   # into ~/.agents/skills/
+```
+
+or commit the skill folders to your repo under `.agents/skills/` so every
+checkout carries them.
+
+**Standing context, any harness.** Paste this into your repo's AGENTS.md:
+
+```markdown
+## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.
+```
 
 ## Documentation
 

{backdraft-0.4.0 → backdraft-0.4.1}/README.md

@@ -207,13 +207,7 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship inside the package, and the CLI installs them:
-
-```bash
-backdraft skill install          # the writing skill, into ~/.claude/skills/
-backdraft skill install --all    # plus backfill and artifact-reading
-backdraft skill install --project  # into this repo's .claude/skills/
-```
+Three agent skills ship inside the package and in this repo:
 
 | Skill | For |
 |---|---|
@@ -222,7 +216,51 @@ backdraft skill install --project  # into this repo's .claude/skills/
 | [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
 
 The CLI is the system; a skill is one page telling an agent to use it. Nothing in
-the skills is required to use backdraft by hand.
+the skills is required to use backdraft by hand. How the skills reach your agent
+depends on the harness:
+
+**Claude Code.** The repo is its own plugin marketplace, so the plugin route
+tracks releases:
+
+```text
+/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft
+```
+
+Or have the CLI copy the skills into your skills directory:
+
+```bash
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
+```
+
+**Claude Cowork.** Once the plugin is listed in Anthropic's community
+directory, it installs from Cowork's built-in skills directory. Until then,
+zip a skill folder from `skills/` and upload it under Customize > Skills.
+Inside a Cowork session the CLI itself runs per-command as
+`uvx backdraft ...`, since installs do not persist between sessions.
+
+**Codex, Cursor, Copilot.** Agents in this family read skills from
+`~/.agents/skills`:
+
+```bash
+backdraft skill install --agent codex   # into ~/.agents/skills/
+```
+
+or commit the skill folders to your repo under `.agents/skills/` so every
+checkout carries them.
+
+**Standing context, any harness.** Paste this into your repo's AGENTS.md:
+
+```markdown
+## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.
+```
 
 ## Documentation
 

{backdraft-0.4.0 → backdraft-0.4.1}/ROADMAP.md

@@ -46,8 +46,12 @@ the objection rather than rediscovering it.
 - **HTML pages and email (.eml)** — both arrive in diligence folders, both
   have messy identity questions (what is "the source" of a web page?) that
   deserve a decision row before code.
-- **Distribution** — published on PyPI; still queued: a skills-registry
-  listing when one becomes the standard channel.
+- **Distribution** — published on PyPI; the repo now ships
+  `.claude-plugin/plugin.json` and `marketplace.json`, so it installs as a
+  Claude Code plugin and self-hosts its marketplace, and the AGENTS.md
+  snippet is published in the README and site docs. Still queued: the
+  community-directory listing (submission form is a maintainer action,
+  pending), which is also what surfaces the skills in Cowork's directory.
 
 ## Someday
 

{backdraft-0.4.0 → backdraft-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "backdraft"
-version = "0.4.0"
+version = "0.4.1"
 description = "Drop-in provenance for factual claims: one click from any claim to the evidence behind it."
 readme = "README.md"
 requires-python = ">=3.13"

{backdraft-0.4.0 → backdraft-0.4.1}/site/docs.html

@@ -109,7 +109,7 @@ footer{text-align:center;font-family:var(--sans);font-size:.74rem;color:var(--mu
   <a href="#writing">Writing rules</a>
   <a href="#verification">Verification</a>
   <a href="#files">Files &amp; the artifact</a>
-  <a href="#agents">Agents</a>
+  <a href="#agents">Agents &amp; harnesses</a>
   <a href="#security">Security &amp; privacy</a>
   <a href="#faq">FAQ</a>
 </aside>
@@ -277,14 +277,41 @@ of a gigabyte corpus is a ~2&nbsp;MB file. Recipients need the one
 </section>
 
 <section id="agents">
-<h2>Agents</h2>
-<pre>backdraft skill install          <span class="dim"># the writing skill, into ~/.claude/skills/</span>
-backdraft skill install --all    <span class="dim"># plus backfill and artifact-reading</span>
-backdraft skill install --project<span class="dim">  # into this repo's .claude/skills/</span></pre>
+<h2>Agents and harnesses</h2>
 <p>The skill's core instruction is a substitution: for source documents, use
 <code>backdraft read</code>/<code>search</code>, never raw file reads. The
 token-efficient reference for any agent is <a href="llms.txt">llms.txt</a>
-(~800 tokens).</p>
+(~800 tokens). How the skill reaches your agent depends on the harness.</p>
+<h3>Claude Code</h3>
+<p>The repo is its own plugin marketplace, so the plugin route tracks
+releases:</p>
+<pre>/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft</pre>
+<p>Or have the CLI copy the skills into your skills directory:</p>
+<pre>backdraft skill install          <span class="dim"># the writing skill, into ~/.claude/skills/</span>
+backdraft skill install --all    <span class="dim"># plus backfill and artifact-reading</span>
+backdraft skill install --project<span class="dim">  # into this repo's .claude/skills/</span></pre>
+<h3>Claude Cowork</h3>
+<p>Once the plugin is listed in Anthropic's community directory, it installs
+from Cowork's built-in skills directory; until then, zip a skill folder from
+the repo's <code>skills/</code> and upload it under Customize &gt; Skills.
+Inside a session, run the CLI per-command as <code>uvx backdraft ...</code>,
+since installs do not persist between sessions.</p>
+<h3>Codex, Cursor, Copilot</h3>
+<p>Agents in this family read skills from <code>~/.agents/skills</code>:</p>
+<pre>backdraft skill install --agent codex   <span class="dim"># into ~/.agents/skills/</span></pre>
+<p>Or commit the skill folders to your repo under <code>.agents/skills/</code>
+so every checkout carries them. For Codex cloud environments, add
+<code>pip install backdraft</code> to the setup script, which runs while the
+network is still on.</p>
+<h3>Standing context</h3>
+<p>For any harness that reads AGENTS.md, paste this into your repo's file:</p>
+<pre>## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.</pre>
 </section>
 
 <section id="security">

{backdraft-0.4.0 → backdraft-0.4.1}/site/llms.txt

@@ -10,8 +10,15 @@ https://github.com/spencerbraun/backdraft/blob/main/skills/backdraft/SKILL.md
 
 ## Install
 
-uv tool install backdraft
-backdraft skill install   # copies the writing skill into ~/.claude/skills/
+# Sandboxed session (Cowork, Codex cloud, CI): do NOT install. Run every
+# command through uvx instead: `uvx backdraft init`, `uvx backdraft read` …
+# No PATH edits, never run `backdraft skill install`, never modify agent
+# config from inside a session.
+# Owned machine:
+uv tool install backdraft   # pip install backdraft where uv is absent
+# Human-run setup step (not for sessions): `backdraft skill install` copies
+# the writing skill into ~/.claude/skills/ (Claude Code); add
+# `--agent codex` to target ~/.agents/skills for the Codex family.
 # Vision-model extraction for PDFs and images ships by default (needs poppler
 # for PDFs + BACKDRAFT_VLM_API_KEY). Ambient provider keys (OPENAI_API_KEY
 # etc.) are NEVER read; only BACKDRAFT_*.

{backdraft-0.4.0 → backdraft-0.4.1}/skills/backdraft/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backdraft
-description: Write a document whose factual claims are each traceable to the source text behind them. Use whenever the task is to produce a memo, report, summary, analysis, brief, or answer grounded in specific source files (PDFs, spreadsheets, docs) and the reader will need to check where a number or statement came from. Triggers on "cite your sources", "with citations", "show where this came from", "grounded in these documents", "provenance", "backdraft", or any request to read source files and write findings from them.
+description: Write documents whose factual claims each carry a checkable citation into source files. Use when producing a memo, report, or analysis from PDFs, spreadsheets, or docs with citations or provenance.
 ---
 
 # backdraft — writing with citations that resolve
@@ -13,6 +13,12 @@ fact you obtained any other way has no receipt and cannot be cited.
 
 ## Workflow
 
+If `backdraft` is not on PATH (sandboxed sessions start fresh), run every
+command through uvx instead: `uvx backdraft init`, `uvx backdraft read`, and so
+on. Where uv is absent, `pip install backdraft` once per session, then use
+`backdraft` or `python -m backdraft`. Never modify PATH, shell rc files, or
+agent config directories; installs from PyPI need no special permissions.
+
 ```bash
 backdraft init                                    # once per project
 backdraft ingest report.pdf model.xlsx notes.md   # every source, up front

{backdraft-0.4.0 → backdraft-0.4.1}/skills/backdraft-artifact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backdraft-artifact
-description: Read, check, or summarize a backdraft artifact — a `*.backdraft.json` sidecar or `*.backdraft.html` file — encountered with no other context. Use when handed a file with either extension, when a document mentions claims with tokens shaped `bd:slug:locator:hash`, or when asked to "check the citations in this", "verify this artifact", "what does this sidecar say", "audit these claims", or "is this document's evidence any good". Applies to reviewing someone else's bound document, not to producing one.
+description: Read and check a backdraft artifact (*.backdraft.json or *.backdraft.html), verifying receipts and summarizing claim statuses. Use when handed such a file or asked to audit its citations.
 ---
 
 # backdraft-artifact — reading a bound document cold

{backdraft-0.4.0 → backdraft-0.4.1}/skills/backdraft-backfill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backdraft-backfill
-description: Attribute an existing document to its sources after the fact — attach a citation to each factual claim in a memo, report, or draft that was written without them, and produce an explicit list of the claims no source supports. Use when asked to "add citations to this", "source these claims", "where did these numbers come from", "check this against the source documents", "fact-check this memo against these files", or to audit an existing document for unsupported statements. Not for writing a new document — use the `backdraft` skill for that.
+description: Attach citations to an existing document after the fact, tracing each factual claim to source files and listing unsupported claims. Use for add-citations or fact-check-against-these-files requests.
 ---
 
 # backdraft-backfill — attributing a document that already exists
@@ -14,6 +14,12 @@ what the claim says — a plausible-looking hit is not evidence.**
 
 ## 1. Ingest the sources
 
+If `backdraft` is not on PATH (sandboxed sessions start fresh), run every
+command through uvx instead: `uvx backdraft init`, `uvx backdraft read`, and so
+on. Where uv is absent, `pip install backdraft` once per session, then use
+`backdraft` or `python -m backdraft`. Never modify PATH, shell rc files, or
+agent config directories; installs from PyPI need no special permissions.
+
 ```bash
 backdraft init
 backdraft ingest sources/*.pdf sources/*.xlsx

backdraft-0.4.1/src/backdraft/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m backdraft` — the CLI for environments without a console script."""
+
+from backdraft.cli import main
+
+if __name__ == "__main__":
+    main()

{backdraft-0.4.0 → backdraft-0.4.1}/src/backdraft/cli.py

@@ -154,6 +154,11 @@ def ingest(
 
 SKILLS = ("backdraft", "backdraft-backfill", "backdraft-artifact")
 
+# Skills directories per agent family: Claude Code reads `.claude/skills/`;
+# `.agents/skills/` is the Agent Skills standard path read by OpenAI Codex,
+# Cursor, Copilot and others.
+AGENT_DIRS = {"claude": ".claude", "codex": ".agents"}
+
 
 def _skills_source() -> Path:
     """Where the bundled skills live: package data in a wheel, repo in a checkout."""
@@ -171,37 +176,50 @@ def skill(
     action: Annotated[str, typer.Argument(help="`install` is the only action.")] = "install",
     project: Annotated[
         bool,
-        typer.Option("--project", help="Install into ./.claude/skills instead of ~/.claude/skills."),
+        typer.Option("--project", help="Install into the project's skills directory instead of the home one."),
     ] = False,
     all_: Annotated[
         bool,
         typer.Option("--all", help="Also install the backfill and artifact-reading skills."),
     ] = False,
+    agent: Annotated[
+        str,
+        typer.Option("--agent", help="Target agent layout: `claude`, `codex`, or `all`."),
+    ] = "claude",
 ) -> None:
     """Install the agent skill: `backdraft skill install`, then ask for cited work.
 
-    Copies the writing skill into your agent's skills directory (Claude Code
-    layout: `~/.claude/skills/`, or the project's `.claude/skills/` with
-    `--project`). `--all` adds the backfill and artifact-reading skills.
+    Copies the writing skill into your agent's skills directory. `--agent claude`
+    (the default) targets Claude Code's `~/.claude/skills/`; `--agent codex`
+    targets `~/.agents/skills/`, the Agent Skills standard path read by OpenAI
+    Codex, Cursor, Copilot and others; `--agent all` targets both. `--project`
+    installs under the current directory (`.claude/skills/`, `.agents/skills/`)
+    instead of the home directory. `--all` adds the backfill and
+    artifact-reading skills.
     """
     import shutil
 
     with guard():
         if action != "install":
             raise UsageError(f"unknown action {action!r}; try: backdraft skill install")
+        if agent not in (*AGENT_DIRS, "all"):
+            raise UsageError(f"unknown agent {agent!r}; try: claude, codex, or all")
         source = _skills_source()
-        target_root = (Path.cwd() / ".claude" if project else Path.home() / ".claude") / "skills"
+        agents = tuple(AGENT_DIRS) if agent == "all" else (agent,)
+        base = Path.cwd() if project else Path.home()
         names = SKILLS if all_ else SKILLS[:1]
-        for name in names:
-            src = source / name
-            if not src.is_dir():
-                raise UsageError(f"bundled skill missing: {name}")
-            dst = target_root / name
-            dst.mkdir(parents=True, exist_ok=True)
-            for item in src.iterdir():
-                if item.is_file():
-                    shutil.copy2(item, dst / item.name)
-            typer.echo(f"installed {name} -> {dst}")
+        for agent_name in agents:
+            target_root = base / AGENT_DIRS[agent_name] / "skills"
+            for name in names:
+                src = source / name
+                if not src.is_dir():
+                    raise UsageError(f"bundled skill missing: {name}")
+                dst = target_root / name
+                dst.mkdir(parents=True, exist_ok=True)
+                for item in src.iterdir():
+                    if item.is_file():
+                        shutil.copy2(item, dst / item.name)
+                typer.echo(f"installed {name} -> {dst}")
     typer.echo('next: ask your agent for cited work, e.g. "Write me a memo from ./docs, with citations."')
 
 

{backdraft-0.4.0 → backdraft-0.4.1}/tests/test_cli.py

@@ -217,3 +217,92 @@ def test_skill_install_copies_the_bundled_skill(tmp_path, monkeypatch) -> None:
     result = CliRunner().invoke(app, ["skill", "install", "--all"])
     assert result.exit_code == 0, result.output
     assert (tmp_path / ".claude" / "skills" / "backdraft-backfill" / "SKILL.md").is_file()
+
+
+def test_skill_install_default_agent_touches_only_claude(tmp_path, monkeypatch) -> None:
+    from typer.testing import CliRunner
+
+    from backdraft.cli import app
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    result = CliRunner().invoke(app, ["skill", "install"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / ".claude" / "skills" / "backdraft" / "SKILL.md").is_file()
+    assert not (tmp_path / ".agents").exists()
+
+
+def test_skill_install_agent_codex_uses_the_standard_path(tmp_path, monkeypatch) -> None:
+    from typer.testing import CliRunner
+
+    from backdraft.cli import app
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    result = CliRunner().invoke(app, ["skill", "install", "--agent", "codex"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / ".agents" / "skills" / "backdraft" / "SKILL.md").is_file()
+    assert not (tmp_path / ".claude").exists()
+
+
+def test_skill_install_agent_all_lands_in_both_layouts(tmp_path, monkeypatch) -> None:
+    from typer.testing import CliRunner
+
+    from backdraft.cli import app
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    result = CliRunner().invoke(app, ["skill", "install", "--agent", "all", "--all"])
+    assert result.exit_code == 0, result.output
+    for root in (".claude", ".agents"):
+        for name in ("backdraft", "backdraft-backfill", "backdraft-artifact"):
+            assert (tmp_path / root / "skills" / name / "SKILL.md").is_file()
+
+
+def test_skill_install_agent_codex_project_lands_in_cwd(tmp_path, monkeypatch) -> None:
+    from typer.testing import CliRunner
+
+    from backdraft.cli import app
+
+    monkeypatch.chdir(tmp_path)
+    result = CliRunner().invoke(app, ["skill", "install", "--agent", "codex", "--project"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / ".agents" / "skills" / "backdraft" / "SKILL.md").is_file()
+
+
+def test_skill_install_rejects_an_unknown_agent(tmp_path, monkeypatch) -> None:
+    from typer.testing import CliRunner
+
+    from backdraft.cli import app
+
+    monkeypatch.setattr("pathlib.Path.home", lambda: tmp_path)
+    result = CliRunner().invoke(app, ["skill", "install", "--agent", "cursor"])
+    assert result.exit_code == 1
+    assert "unknown agent" in result.output
+
+
+def test_python_dash_m_backdraft_runs_the_cli() -> None:
+    import subprocess
+    import sys
+
+    result = subprocess.run(
+        [sys.executable, "-m", "backdraft", "--help"],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    assert "ingest" in result.stdout
+
+
+def test_skill_descriptions_fit_the_upload_cap() -> None:
+    """claude.ai's skill upload rejects descriptions over 200 characters."""
+    import re
+
+    from backdraft.cli import SKILLS, _skills_source
+
+    for name in SKILLS:
+        text = (_skills_source() / name / "SKILL.md").read_text(encoding="utf-8")
+        match = re.search(r"^description: (.+)$", text, flags=re.MULTILINE)
+        assert match, name
+        assert len(match.group(1)) <= 200, (name, len(match.group(1)))
+        # An unquoted YAML scalar dies on ": " — keep descriptions parseable.
+        assert ": " not in match.group(1), name
+        named = re.search(r"^name: (.+)$", text, flags=re.MULTILINE)
+        assert named and named.group(1) == name

{backdraft-0.4.0 → backdraft-0.4.1}/uv.lock

@@ -53,7 +53,7 @@ wheels = [
 
 [[package]]
 name = "backdraft"
-version = "0.4.0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "openai" },