docsgraph 0.1.0a2__tar.gz → 0.1.0a4__tar.gz

docsgraph-0.1.0a4/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

docsgraph-0.1.0a4/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+custom:
+  - https://jokeuncle.github.io/cairn/#support

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -12,8 +12,8 @@ body:
     id: version
     attributes:
       label: Cairn version
-      description: Output of `cairn version` (or your installed package version).
-      placeholder: "0.1.0a1"
+      description: Output of `docsgraph version` (or your installed package version).
+      placeholder: "0.1.0a3"
     validations:
       required: true
 
@@ -53,7 +53,7 @@ body:
     id: actual
     attributes:
       label: Actual behavior
-      description: Include any error output. If `cairn serve` is involved, the JSON-line log is very helpful.
+      description: Include any error output. If `docsgraph serve` is involved, the JSON-line log is very helpful.
       render: shell
     validations:
       required: true

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Usage questions and support
+    url: https://github.com/jokeuncle/cairn/blob/main/SUPPORT.md
+    about: Read the support policy before opening a usage question.
   - name: Security disclosure
     url: https://github.com/jokeuncle/cairn/blob/main/SECURITY.md
     about: Report a security issue privately — please do not open a public issue.

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/.github/PULL_REQUEST_TEMPLATE.md

@@ -31,9 +31,9 @@
 -->
 
 ```
-ruff check src tests
-mypy src/cairn
-pytest tests/unit -q
+ruff check .
+mypy src tests
+pytest
 ```
 
 - [ ] Unit tests added / updated

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

@@ -21,10 +21,10 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -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
@@ -48,10 +48,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: lint-types-tests
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -65,7 +65,7 @@ jobs:
         run: python -m twine check dist/*
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: cairn-dist
           path: dist/*

docsgraph-0.1.0a4/.github/workflows/pages.yml

@@ -0,0 +1,43 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_run:
+    workflows: ["Release"]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Deploy static site
+    runs-on: ubuntu-latest
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

docsgraph-0.1.0a4/.github/workflows/prepare-release.yml

@@ -0,0 +1,52 @@
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version without leading v, e.g. 0.1.0a4"
+        required: true
+        type: string
+      date:
+        description: "Release date in YYYY-MM-DD format. Defaults to the runner UTC date."
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  prepare:
+    name: Update release metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: main
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Prepare changelog and version metadata
+        run: |
+          args=("${{ inputs.version }}")
+          if [ -n "${{ inputs.date }}" ]; then
+            args+=("--date" "${{ inputs.date }}")
+          fi
+          python scripts/prepare_release.py "${args[@]}"
+          python scripts/prepare_release.py "${{ inputs.version }}" --check
+          git diff --check
+
+      - name: Commit release metadata
+        run: |
+          if git diff --quiet; then
+            echo "No release metadata changes to commit."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml src/cairn/__init__.py README.md CHANGELOG.md docs/release-checklist.md docs/retrieval-architecture-canvas.html
+          git commit -m "Prepare release ${{ inputs.version }}"
+          git push origin HEAD:main

docsgraph-0.1.0a4/.github/workflows/release.yml

@@ -0,0 +1,130 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  verify:
+    name: lint + types + tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        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: Validate release metadata
+        run: python scripts/prepare_release.py "${GITHUB_REF_NAME#v}" --check
+
+      - 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@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build distributions
+        run: python -m build --wheel --sdist
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    # Trusted publishing requires the PyPI `docsgraph` project to trust this
+    # GitHub workflow/environment under Settings → Publishing.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/docsgraph
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - 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@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        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, publish-pypi, verify-pypi-install]
+    permissions:
+      contents: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') || contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/.github/workflows/repo-regression.yml

@@ -16,10 +16,10 @@ jobs:
     timeout-minutes: 60
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: pip

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/ARCHITECTURE.md

@@ -302,20 +302,20 @@ configured primary when omitted.
 
 ### Layer 5: Tooling (CLI / inspector / extensions)
 
-CLI (`cairn`, typer-based):
+CLI (`docsgraph`, typer-based; `cairn` remains a compatibility alias):
 
 ```
-cairn init                  # scaffold a .cairn/ in cwd
-cairn index <path>          # index a document
-cairn serve [--http]        # start MCP server
-cairn inspect <doc-id>      # print index stats
-cairn outline <doc-id>      # print tree
-cairn query <doc-id> ...    # exercise tools from terminal
-cairn migrate               # bump index format versions
+docsgraph init                  # scaffold a .cairn/ in cwd
+docsgraph index <path>          # index a document
+docsgraph serve [--http]        # start MCP server
+docsgraph inspect <doc-id>      # print index stats
+docsgraph outline <doc-id>      # print tree
+docsgraph query <doc-id> ...    # exercise tools from terminal
+docsgraph migrate               # bump index format versions
 ```
 
 Future (v0.3+):
-- `cairn web` — local inspector UI (read-only).
+- `docsgraph web` — local inspector UI (read-only).
 - VSCode extension surfacing the same inspector.
 
 ---

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

@@ -6,12 +6,39 @@ All notable changes to Cairn. Format follows
 
 ## Unreleased
 
+No unreleased changes yet.
+
+## [0.1.0a4] — 2026-06-23
+
+### Added
+
+- Product website under `docs/index.html`, deployed to GitHub Pages on `main`
+  pushes and after successful release workflows.
+
+### Changed
+
+- Repo-scoped MCP config now defaults to dynamic workspace resolution
+  (`args = ["serve"]`) instead of pinning the repo where `docsgraph install` ran.
+  Use `--repo` for a fixed-repo server, or per-call `projectPath` for explicit
+  cross-repo queries.
+- PyPI project metadata and README now point the project homepage to the
+  GitHub Pages site.
+- GitHub Actions workflows now use current major versions to avoid deprecated
+  Node runtime warnings.
+- First-run website and contributor docs now prefer the `docsgraph` command and
+  deterministic `--fake` smoke-test path.
+- Added support and editor-configuration metadata for contributor onboarding.
+- Added a GitHub Sponsor entry plus website and support-page links for optional
+  project sponsorship.
+
+## [0.1.0a3] — 2026-06-22
+
 ### Added
 
 - **Doubao multimodal embeddings.** `CAIRN_EMBED_PROVIDER=doubao-vision`
   targets Volcengine ARK's `/embeddings/multimodal` shape and defaults to
   `doubao-embedding-vision-251215` with 2048-dimensional vectors.
-- **Static graph inspector.** `cairn inspect <doc-dir> --out inspector.html`
+- **Static graph inspector.** `docsgraph inspect <doc-dir> --out inspector.html`
   writes a standalone HTML relationship explorer for sections, entities,
   tree edges, mentions, and cross-references.
 - **Semantic hit evidence.** `search_semantic` now returns an explanatory
@@ -22,8 +49,9 @@ All notable changes to Cairn. Format follows
 - **Benchmark/index progress output.** CLI indexing and benchmark runs now
   emit stage progress so hosted-model runs do not sit silently during long
   summary-generation phases.
-- **Repository documentation workflow.** `cairn init -y`, `cairn sync`,
-  `cairn status`, repo-scoped `cairn serve`, and repo-scoped `cairn inspect`
+- **Repository documentation workflow.** `docsgraph init -y`, `docsgraph sync`,
+  `docsgraph status`, repo-scoped `docsgraph serve`, and repo-scoped
+  `docsgraph inspect`
   turn a project directory into a multi-document MCP knowledge layer. Repo MCP
   adds `list_documents`, cross-document `search_documents`, `repo_context`,
   `repo_graph`, `repo_impact`, and routes normal tools by optional `doc`.
@@ -37,10 +65,14 @@ All notable changes to Cairn. Format follows
   `node_modules/**`, `dist/**`, and `.pytest_cache/**` now apply at any depth,
   so broad include globs do not accidentally index frontend dependencies,
   caches, or generated build output.
-- **Open-source DX commands.** `cairn doctor` validates repo setup and index
-  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.
+- **Open-source DX commands.** `docsgraph doctor` validates repo setup and index
+  freshness; `docsgraph mcp config` prints MCP snippets for Claude, Cursor,
+  Codex, and Goose. `docsgraph 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 +82,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 +133,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
 
@@ -206,8 +243,8 @@ naive vector-RAG baseline.
 - `PRODUCT.md`, `ARCHITECTURE.md`, `CLAUDE.md`, `ROADMAP.md`,
   `CONTRIBUTING.md`, `LICENSE` (Apache-2.0).
 - `docs/specs/mcp-tools.md`: authoritative tool schemas.
-- `docs/canvas.html`: single-file visual explainer comparing Naive RAG,
-  RAPTOR, BookRAG, A-RAG, and Cairn.
+- `docs/retrieval-architecture-canvas.html`: single-file visual explainer
+  comparing Naive RAG, RAPTOR, BookRAG, A-RAG, and Cairn.
 - `docs/decisions/0001-foundation.md`: founding ADR.
 - `examples/hero-demo.md`: self-referential reproducible demo (Cairn
   navigates its own architecture document).

{docsgraph-0.1.0a2 → docsgraph-0.1.0a4}/CONTRIBUTING.md

@@ -139,10 +139,10 @@ A good test:
 
 Please file an issue with:
 
-- Cairn version (`cairn --version`) and Python version.
+- Cairn version (`docsgraph version`) and Python version.
 - A minimal reproducer (ideally a small document and a command).
 - Expected vs. actual behavior.
-- Any error log lines (JSON-lines from `cairn serve` are very helpful).
+- Any error log lines (JSON-lines from `docsgraph serve` are very helpful).
 
 ---
 

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

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: docsgraph
-Version: 0.1.0a2
+Version: 0.1.0a4
 Summary: Local-first documentation graph for AI agents. CodeGraph for docs, exposed through MCP.
-Project-URL: Homepage, https://github.com/jokeuncle/cairn
+Project-URL: Homepage, https://jokeuncle.github.io/cairn/
 Project-URL: Documentation, https://github.com/jokeuncle/cairn/tree/main/docs
 Project-URL: Repository, https://github.com/jokeuncle/cairn
 Project-URL: Issues, https://github.com/jokeuncle/cairn/issues
@@ -260,11 +260,12 @@ 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)
+[![PyPI](https://img.shields.io/pypi/v/docsgraph?include_prereleases&label=PyPI)](https://pypi.org/project/docsgraph/)
+[![Website](https://img.shields.io/badge/website-cairn-48c7ba.svg)](https://jokeuncle.github.io/cairn/)
 [![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/)
 
-![Cairn demo: repository documentation graph and MCP tools](docs/assets/cairn-demo.svg)
+![Cairn demo: repository documentation graph and MCP tools](docs/assets/docsgraph-repo-demo.svg)
 
 Cairn is a **local-first, MCP-native DocsGraph** for software
 repositories and large structured documents. It turns README files, specs,
@@ -282,9 +283,9 @@ 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.0a4`.** Markdown + PDF ingest, the core MCP tool set,
 > the full structure-aware index (tree + summaries + entities + xrefs +
-> vectors), repo-level `init/sync/status`, repo-scoped MCP with
+> vectors), repo-level `init/sync/status`, repo-scoped MCP tools with
 > `list_documents`, `search_documents`, `repo_context`, `repo_graph`, and
 > `repo_impact`, failure-isolated sync, static graph inspector, Doubao
 > multimodal embeddings, and a benchmark harness with headline numbers. See
@@ -308,6 +309,7 @@ For the in-depth motivation, see [`PRODUCT.md`](PRODUCT.md).
 For the technical design, see [`ARCHITECTURE.md`](ARCHITECTURE.md).
 For the public documentation quality contract Cairn optimizes for, see
 [`docs/golden-docs-standard.md`](docs/golden-docs-standard.md).
+The product website is published at <https://jokeuncle.github.io/cairn/>.
 
 ---
 
@@ -329,7 +331,11 @@ For the public documentation quality contract Cairn optimizes for, see
    result carries stable anchors for verification.
 
 A visual explainer comparing Cairn's approach to RAPTOR, BookRAG, and A-RAG
-lives at [`docs/canvas.html`](docs/canvas.html). Open it in any browser.
+lives at
+[`docs/retrieval-architecture-canvas.html`](docs/retrieval-architecture-canvas.html).
+The repository workflow map lives at
+[`docs/repo-docs-workflow-canvas.html`](docs/repo-docs-workflow-canvas.html).
+Open either file in any browser.
 
 ---
 
@@ -352,6 +358,25 @@ 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"]`. The server resolves the current MCP workspace at call time,
+so a global agent config does not stay pinned to the repo where it was installed.
+Pass `--repo /path/to/repo` to `docsgraph install` or `docsgraph mcp config`
+only when you intentionally want a fixed-repo MCP server.
+
 ### Repository Workflow
 
 Inside any repository:
@@ -442,7 +467,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,11 +682,13 @@ 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**,
-mypy strict clean, ruff clean.
+Full plan: [`ROADMAP.md`](ROADMAP.md). CI runs ruff, strict mypy, pytest, and
+package build checks across Python 3.11, 3.12, and 3.13.
 
 Maintainer release gate: [`docs/release-checklist.md`](docs/release-checklist.md).
 
+Support and sponsorship options live in [`SUPPORT.md`](SUPPORT.md).
+
 ---
 
 ## Contributing