contextkeeper 0.2.0__tar.gz

contextkeeper-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+
+packages/npm/node_modules/
+packages/npm/package-lock.json
+packages/python/dist/

contextkeeper-0.2.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: contextkeeper
+Version: 0.2.0
+Summary: Zero model drift between AI agents. Universal session continuity protocol and CLI for Claude, GPT, Gemini, and any LLM.
+Project-URL: Homepage, https://github.com/TheRealDataBoss/workbench
+Project-URL: Repository, https://github.com/TheRealDataBoss/workbench
+Project-URL: Issues, https://github.com/TheRealDataBoss/workbench/issues
+Author: TheRealDataBoss
+License-Expression: MIT
+Keywords: ai,chatgpt,claude,cli,context,continuity,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# contextkeeper
+
+Zero model drift between AI agents. Universal session continuity protocol and CLI for Claude, GPT, Gemini, and any LLM.
+
+## Install
+
+```sh
+pip install contextkeeper
+```
+
+## Commands
+
+### `contextkeeper init`
+Initialize contextkeeper state files in the current project. Auto-detects project type, generates STATE_VECTOR.json and HANDOFF.md, and creates a `.workbench` config file.
+
+```sh
+cd my-project
+contextkeeper init
+```
+
+Options:
+- `-p, --project` — Project slug (default: directory name)
+- `-t, --type` — Project type override
+- `--bridge` — Bridge repo (e.g. `yourname/workbench`)
+
+### `contextkeeper sync`
+Sync state files to your bridge repo.
+
+```sh
+contextkeeper sync
+```
+
+Options:
+- `--bridge` — Bridge repo override
+- `--dry-run` — Preview without pushing
+
+### `contextkeeper status`
+Show status of all projects in the bridge repo.
+
+```sh
+contextkeeper status --bridge yourname/workbench
+```
+
+Options:
+- `--bridge` — Bridge repo
+- `--json` — Output as JSON
+
+### `contextkeeper bootstrap`
+Generate a paste-ready bootstrap prompt for any AI chat.
+
+```sh
+contextkeeper bootstrap -p my-project --clipboard
+```
+
+Options:
+- `-p, --project` — Project slug (required)
+- `--bridge` — Bridge repo override
+- `--clipboard` — Copy to clipboard
+
+### `contextkeeper doctor`
+Check environment and configuration health.
+
+```sh
+contextkeeper doctor
+```
+
+## How It Works
+
+1. `contextkeeper init` creates structured state files in your project
+2. `contextkeeper sync` pushes them to a central bridge repo on GitHub
+3. `contextkeeper bootstrap` generates a prompt you paste into any AI chat
+4. The AI reads your state files and has full context in under 60 seconds
+
+## Requirements
+
+- Python 3.10+
+- git
+
+## License
+
+MIT

contextkeeper-0.2.0/README.md

@@ -0,0 +1,81 @@
+# contextkeeper
+
+Zero model drift between AI agents. Universal session continuity protocol and CLI for Claude, GPT, Gemini, and any LLM.
+
+## Install
+
+```sh
+pip install contextkeeper
+```
+
+## Commands
+
+### `contextkeeper init`
+Initialize contextkeeper state files in the current project. Auto-detects project type, generates STATE_VECTOR.json and HANDOFF.md, and creates a `.workbench` config file.
+
+```sh
+cd my-project
+contextkeeper init
+```
+
+Options:
+- `-p, --project` — Project slug (default: directory name)
+- `-t, --type` — Project type override
+- `--bridge` — Bridge repo (e.g. `yourname/workbench`)
+
+### `contextkeeper sync`
+Sync state files to your bridge repo.
+
+```sh
+contextkeeper sync
+```
+
+Options:
+- `--bridge` — Bridge repo override
+- `--dry-run` — Preview without pushing
+
+### `contextkeeper status`
+Show status of all projects in the bridge repo.
+
+```sh
+contextkeeper status --bridge yourname/workbench
+```
+
+Options:
+- `--bridge` — Bridge repo
+- `--json` — Output as JSON
+
+### `contextkeeper bootstrap`
+Generate a paste-ready bootstrap prompt for any AI chat.
+
+```sh
+contextkeeper bootstrap -p my-project --clipboard
+```
+
+Options:
+- `-p, --project` — Project slug (required)
+- `--bridge` — Bridge repo override
+- `--clipboard` — Copy to clipboard
+
+### `contextkeeper doctor`
+Check environment and configuration health.
+
+```sh
+contextkeeper doctor
+```
+
+## How It Works
+
+1. `contextkeeper init` creates structured state files in your project
+2. `contextkeeper sync` pushes them to a central bridge repo on GitHub
+3. `contextkeeper bootstrap` generates a prompt you paste into any AI chat
+4. The AI reads your state files and has full context in under 60 seconds
+
+## Requirements
+
+- Python 3.10+
+- git
+
+## License
+
+MIT

contextkeeper-0.2.0/contextkeeper/__init__.py

@@ -0,0 +1,3 @@
+"""contextkeeper: Zero model drift between AI agents. Universal session continuity protocol and CLI."""
+
+__version__ = "0.2.0"

contextkeeper-0.2.0/contextkeeper/bootstrap.py

@@ -0,0 +1,112 @@
+"""contextkeeper bootstrap — generate paste-ready AI bootstrap prompt."""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from git import Repo
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+def _load_config(cwd: Path) -> dict | None:
+    config_path = cwd / ".workbench"
+    if not config_path.exists():
+        return None
+    return json.loads(config_path.read_text(encoding="utf-8"))
+
+
+def _copy_to_clipboard(text: str) -> bool:
+    """Attempt to copy text to the system clipboard. Returns True on success."""
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            subprocess.run(["pbcopy"], input=text.encode(), check=True)
+        elif system == "Windows":
+            subprocess.run(["clip"], input=text.encode(), check=True)
+        else:
+            subprocess.run(
+                ["xclip", "-selection", "clipboard"],
+                input=text.encode(),
+                check=True,
+            )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def generate_bootstrap(
+    project: str,
+    bridge: str | None = None,
+    clipboard: bool = False,
+) -> None:
+    """Generate a paste-ready bootstrap prompt for any AI chat."""
+    cwd = Path.cwd()
+    config = _load_config(cwd)
+    bridge_repo = bridge or (config and config.get("bridge_repo"))
+
+    console.print("\n  [cyan]contextkeeper bootstrap[/cyan]\n")
+
+    if not bridge_repo:
+        console.print("  [red]No bridge repo configured. Run contextkeeper init or pass --bridge.[/red]")
+        raise SystemExit(1)
+
+    # Verify the project exists
+    tmp_dir = Path(tempfile.mkdtemp(prefix="workbench-"))
+    try:
+        bridge_url = f"https://github.com/{bridge_repo}.git"
+
+        with console.status("Verifying project in bridge repo..."):
+            Repo.clone_from(bridge_url, str(tmp_dir), depth=1)
+
+        project_dir = tmp_dir / "projects" / project
+        if not project_dir.exists():
+            console.print(f'  [red]Project "{project}" not found in bridge repo.[/red]')
+            projects_dir = tmp_dir / "projects"
+            if projects_dir.exists():
+                available = [d.name for d in projects_dir.iterdir() if d.is_dir()]
+                if available:
+                    console.print(f"  [dim]Available: {', '.join(available)}[/dim]")
+            raise SystemExit(1)
+
+        sv_path = project_dir / "STATE_VECTOR.json"
+        if not sv_path.exists():
+            console.print(f"  [red]No STATE_VECTOR.json found for {project}[/red]")
+            raise SystemExit(1)
+
+        console.print(f'  [green]Project "{project}" verified[/green]')
+
+        # Build bootstrap prompt with all URLs explicit
+        base_url = f"https://raw.githubusercontent.com/{bridge_repo}/main"
+        urls = [
+            f"{base_url}/PROFILE.md",
+            f"{base_url}/projects/{project}/HANDOFF.md",
+            f"{base_url}/projects/{project}/STATE_VECTOR.json",
+        ]
+
+        prompt_lines = [
+            f"Fetch these URLs and bootstrap the {project} project:",
+            *urls,
+        ]
+        prompt = "\n".join(prompt_lines)
+
+        console.print("\n  Paste this into any new AI chat:\n")
+        console.print(Panel(prompt, border_style="green", padding=(1, 2)))
+
+        if clipboard:
+            if _copy_to_clipboard(prompt):
+                console.print("  [green]Copied to clipboard![/green]")
+            else:
+                console.print("  [yellow]Could not copy to clipboard. Copy manually from above.[/yellow]")
+
+        console.print()
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)

contextkeeper-0.2.0/contextkeeper/cli.py

@@ -0,0 +1,61 @@
+"""Typer CLI entry point for contextkeeper."""
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="contextkeeper",
+    help="Zero model drift between AI agents. Universal session continuity protocol and CLI for Claude, GPT, Gemini, and any LLM.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def init(
+    project: str = typer.Option(None, "--project", "-p", help="Project slug"),
+    project_type: str = typer.Option(None, "--type", "-t", help="Project type override"),
+    bridge: str = typer.Option(None, "--bridge", help="Bridge repo (e.g. user/workbench)"),
+) -> None:
+    """Initialize contextkeeper state files in the current project."""
+    from contextkeeper.init import init_project
+
+    init_project(project=project, project_type=project_type, bridge=bridge)
+
+
+@app.command()
+def sync(
+    bridge: str = typer.Option(None, "--bridge", help="Bridge repo override"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without pushing"),
+) -> None:
+    """Sync state files to the bridge repo."""
+    from contextkeeper.sync import sync_project
+
+    sync_project(bridge=bridge, dry_run=dry_run)
+
+
+@app.command()
+def status(
+    bridge: str = typer.Option(None, "--bridge", help="Bridge repo"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Show status of all projects in the bridge repo."""
+    from contextkeeper.status import show_status
+
+    show_status(bridge=bridge, json_output=json_output)
+
+
+@app.command()
+def bootstrap(
+    project: str = typer.Option(..., "--project", "-p", help="Project slug"),
+    bridge: str = typer.Option(None, "--bridge", help="Bridge repo override"),
+    clipboard: bool = typer.Option(False, "--clipboard", help="Copy to clipboard"),
+) -> None:
+    """Generate a paste-ready bootstrap prompt for any AI."""
+    from contextkeeper.bootstrap import generate_bootstrap
+
+    generate_bootstrap(project=project, bridge=bridge, clipboard=clipboard)
+
+
+if __name__ == "__main__":
+    app()

contextkeeper-0.2.0/contextkeeper/init.py

@@ -0,0 +1,157 @@
+"""contextkeeper init — initialize state files in the current project."""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+
+import questionary
+from rich.console import Console
+
+console = Console()
+
+PROJECT_TYPE_SIGNALS: list[tuple[str, str, str]] = [
+    ("manage.py", "web_app", "Django web app"),
+    ("next.config.js", "web_app", "Next.js web app"),
+    ("next.config.mjs", "web_app", "Next.js web app"),
+    ("vite.config.ts", "web_app", "Vite web app"),
+    ("vite.config.js", "web_app", "Vite web app"),
+    ("Cargo.toml", "cli_tool", "Rust project"),
+    ("setup.py", "library", "Python library"),
+    ("pyproject.toml", "library", "Python project"),
+    ("requirements.txt", "ml_pipeline", "Python ML pipeline"),
+    ("package.json", "web_app", "Node.js project"),
+]
+
+DEFAULT_GATES: dict[str, list[str]] = {
+    "web_app": ["npm test", "npm run build", "git status"],
+    "ml_pipeline": ["python -m pytest", "git status"],
+    "research_notebook": ["jupyter nbconvert --execute --to notebook", "git status"],
+    "data_pipeline": ["python -m pytest", "git status"],
+    "mobile_app": ["npm test", "npm run build", "git status"],
+    "cli_tool": ["npm test", "npm run build", "git status"],
+    "library": ["python -m pytest", "git status"],
+    "course_module": ["jupyter nbconvert --execute --to notebook", "git status"],
+    "other": ["git status"],
+}
+
+
+def detect_project_type(directory: Path) -> tuple[str, str]:
+    """Detect project type by inspecting files in the directory."""
+    for filename, ptype, label in PROJECT_TYPE_SIGNALS:
+        if (directory / filename).exists():
+            return ptype, f"{label} (found {filename})"
+
+    # Check for notebooks
+    notebooks = list(directory.glob("*.ipynb"))
+    if notebooks:
+        return "research_notebook", f"Research notebook ({len(notebooks)} .ipynb files)"
+
+    return "other", "Unknown project type"
+
+
+def init_project(
+    project: str | None = None,
+    project_type: str | None = None,
+    bridge: str | None = None,
+) -> None:
+    """Initialize workbench state files in the current project."""
+    cwd = Path.cwd()
+    project_name = project or cwd.name
+
+    console.print("\n  [cyan]contextkeeper init[/cyan]\n")
+
+    # Detect project type
+    detected_type, detected_label = detect_project_type(cwd)
+    console.print(f"  [green]Detected:[/green] {detected_label}")
+    resolved_type = project_type or detected_type
+
+    # Prompt for bridge repo
+    bridge_repo = bridge
+    if not bridge_repo:
+        bridge_repo = questionary.text(
+            "Bridge repo (e.g. yourname/workbench):"
+        ).ask()
+
+    # Create directories
+    handoff_dir = cwd / "handoff"
+    docs_dir = cwd / "docs"
+    handoff_dir.mkdir(parents=True, exist_ok=True)
+    docs_dir.mkdir(parents=True, exist_ok=True)
+
+    gates = DEFAULT_GATES.get(resolved_type, ["git status"])
+
+    # Generate STATE_VECTOR.json
+    state_vector = {
+        "schema_version": "workbench-v1.0",
+        "project": project_name,
+        "project_type": resolved_type,
+        "local_path": str(cwd),
+        "state_machine_status": "IDLE",
+        "active_task_id": None,
+        "active_task_title": None,
+        "current_blocker": None,
+        "last_verified_state": "Initial project setup",
+        "gates": gates,
+        "last_updated": date.today().isoformat(),
+        "repo": f"https://github.com/{bridge_repo}" if bridge_repo else "local only",
+        "branch": "main",
+        "repo_head_sha": None,
+        "effective_verified_sha": None,
+    }
+
+    sv_path = handoff_dir / "STATE_VECTOR.json"
+    sv_path.write_text(json.dumps(state_vector, indent=2) + "\n", encoding="utf-8")
+    console.print(f"  [green]Created:[/green] {sv_path}")
+
+    # Generate HANDOFF.md
+    handoff_content = f"""# {project_name} — Project Handoff
+schema_version: workbench-v1.0
+
+## What It Is
+[FILL IN: Describe this project in one paragraph.]
+
+## Where It Is
+- Local: {cwd}
+- GitHub: {state_vector['repo']}
+- Branch: main
+
+## Current Status
+State machine: IDLE. No active task.
+
+## Active Blocker
+None
+
+## Non-Negotiables
+- [FILL IN: List project invariants]
+
+## Gates
+{chr(10).join(f'- {g}' for g in gates)}
+
+## Environment Setup
+[FILL IN: Steps to run from a clean clone]
+
+## Next Action
+[FILL IN: First task to work on]
+"""
+
+    handoff_path = docs_dir / "HANDOFF.md"
+    handoff_path.write_text(handoff_content, encoding="utf-8")
+    console.print(f"  [green]Created:[/green] {handoff_path}")
+
+    # Write .workbench config
+    config = {
+        "bridge_repo": bridge_repo,
+        "project_name": project_name,
+        "state_vector_path": "handoff/STATE_VECTOR.json",
+        "handoff_path": "docs/HANDOFF.md",
+    }
+    config_path = cwd / ".workbench"
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    console.print(f"  [green]Created:[/green] {config_path}")
+
+    console.print("\n  [cyan]Next steps:[/cyan]")
+    console.print("  1. Fill in the [FILL IN] sections in docs/HANDOFF.md")
+    console.print("  2. Review handoff/STATE_VECTOR.json")
+    console.print("  3. Run: [bold]contextkeeper sync[/bold] to push to your bridge repo\n")

contextkeeper-0.2.0/contextkeeper/status.py

@@ -0,0 +1,136 @@
+"""contextkeeper status — show status of all projects in the bridge repo."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from pathlib import Path
+
+from git import Repo
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+STATUS_STYLES: dict[str, str] = {
+    "EXECUTING": "bold yellow",
+    "PROTOCOL_BREACH": "bold red",
+    "IDLE": "dim",
+    "VERIFIED": "green",
+    "SEALED": "green",
+    "AWAITING_REVIEW": "blue",
+    "AWAITING_MANUAL_VALIDATION": "magenta",
+    "PROPOSED": "cyan",
+    "REVIEWED": "cyan",
+    "VALIDATED": "green",
+    "AWAITING_SEAL": "yellow",
+}
+
+
+def _load_config(cwd: Path) -> dict | None:
+    config_path = cwd / ".workbench"
+    if not config_path.exists():
+        return None
+    return json.loads(config_path.read_text(encoding="utf-8"))
+
+
+def show_status(bridge: str | None = None, json_output: bool = False) -> None:
+    """Fetch and display status of all projects in the bridge repo."""
+    cwd = Path.cwd()
+    config = _load_config(cwd)
+    bridge_repo = bridge or (config and config.get("bridge_repo"))
+
+    console.print("\n  [cyan]contextkeeper status[/cyan]\n")
+
+    if not bridge_repo:
+        console.print("  [red]No bridge repo configured. Run contextkeeper init or pass --bridge.[/red]")
+        raise SystemExit(1)
+
+    tmp_dir = Path(tempfile.mkdtemp(prefix="workbench-"))
+    try:
+        bridge_url = f"https://github.com/{bridge_repo}.git"
+
+        with console.status("Fetching project states..."):
+            Repo.clone_from(bridge_url, str(tmp_dir), depth=1)
+
+        projects_dir = tmp_dir / "projects"
+        if not projects_dir.exists():
+            console.print("  [yellow]No projects directory found in bridge repo.[/yellow]")
+            return
+
+        project_dirs = sorted(
+            [d for d in projects_dir.iterdir() if d.is_dir()]
+        )
+
+        if not project_dirs:
+            console.print("  [yellow]No projects found.[/yellow]")
+            return
+
+        rows: list[dict[str, str]] = []
+        for pdir in project_dirs:
+            sv_path = pdir / "STATE_VECTOR.json"
+            if not sv_path.exists():
+                rows.append({
+                    "name": pdir.name,
+                    "type": "?",
+                    "status": "NO STATE",
+                    "task": "-",
+                    "blocker": "-",
+                    "updated": "-",
+                })
+                continue
+
+            sv = json.loads(sv_path.read_text(encoding="utf-8"))
+            task_id = sv.get("active_task_id")
+            task_title = sv.get("active_task_title", "")
+            task_str = f"{task_id}: {task_title}"[:50] if task_id else "-"
+
+            blocker = sv.get("current_blocker")
+            blocker_str = (blocker[:40] + "...") if blocker and len(blocker) > 40 else (blocker or "-")
+
+            rows.append({
+                "name": pdir.name,
+                "type": sv.get("project_type", "?"),
+                "status": sv.get("state_machine_status", "?"),
+                "task": task_str,
+                "blocker": blocker_str,
+                "updated": sv.get("last_updated", "?"),
+            })
+
+        if json_output:
+            console.print_json(json.dumps(rows, indent=2))
+            return
+
+        # Build rich table
+        table = Table(show_header=True, header_style="bold", pad_edge=False, box=None)
+        table.add_column("Project", style="white", min_width=16)
+        table.add_column("Type", style="dim", min_width=14)
+        table.add_column("Status", min_width=20)
+        table.add_column("Active Task", style="white", min_width=30)
+        table.add_column("Updated", style="dim", min_width=10)
+
+        for row in rows:
+            status_val = row["status"]
+            style = STATUS_STYLES.get(status_val, "white")
+            table.add_row(
+                row["name"],
+                row["type"],
+                f"[{style}]{status_val}[/{style}]",
+                row["task"],
+                row["updated"],
+            )
+
+        console.print(table)
+
+        # Show blockers
+        blocked = [r for r in rows if r["blocker"] != "-"]
+        if blocked:
+            console.print("\n  [yellow]Blockers:[/yellow]")
+            for row in blocked:
+                console.print(f"    [red]{row['name']}:[/red] {row['blocker']}")
+
+        console.print()
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)

contextkeeper-0.2.0/contextkeeper/sync.py

@@ -0,0 +1,133 @@
+"""contextkeeper sync — push state files to the bridge repo."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+import jsonschema
+from git import Repo
+from rich.console import Console
+from rich.spinner import Spinner
+
+console = Console()
+
+
+def _load_config(cwd: Path) -> dict | None:
+    config_path = cwd / ".workbench"
+    if not config_path.exists():
+        return None
+    return json.loads(config_path.read_text(encoding="utf-8"))
+
+
+def _load_schema() -> dict | None:
+    # Try relative to this package (installed from repo)
+    candidates = [
+        Path(__file__).resolve().parent.parent.parent.parent / "protocol" / "workbench.schema.json",
+        Path.home() / ".workbench" / "src" / "protocol" / "workbench.schema.json",
+    ]
+    for path in candidates:
+        if path.exists():
+            return json.loads(path.read_text(encoding="utf-8"))
+    return None
+
+
+def sync_project(bridge: str | None = None, dry_run: bool = False) -> None:
+    """Sync state files to the workbench bridge repo."""
+    cwd = Path.cwd()
+    config = _load_config(cwd)
+
+    console.print("\n  [cyan]contextkeeper sync[/cyan]\n")
+
+    if not config and not bridge:
+        console.print("  [red]No .workbench config found. Run contextkeeper init first, or pass --bridge.[/red]")
+        raise SystemExit(1)
+
+    bridge_repo = bridge or (config and config.get("bridge_repo"))
+    project_name = config.get("project_name", "") if config else ""
+    sv_rel = config.get("state_vector_path", "handoff/STATE_VECTOR.json") if config else "handoff/STATE_VECTOR.json"
+    handoff_rel = config.get("handoff_path", "docs/HANDOFF.md") if config else "docs/HANDOFF.md"
+
+    if not bridge_repo:
+        console.print("  [red]No bridge repo configured. Run contextkeeper init or pass --bridge.[/red]")
+        raise SystemExit(1)
+
+    if not project_name:
+        console.print("  [red]No project_name in .workbench config.[/red]")
+        raise SystemExit(1)
+
+    # Read and validate STATE_VECTOR.json
+    sv_path = cwd / sv_rel
+    if not sv_path.exists():
+        console.print(f"  [red]STATE_VECTOR.json not found at {sv_path}[/red]")
+        raise SystemExit(1)
+
+    with console.status("Validating STATE_VECTOR.json..."):
+        state_vector = json.loads(sv_path.read_text(encoding="utf-8"))
+        schema = _load_schema()
+        if schema:
+            try:
+                jsonschema.validate(instance=state_vector, schema=schema)
+            except jsonschema.ValidationError as e:
+                console.print(f"  [red]Validation failed: {e.message}[/red]")
+                raise SystemExit(1)
+
+    console.print("  [green]STATE_VECTOR.json is valid[/green]")
+
+    if dry_run:
+        console.print("\n  [yellow]Dry run — would sync:[/yellow]")
+        console.print(f"    {sv_rel} → projects/{project_name}/STATE_VECTOR.json")
+        handoff_path = cwd / handoff_rel
+        if handoff_path.exists():
+            console.print(f"    {handoff_rel} → projects/{project_name}/HANDOFF.md")
+        console.print()
+        return
+
+    # Clone bridge repo, copy files, commit, push
+    tmp_dir = Path(tempfile.mkdtemp(prefix="workbench-"))
+    try:
+        bridge_url = f"https://github.com/{bridge_repo}.git"
+
+        with console.status("Cloning bridge repo..."):
+            repo = Repo.clone_from(bridge_url, str(tmp_dir), depth=1)
+
+        console.print("  [green]Bridge repo cloned[/green]")
+
+        target_dir = tmp_dir / "projects" / project_name
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        shutil.copy2(str(sv_path), str(target_dir / "STATE_VECTOR.json"))
+        console.print("  [green]Copied: STATE_VECTOR.json[/green]")
+
+        handoff_path = cwd / handoff_rel
+        if handoff_path.exists():
+            shutil.copy2(str(handoff_path), str(target_dir / "HANDOFF.md"))
+            console.print("  [green]Copied: HANDOFF.md[/green]")
+
+        next_task_path = cwd / "docs" / "NEXT_TASK.md"
+        if next_task_path.exists():
+            shutil.copy2(str(next_task_path), str(target_dir / "NEXT_TASK.md"))
+            console.print("  [green]Copied: NEXT_TASK.md[/green]")
+
+        # Commit and push
+        with console.status("Pushing to bridge repo..."):
+            repo.index.add("*")
+            if not repo.is_dirty(untracked_files=True):
+                console.print("  [yellow]No changes to push[/yellow]")
+                return
+
+            timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+            commit_msg = f"chore(workbench): sync {project_name} -- {timestamp}"
+            repo.index.commit(commit_msg)
+            repo.remotes.origin.push()
+
+        sha = repo.head.commit.hexsha[:7]
+        console.print(f"  [green]Pushed: [bold]{sha}[/bold][/green]")
+        console.print(f"\n  [green]Sync complete for [bold]{project_name}[/bold][/green]")
+        console.print(f"  [dim]{commit_msg}[/dim]\n")
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)

contextkeeper-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextkeeper"
+version = "0.2.0"
+description = "Zero model drift between AI agents. Universal session continuity protocol and CLI for Claude, GPT, Gemini, and any LLM."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "TheRealDataBoss" },
+]
+keywords = [
+    "ai",
+    "claude",
+    "chatgpt",
+    "context",
+    "continuity",
+    "developer-tools",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "gitpython>=3.1.0",
+    "jsonschema>=4.0.0",
+    "httpx>=0.24.0",
+    "questionary>=2.0.0",
+]
+
+[project.scripts]
+contextkeeper = "contextkeeper.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/TheRealDataBoss/workbench"
+Repository = "https://github.com/TheRealDataBoss/workbench"
+Issues = "https://github.com/TheRealDataBoss/workbench/issues"