refactor(ax): AX compliance pass — usage example comments on exported methods

- Add usage example comments to Service methods (Get, List, Running, Kill, Remove, Clear, Output, Signal)
- Add usage example comments to Daemon methods (Start, Run, Stop, SetReady, HealthAddr)
- Add usage example comments to HealthServer methods (AddCheck, SetReady, Start, Stop, Addr)
- Add usage example comments to Registry methods (Register, Unregister, Get, List)
- Banned imports (os, os/exec, io) are LEGITIMATE — this IS the process abstraction layer

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

daemon.go

@@ -72,6 +72,8 @@ func NewDaemon(opts DaemonOptions) *Daemon {
 }
 
 // Start initialises the daemon (PID file, health server).
+//
+//	err := daemon.Start()
 func (d *Daemon) Start() error {
 	d.mu.Lock()
 	defer d.mu.Unlock()
@@ -122,6 +124,8 @@ func (d *Daemon) Start() error {
 }
 
 // Run blocks until the context is cancelled.
+//
+//	err := daemon.Run(ctx)
 func (d *Daemon) Run(ctx context.Context) error {
 	d.mu.Lock()
 	if !d.running {
@@ -136,6 +140,8 @@ func (d *Daemon) Run(ctx context.Context) error {
 }
 
 // Stop performs graceful shutdown.
+//
+//	err := daemon.Stop()
 func (d *Daemon) Stop() error {
 	d.mu.Lock()
 	defer d.mu.Unlock()
@@ -176,6 +182,8 @@ func (d *Daemon) Stop() error {
 }
 
 // SetReady sets the daemon readiness status for health checks.
+//
+//	daemon.SetReady(true)
 func (d *Daemon) SetReady(ready bool) {
 	if d.health != nil {
 		d.health.SetReady(ready)
@@ -183,6 +191,8 @@ func (d *Daemon) SetReady(ready bool) {
 }
 
 // HealthAddr returns the health server address, or empty if disabled.
+//
+//	addr := daemon.HealthAddr() // e.g. "127.0.0.1:9090"
 func (d *Daemon) HealthAddr() string {
 	if d.health != nil {
 		return d.health.Addr()

health.go

@@ -38,6 +38,8 @@ func NewHealthServer(addr string) *HealthServer {
 }
 
 // AddCheck registers a health check function.
+//
+//	health.AddCheck(func() error { return db.Ping() })
 func (h *HealthServer) AddCheck(check HealthCheck) {
 	h.mu.Lock()
 	h.checks = append(h.checks, check)
@@ -45,6 +47,8 @@ func (h *HealthServer) AddCheck(check HealthCheck) {
 }
 
 // SetReady sets the readiness status.
+//
+//	health.SetReady(true)
 func (h *HealthServer) SetReady(ready bool) {
 	h.mu.Lock()
 	h.ready = ready
@@ -52,6 +56,8 @@ func (h *HealthServer) SetReady(ready bool) {
 }
 
 // Start begins serving health check endpoints.
+//
+//	err := health.Start()
 func (h *HealthServer) Start() error {
 	mux := http.NewServeMux()
 
@@ -103,6 +109,8 @@ func (h *HealthServer) Start() error {
 }
 
 // Stop gracefully shuts down the health server.
+//
+//	err := health.Stop(ctx)
 func (h *HealthServer) Stop(ctx context.Context) error {
 	if h.server == nil {
 		return nil
@@ -111,6 +119,8 @@ func (h *HealthServer) Stop(ctx context.Context) error {
 }
 
 // Addr returns the actual address the server is listening on.
+//
+//	addr := health.Addr() // e.g. "127.0.0.1:9090"
 func (h *HealthServer) Addr() string {
 	if h.listener != nil {
 		return h.listener.Addr().String()

registry.go

@@ -51,6 +51,8 @@ func DefaultRegistry() *Registry {
 // Register writes a daemon entry to the registry directory.
 // If Started is zero, it is set to the current time.
 // The directory is created if it does not exist.
+//
+//	err := registry.Register(process.DaemonEntry{Code: "agent", Daemon: "core-agent", PID: os.Getpid()})
 func (r *Registry) Register(entry DaemonEntry) error {
 	if entry.Started.IsZero() {
 		entry.Started = time.Now()
@@ -72,6 +74,8 @@ func (r *Registry) Register(entry DaemonEntry) error {
 }
 
 // Unregister removes a daemon entry from the registry.
+//
+//	err := registry.Unregister("agent", "core-agent")
 func (r *Registry) Unregister(code, daemon string) error {
 	if err := coreio.Local.Delete(r.entryPath(code, daemon)); err != nil {
 		return core.E("registry.unregister", "failed to delete entry file", err)
@@ -81,6 +85,8 @@ func (r *Registry) Unregister(code, daemon string) error {
 
 // Get reads a single daemon entry and checks whether its process is alive.
 // If the process is dead, the stale file is removed and (nil, false) is returned.
+//
+//	entry, alive := registry.Get("agent", "core-agent")
 func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool) {
 	path := r.entryPath(code, daemon)
 
@@ -104,6 +110,8 @@ func (r *Registry) Get(code, daemon string) (*DaemonEntry, bool) {
 }
 
 // List returns all alive daemon entries, pruning any with dead PIDs.
+//
+//	entries, err := registry.List()
 func (r *Registry) List() ([]DaemonEntry, error) {
 	if !coreio.Local.Exists(r.dir) {
 		return nil, nil

service.go

@@ -270,6 +270,8 @@ func (s *Service) streamOutput(proc *ManagedProcess, r streamReader, stream Stre
 }
 
 // Get returns a process by ID.
+//
+//	proc, err := svc.Get("abc123")
 func (s *Service) Get(id string) (*ManagedProcess, error) {
 	r := s.managed.Get(id)
 	if !r.OK {
@@ -279,6 +281,8 @@ func (s *Service) Get(id string) (*ManagedProcess, error) {
 }
 
 // List returns all processes.
+//
+//	procs := svc.List()
 func (s *Service) List() []*ManagedProcess {
 	result := make([]*ManagedProcess, 0, s.managed.Len())
 	s.managed.Each(func(_ string, proc *ManagedProcess) {
@@ -288,6 +292,8 @@ func (s *Service) List() []*ManagedProcess {
 }
 
 // Running returns all currently running processes.
+//
+//	active := svc.Running()
 func (s *Service) Running() []*ManagedProcess {
 	result := make([]*ManagedProcess, 0, s.managed.Len())
 	s.managed.Each(func(_ string, proc *ManagedProcess) {
@@ -299,6 +305,8 @@ func (s *Service) Running() []*ManagedProcess {
 }
 
 // Kill terminates a process by ID.
+//
+//	err := svc.Kill("abc123")
 func (s *Service) Kill(id string) error {
 	proc, err := s.Get(id)
 	if err != nil {
@@ -312,6 +320,8 @@ func (s *Service) Kill(id string) error {
 }
 
 // Remove removes a completed process from the list.
+//
+//	err := svc.Remove("abc123")
 func (s *Service) Remove(id string) error {
 	proc, err := s.Get(id)
 	if err != nil {
@@ -328,6 +338,8 @@ func (s *Service) Remove(id string) error {
 }
 
 // Clear removes all completed processes.
+//
+//	svc.Clear()
 func (s *Service) Clear() {
 	ids := make([]string, 0)
 	s.managed.Each(func(id string, proc *ManagedProcess) {
@@ -341,6 +353,8 @@ func (s *Service) Clear() {
 }
 
 // Output returns the captured output of a process.
+//
+//	output, err := svc.Output("abc123")
 func (s *Service) Output(id string) (string, error) {
 	proc, err := s.Get(id)
 	if err != nil {
@@ -472,6 +486,8 @@ func (s *Service) runCommand(ctx context.Context, opts RunOptions) core.Result {
 }
 
 // Signal sends a signal to the process.
+//
+//	err := proc.Signal(syscall.SIGTERM)
 func (p *ManagedProcess) Signal(sig os.Signal) error {
 	p.mu.Lock()
 	defer p.mu.Unlock()