diff --git a/cmd/core-agent/main.go b/cmd/core-agent/main.go
index 8c9530b..d3bb324 100644
--- a/cmd/core-agent/main.go
+++ b/cmd/core-agent/main.go
@@ -16,7 +16,7 @@ import (
 
 func main() {
 	if err := runCoreAgent(); err != nil {
-		core.Error(err.Error())
+		core.Error("core-agent failed", "err", err)
 		syscall.Exit(1)
 	}
 }
diff --git a/docs/RFC.md b/docs/RFC.md
index efa8239..dd08e82 100644
--- a/docs/RFC.md
+++ b/docs/RFC.md
@@ -434,6 +434,7 @@ func (s *PrepSubsystem) gitCmd(ctx context.Context, dir string, args ...string)
 
 ## Changelog
 
+- 2026-03-30: main now logs startup failures with structured context, and the workspace contract reference restored usage-example comments for the Action lifecycle messages.
 - 2026-03-29: cmd/core-agent no longer rewrites `os.Args` before startup. The binary-owned commands now use named handlers, keeping the entrypoint on Core CLI primitives instead of repo-local argument mutation.
 - 2026-03-29: brain/provider.go no longer imports net/http for Gin handlers. Handler responses now use named status constants and shared response helpers. HTTP remains intentionally centralised in pkg/agentic/transport.go.
 - 2026-03-26: WIP — net/http consolidated to transport.go (ONE file). net/url + io/fs eliminated. RFC-025 updated with 3 new quality gates (net/http, net/url, io/fs). 1:1 test + example test coverage. Array[T].Deduplicate replaces custom helpers.
diff --git a/pkg/lib/workspace/default/.core/reference/contract.go b/pkg/lib/workspace/default/.core/reference/contract.go
index 8718a90..db55fe7 100644
--- a/pkg/lib/workspace/default/.core/reference/contract.go
+++ b/pkg/lib/workspace/default/.core/reference/contract.go
@@ -39,15 +39,28 @@ type Stoppable interface {
 
 // --- Action Messages ---
 
+// ActionServiceStartup marks the broadcast that fires before services start.
+//
+//	c.ACTION(core.ActionServiceStartup{})
 type ActionServiceStartup struct{}
+
+// ActionServiceShutdown marks the broadcast that fires before services stop.
+//
+//	c.ACTION(core.ActionServiceShutdown{})
 type ActionServiceShutdown struct{}
 
+// ActionTaskStarted marks the broadcast that a named task has started.
+//
+//	c.ACTION(core.ActionTaskStarted{TaskIdentifier: "task-42", Action: "agentic.dispatch"})
 type ActionTaskStarted struct {
 	TaskIdentifier string
 	Action         string
 	Options        Options
 }
 
+// ActionTaskProgress marks the broadcast that a named task has reported progress.
+//
+//	c.ACTION(core.ActionTaskProgress{TaskIdentifier: "task-42", Action: "agentic.dispatch", Progress: 0.5})
 type ActionTaskProgress struct {
 	TaskIdentifier string
 	Action         string
@@ -55,6 +68,9 @@ type ActionTaskProgress struct {
 	Message        string
 }
 
+// ActionTaskCompleted marks the broadcast that a named task has completed.
+//
+//	c.ACTION(core.ActionTaskCompleted{TaskIdentifier: "task-42", Action: "agentic.dispatch"})
 type ActionTaskCompleted struct {
 	TaskIdentifier string
 	Action         string