buildlog 0.10.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

buildlog/cli.py

@@ -165,7 +165,7 @@ def _init_mcp(settings_path: Path | None = None, global_mode: bool = False) -> N
 
     Args:
         settings_path: Path to settings.json. Defaults to .claude/settings.json
-        global_mode: If True, display global-specific messaging
+        global_mode: If True, also writes usage instructions to ~/.claude/CLAUDE.md
     """
     import json as json_module
 
@@ -190,21 +190,57 @@ def _init_mcp(settings_path: Path | None = None, global_mode: bool = False) -> N
         if "mcpServers" not in data:
             data["mcpServers"] = {}
 
-        if "buildlog" in data["mcpServers"]:
-            click.echo(f"buildlog MCP server already registered in {location}")
-            return
+        mcp_already_registered = "buildlog" in data["mcpServers"]
 
-        data["mcpServers"]["buildlog"] = {"command": "buildlog-mcp", "args": []}
+        if not mcp_already_registered:
+            data["mcpServers"]["buildlog"] = {"command": "buildlog-mcp", "args": []}
+            settings_path.parent.mkdir(parents=True, exist_ok=True)
+            settings_path.write_text(json_module.dumps(data, indent=2) + "\n")
+            click.echo(f"Registered buildlog MCP server in {location}")
+        else:
+            click.echo(f"buildlog MCP server already registered in {location}")
 
-        settings_path.parent.mkdir(parents=True, exist_ok=True)
-        settings_path.write_text(json_module.dumps(data, indent=2) + "\n")
-        click.echo(f"Registered buildlog MCP server in {location}")
+        # In global mode, also write/update ~/.claude/CLAUDE.md with usage instructions
         if global_mode:
-            click.echo("Claude Code now has access to buildlog tools in all projects.")
+            _init_global_claude_md(settings_path.parent)
+            click.echo(
+                "Claude Code now has buildlog tools + instructions in all projects."
+            )
+
     except Exception as e:
         click.echo(f"Warning: could not register MCP server: {e}", err=True)
 
 
+def _init_global_claude_md(claude_dir: Path) -> None:
+    """Write buildlog usage instructions to ~/.claude/CLAUDE.md.
+
+    Creates or appends to the global CLAUDE.md so Claude knows how to use
+    buildlog tools automatically in any project.
+    """
+    from buildlog.constants import CLAUDE_MD_GLOBAL_SECTION
+
+    claude_md_path = claude_dir / "CLAUDE.md"
+
+    try:
+        if claude_md_path.exists():
+            content = claude_md_path.read_text()
+            # Check if buildlog section already exists
+            if "## buildlog" in content:
+                click.echo("buildlog instructions already in ~/.claude/CLAUDE.md")
+                return
+            # Append to existing file
+            with open(claude_md_path, "a") as f:
+                f.write(CLAUDE_MD_GLOBAL_SECTION)
+            click.echo("Added buildlog instructions to ~/.claude/CLAUDE.md")
+        else:
+            # Create new file with header
+            header = "# Global Claude Instructions\n\nThese instructions apply to all projects.\n"
+            claude_md_path.write_text(header + CLAUDE_MD_GLOBAL_SECTION)
+            click.echo("Created ~/.claude/CLAUDE.md with buildlog instructions")
+    except Exception as e:
+        click.echo(f"Warning: could not write CLAUDE.md: {e}", err=True)
+
+
 @main.command("init-mcp")
 @click.option(
     "--global",

buildlog/constants.py

@@ -1,5 +1,44 @@
 """Shared constants for buildlog, including the CLAUDE.md integration section."""
 
+# Shorter version for global ~/.claude/CLAUDE.md - focused on "always on" usage
+CLAUDE_MD_GLOBAL_SECTION = """
+## buildlog (Always On)
+
+buildlog is your ambient data capture layer. It runs in ALL projects via MCP.
+Use these tools to track work, extract learnings, and feed downstream systems.
+
+### Core Loop (use after every significant commit)
+
+1. `buildlog_overview()` — check project state
+2. `buildlog_commit(message="...")` — git commit with auto entry logging
+3. `buildlog_gauntlet_rules()` + review + `buildlog_gauntlet_issues([...])` — run gauntlet
+4. `buildlog_log_reward(outcome="accepted")` — close the feedback loop
+
+### Key Tools
+
+| Tool | When to Use |
+|------|-------------|
+| `buildlog_overview()` | Start of session, check state |
+| `buildlog_commit(message)` | Wrap git commits with logging |
+| `buildlog_entry_new(slug)` | Create journal entry |
+| `buildlog_gauntlet_rules()` | Load reviewer personas |
+| `buildlog_gauntlet_issues(issues)` | Process review findings |
+| `buildlog_log_reward(outcome)` | Feedback after approval |
+| `buildlog_skills()` | Extract patterns from entries |
+| `buildlog_status()` | See extracted skills |
+| `buildlog_promote(skill_ids)` | Surface to agent rules |
+
+### Outputs (ambient capture for downstream)
+
+- Journal entries: `buildlog/*.md`
+- Reward signals: `buildlog/.buildlog/reward_events.jsonl`
+- Extracted skills: `buildlog/.buildlog/promoted.json`
+- Review learnings: `buildlog/.buildlog/review_learnings.json`
+
+This data feeds automated content generation, engineering logs, and learning systems.
+"""
+
+# Full version for per-project CLAUDE.md - comprehensive reference
 CLAUDE_MD_BUILDLOG_SECTION = """
 ## buildlog Integration
 

{buildlog-0.10.0.dist-info → buildlog-0.10.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildlog
-Version: 0.10.0
+Version: 0.10.1
 Summary: Engineering notebook for AI-assisted development
 Project-URL: Homepage, https://github.com/Peleke/buildlog-template
 Project-URL: Repository, https://github.com/Peleke/buildlog-template
@@ -163,46 +163,48 @@ The roadmap: contextual bandits (now) -> richer policy models -> longer-horizon
 
 ## Installation
 
-### Quick start
+### Always-On Mode (recommended)
+
+We run buildlog as an **ambient data capture layer** across all projects. One command, works everywhere:
 
 ```bash
-pip install buildlog          # MCP server included by default
-buildlog init --defaults      # scaffold project, register MCP, update CLAUDE.md
+pipx install buildlog         # or: uv tool install buildlog
+buildlog init-mcp --global    # registers MCP + writes instructions to ~/.claude/CLAUDE.md
 ```
 
-That's it. Claude Code will now have access to all 29 buildlog tools.
+That's it. Claude Code now has all 29 buildlog tools **and knows how to use them** in every project you open. No per-project setup needed.
 
-### Global install (recommended)
+The `--global` flag:
+- Registers the MCP server in `~/.claude/settings.json`
+- Creates `~/.claude/CLAUDE.md` with usage instructions so Claude proactively uses buildlog
+- Works immediately in any repo, even without a local `buildlog/` directory
 
-```bash
-uv tool install buildlog   # or: pipx install buildlog
-```
+This is how we use buildlog ourselves: always on, capturing structured trajectories from every session, feeding downstream systems that generate engineering logs, courses, and content.
 
-This puts `buildlog` and `buildlog-mcp` on your PATH. Works from any directory.
+### Per-project setup
 
-### Per-project (virtual environment)
+If you prefer explicit per-project control:
 
 ```bash
-uv pip install buildlog    # or: pip install buildlog
+pip install buildlog          # MCP server included by default
+buildlog init --defaults      # scaffold buildlog/, register MCP, update CLAUDE.md
 ```
 
+This creates a `buildlog/` directory with templates and configures Claude Code for that specific project.
+
 ### For JS/TS projects
 
 ```bash
 npx @peleke.s/buildlog init
 ```
 
-### MCP server for Claude Code
-
-`buildlog init` auto-registers the MCP server. For existing projects:
+### Verify installation
 
 ```bash
-buildlog init-mcp          # register MCP in .claude/settings.json
 buildlog mcp-test          # verify all 29 tools are registered
+buildlog overview          # check project state (works without init in global mode)
 ```
 
-This exposes buildlog tools (seeds, skills, experiments, gauntlet, bandit status) to any Claude Code session.
-
 ## Quick Start
 
 ```bash

{buildlog-0.10.0.dist-info → buildlog-0.10.1.dist-info}/RECORD

@@ -1,7 +1,7 @@
 buildlog/__init__.py,sha256=wxluyg3fDOiaKUAOJa0cav39hwtNJS5Y_0X20uL_yi4,90
-buildlog/cli.py,sha256=YSLegAPnIqPR_AGEkSTe3DaZilhRH4kdDUhbk1dLCD4,74956
+buildlog/cli.py,sha256=YlAo1h43dZuBL7AkEZpd1uJsKnakHNekw8ywBF5PJW4,76508
 buildlog/confidence.py,sha256=jPvN0_3drGHQG1C7iUxUtYjKC62nNKsHHxu6WXMfJFg,10137
-buildlog/constants.py,sha256=nwRAiI4NcXczdUK1C332i36BfnPqjMp4gHg2E4y4n5M,5783
+buildlog/constants.py,sha256=9byHhexkEaHcM8jjK0F2C_CssPSO9ujvVbbBIi04ZJ4,7419
 buildlog/distill.py,sha256=PL7UBToBb27BrCOTWGBTDIXGggtrUumHHBs0_MfG6vY,14166
 buildlog/embeddings.py,sha256=vPydWjJVkYp172zFou-lJ737qsu6vRMQAMs143RGIpA,12364
 buildlog/llm.py,sha256=t_3KnJ_eBmrtHaay4owG3EgGbJrVp_T379P0tTuyJf8,16986
@@ -42,18 +42,18 @@ buildlog/seed_engine/llm_extractor.py,sha256=nfTmN4vuEiPQuhiL_2DX1QZ7TZlDR2vxYy0
 buildlog/seed_engine/models.py,sha256=qESSuoF3CJy8pp96E3Vmb38V-snzeaW0Xg0RfbH8v1U,3418
 buildlog/seed_engine/pipeline.py,sha256=cyR2Vf32Hf0PK5DxnaFcq56ygjJIiJWiIkHY4Uz7AS8,8082
 buildlog/seed_engine/sources.py,sha256=8j9oUFZCSKMr5VpIuAxTPY3wTzfTEmw6M_41_aismiE,11184
-buildlog-0.10.0.data/data/share/buildlog/copier.yml,sha256=hD_UcLGB9eDxTGkWjHAvUoiqQKhLC0w3G-kPKX_p43I,802
-buildlog-0.10.0.data/data/share/buildlog/post_gen.py,sha256=YQJYQjbRqfmyKrRRkdqk8qTkXwqompg-AgroKUR8W9M,2020
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/2026-01-01-example.md,sha256=7x9sKmydfmfKyNz9hV7MtYnQJuBwbxNanbPOcpQDDZQ,7040
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md,sha256=osclytWwl5jUiTgSpuT4cT3h3oPvCkZ5GPCnFuJZNcY,3802
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/_TEMPLATE.md,sha256=CUvxgcx1-9XT_EdQ8e_vnuPq_h-u1uhXJgForJU2Pso,2932
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/_TEMPLATE_QUICK.md,sha256=eUr5MiqLsM6drV7rAq53R1SLkK8G7LkMAUjWKXx81IA,409
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/.buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/.buildlog/seeds/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.10.0.data/data/share/buildlog/template/buildlog/assets/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-buildlog-0.10.0.dist-info/METADATA,sha256=3rhwCyjU4M6hABubghAUvxA2uEz1YvK8hjMaoQY_PYk,11465
-buildlog-0.10.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-buildlog-0.10.0.dist-info/entry_points.txt,sha256=BMFclPOomp_sgaa0OqBg6LfqCMlqzjZV88ww5TrPPoo,87
-buildlog-0.10.0.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
-buildlog-0.10.0.dist-info/RECORD,,
+buildlog-0.10.1.data/data/share/buildlog/copier.yml,sha256=hD_UcLGB9eDxTGkWjHAvUoiqQKhLC0w3G-kPKX_p43I,802
+buildlog-0.10.1.data/data/share/buildlog/post_gen.py,sha256=YQJYQjbRqfmyKrRRkdqk8qTkXwqompg-AgroKUR8W9M,2020
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/2026-01-01-example.md,sha256=7x9sKmydfmfKyNz9hV7MtYnQJuBwbxNanbPOcpQDDZQ,7040
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/BUILDLOG_SYSTEM.md,sha256=osclytWwl5jUiTgSpuT4cT3h3oPvCkZ5GPCnFuJZNcY,3802
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/_TEMPLATE.md,sha256=CUvxgcx1-9XT_EdQ8e_vnuPq_h-u1uhXJgForJU2Pso,2932
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/_TEMPLATE_QUICK.md,sha256=eUr5MiqLsM6drV7rAq53R1SLkK8G7LkMAUjWKXx81IA,409
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/.buildlog/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/.buildlog/seeds/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.10.1.data/data/share/buildlog/template/buildlog/assets/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+buildlog-0.10.1.dist-info/METADATA,sha256=BvQtReyHfyKdwVZF2JpZioaFrzzPrWF4J3_w_xsxosY,11971
+buildlog-0.10.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+buildlog-0.10.1.dist-info/entry_points.txt,sha256=BMFclPOomp_sgaa0OqBg6LfqCMlqzjZV88ww5TrPPoo,87
+buildlog-0.10.1.dist-info/licenses/LICENSE,sha256=fAgt-akug9nAwIj6M-SIf8u3ck-T7pJTwfmy9vWYASk,1074
+buildlog-0.10.1.dist-info/RECORD,,