feat: complete per-file examples — 54 examples across 17 files

New example files: entitlement, task, lock, log, drive, config,
command, info. Every major source file now has a dedicated
*_example_test.go with compilable, tested examples.

561 tests, 84.8% coverage.

Co-Authored-By: Virgil <virgil@lethean.io>

command_example_test.go

@@ -0,0 +1,41 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleCore_Command_register() {
+	c := New()
+	c.Command("deploy/to/homelab", Command{
+		Description: "Deploy to homelab",
+		Action: func(opts Options) Result {
+			return Result{Value: "deployed", OK: true}
+		},
+	})
+
+	fmt.Println(c.Command("deploy/to/homelab").OK)
+	// Output: true
+}
+
+func ExampleCore_Command_managed() {
+	c := New()
+	c.Command("serve", Command{
+		Action:  func(_ Options) Result { return Result{OK: true} },
+		Managed: "process.daemon",
+	})
+
+	cmd := c.Command("serve").Value.(*Command)
+	fmt.Println(cmd.IsManaged())
+	// Output: true
+}
+
+func ExampleCore_Commands() {
+	c := New()
+	c.Command("deploy", Command{Action: func(_ Options) Result { return Result{OK: true} }})
+	c.Command("test", Command{Action: func(_ Options) Result { return Result{OK: true} }})
+
+	fmt.Println(c.Commands())
+	// Output: [deploy test]
+}

config_example_test.go

@@ -0,0 +1,42 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleConfig_Set() {
+	c := New()
+	c.Config().Set("database.host", "localhost")
+	c.Config().Set("database.port", 5432)
+
+	fmt.Println(c.Config().String("database.host"))
+	fmt.Println(c.Config().Int("database.port"))
+	// Output:
+	// localhost
+	// 5432
+}
+
+func ExampleConfig_Enable() {
+	c := New()
+	c.Config().Enable("dark-mode")
+	c.Config().Enable("beta-features")
+
+	fmt.Println(c.Config().Enabled("dark-mode"))
+	fmt.Println(c.Config().EnabledFeatures())
+	// Output:
+	// true
+	// [dark-mode beta-features]
+}
+
+func ExampleConfigVar() {
+	v := NewConfigVar(42)
+	fmt.Println(v.Get(), v.IsSet())
+
+	v.Unset()
+	fmt.Println(v.Get(), v.IsSet())
+	// Output:
+	// 42 true
+	// 0 false
+}

drive_example_test.go

@@ -0,0 +1,36 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleDrive_New() {
+	c := New()
+	c.Drive().New(NewOptions(
+		Option{Key: "name", Value: "forge"},
+		Option{Key: "transport", Value: "https://forge.lthn.ai"},
+	))
+
+	fmt.Println(c.Drive().Has("forge"))
+	fmt.Println(c.Drive().Names())
+	// Output:
+	// true
+	// [forge]
+}
+
+func ExampleDrive_Get() {
+	c := New()
+	c.Drive().New(NewOptions(
+		Option{Key: "name", Value: "charon"},
+		Option{Key: "transport", Value: "http://10.69.69.165:9101"},
+	))
+
+	r := c.Drive().Get("charon")
+	if r.OK {
+		h := r.Value.(*DriveHandle)
+		fmt.Println(h.Transport)
+	}
+	// Output: http://10.69.69.165:9101
+}

entitlement_example_test.go

@@ -0,0 +1,53 @@
+package core_test
+
+import (
+	"context"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleEntitlement_UsagePercent() {
+	e := Entitlement{Limit: 100, Used: 75}
+	fmt.Println(e.UsagePercent())
+	// Output: 75
+}
+
+func ExampleCore_SetEntitlementChecker() {
+	c := New()
+	c.SetEntitlementChecker(func(action string, qty int, _ context.Context) Entitlement {
+		limits := map[string]int{"social.accounts": 5, "ai.credits": 100}
+		usage := map[string]int{"social.accounts": 3, "ai.credits": 95}
+
+		limit, ok := limits[action]
+		if !ok {
+			return Entitlement{Allowed: false, Reason: "not in package"}
+		}
+		used := usage[action]
+		remaining := limit - used
+		if qty > remaining {
+			return Entitlement{Allowed: false, Limit: limit, Used: used, Remaining: remaining, Reason: "limit exceeded"}
+		}
+		return Entitlement{Allowed: true, Limit: limit, Used: used, Remaining: remaining}
+	})
+
+	fmt.Println(c.Entitled("social.accounts", 2).Allowed)
+	fmt.Println(c.Entitled("social.accounts", 5).Allowed)
+	fmt.Println(c.Entitled("ai.credits").NearLimit(0.9))
+	// Output:
+	// true
+	// false
+	// true
+}
+
+func ExampleCore_RecordUsage() {
+	c := New()
+	var recorded string
+	c.SetUsageRecorder(func(action string, qty int, _ context.Context) {
+		recorded = fmt.Sprintf("%s:%d", action, qty)
+	})
+
+	c.RecordUsage("ai.credits", 10)
+	fmt.Println(recorded)
+	// Output: ai.credits:10
+}

info_example_test.go

@@ -0,0 +1,18 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleEnv() {
+	fmt.Println(Env("OS"))   // e.g. "darwin"
+	fmt.Println(Env("ARCH")) // e.g. "arm64"
+}
+
+func ExampleEnvKeys() {
+	keys := EnvKeys()
+	fmt.Println(len(keys) > 0)
+	// Output: true
+}

lock_example_test.go

@@ -0,0 +1,19 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleCore_Lock() {
+	c := New()
+	lock := c.Lock("drain")
+	lock.Mutex.Lock()
+	fmt.Println("locked")
+	lock.Mutex.Unlock()
+	fmt.Println("unlocked")
+	// Output:
+	// locked
+	// unlocked
+}

log_example_test.go

@@ -0,0 +1,15 @@
+package core_test
+
+import . "dappco.re/go/core"
+
+func ExampleInfo() {
+	Info("server started", "port", 8080)
+}
+
+func ExampleWarn() {
+	Warn("deprecated", "feature", "old-api")
+}
+
+func ExampleSecurity() {
+	Security("access denied", "user", "unknown", "action", "admin.nuke")
+}

task_example_test.go

@@ -0,0 +1,51 @@
+package core_test
+
+import (
+	"context"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleTask_Run() {
+	c := New()
+	var order string
+
+	c.Action("step.a", func(_ context.Context, _ Options) Result {
+		order += "a"
+		return Result{Value: "from-a", OK: true}
+	})
+	c.Action("step.b", func(_ context.Context, opts Options) Result {
+		order += "b"
+		input := opts.Get("_input")
+		if input.OK {
+			return Result{Value: "got:" + input.Value.(string), OK: true}
+		}
+		return Result{OK: true}
+	})
+
+	c.Task("pipe", Task{
+		Steps: []Step{
+			{Action: "step.a"},
+			{Action: "step.b", Input: "previous"},
+		},
+	})
+
+	r := c.Task("pipe").Run(context.Background(), c, NewOptions())
+	fmt.Println(order)
+	fmt.Println(r.Value)
+	// Output:
+	// ab
+	// got:from-a
+}
+
+func ExampleCore_PerformAsync() {
+	c := New()
+	c.Action("bg.work", func(_ context.Context, _ Options) Result {
+		return Result{Value: "done", OK: true}
+	})
+
+	r := c.PerformAsync("bg.work", NewOptions())
+	fmt.Println(HasPrefix(r.Value.(string), "id-"))
+	// Output: true
+}