diff --git a/pkg/mcp/notify.go b/pkg/mcp/notify.go
index 0865489..90425db 100644
--- a/pkg/mcp/notify.go
+++ b/pkg/mcp/notify.go
@@ -48,17 +48,24 @@ func (lw *lockedWriter) Close() error { return nil }
 // Created once when the MCP service enters stdio mode.
 var sharedStdout = &lockedWriter{w: os.Stdout}
 
-// Notification method names used by the MCP server.
-const (
-	ChannelNotificationMethod = "notifications/claude/channel"
-	LoggingNotificationMethod = "notifications/message"
-	// ClaudeChannelCapabilityName is the experimental capability key advertised
-	// by the MCP server for channel-based client notifications.
-	ClaudeChannelCapabilityName = "claude/channel"
-)
+// ChannelNotificationMethod is the JSON-RPC method used for named channel
+// events sent through claude/channel.
+const ChannelNotificationMethod = "notifications/claude/channel"
+
+// LoggingNotificationMethod is the JSON-RPC method used for log messages sent
+// to connected MCP clients.
+const LoggingNotificationMethod = "notifications/message"
+
+// ClaudeChannelCapabilityName is the experimental capability key advertised
+// by the MCP server for channel-based client notifications.
+const ClaudeChannelCapabilityName = "claude/channel"
 
 // Shared channel names. Keeping them central avoids drift between emitters
 // and the advertised claude/channel capability.
+//
+// Use these names when emitting structured events from subsystems:
+//
+//	s.ChannelSend(ctx, ChannelProcessStart, map[string]any{"id": "proc-1"})
 const (
 	ChannelBuildStart        = "build.start"
 	ChannelBuildComplete     = "build.complete"
diff --git a/pkg/mcp/register.go b/pkg/mcp/register.go
index f8d95d7..6a10811 100644
--- a/pkg/mcp/register.go
+++ b/pkg/mcp/register.go
@@ -60,6 +60,8 @@ func Register(c *core.Core) core.Result {
 
 // OnStartup implements core.Startable — registers MCP transport commands.
 //
+//	svc.OnStartup(context.Background())
+//
 //	core-agent mcp    — start MCP server on stdio
 //	core-agent serve  — start MCP server on HTTP
 func (s *Service) OnStartup(ctx context.Context) core.Result {
@@ -94,9 +96,9 @@ func (s *Service) OnStartup(ctx context.Context) core.Result {
 }
 
 // HandleIPCEvents implements Core's IPC handler interface.
-// Catches ChannelPush messages from other services and pushes them to Claude Code sessions.
 //
 //	c.ACTION(mcp.ChannelPush{Channel: "agent.status", Data: statusMap})
+// Catches ChannelPush messages from other services and pushes them to Claude Code sessions.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) core.Result {
 	ctx := context.Background()
 	if c != nil {
@@ -175,6 +177,8 @@ func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) core.Result {
 }
 
 // OnShutdown implements core.Stoppable — stops the MCP transport.
+//
+//	svc.OnShutdown(context.Background())
 func (s *Service) OnShutdown(ctx context.Context) core.Result {
 	if err := s.Shutdown(ctx); err != nil {
 		return core.Result{Value: err, OK: false}