docsgraph 0.1.0a2__tar.gz → 0.1.0a3__tar.gz

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
         run: ruff check .
 
       - name: mypy --strict
-        run: mypy src tests
+        run: mypy --python-version "${{ matrix.python-version }}" src tests
 
       - name: pytest
         run: pytest

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/.github/workflows/release.yml

@@ -6,9 +6,36 @@ on:
       - "v*"
 
 jobs:
+  verify:
+    name: lint + types + tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: ruff
+        run: ruff check .
+
+      - name: mypy --strict
+        run: mypy --python-version "3.13" src tests
+
+      - name: pytest
+        run: pytest
+
   build:
     name: Build wheel + sdist for ${{ github.ref_name }}
     runs-on: ubuntu-latest
+    needs: verify
     steps:
       - uses: actions/checkout@v4
 
@@ -36,13 +63,11 @@ jobs:
     name: Publish to PyPI
     runs-on: ubuntu-latest
     needs: build
-    # Trusted publishing — requires the PyPI project to opt into
-    # GitHub OIDC publishing under Settings → Publishing.
-    # Until then, leave this job disabled by editing the `if`.
-    if: ${{ false }}
+    # Trusted publishing requires the PyPI `docsgraph` project to trust this
+    # GitHub workflow/environment under Settings → Publishing.
     environment:
       name: pypi
-      url: https://pypi.org/p/cairn
+      url: https://pypi.org/p/docsgraph
     permissions:
       id-token: write
     steps:
@@ -55,10 +80,35 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
+  verify-pypi-install:
+    name: Verify install from PyPI
+    runs-on: ubuntu-latest
+    needs: publish-pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Verify published package from official index
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          for attempt in 1 2 3 4 5; do
+            if python scripts/verify_pypi_install.py --version "$version" --repo . --sync-repo; then
+              exit 0
+            fi
+            echo "PyPI install verification failed on attempt $attempt; retrying..."
+            sleep 30
+          done
+          python scripts/verify_pypi_install.py --version "$version" --repo . --sync-repo
+
   github-release:
     name: Attach artifacts to GitHub release
     runs-on: ubuntu-latest
-    needs: build
+    needs: [build, publish-pypi, verify-pypi-install]
     permissions:
       contents: write
     steps:

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/CHANGELOG.md

@@ -41,6 +41,10 @@ All notable changes to Cairn. Format follows
   freshness; `cairn mcp config` prints MCP snippets for Claude, Cursor, Codex,
   and Goose. `cairn serve --repo <path>` makes generated configs independent
   from the client's working directory.
+- **Agent self-install command.** `docsgraph install` writes the Cairn MCP
+  server config for Codex, Claude, Cursor, or Goose, while
+  `docsgraph install --dry-run` prints the target path and config without
+  touching disk.
 - **Public repo smoke evaluator.** `scripts/eval_repos.py` reproduces the
   uv / MCP Python SDK / FastAPI template repo-document smoke tests used for
   release readiness.
@@ -50,7 +54,10 @@ All notable changes to Cairn. Format follows
 - **Golden documentation standard.** `docs/golden-docs-standard.md` publishes
   the repo-doc shapes Cairn rewards and the tuning policy maintainers must
   follow when mature-repository smoke runs expose quality gaps.
-- **Optional MarkItDown ingestion.** Installing `cairn[markitdown]` lets Cairn
+- **PyPI installation verifier.** `scripts/verify_pypi_install.py` installs a
+  released `docsgraph` wheel from the official Python index into a clean
+  temporary environment and checks both `docsgraph` and `cairn` console scripts.
+- **Optional MarkItDown ingestion.** Installing `docsgraph[markitdown]` lets Cairn
   convert local DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, EPUB, and related files
   to Markdown before indexing them through the canonical Markdown pipeline.
 
@@ -98,6 +105,8 @@ All notable changes to Cairn. Format follows
   Cairn product name while making the installed tool obvious and avoiding the
   unrelated package that already occupies `cairn`.
 - Strict mypy now passes across both `src` and `tests`.
+- The release workflow now runs lint, type checks, tests, build validation, and
+  PyPI Trusted Publishing from the `pypi` GitHub environment on version tags.
 
 ## [0.1.0a2] — 2026-06-11
 

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docsgraph
-Version: 0.1.0a2
+Version: 0.1.0a3
 Summary: Local-first documentation graph for AI agents. CodeGraph for docs, exposed through MCP.
 Project-URL: Homepage, https://github.com/jokeuncle/cairn
 Project-URL: Documentation, https://github.com/jokeuncle/cairn/tree/main/docs
@@ -260,7 +260,7 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/jokeuncle/cairn/actions/workflows/ci.yml/badge.svg)](https://github.com/jokeuncle/cairn/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.1.0a2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.1.0a3-blue.svg)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
 [![MCP](https://img.shields.io/badge/MCP-native-7c3aed.svg)](https://modelcontextprotocol.io/)
 
@@ -282,7 +282,7 @@ The result: better retrieval accuracy, lower token spend, and a practical MCP
 tool layer between your project documentation and every AI coding agent you
 use. Local-first. Vendor-neutral. Designed for open-source repos.
 
-> 🚀 **Alpha — `0.1.0a2`.** Markdown + PDF ingest, all eight MCP tools,
+> 🚀 **Alpha — `0.1.0a3`.** Markdown + PDF ingest, all eight MCP tools,
 > the full structure-aware index (tree + summaries + entities + xrefs +
 > vectors), repo-level `init/sync/status`, repo-scoped MCP with
 > `list_documents`, `search_documents`, `repo_context`, `repo_graph`, and
@@ -352,6 +352,22 @@ Or run it without installing:
 uvx docsgraph --help
 ```
 
+AI agents that can run shell commands can install and wire Cairn into their own
+MCP config. Start with a dry run, then write the config once the target path
+looks right:
+
+```bash
+uvx docsgraph init -y
+uvx docsgraph sync --fake
+uvx docsgraph install --client codex --dry-run --fake
+uvx docsgraph install --client codex --yes --fake
+```
+
+Use `--client claude`, `--client cursor`, or `--client goose` for other MCP
+clients. `docsgraph install` writes the same server config that
+`docsgraph mcp config` prints, with `command = "docsgraph"` and
+`args = ["serve", "--repo", "..."]`.
+
 ### Repository Workflow
 
 Inside any repository:
@@ -442,7 +458,7 @@ Markdown parser. This expands coverage to formats such as DOCX, PPTX, XLSX,
 HTML, CSV, JSON, XML, and EPUB without making the base install heavy:
 
 ```bash
-.venv/bin/pip install -e ".[markitdown]"
+pip install "docsgraph[markitdown]"
 .venv/bin/docsgraph init -y --force --markitdown
 .venv/bin/docsgraph sync --fake
 ```
@@ -657,7 +673,7 @@ choices we adopted, modified, or declined.
 | 4 — v0.4 polish for production | ☐ | DOCX/RTF/EPUB, VSCode extension, security review |
 | v1.0 GA | ☐ | All `PRODUCT.md` §7 success criteria met |
 
-Full plan: [`ROADMAP.md`](ROADMAP.md). Current test suite: **436 passing**,
+Full plan: [`ROADMAP.md`](ROADMAP.md). Current test suite: **440 passing**,
 mypy strict clean, ruff clean.
 
 Maintainer release gate: [`docs/release-checklist.md`](docs/release-checklist.md).

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/README.md

@@ -6,7 +6,7 @@
 
 [![CI](https://github.com/jokeuncle/cairn/actions/workflows/ci.yml/badge.svg)](https://github.com/jokeuncle/cairn/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.1.0a2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.1.0a3-blue.svg)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
 [![MCP](https://img.shields.io/badge/MCP-native-7c3aed.svg)](https://modelcontextprotocol.io/)
 
@@ -28,7 +28,7 @@ The result: better retrieval accuracy, lower token spend, and a practical MCP
 tool layer between your project documentation and every AI coding agent you
 use. Local-first. Vendor-neutral. Designed for open-source repos.
 
-> 🚀 **Alpha — `0.1.0a2`.** Markdown + PDF ingest, all eight MCP tools,
+> 🚀 **Alpha — `0.1.0a3`.** Markdown + PDF ingest, all eight MCP tools,
 > the full structure-aware index (tree + summaries + entities + xrefs +
 > vectors), repo-level `init/sync/status`, repo-scoped MCP with
 > `list_documents`, `search_documents`, `repo_context`, `repo_graph`, and
@@ -98,6 +98,22 @@ Or run it without installing:
 uvx docsgraph --help
 ```
 
+AI agents that can run shell commands can install and wire Cairn into their own
+MCP config. Start with a dry run, then write the config once the target path
+looks right:
+
+```bash
+uvx docsgraph init -y
+uvx docsgraph sync --fake
+uvx docsgraph install --client codex --dry-run --fake
+uvx docsgraph install --client codex --yes --fake
+```
+
+Use `--client claude`, `--client cursor`, or `--client goose` for other MCP
+clients. `docsgraph install` writes the same server config that
+`docsgraph mcp config` prints, with `command = "docsgraph"` and
+`args = ["serve", "--repo", "..."]`.
+
 ### Repository Workflow
 
 Inside any repository:
@@ -188,7 +204,7 @@ Markdown parser. This expands coverage to formats such as DOCX, PPTX, XLSX,
 HTML, CSV, JSON, XML, and EPUB without making the base install heavy:
 
 ```bash
-.venv/bin/pip install -e ".[markitdown]"
+pip install "docsgraph[markitdown]"
 .venv/bin/docsgraph init -y --force --markitdown
 .venv/bin/docsgraph sync --fake
 ```
@@ -403,7 +419,7 @@ choices we adopted, modified, or declined.
 | 4 — v0.4 polish for production | ☐ | DOCX/RTF/EPUB, VSCode extension, security review |
 | v1.0 GA | ☐ | All `PRODUCT.md` §7 success criteria met |
 
-Full plan: [`ROADMAP.md`](ROADMAP.md). Current test suite: **436 passing**,
+Full plan: [`ROADMAP.md`](ROADMAP.md). Current test suite: **440 passing**,
 mypy strict clean, ruff clean.
 
 Maintainer release gate: [`docs/release-checklist.md`](docs/release-checklist.md).

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/docs/release-checklist.md

@@ -37,20 +37,16 @@ UV_PROJECT_ENVIRONMENT=/tmp/cairn-test-venv-py313 uv run --python 3.13 --extra d
 UV_PROJECT_ENVIRONMENT=/tmp/cairn-test-venv-py313 uv run --python 3.13 --extra dev pytest
 
 rm -rf /tmp/cairn-dist
-UV_PROJECT_ENVIRONMENT=/tmp/cairn-build-venv-py313 \
-  uv run --python 3.13 --with build --with twine \
-  python -m build --outdir /tmp/cairn-dist
-UV_PROJECT_ENVIRONMENT=/tmp/cairn-build-venv-py313 \
-  uv run --python 3.13 --with build --with twine \
-  python -m twine check /tmp/cairn-dist/*
+uv build --out-dir /tmp/cairn-dist
+uv publish --dry-run /tmp/cairn-dist/*
 ```
 
 Expected current gate:
 
 - `ruff check .`: pass
 - `mypy src tests`: pass
-- `pytest`: 436 passing
-- `twine check`: wheel and sdist pass
+- `pytest`: 440 passing
+- `uv publish --dry-run`: wheel and sdist pass upload validation
 
 ## Dogfood Checks
 
@@ -121,6 +117,27 @@ export CAIRN_EMBED_MODEL=doubao-embedding-vision-251215
 The corresponding API key variables must be set locally, but real values must
 never appear in git, shell history snippets, benchmark reports, or CI logs.
 
+## Trusted Publishing
+
+Public PyPI publishing must use GitHub OIDC Trusted Publishing, not a long-lived
+API token in a local shell. Configure PyPI before pushing a release tag:
+
+- Project: `docsgraph`
+- Owner / repository: `jokeuncle/cairn`
+- Workflow: `.github/workflows/release.yml`
+- Environment: `pypi`
+
+In GitHub, create the `pypi` environment and require maintainer approval if the
+repository is not fully locked down. Revoke any account-wide PyPI token used for
+manual bootstrapping after the first project-scoped setup is in place.
+
+After the tag workflow publishes, verify the official source install from a
+clean temporary environment:
+
+```bash
+python scripts/verify_pypi_install.py --version "$(uv run docsgraph version)" --repo . --sync-repo
+```
+
 ## Secret And Generated-File Audit
 
 ```bash
@@ -144,5 +161,5 @@ git push origin main --tags
 ```
 
 The release workflow builds wheel/sdist and attaches them to the GitHub
-release. PyPI publishing is intentionally disabled until trusted publishing is
-configured for the package.
+release. It also publishes to PyPI through Trusted Publishing when the `pypi`
+environment is approved and the PyPI project trusts this workflow.

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "docsgraph"
-version = "0.1.0a2"
+version = "0.1.0a3"
 description = "Local-first documentation graph for AI agents. CodeGraph for docs, exposed through MCP."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -116,6 +116,11 @@ ignore_missing_imports = true
 module = ["markitdown", "markitdown.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["numpy", "numpy.*"]
+follow_imports = "skip"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-ra --strict-markers"

docsgraph-0.1.0a3/scripts/verify_pypi_install.py

@@ -0,0 +1,185 @@
+"""Verify a published docsgraph package from the public Python index."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--version",
+        default=None,
+        help="Version to install. Defaults to the current pyproject version.",
+    )
+    parser.add_argument(
+        "--index-url",
+        default="https://pypi.org/simple",
+        help="Python package index URL to install from.",
+    )
+    parser.add_argument(
+        "--repo",
+        type=Path,
+        default=None,
+        help="Optional initialized repo to smoke-test MCP config against.",
+    )
+    parser.add_argument(
+        "--sync-repo",
+        action="store_true",
+        help="Run docsgraph sync/status/query in --repo after installing.",
+    )
+    args = parser.parse_args()
+
+    root = Path(__file__).resolve().parents[1]
+    version = args.version or _project_version(root / "pyproject.toml")
+    requirement = f"docsgraph=={version}"
+
+    with tempfile.TemporaryDirectory(prefix="docsgraph-pypi-") as tmp:
+        venv = Path(tmp) / "venv"
+        python = _create_venv(venv)
+        _install(python, args.index_url, requirement)
+
+        docsgraph = _script_path(venv, "docsgraph")
+        cairn = _script_path(venv, "cairn")
+        _run([str(docsgraph), "--help"])
+        _run([str(cairn), "--help"])
+        _run([str(docsgraph), "version"], expected=version)
+
+        _run(
+            [
+                str(python),
+                "-c",
+                (
+                    "from importlib.metadata import metadata, version; "
+                    "m=metadata('docsgraph'); "
+                    "print(m['Name']); print(version('docsgraph'))"
+                ),
+            ],
+            expected=f"docsgraph\n{version}",
+        )
+
+        if args.repo is not None:
+            repo = args.repo.resolve()
+            _run(
+                [
+                    str(docsgraph),
+                    "mcp",
+                    "config",
+                    "--client",
+                    "codex",
+                    "--repo",
+                    str(repo),
+                    "--fake",
+                ],
+                cwd=repo,
+                expected='command = "docsgraph"',
+            )
+            if args.sync_repo:
+                _run([str(docsgraph), "sync", "--fake"], cwd=repo)
+                _run([str(docsgraph), "status"], cwd=repo, expected="documents:")
+                _run(
+                    [
+                        str(docsgraph),
+                        "query",
+                        "repo",
+                        "what is this project?",
+                        "--fake",
+                    ],
+                    cwd=repo,
+                    expected='"hits"',
+                )
+
+    print(f"verified {requirement} from {args.index_url}")
+    return 0
+
+
+def _project_version(pyproject: Path) -> str:
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    return str(data["project"]["version"])
+
+
+def _create_venv(venv: Path) -> Path:
+    uv = shutil.which("uv")
+    if uv:
+        _run([uv, "venv", str(venv)])
+        return _venv_python(venv)
+
+    _run([sys.executable, "-m", "venv", str(venv)])
+    python = _venv_python(venv)
+    _run([str(python), "-m", "ensurepip", "--upgrade"])
+    return python
+
+
+def _install(python: Path, index_url: str, requirement: str) -> None:
+    uv = shutil.which("uv")
+    if uv:
+        _run(
+            [
+                uv,
+                "pip",
+                "install",
+                "--python",
+                str(python),
+                "--index-url",
+                index_url,
+                requirement,
+            ]
+        )
+        return
+    _run(
+        [
+            str(python),
+            "-m",
+            "pip",
+            "install",
+            "--index-url",
+            index_url,
+            requirement,
+        ]
+    )
+
+
+def _venv_python(venv: Path) -> Path:
+    if sys.platform == "win32":
+        return venv / "Scripts" / "python.exe"
+    return venv / "bin" / "python"
+
+
+def _script_path(venv: Path, name: str) -> Path:
+    suffix = ".exe" if sys.platform == "win32" else ""
+    directory = "Scripts" if sys.platform == "win32" else "bin"
+    return venv / directory / f"{name}{suffix}"
+
+
+def _run(
+    cmd: list[str],
+    *,
+    cwd: Path | None = None,
+    expected: str | None = None,
+) -> str:
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(result.stdout, file=sys.stderr)
+        raise SystemExit(result.returncode)
+    if expected is not None and expected not in result.stdout:
+        print(result.stdout, file=sys.stderr)
+        msg = f"expected output to contain: {expected!r}"
+        raise SystemExit(msg)
+    return result.stdout
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{docsgraph-0.1.0a2 → docsgraph-0.1.0a3}/src/cairn/__init__.py

@@ -1,5 +1,5 @@
 """Cairn — structure-aware, MCP-native retrieval for large documents."""
 
-__version__ = "0.1.0a2"
+__version__ = "0.1.0a3"
 
 __all__ = ["__version__"]