From d3e2f7da1ed1335cacd92ff2ec48e1a24af9d227 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 19:29:17 +0000
Subject: [PATCH] docs(cgo): add agent-oriented package usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 doc.go | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 doc.go

diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..d1e33df
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,23 @@
+// Package cgo is a focused harness for safe Go-to-C interop helpers.
+//
+// Common usage:
+//
+//	buffer := NewBuffer(32)
+//	n := buffer.CopyFrom([]byte("agent"))
+//	defer buffer.Free()
+//
+//	err := Call(unsafe.Pointer(C.some_function), buffer.Ptr(), SizeT(n))
+//	if err != nil {
+//		// handle mapped C errno
+//	}
+//
+//	scope := NewScope()
+//	defer scope.Close()
+//	cString := scope.CString("hello")
+//	buffer := scope.Buffer(16)
+//
+//	if err := Call(unsafe.Pointer(C.another_function), cString, buffer.Ptr()); err != nil {
+//		// scope.Close() will release C string + buffer
+//	}
+package cgo
+