google_workspace_fastmcp2: Instructions file for Claude Code

CLAUDE.md

Release / deployment pattern

• A release is a version bump merged to main. .github/workflows/publish.yml runs on every push to main and publishes to PyPI only if version in pyproject.toml differs from the previous commit (HEAD~1). No tags involved.
• Every PR that should ship must bump the version in both places, kept in sync:
  • pyproject.toml → version = "X.Y.Z"
  • uv.lock → the google-workspace-unlimited package entry's version
• Title the release PR / merge commit Release X.Y.Z — <summary> (see git history for examples).
• Semver-ish: patch for fixes, minor for new tools/features or behavior-default changes.
• Downstream consumers: PyPI (uvx google-workspace-unlimited) and Glama's Docker build (clones this repo and runs uv sync). The wheel must include all runtime packages — check [tool.hatch.build.targets.wheel] when adding a new top-level package dir (a missing lifespans/ broke 2.4.x on PyPI).

Glama hosted deploy (admin build spec)

• cmdArguments must use uv run --no-sync — plain uv run rebuilds the package on every container start (~33s), blowing Glama's ~35s health-check timeout and marking the server "unhealthy" (503s on every request).
• buildSteps: uv sync --compile-bytecode, then uv run --no-sync python -c 'import server' || true to warm imports at build time (~12s cold start, measured).
• Set QDRANT_AUTO_LAUNCH=false in hosted env vars (default true tries to launch Qdrant via Docker, which doesn't exist in the container).

Learned model artifacts

• Checkpoints ship via MODEL_ARTIFACT_URI (JSON map {"gchat": gs://…, "email": gs://…}); servers download them at startup into credentials/model_cache/<domain>/.
• A cached artifact is never re-checked against the bucket — the checksum only compares the local file with its own registry entry. After re-publishing, delete credentials/model_cache/<domain>/best_model_unified.pt (or the deployment's MODEL_ARTIFACT_CACHE_DIR copy) on any host that already has it; fresh containers pick it up automatically.
• Before overwriting a published checkpoint, copy it aside in the bucket (e.g. best_model_unified.pre-<change>-<date>.pt).
• Offline/local runs: point slot assignment at a file with UNIFIED_TRN_CHECKPOINT_<DOMAIN>=… (artifact paths take precedence when present).
• The email checkpoint carries placement_head (learned item→block placement); build it with research/trm/email/build_placement_head.py (research is gitignored and never imported by production).