release: v0.1.1 — CI fix, AGENTS.md/CLAUDE.md, update-check, PyPI publish

Hardens v0.1.0 with four scope additions ahead of the SoftChat rip-out
(Plan 80.6-14):

1. CI fix: test_cli_smoke subprocess pins NO_COLOR=1, TERM=dumb,
   COLUMNS=200, pops FORCE_COLOR — eliminates Rich color-escape pollution
   that broke help-text assertions on GH Actions runners.

2. AGENTS.md + CLAUDE.md added per the Apr 2026 cross-tool convention.
   Concise, dense imperative bullets; CLAUDE.md delegates to AGENTS.md.

3. update_check module: pip-style fire-and-forget GitHub Releases probe.
   Daemon thread writes platformdirs.user_cache_dir/update_check.json;
   next invocation prints stderr footer if newer release cached. 24h TTL,
   6h backoff on 403/429, ETag-aware. Suppress with SUPAMEM_NO_UPDATE_CHECK,
   NO_UPDATE_NOTIFIER, or CI. Skipped when stderr is non-TTY. Surfaced in
   supamem doctor.

4. Release pipeline: split into build / publish-pypi / github-release jobs.
   PyPI publishing via Trusted Publisher OIDC (environment: pypi,
   id-token: write); first publish auto-converts the pending publisher
   registered at pypi.org. License metadata migrated to PEP 639 SPDX
   expression. New deps: platformdirs>=4.2, packaging>=23.0.

180/180 tests green; ruff clean; twine check PASSED.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dzmitrys-dev

.github/workflows/release.yml

@@ -5,10 +5,9 @@ on:
     tags: ['v*']
 
 jobs:
-  release:
+  build:
+    name: Build wheel + sdist
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -19,15 +18,56 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install build
-        run: pip install build
+      - name: Install build + twine
+        run: pip install build twine
 
-      - name: Build wheel + sdist
+      - name: Build
         run: python -m build
 
+      - name: Twine check
+        run: twine check dist/*
+
       - name: List artifacts
         run: ls -lh dist/
 
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI (Trusted Publisher OIDC)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/supamem
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
       - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         with:

AGENTS.md

@@ -0,0 +1,116 @@
+# AGENTS.md — supamem
+
+Operational guide for AI coding agents working in this repository. Project-agnostic dual-memory CLI for Claude Code, Cursor, and OpenCode.
+
+## Project Snapshot
+
+- **Language:** Python 3.12+
+- **Build backend:** hatchling
+- **Package manager:** `uv`
+- **CLI entry:** `supamem` → `src/supamem/cli.py:main`
+- **Tests:** `pytest` (config in `pyproject.toml`)
+- **Lint/format:** `ruff` (line length 100, target py312)
+- **External deps:** Qdrant 1.10+ (HTTP), MCP 1.13+, fastembed, langchain-text-splitters
+
+## Architecture
+
+```
+src/supamem/
+├── cli.py              # Typer-based CLI dispatcher
+├── console.py          # Shared Rich console + theme (single source of branding)
+├── config.py           # Pydantic config schema (D-38)
+├── config_io.py        # Discovery: project → user → defaults; merge order locked
+├── doctor.py           # Health + drift report (Plan 80.6-11)
+├── init.py             # Greenfield bootstrap (Plan 80.6-08)
+├── migrate.py          # Brownfield migration paths (Plan 80.6-09)
+├── mcp_server.py       # MCP server entrypoint
+├── embedders/          # minilm, bm25 — pluggable via entry-points
+├── indexer/            # chunker (markdown_header), manifest
+├── retrieval/          # tuned_hybrid, dense, bm25 backends
+├── eval/               # Bench runner + bundled goldens (Plan 80.6-12)
+├── hooks/              # claude_code, cursor — per-client snapshot hooks
+├── install/            # claude_code, cursor, opencode — config installers
+├── share/              # Canonical artifact templates
+└── stats/              # Welford counter for usage telemetry
+```
+
+## Plugin Entry Points (D-48)
+
+Three plugin groups in `pyproject.toml`. Third parties add backends without forking:
+
+- `supamem.retrieval` — `tuned_hybrid`, `dense`, `bm25`
+- `supamem.embedder` — `minilm`, `bm25`
+- `supamem.chunker` — `markdown_header`
+
+## Config Discovery (D-38)
+
+Order: `./.supamem/config.toml` (project) → `~/.config/supamem/config.toml` (user) → `share/default.toml` (shipped). Merge is shallow; project wins.
+
+## Hard Constraints
+
+- NEVER bypass failing tests — fix root cause
+- NEVER hardcode collection names; always read from `config.collection`
+- NEVER print to stdout in MCP server — JSON-RPC contract requires stdio purity (use `err_console`)
+- NEVER write to `~/` outside `~/.cache/supamem/` and `~/.config/supamem/` without explicit user opt-in
+- NEVER delete a Qdrant collection without `--force` flag confirmation
+- ALWAYS use `console.py` exports for terminal output (no bare `print()`)
+- ALWAYS run `pytest` from project root via `uv run pytest`
+
+## Workflow
+
+```bash
+# Setup
+uv sync --extra dev
+
+# Tests
+uv run pytest                      # full suite
+uv run pytest tests/test_X.py -v   # single file
+
+# Lint / type
+uv run ruff check src tests
+uv run ruff format src tests
+
+# Build + verify
+uv build
+uvx twine check dist/*
+
+# Run locally
+uv run supamem --help
+uv run python -m supamem doctor
+```
+
+## Test Discipline
+
+- Subprocess-based CLI smoke tests (`test_cli_smoke.py`) MUST pin a deterministic env: `NO_COLOR=1`, `TERM=dumb`, `COLUMNS=200` — pop `FORCE_COLOR`. Rich autodetect alone is insufficient on CI runners.
+- Use `pytest-asyncio` with `mode=Mode.STRICT`; mark async tests with `@pytest.mark.asyncio`.
+- Mock Qdrant via fixtures, not by hitting a live instance — bench/eval suites are the integration boundary.
+
+## Release Process
+
+1. Bump `version` in `pyproject.toml` and add `CHANGELOG.md` entry.
+2. Verify license metadata complies with PEP 639 (`license = "MIT"` SPDX, no `License ::` classifier).
+3. `uv build && uvx twine check dist/*`
+4. Create annotated tag: `git tag -a vX.Y.Z -m "..."`
+5. Push tag: `git push origin vX.Y.Z` — release workflow publishes to PyPI via Trusted Publisher OIDC.
+6. Verify on PyPI: `pip install supamem==X.Y.Z` in a clean venv.
+
+PyPI tags are immutable: never re-use a published version number.
+
+## Update-check (v0.1.1+)
+
+A daemon thread probes GitHub Releases on every CLI invocation, caches result for 24h in `platformdirs.user_cache_dir("supamem")/update_check.json`, and prints a stderr footer on the *next* invocation if a newer version is available. Suppress with `SUPAMEM_NO_UPDATE_CHECK=1`, `CI=1`, or `NO_UPDATE_NOTIFIER=1`. Never blocks; never raises.
+
+## Reference Links
+
+- README: high-level overview, install, quickstart
+- MIGRATION.md: version-to-version upgrade notes
+- CHANGELOG.md: release log
+- `docs/` (if present): ADRs, design docs
+
+## Decision Guides
+
+- New backend: register via entry-point group, do NOT modify `cli.py` dispatch
+- New CLI subcommand: add Typer command in `cli.py`, route to module under `src/supamem/`
+- New config field: extend `config.py` Pydantic schema + bump default in `share/default.toml`
+- New hook target: add module under `src/supamem/hooks/<client>.py`, register in `cli.py hook` dispatcher
+- Failure in network code: blanket `except Exception: pass` is correct for non-essential probes (update_check); for indexing/retrieval, surface error to user via `err_console`

CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to `supamem` will be documented in this file.
 
+## v0.1.1 — 2026-04-29
+
+First PyPI release. Hardens v0.1.0 with CI fixes, agent guides, an update-check
+notifier, and a published wheel/sdist on PyPI so downstream consumers can pin a
+version range instead of a git tag.
+
+### Added
+
+- `supamem.update_check` — pip-style fire-and-forget GitHub Releases probe.
+  Daemon thread writes `platformdirs.user_cache_dir("supamem")/update_check.json`;
+  the *next* invocation prints a stderr footer if a newer release is cached.
+  24h TTL, 6h backoff on 403/429, ETag-aware. Suppress with
+  `SUPAMEM_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, or `CI=1`. Skipped when
+  stderr is non-TTY. Surfaced in `supamem doctor` (new "Update check" section).
+- `AGENTS.md` + `CLAUDE.md` — agent-facing project guides per the Apr 2026
+  cross-tool convention.
+
+### Changed
+
+- License metadata migrated to PEP 639 SPDX expression (`license = "MIT"`),
+  removing legacy `{ text = "MIT" }` form.
+- Distribution channel: PyPI (was git-tag-only). Install via
+  `pip install supamem` or `uv tool install supamem`.
+
+### Fixed
+
+- `tests/test_cli_smoke.py` subprocess env now pins `NO_COLOR=1`, `TERM=dumb`,
+  `COLUMNS=200`, and pops `FORCE_COLOR` — eliminates Rich color escapes that
+  broke CI assertions on GitHub Actions runners.
+
 ## v0.1.0 — 2026-04-29
 
 The initial public release. Extracted from the SoftChat dual-memory stack

CLAUDE.md

@@ -0,0 +1,43 @@
+# CLAUDE.md — supamem
+
+Claude Code instructions for the supamem repository.
+
+@AGENTS.md
+
+## Workflow
+
+- Use `/brainstorm` before ambiguous feature work
+- Use `/write-plan` before multi-step implementation
+- Use `/systematic-debug` before proposing bug fixes
+- Verify with `uv run pytest` (project root) and `uv run ruff check src tests` before claiming done
+
+## Hard Constraints
+
+- NEVER use bare `print()` — import from `src/supamem/console.py`
+- NEVER print to stdout from `mcp_server.py` — JSON-RPC purity (use `err_console`)
+- NEVER hardcode collection names — read `config.collection`
+- NEVER skip the PEP 639 license check on release — `license = "MIT"` SPDX, no `License ::` classifier
+- NEVER force-move a published git tag — PyPI rejects re-uploads of the same version
+- NEVER suppress errors in indexing/retrieval paths — surface via `err_console`
+- Update-check is the ONLY code path where blanket `except Exception: pass` is acceptable
+
+## Definition Of Done
+
+- `uv run pytest` green (full suite)
+- `uv run ruff check src tests` clean
+- New CLI subcommand: smoke test in `tests/test_cli_smoke.py`
+- New backend: registered via entry-point, covered by unit + integration test
+- Release: `uv build && uvx twine check dist/*` clean before tagging
+
+## Critical Config
+
+- Config discovery order: `.supamem/config.toml` → `~/.config/supamem/config.toml` → `share/default.toml`
+- Cache dir: `platformdirs.user_cache_dir("supamem")` — never `~/.cache/supamem` directly
+- CI env: smoke tests pin `NO_COLOR=1`, `TERM=dumb`, `COLUMNS=200`, pop `FORCE_COLOR`
+
+## When Blocked
+
+- Test fails on CI but passes locally: check Rich color escape pollution (see test_cli_smoke env override)
+- Import error: confirm `uv sync --extra dev` ran; check entry-points in `pyproject.toml`
+- Qdrant connection failure: `docker compose up qdrant` or use mock fixture
+- 2+ verification failures: stop and report blocker with command output

pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supamem"
-version = "0.1.0"
+version = "0.1.1"
 description = "Project-agnostic dual-memory tooling for Claude Code, Cursor, and opencode"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
 requires-python = ">=3.12"
 authors = [{ name = "dzmitrys-dev" }]
 dependencies = [
@@ -19,6 +19,8 @@ dependencies = [
   "pydantic>=2.5",
   "tomli-w>=1.0",
   "langchain-text-splitters>=0.3",
+  "platformdirs>=4.2",
+  "packaging>=23.0",
 ]
 
 [project.urls]

src/supamem/__init__.py

@@ -1,2 +1,2 @@
 """supamem — project-agnostic dual-memory tooling."""
-__version__ = "0.1.0"
+__version__ = "0.1.1"

src/supamem/cli.py

@@ -244,7 +244,23 @@ def cmd_migrate(
 
 
 def main() -> None:
-    app()
+    # Fire-and-forget update probe — writes cache for *next* invocation. Skipped
+    # when env vars opt out, when stderr is non-TTY (piped/redirected output),
+    # or when the in-process probe fails for any reason. Never blocks.
+    from supamem.update_check import get_pending_notification, start_background_check
+
+    start_background_check(__version__)
+    try:
+        app()
+    finally:
+        # Print any update notice queued from the *previous* invocation. Goes
+        # to stderr so JSON consumers piping stdout are unaffected.
+        notice = get_pending_notification(__version__)
+        if notice:
+            try:
+                err_console.print(notice, end="")
+            except Exception:
+                pass
 
 
 if __name__ == "__main__":

src/supamem/doctor.py

@@ -17,6 +17,7 @@
 
 import logging
 import re
+import time
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any
@@ -160,7 +161,32 @@ def run_doctor(*, redact_secrets: bool = True) -> int:
         else:
             ok(f"{row['client']:<12} v{row['block_version']} (current)")
 
-    # ── Section 4: Exit code ─────────────────────────────────────────────
+    # ── Section 4: Update check ──────────────────────────────────────────
+    console.print()
+    console.print("[supamem.brand]Update check[/supamem.brand]")
+    from supamem.update_check import doctor_report
+
+    uc = doctor_report(__version__)
+    cached = uc.get("cached_latest_version")
+    last_ts = uc.get("last_check_ts")
+    last_human = (
+        time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime(last_ts))
+        if last_ts
+        else "never"
+    )
+    if uc.get("update_available"):
+        warn(
+            f"update available: {uc['current_version']} → {cached} "
+            f"(last check: {last_human})"
+        )
+    elif cached:
+        ok(f"on latest cached version v{cached} (last check: {last_human})")
+    else:
+        info(f"no probe yet — runs in background on next invocation (cache: {uc['cache_path']})")
+    if uc.get("suppressed_by_env"):
+        info(f"suppressed by env: {', '.join(uc['suppressed_by_env'])}")
+
+    # ── Section 5: Exit code ─────────────────────────────────────────────
     rc = 0
     if not qdrant_up or any_drift or (qdrant_up and not coll_status.get("present")):
         rc = 1