docs + refactor: fix audit inconsistencies, decouple product from research packages

CLAUDE.md

@@ -15,9 +15,10 @@ Igor is the runtime for portable, immortal software agents. The checkpoint file
 ```bash
 make bootstrap       # Install toolchain (Go, golangci-lint, goimports, TinyGo)
 make build           # Build igord → bin/igord
-make agent              # Build example WASM agent → agents/example/agent.wasm
+make agent              # Build example WASM agent → agents/research/example/agent.wasm
 make agent-heartbeat    # Build heartbeat WASM agent → agents/heartbeat/agent.wasm
 make agent-pricewatcher # Build price watcher WASM agent → agents/pricewatcher/agent.wasm
+make agent-sentinel     # Build treasury sentinel WASM agent → agents/sentinel/agent.wasm
 make test            # Run tests: go test -v ./...
 make lint            # golangci-lint (5m timeout)
 make vet             # go vet
@@ -27,6 +28,7 @@ make run-agent       # Build + run example agent with budget 1.0
 make demo              # Build + run bridge reconciliation demo
 make demo-portable     # Build + run portable agent demo (run → stop → copy → resume → verify)
 make demo-pricewatcher # Build + run price watcher demo (fetch prices → stop → resume → verify)
+make demo-sentinel     # Build + run treasury sentinel demo (effect lifecycle → crash → reconcile)
 make clean           # Remove bin/, checkpoints/, agent.wasm
 ```
 
@@ -35,14 +37,14 @@ Run a single test: `go test -v -run TestName ./internal/agent/...`
 Run manually (new subcommands):
 ```bash
 ./bin/igord run --budget 1.0 agents/heartbeat/agent.wasm
-./bin/igord resume checkpoints/heartbeat/checkpoint.ckpt agents/heartbeat/agent.wasm
+./bin/igord resume --checkpoint checkpoints/heartbeat/checkpoint.ckpt --wasm agents/heartbeat/agent.wasm
 ./bin/igord verify checkpoints/heartbeat/history/
 ./bin/igord inspect checkpoints/heartbeat/checkpoint.ckpt
 ```
 
 Legacy mode (P2P/migration):
 ```bash
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 ./bin/igord --migrate-agent local-agent --to /ip4/127.0.0.1/tcp/4002/p2p/<peerID> --wasm agent.wasm
 ```
 
@@ -79,18 +81,21 @@ Atomic writes via temp file → fsync → rename. Every checkpoint is also archi
 - `pkg/manifest/` — Capability manifest parsing and validation
 - `pkg/protocol/` — Message types: `AgentPackage`, `AgentTransfer`, `AgentStarted`
 - `pkg/receipt/` — Payment receipt data structure, Ed25519 signing, binary serialization
-- `sdk/igor/` — Agent SDK: hostcall wrappers (ClockNow, RandBytes, Log, WalletBalance), lifecycle plumbing (Agent interface), Encoder/Decoder with Raw/FixedBytes/ReadInto for checkpoint serialization
+- `sdk/igor/` — Agent SDK: hostcall wrappers (ClockNow, RandBytes, Log, WalletBalance), lifecycle plumbing (Agent interface), Encoder/Decoder with Raw/FixedBytes/ReadInto for checkpoint serialization, EffectLog for intent tracking across checkpoint/resume
+- `sdk/igor/effects.go` — Effect lifecycle primitives: EffectLog, IntentState (Recorded→InFlight→Confirmed/Unresolved→Compensated), the resume rule (InFlight→Unresolved on Unmarshal)
 - `agents/heartbeat/` — Demo agent: logs heartbeat with tick count and age, milestones every 10 ticks
 - `agents/pricewatcher/` — Demo agent: fetches BTC/ETH prices from CoinGecko, tracks high/low/latest across checkpoint/resume
-- `agents/example/` — Original demo agent (Survivor) from research phases
+- `agents/sentinel/` — Treasury sentinel: monitors simulated treasury balance, triggers refills with effect-safe intent tracking, demonstrates crash recovery and reconciliation
+- `agents/research/example/` — Original demo agent (Survivor) from research phases
+- `agents/research/reconciliation/` — Bridge reconciliation demo agent (research phase)
 - `scripts/demo-portable.sh` — End-to-end portable agent demo
 
 ### Migration flow
 Source checkpoints → packages (WASM + checkpoint + budget) → transfers over libp2p → target instantiates + resumes → target confirms → source terminates + deletes local checkpoint. Single-instance invariant maintained throughout. Failures classified as retriable/fatal/ambiguous; ambiguous transfers enter RECOVERY_REQUIRED state (EI-6). Retry with exponential backoff; peer registry tracks health for target selection.
 
 ### CLI subcommands (Product Phase 1)
 - `igord run [flags] <agent.wasm>` — run agent with new identity (`--budget`, `--checkpoint-dir`, `--agent-id`)
-- `igord resume <checkpoint.ckpt> <agent.wasm>` — resume agent from checkpoint file
+- `igord resume --checkpoint <path> --wasm <path>` — resume agent from checkpoint file
 - `igord verify <history-dir>` — verify checkpoint lineage chain
 - `igord inspect <checkpoint.ckpt>` — display checkpoint details with DID identity
 

LICENSE

@@ -186,7 +186,7 @@
       "Refer to the LICENSE file" or similar statement added to each
       source file to indicate the file is part of the licensed work.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 Janko Simonovic
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -1,14 +1,15 @@
-.PHONY: help bootstrap build build-lab clean test lint vet fmt fmt-check tidy agent agent-heartbeat agent-reconciliation agent-pricewatcher run-agent demo demo-portable demo-pricewatcher gh-check gh-metadata gh-release
+.PHONY: help bootstrap build build-lab clean test lint vet fmt fmt-check tidy agent agent-heartbeat agent-reconciliation agent-pricewatcher agent-sentinel run-agent demo demo-portable demo-pricewatcher demo-sentinel gh-check gh-metadata gh-release
 
 .DEFAULT_GOAL := help
 
 # Build configuration
 BINARY_NAME := igord
 BINARY_DIR := bin
-AGENT_DIR := agents/example
+AGENT_DIR := agents/research/example
 HEARTBEAT_AGENT_DIR := agents/heartbeat
-RECONCILIATION_AGENT_DIR := agents/reconciliation
+RECONCILIATION_AGENT_DIR := agents/research/reconciliation
 PRICEWATCHER_AGENT_DIR := agents/pricewatcher
+SENTINEL_AGENT_DIR := agents/sentinel
 
 # Go commands
 GOCMD := go
@@ -51,11 +52,12 @@ clean: ## Remove build artifacts
 	$(GOCLEAN)
 	rm -rf $(BINARY_DIR)
 	rm -rf checkpoints
-	rm -f agents/example/agent.wasm
-	rm -f agents/example/agent.wasm.checkpoint
+	rm -f agents/research/example/agent.wasm
+	rm -f agents/research/example/agent.wasm.checkpoint
 	rm -f agents/heartbeat/agent.wasm
-	rm -f agents/reconciliation/agent.wasm
+	rm -f agents/research/reconciliation/agent.wasm
 	rm -f agents/pricewatcher/agent.wasm
+	rm -f agents/sentinel/agent.wasm
 	@echo "Clean complete"
 
 test: ## Run tests (with race detector)
@@ -127,10 +129,17 @@ agent-pricewatcher: ## Build price watcher demo agent WASM
 	cd $(PRICEWATCHER_AGENT_DIR) && $(MAKE) build
 	@echo "Agent built: $(PRICEWATCHER_AGENT_DIR)/agent.wasm"
 
+agent-sentinel: ## Build treasury sentinel demo agent WASM
+	@echo "Building sentinel agent..."
+	@which tinygo > /dev/null || \
+		(echo "tinygo not found. See docs/governance/DEVELOPMENT.md for installation" && exit 1)
+	cd $(SENTINEL_AGENT_DIR) && $(MAKE) build
+	@echo "Agent built: $(SENTINEL_AGENT_DIR)/agent.wasm"
+
 demo: build agent-reconciliation ## Build and run reconciliation demo
 	@echo "Building demo runner..."
 	@mkdir -p $(BINARY_DIR)
-	$(GOBUILD) -o $(BINARY_DIR)/demo-reconciliation ./cmd/demo-reconciliation
+	$(GOBUILD) -o $(BINARY_DIR)/demo-reconciliation ./agents/research/reconciliation/cmd/demo
 	@echo "Running Bridge Reconciliation Demo..."
 	./$(BINARY_DIR)/demo-reconciliation --wasm $(RECONCILIATION_AGENT_DIR)/agent.wasm
 
@@ -144,6 +153,11 @@ demo-pricewatcher: build agent-pricewatcher ## Run the price watcher demo (fetch
 	@chmod +x scripts/demo-pricewatcher.sh
 	@./scripts/demo-pricewatcher.sh
 
+demo-sentinel: build agent-sentinel ## Run the treasury sentinel demo (effect lifecycle, crash recovery)
+	@echo "Running Treasury Sentinel Demo..."
+	@chmod +x scripts/demo-sentinel.sh
+	@./scripts/demo-sentinel.sh
+
 check: fmt-check vet lint test ## Run all checks (formatting, vet, lint, tests)
 	@echo "All checks passed"
 

agents/example/README.md → agents/research/example/README.md

@@ -68,17 +68,17 @@ make agent    # from repo root
 
 ```bash
 make run-agent                    # default budget 1.0
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 ```
 
 ## Demonstrating Survival
 
 ```bash
 # Start the agent
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 
 # Let it tick a few times, then Ctrl-C (checkpoints on shutdown)
 
 # Restart — it resumes from checkpoint, tick count and age continue
-./bin/igord --run-agent agents/example/agent.wasm --budget 10.0
+./bin/igord --run-agent agents/research/example/agent.wasm --budget 10.0
 ```

agents/research/example/go.mod

@@ -0,0 +1,7 @@
+module github.com/simonovic86/igor/agents/research/example
+
+go 1.24
+
+require github.com/simonovic86/igor/sdk/igor v0.0.0
+
+replace github.com/simonovic86/igor/sdk/igor => ../../../sdk/igor

cmd/demo-reconciliation/main.go → agents/research/reconciliation/cmd/demo/main.go

@@ -158,8 +158,8 @@ func runDemo(wasmPath string) error {
 	}
 
 	leaseEpoch := "(1,0)"
-	if instB.Lease != nil {
-		leaseEpoch = instB.Lease.Epoch.String()
+	if lease, ok := instB.Lease.(*authority.Lease); ok && lease != nil {
+		leaseEpoch = lease.Epoch.String()
 	}
 	fmt.Printf("  Agent migrated to node-b (epoch: %s)\n", leaseEpoch)
 	fmt.Println()

agents/research/reconciliation/go.mod

@@ -0,0 +1,7 @@
+module github.com/simonovic86/igor/agents/research/reconciliation
+
+go 1.24
+
+require github.com/simonovic86/igor/sdk/igor v0.0.0
+
+replace github.com/simonovic86/igor/sdk/igor => ../../../sdk/igor

agents/sentinel/Makefile

@@ -0,0 +1,7 @@
+.PHONY: build clean
+
+build:
+	tinygo build -target=wasi -no-debug -o agent.wasm .
+
+clean:
+	rm -f agent.wasm

agents/sentinel/agent.manifest.json

@@ -0,0 +1,10 @@
+{
+  "capabilities": {
+    "clock": { "version": 1 },
+    "rand": { "version": 1 },
+    "log": { "version": 1 }
+  },
+  "resource_limits": {
+    "max_memory_bytes": 67108864
+  }
+}

agents/example/go.mod → agents/sentinel/go.mod

@@ -1,4 +1,4 @@
-module github.com/simonovic86/igor/agents/example
+module github.com/simonovic86/igor/agents/sentinel
 
 go 1.24