Add "API-Reference"

API-Reference.-.md

@@ -0,0 +1,185 @@
+# API Reference
+
+All methods are on the `*Store` type. Errors are wrapped with context (e.g. `store.Get: config/theme: store: not found`).
+
+## Constructor
+
+### New
+
+```go
+func New(dbPath string) (*Store, error)
+```
+
+Creates a new Store backed by a SQLite database at `dbPath`. Enables WAL journal mode for concurrent read access and creates the `kv` table if it does not exist.
+
+Use `":memory:"` for an ephemeral in-memory database (ideal for tests).
+
+```go
+// File-backed store
+s, err := store.New("/var/lib/myapp/data.db")
+
+// In-memory store for tests
+s, err := store.New(":memory:")
+```
+
+**Errors:** Returns an error if the database cannot be opened, WAL mode cannot be enabled, or the schema cannot be created.
+
+---
+
+## Close
+
+```go
+func (s *Store) Close() error
+```
+
+Closes the underlying SQLite database connection. Always defer this after creating a store.
+
+```go
+s, err := store.New("app.db")
+if err != nil {
+    log.Fatal(err)
+}
+defer s.Close()
+```
+
+---
+
+## Get
+
+```go
+func (s *Store) Get(group, key string) (string, error)
+```
+
+Retrieves a single value by group and key.
+
+```go
+val, err := s.Get("config", "theme")
+if errors.Is(err, store.ErrNotFound) {
+    // Key does not exist
+}
+```
+
+**Returns:** The value string, or an error wrapping `ErrNotFound` if the key does not exist in the given group.
+
+---
+
+## Set
+
+```go
+func (s *Store) Set(group, key, value string) error
+```
+
+Stores a value under the given group and key. Uses upsert semantics: if the key already exists in the group, its value is overwritten.
+
+```go
+err := s.Set("config", "theme", "dark")
+err = s.Set("config", "theme", "light")  // Overwrites "dark"
+```
+
+**Errors:** Returns an error only on database failure.
+
+---
+
+## Delete
+
+```go
+func (s *Store) Delete(group, key string) error
+```
+
+Removes a single key from a group. No error is returned if the key does not exist (the DELETE is a no-op).
+
+```go
+err := s.Delete("config", "theme")
+```
+
+---
+
+## DeleteGroup
+
+```go
+func (s *Store) DeleteGroup(group string) error
+```
+
+Removes all keys belonging to a group. Useful for clearing an entire namespace.
+
+```go
+err := s.DeleteGroup("cache")
+```
+
+---
+
+## GetAll
+
+```go
+func (s *Store) GetAll(group string) (map[string]string, error)
+```
+
+Returns all key-value pairs in a group as a map. Returns an empty (non-nil) map if the group has no keys.
+
+```go
+all, err := s.GetAll("config")
+// all = map[string]string{"theme": "dark", "lang": "en-GB"}
+
+empty, err := s.GetAll("nonexistent")
+// empty = map[string]string{}
+```
+
+---
+
+## Count
+
+```go
+func (s *Store) Count(group string) (int, error)
+```
+
+Returns the number of keys in a group. Returns 0 for groups that do not exist or have no keys.
+
+```go
+n, err := s.Count("config")
+fmt.Printf("%d keys
+", n)
+```
+
+---
+
+## Render
+
+```go
+func (s *Store) Render(tmplStr, group string) (string, error)
+```
+
+Loads all key-value pairs from a group and executes a Go `text/template` against them. The template receives a `map[string]string` where keys are the store keys and values are the store values.
+
+See [[Template-Rendering]] for detailed examples and template syntax.
+
+```go
+tmpl := `{"pool":"{{ .pool }}","wallet":"{{ .wallet }}"}`
+out, err := s.Render(tmpl, "user")
+// out = `{"pool":"pool.lthn.io:3333","wallet":"iz..."}`
+```
+
+**Errors:** Returns an error if the database query fails, the template cannot be parsed, or template execution fails (e.g. referencing a key that does not exist without using `index`).
+
+---
+
+## ErrNotFound
+
+```go
+var ErrNotFound = errors.New("store: not found")
+```
+
+Sentinel error returned (wrapped) by `Get` when the requested group/key combination does not exist. Use `errors.Is` to check:
+
+```go
+val, err := s.Get("config", "missing")
+if errors.Is(err, store.ErrNotFound) {
+    // Handle missing key
+}
+```
+
+The full error message includes the group and key: `store.Get: config/missing: store: not found`.
+
+## Related
+
+- [[Home]] — Package overview, installation, schema diagram
+- [[Template-Rendering]] — Go template syntax and Render examples