docs: streamline ai docs + readme

Author: matthiaszimmermann

.github/copilot-instructions.md

@@ -29,14 +29,25 @@ Quick reference for enhancing this starter repo for AI-assisted development.
 
 ## 📚 Documentation Improvements
 
-### 4. Consolidate API_REFERENCE.md
+### 4. ✅ API_REFERENCE.md Removed
 
-**Current issue:** 90% overlap with README creates maintenance burden
+**Decision:** Deleted to avoid documentation drift
 
-**Options:**
-- **A)** Merge into README, keep API_REFERENCE as pure method signatures only
-- **B)** Keep API_REFERENCE comprehensive, make README a quickstart only
-- **Recommended:** Option A - developers expect README to be comprehensive
+**Rationale:**
+- SDK has comprehensive docstrings in `module_base.py` for all methods
+- Duplicating method docs creates maintenance burden
+- AI can read SDK source directly via `semantic_search()`
+- Examples (01→05) demonstrate all patterns
+
+**Unique Content to Integrate Later:**
+- Naming conventions table (Python/Query/Events) → Add to README.md
+- Query syntax with system attributes (`$owner`, `$content_type`) → Add to README.md or copilot-instructions.md
+- Event handling patterns (camelCase in events) → Already covered in copilot-instructions.md
+
+**Action Items:**
+- [ ] Add naming conventions quick reference table to README
+- [ ] Add query syntax section to README (system attributes)
+- [ ] Ensure copilot-instructions.md covers event naming
 
 ### 5. Add "Next Steps" Comments to Examples
 
@@ -64,40 +75,6 @@ Add to README:
 
 ---
 
-## 🧪 Testing Enhancements
-
-### 7. Add Tests for Remaining Examples
-
-**Currently tested:** 01_basic_crud, 02_queries, utilities
-
-**Missing:**
-- `test_03_events.py` - Event watching patterns
-- `test_04_web3_integration.py` - Direct contract interaction
-
-**Note:** Current tests are actually good examples! They show:
-- Time conversion utilities
-- Entity existence checks
-- Extension patterns
-- Field mask usage
-
-### 8. Test for Common Mistakes
-
-Add tests that catch typical errors:
-```python
-def test_content_type_in_query():
-    """Ensure snake_case used in queries (common AI mistake)."""
-    # Should use $content_type not $contentType
-    result = client.arkiv.query_entities('$content_type = "text/plain"')
-    assert len(list(result)) >= 0  # Should not raise error
-
-def test_event_arg_naming():
-    """Document that event args use camelCase."""
-    # This test is documentation for AI
-    pass
-```
-
----
-
 ## 🚀 Advanced Patterns
 
 ### 9. Common Patterns Library (Optional)
@@ -139,7 +116,7 @@ from arkiv import Arkiv
 
 ## 🎨 Visual/Media
 
-### 11. Demo GIF or Video
+### 11. Demo Video
 
 - **README.md**: Embed 60-second demo showing repo → run → output
 - AI can't create this but can prompt maintainer to add it
@@ -181,9 +158,8 @@ Add to README or separate `TROUBLESHOOTING.md`:
 | 🔴 HIGH | Medium | High | #3 - Mini Chat Example |
 | 🟡 MEDIUM | Low | Medium | #5 - "Next Steps" Comments |
 | 🟡 MEDIUM | Low | Medium | #6 - Quick Reference Table |
-| 🟡 MEDIUM | Medium | Medium | #4 - Consolidate API_REFERENCE |
 | 🟢 LOW | Medium | Low | #9 - Patterns Library |
-| 🟢 LOW | High | Medium | #11 - Demo GIF |
+| 🟢 LOW | High | Medium | #11 - Demo Video |
 
 ---
 
@@ -198,7 +174,7 @@ Add to README or separate `TROUBLESHOOTING.md`:
 5. Add Quick Reference table to README (1 hour)
 
 **Week 3 (Polish):**
-6. Consolidate API_REFERENCE.md (2 hours)
+6. Integrate unique API_REFERENCE content to README (1 hour)
 7. Add troubleshooting section (1 hour)
 
 **Ongoing:**

API_REFERENCE.md

@@ -98,7 +98,9 @@
 print("   - Useful for testing ownership transfers\n")
 
 original_account = client.eth.default_account
+original_signer = client.current_signer  # Track the current signer name
 print(f"📋 Starting with account: {original_account}")
+print(f"   Current signer name: {original_signer}")
 
 # Create and add a second account
 account_name = "second-account"
@@ -126,10 +128,14 @@
 print(f"✅ Entity created: {entity_key3}")
 print(f"   Owner: {entity.owner if entity else 'N/A'}\n")
 
-# Switch back to original (use account name from registry)
+# Switch back to original (use current_signer to track the name)
 print("🔄 Switching back to original account...")
-client.switch_to("default")  # Use account name, not address
-print(f"✅ Now signing with: {client.eth.default_account}\n")
+if original_signer:
+    client.switch_to(original_signer)  # Use the saved signer name
+    print(f"✅ Now signing with: {client.eth.default_account}")
+    print(f"   Current signer name: {client.current_signer}\n")
+else:
+    print("⚠️  No original signer to switch back to\n")
 
 
 print("=" * 70)
@@ -178,6 +184,7 @@
    ✅ Testing ownership transfers
    ✅ Multi-user scenarios
    ✅ Demonstrating permissions
+   💡 Use client.current_signer to track current account name
 
 5. NODE REFERENCE (client.node):
    ✅ Fund test accounts

README.md

@@ -74,6 +74,10 @@
 print(f"   Extended expiration: {extended_entity.expires_at_block}\n")
 
 print("👤 Step 5: Changing entity owner...")
+# Track original signer before switching
+original_signer = client.current_signer
+print(f"   Current signer: {original_signer}")
+
 # Create a new account to transfer ownership to
 from arkiv import NamedAccount
 new_owner_account = NamedAccount.create("new-owner")
@@ -94,8 +98,10 @@
 
 print("🗑️  Step 6: Deleting entity (as new owner)...")
 # Switch to new owner to delete (only owner can delete)
+print(f"   Switching from '{client.current_signer}' to 'new-owner' account...")
 client.accounts["new-owner"] = new_owner_account
 client.switch_to("new-owner")
+print(f"   Current signer: {client.current_signer}")
 
 receipt = client.arkiv.delete_entity(entity_key)
 print(f"✅ Entity deleted!")

ai_first_template_todos.md

@@ -104,17 +104,21 @@ def on_owner_changed(event: ChangeOwnerEvent, tx_hash: TxHash) -> None:
 print(f"     Extended entity: {entity_key}")
 
 print("4️⃣  Operation 4: Changing entity owner...")
+original_signer = client.current_signer  # Track original account name
 account_name = "new-owner"
 new_account = NamedAccount.create(account_name)
 receipt = client.arkiv.change_owner(entity_key, new_account.address)
-print(f"     Changed owner of entity: {entity_key} to {new_account.address} ")
+print(f"     Changed owner of entity: {entity_key} to {new_account.address}")
+print(f"     Original signer: {original_signer}")
 
 print("5️⃣  Operation 5: Deleting entity (as new owner)...")
 node = client.node
 assert node is not None
 node.fund_account(new_account)  # Fund the new account
-client.accounts[account_name] = new_account # Add to client accounts
-client.switch_to(account_name) # Switch signing account to new owner
+client.accounts[account_name] = new_account  # Add to client accounts
+print(f"     Switching from '{client.current_signer}' to '{account_name}' account...")
+client.switch_to(account_name)  # Switch signing account to new owner
+print(f"     Current signer: {client.current_signer}")
 receipt = client.arkiv.delete_entity(entity_key)
 print(f"     Deleted entity: {entity_key}")
 

src/arkiv_starter/01_clients.py

@@ -77,6 +77,8 @@ def test_multiple_accounts_switch_to(arkiv_node):
     client = Arkiv(provider, account=account)
 
     original_account = client.eth.default_account
+    original_signer = client.current_signer  # Track original account name
+    assert original_signer is not None
 
     # Create and add second account
     second_account = NamedAccount.create("test-second-account")
@@ -91,6 +93,7 @@ def test_multiple_accounts_switch_to(arkiv_node):
     # Switch to second account
     client.switch_to("second-account")
     assert client.eth.default_account == second_account.address
+    assert client.current_signer == "second-account"
 
     # Create entity with second account
     entity_key, receipt = client.arkiv.create_entity(
@@ -104,12 +107,10 @@ def test_multiple_accounts_switch_to(arkiv_node):
     assert entity is not None
     assert entity.owner == second_account.address
 
-    # Switch back to original (need to find the key)
-    for name, acc in client.accounts.items():
-        if acc.address == original_account:
-            client.switch_to(name)
-            break
+    # Switch back to original using tracked signer name
+    client.switch_to(original_signer)
     assert client.eth.default_account == original_account
+    assert client.current_signer == original_signer
 
 
 def test_node_reference():