fix(examples): isolate Python API demos from caller queues

examples/python-api/01_basic_usage.py

@@ -8,20 +8,24 @@
 3. Use the quick_ticket helper
 """
 
+from demo_store import isolated_demo
+
 from planfile import Planfile, quick_ticket
 
 
+@isolated_demo
 def example_1_basic_initialization():
     """Initialize planfile with auto-discovery."""
     print("=== Example 1: Basic Initialization ===\n")
 
     # Auto-discover .planfile/ in current or parent directories
     pf = Planfile.auto_discover(".")
-    print(f"✓ Planfile initialized at: {pf.store.root}")
-    print(f"  Store path: {pf.store.planfile_dir}")
+    print(f"✓ Planfile initialized at: {pf.store.project_dir}")
+    print(f"  Store path: {pf.store.base_dir}")
     print()
 
 
+@isolated_demo
 def example_2_create_ticket():
     """Create a ticket programmatically."""
     print("=== Example 2: Creating a Ticket ===\n")
@@ -30,7 +34,7 @@ def example_2_create_ticket():
 
     # Create a simple ticket
     ticket = pf.create_ticket(
-        title="Fix authentication bug",
+        name="Fix authentication bug",
         description="Users cannot login with OAuth provider",
         priority="high",
         status="open",
@@ -39,20 +43,21 @@ def example_2_create_ticket():
     )
 
     print(f"✓ Created ticket: {ticket.id}")
-    print(f"  Title: {ticket.title}")
+    print(f"  Title: {ticket.name}")
     print(f"  Priority: {ticket.priority}")
     print(f"  Status: {ticket.status}")
     print(f"  Sprint: {ticket.sprint}")
     print()
 
 
+@isolated_demo
 def example_3_quick_ticket():
     """Use quick_ticket helper for one-off ticket creation."""
     print("=== Example 3: Quick Ticket Helper ===\n")
 
     # One-liner for tools and scripts
     ticket = quick_ticket(
-        title="Production alert: High memory usage on prod-01",
+        name="Production alert: High memory usage on prod-01",
         tool="monitoring-system",
         priority="critical",
         context={"server": "prod-01", "metric": "memory", "threshold": "90%", "duration": "5m"},
@@ -64,6 +69,7 @@ def example_3_quick_ticket():
     print()
 
 
+@isolated_demo
 def example_4_list_tickets():
     """List and filter tickets."""
     print("=== Example 4: Listing Tickets ===\n")
@@ -75,7 +81,7 @@ def example_4_list_tickets():
     print(f"Found {len(tickets)} tickets in current sprint:\n")
 
     for t in tickets[:5]:  # Show first 5
-        print(f"  {t.id}: {t.title} [{t.status}]")
+        print(f"  {t.id}: {t.name} [{t.status}]")
 
     if len(tickets) > 5:
         print(f"  ... and {len(tickets) - 5} more")
@@ -86,6 +92,7 @@ def example_4_list_tickets():
     print()
 
 
+@isolated_demo
 def main():
     """Run all examples."""
     print("\n" + "=" * 60)

examples/python-api/02_ticket_management.py

@@ -9,9 +9,12 @@
 - Delete
 """
 
+from demo_store import isolated_demo
+
 from planfile import Planfile
 
 
+@isolated_demo
 def example_create_tickets():
     """Create multiple tickets."""
     print("=== Creating Tickets ===\n")
@@ -20,7 +23,7 @@ def example_create_tickets():
 
     # Create different types of tickets (using labels to categorize)
     bug = pf.create_ticket(
-        title="Login button not working on mobile",
+        name="Login button not working on mobile",
         description="Users report login button is unresponsive on iOS Safari",
         priority="high",
         labels=["bug", "mobile", "ios"],
@@ -29,15 +32,15 @@ def example_create_tickets():
     print(f"✓ Bug ticket: {bug.id}")
 
     feature = pf.create_ticket(
-        title="Add dark mode support",
+        name="Add dark mode support",
         description="Implement system-wide dark mode toggle",
         priority="medium",
         labels=["feature", "ui", "accessibility"],
     )
     print(f"✓ Feature ticket: {feature.id}")
 
     docs = pf.create_ticket(
-        title="Update API documentation",
+        name="Update API documentation",
         description="Add examples for new endpoints",
         priority="low",
         labels=["docs", "api"],
@@ -47,6 +50,7 @@ def example_create_tickets():
     return [bug.id, feature.id, docs.id]
 
 
+@isolated_demo
 def example_read_tickets(ticket_ids):
     """Read/retrieve tickets."""
     print("=== Reading Tickets ===\n")
@@ -57,7 +61,7 @@ def example_read_tickets(ticket_ids):
     ticket = pf.get_ticket(ticket_ids[0])
     print("Single ticket lookup:")
     print(f"  ID: {ticket.id}")
-    print(f"  Title: {ticket.title}")
+    print(f"  Title: {ticket.name}")
     print(f"  Priority: {ticket.priority}")
     print(f"  Status: {ticket.status}")
     print()
@@ -67,14 +71,15 @@ def example_read_tickets(ticket_ids):
     print(f"Total tickets: {len(all_tickets)}\n")
 
 
+@isolated_demo
 def example_update_tickets(ticket_ids):
     """Update ticket properties."""
     print("=== Updating Tickets ===\n")
 
     pf = Planfile.auto_discover(".")
 
     # Update status
-    updated = pf.update_ticket(ticket_ids[0], status="in_progress", comment="Started investigation")
+    updated = pf.update_ticket(ticket_ids[0], status="in_progress")
     print(f"✓ Updated {updated.id}: status → {updated.status}")
 
     # Update multiple fields
@@ -88,6 +93,7 @@ def example_update_tickets(ticket_ids):
     print()
 
 
+@isolated_demo
 def example_bulk_operations():
     """Bulk create tickets from external data."""
     print("=== Bulk Operations ===\n")
@@ -97,20 +103,20 @@ def example_bulk_operations():
     # Import from external source (e.g., Jira, CSV, monitoring alerts)
     external_data = [
         {
-            "title": "Database connection timeout",
+            "name": "Database connection timeout",
             "description": "Intermittent timeouts during peak hours",
             "priority": "critical",
             "labels": ["bug"],
             "source_id": "JIRA-1234",
         },
         {
-            "title": "Implement user search",
+            "name": "Implement user search",
             "description": "Add fuzzy search to user directory",
             "priority": "medium",
             "labels": ["feature"],
         },
         {
-            "title": "Refactor auth module",
+            "name": "Refactor auth module",
             "description": "Reduce code complexity in auth.py",
             "priority": "low",
             "labels": ["chore"],
@@ -124,27 +130,29 @@ def example_bulk_operations():
 
     print(f"✓ Bulk created {len(created)} tickets:\n")
     for t in created:
-        print(f"  {t.id}: {t.title} [{t.priority}] - Labels: {t.labels}")
+        print(f"  {t.id}: {t.name} [{t.priority}] - Labels: {t.labels}")
     print()
 
     return [t.id for t in created]
 
 
+@isolated_demo
 def example_delete_and_move(ticket_ids):
     """Delete and move tickets."""
     print("=== Delete and Move ===\n")
 
     pf = Planfile.auto_discover(".")
 
     # Move ticket to different sprint
-    moved = pf.store.move_ticket(ticket_ids[0], to_sprint="backlog")
+    pf.store.move_ticket(ticket_ids[0], to_sprint="backlog")
     print(f"✓ Moved {ticket_ids[0]} to backlog\n")
 
     # Delete a ticket (use with caution)
     # pf.store.delete_ticket(ticket_ids[-1])
     # print(f"✓ Deleted {ticket_ids[-1]}\n")
 
 
+@isolated_demo
 def main():
     """Run all examples."""
     print("\n" + "=" * 60)
@@ -154,7 +162,7 @@ def main():
     ticket_ids = example_create_tickets()
     example_read_tickets(ticket_ids)
     example_update_tickets(ticket_ids)
-    bulk_ids = example_bulk_operations()
+    example_bulk_operations()
     example_delete_and_move(ticket_ids)
 
     print("=" * 60)

examples/python-api/03_integration.py

@@ -8,10 +8,13 @@
 - Track metrics and alerts as tickets
 """
 
+from demo_store import isolated_demo
+
 from planfile import quick_ticket
 from planfile.extensions import TicketLogger
 
 
+@isolated_demo
 def example_cli_tool_integration():
     """Show integration with a CLI tool."""
     print("=== Example: CLI Tool Integration ===\n")
@@ -32,6 +35,7 @@ def example_cli_tool_integration():
     print()
 
 
+@isolated_demo
 def example_monitoring_integration():
     """Monitoring system integration."""
     print("=== Example: Monitoring Integration ===\n")
@@ -55,6 +59,7 @@ def example_monitoring_integration():
     print()
 
 
+@isolated_demo
 def example_ci_pipeline_integration():
     """CI pipeline failure tracking."""
     print("=== Example: CI Pipeline Integration ===\n")
@@ -84,6 +89,7 @@ def example_ci_pipeline_integration():
     print()
 
 
+@isolated_demo
 def example_custom_decorator():
     """Decorator for automatic error tracking."""
     print("=== Example: Error Tracking Decorator ===\n")
@@ -97,7 +103,7 @@ def wrapper(*args, **kwargs):
                     return func(*args, **kwargs)
                 except Exception as e:
                     quick_ticket(
-                        title=f"[{tool_name}] {func.__name__} failed: {str(e)[:40]}",
+                        name=f"[{tool_name}] {func.__name__} failed: {str(e)[:40]}",
                         tool=tool_name,
                         priority="high",
                         description=f"Function {func.__name__} raised {type(e).__name__}",
@@ -138,6 +144,7 @@ def process_data(data):
     print()
 
 
+@isolated_demo
 def main():
     """Run all examples."""
     print("\n" + "=" * 60)

examples/python-api/03_integration_simple.py

@@ -6,9 +6,12 @@
 AFTER: 40 lines (using native API)
 """
 
+from demo_store import isolated_demo
+
 from planfile.extensions import TicketLogger
 
 
+@isolated_demo
 def main():
     """Run simplified integration examples."""
     print("\n" + "=" * 60)
@@ -40,7 +43,7 @@ def risky_operation():
 
     try:
         risky_operation()
-    except:
+    except ValueError:
         print("   Error tracked as ticket")
 
     print("\n" + "=" * 60)

examples/python-api/04_advanced_filtering.py

@@ -8,9 +8,12 @@
 - Export filtered results
 """
 
+from demo_store import isolated_demo
+
 from planfile import Planfile
 
 
+@isolated_demo
 def example_basic_filtering():
     """Basic ticket filtering."""
     print("=== Basic Filtering ===\n")
@@ -34,6 +37,7 @@ def example_basic_filtering():
     print()
 
 
+@isolated_demo
 def example_combined_filters():
     """Combined filter criteria."""
     print("=== Combined Filters ===\n")
@@ -44,10 +48,11 @@ def example_combined_filters():
     urgent_tickets = pf.list_tickets(status="open", priority="high", sprint="current")
     print(f"Urgent tickets in current sprint: {len(urgent_tickets)}")
     for t in urgent_tickets[:3]:
-        print(f"  {t.id}: {t.title}")
+        print(f"  {t.id}: {t.name}")
     print()
 
 
+@isolated_demo
 def example_search_by_labels():
     """Search by labels and tags."""
     print("=== Label-based Search ===\n")
@@ -71,31 +76,36 @@ def example_search_by_labels():
     print()
 
 
+@isolated_demo
 def example_export_filtered():
     """Export filtered results to various formats."""
     print("=== Export Filtered Results ===\n")
 
     pf = Planfile.auto_discover(".")
 
     # Get high priority open tickets for sprint planning
-    sprint_tickets = pf.list_tickets(sprint="current", status="open", priority=["high", "critical"])
+    sprint_tickets = [
+        ticket for ticket in pf.list_tickets(sprint="current", status="open")
+        if ticket.priority in {"high", "critical"}
+    ]
 
     # Export to CSV format
     print("CSV Export:")
     print("id,title,priority,labels")
     for t in sprint_tickets[:5]:
         labels_str = "|".join(t.labels) if t.labels else "none"
-        print(f"{t.id},{t.title[:30]},{t.priority},{labels_str}")
+        print(f"{t.id},{t.name[:30]},{t.priority},{labels_str}")
 
     print("\nMarkdown Export:")
     print("## Sprint Tickets (High/Critical Priority)\n")
     for t in sprint_tickets[:5]:
-        print(f"- **{t.id}** [{t.priority}] {t.title}")
+        print(f"- **{t.id}** [{t.priority}] {t.name}")
         if t.labels:
             print(f"  - Labels: {', '.join(t.labels)}")
     print()
 
 
+@isolated_demo
 def example_statistics():
     """Generate ticket statistics."""
     print("=== Ticket Statistics ===\n")
@@ -131,8 +141,12 @@ def example_statistics():
     print()
 
 
+@isolated_demo
 def main():
     """Run all examples."""
+    Planfile.auto_discover(".").create_ticket(
+        name="Example authentication bug", priority="high", labels=["bug", "backend"]
+    )
     print("\n" + "=" * 60)
     print("Planfile Python Library - Advanced Filtering")
     print("=" * 60 + "\n")