Refactor master package for improved clarity and maintainability

- Enhanced documentation throughout the master package, including function descriptions and struct field comments for better understanding.
- Updated `startPeriodicTasks` to use `reloadInterval` for maintenance tasks, ensuring state backups and instance restarts are performed at appropriate intervals.
- Introduced `saveState` and `saveStateAsync` methods for better state management, allowing for non-blocking state persistence.
- Improved instance handling in REST API, including better validation and error handling in `handleInstances`, `handlePatchInstance`, and `handlePutInstance`.
- Added support for CORS headers in API responses to facilitate cross-origin requests from local clients.
- Enhanced logging and error handling across various methods to improve observability and debugging capabilities.
- Updated `linuxSysInfo` to collect lightweight metrics directly from `/proc`, ensuring compatibility across platforms.
- Improved instance lifecycle management, ensuring that state transitions are handled safely and consistently.

Author: yosebyte

README.md

@@ -1,91 +1,40 @@
-<p align="center">
-  <img src="assets/openctrl.png" alt="OpenCtrl banner" width="50%">
-</p>
-
-<p align="center">
-  <a href="docs/master.md"><img alt="API v2" src="https://img.shields.io/badge/API-v2-14b8a6?style=flat-square"></a>
-  <a href="docs/master.md"><img alt="Events SSE" src="https://img.shields.io/badge/events-SSE-f59e0b?style=flat-square"></a>
-  <img alt="Go 1.26.4" src="https://img.shields.io/badge/Go-1.26.4-00ADD8?style=flat-square&amp;logo=go&amp;logoColor=white">
-  <a href="LICENSE"><img alt="License BSD 3-Clause" src="https://img.shields.io/badge/license-BSD--3--Clause-0f172a?style=flat-square"></a>
-</p>
-
-OpenCtrl is a focused control-plane master for supervising URL-defined
-instances. It stores instance definitions, launches a compatible runtime binary
-for each managed instance, exposes a versioned REST API, and streams live
-lifecycle, log, and metric updates over Server-Sent Events.
-
-It is intentionally narrow: the master owns orchestration, persistence,
-authentication, and observability; runtime binaries own protocol-specific work.
-
-## Contents
-
-- [Highlights](#highlights)
-- [Architecture](#architecture)
-- [Quick Start](#quick-start)
-- [Master URL](#master-url)
-- [API Surface](#api-surface)
-- [Runtime Contract](#runtime-contract)
-- [State and Security](#state-and-security)
-- [Release](#release)
-- [Documentation](#documentation)
-
-## Highlights
-
-| Capability | What it provides |
-| --- | --- |
-| URL-defined instances | Every managed workload is represented by one URL and one generated instance ID. |
-| Process supervision | The master starts, stops, restarts, and deletes child processes through a stable runtime contract. |
-| Versioned control API | REST endpoints are served under `/api/v2` or a custom versioned prefix. |
-| Live event stream | SSE publishes initial state, lifecycle changes, child logs, metric checkpoints, deletions, and shutdown events. |
-| Durable local state | Instance definitions and the API key are persisted beside the executable with a backup file. |
-| Runtime neutrality | The master does not special-case child protocols; compatible binaries validate and execute their own URLs. |
-| TLS-ready operation | HTTP, self-signed TLS, and file-backed TLS certificate modes are selected from the master URL. |
-
-## Architecture
-
-```mermaid
-flowchart LR
-  client["API clients"]
-  events["SSE subscribers"]
-  master["OpenCtrl master"]
-  state["gob state"]
-  runtime["runtime binary"]
-  instA["instance URL"]
-  instB["instance URL"]
-
-  client -->|"REST + X-API-Key"| master
-  master -->|"event: instance"| events
-  master <-->|"load / save"| state
-  master -->|"spawn <runtime> <url>"| runtime
-  runtime --> instA
-  runtime --> instB
-```
+# OpenCtrl
+
+OpenCtrl is an advanced control-plane master for URL-defined runtime instances.
 
-The master process provides the control plane. Child processes stay in the
-foreground, emit logs and optional checkpoints, and exit when the master stops
-them.
+It stores instance definitions, supervises child processes, exposes a versioned
+HTTP API, and streams lifecycle, log, and metric updates over Server-Sent
+Events. The master stays generic: orchestration belongs here; protocol behavior
+belongs to the runtime binary.
 
-## Quick Start
+## Design
 
-Build the master:
+- URL-first instance configuration
+- Runtime-neutral process supervision
+- Versioned REST API under `/api/v2`
+- Server-Sent Events for live state
+- Local durable state with backup
+- HTTP, self-signed TLS, or certificate-backed TLS
+
+## Build
 
 ```sh
 go build -trimpath -o ./bin/openctrl ./cmd/openctrl
 ```
 
-Start a local control plane:
+## Run
 
 ```sh
 ./bin/openctrl 'master://127.0.0.1:8080'
 ```
 
-The master prints an API key on startup:
+On first start, OpenCtrl prints an API key:
 
 ```text
 Master.run: API key created: <api-key>
 ```
 
-Use the key with the versioned API:
+Use it with the API:
 
 ```sh
 BASE='http://127.0.0.1:8080/api/v2'
@@ -95,7 +44,8 @@ curl -H "X-API-Key: ${API_KEY}" "${BASE}/info"
 curl -H "X-API-Key: ${API_KEY}" "${BASE}/instances"
 ```
 
-Run managed instances through a compatible runtime binary:
+To supervise non-`master` instance schemes, point the master at a compatible
+runtime binary:
 
 ```sh
 ./bin/openctrl 'master://127.0.0.1:8080?bin=/opt/openctrl/runtime'
@@ -116,109 +66,79 @@ curl -X POST "${BASE}/instances" \
 master://<host>:<port>[/prefix][?<query>]
 ```
 
-The host and port become the listen address. The optional path becomes the API
-prefix, and the API version is appended automatically.
+The host and port become the listen address. The path becomes the API prefix,
+with the API version appended automatically.
 
-| Master URL | API base |
+| URL | API base |
 | --- | --- |
 | `master://127.0.0.1:8080` | `http://127.0.0.1:8080/api/v2` |
 | `master://127.0.0.1:8080/control` | `http://127.0.0.1:8080/control/v2` |
 | `master://127.0.0.1:8443?tls=1` | `https://127.0.0.1:8443/api/v2` |
 
-| Parameter | Values | Default | Purpose |
-| --- | --- | --- | --- |
-| `tls` | `0`, `1`, `2` | `0` | Select HTTP, self-signed TLS, or certificate-backed TLS. |
-| `crt` | file path | empty | Certificate file used with `tls=2`. |
-| `key` | file path | empty | Private key file used with `tls=2`. |
-| `bin` | file path | current executable | Runtime binary used to launch managed instances. |
+| Query | Description |
+| --- | --- |
+| `tls=0` | Plain HTTP. |
+| `tls=1` | Self-signed TLS. |
+| `tls=2&crt=<path>&key=<path>` | Certificate-backed TLS. |
+| `bin=<path>` | Runtime binary used for managed instances. |
 
-## API Surface
+## API
 
-All protected requests must include:
+All protected requests require:
 
 ```text
 X-API-Key: <api-key>
 ```
 
-Core endpoints:
-
-| Method | Path | Description |
+| Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `/info` | Return master identity, runtime configuration, uptime, and system metrics. |
+| `GET` | `/info` | Read master identity and runtime information. |
 | `POST` | `/info` | Set the master alias. |
-| `GET` | `/instances` | Return all instances, including the internal API-key instance. |
-| `POST` | `/instances` | Create and asynchronously start an instance. |
-| `GET` | `/instances/{id}` | Return one instance. |
-| `PATCH` | `/instances/{id}` | Update metadata, restart policy, or lifecycle action. |
-| `PUT` | `/instances/{id}` | Replace the instance URL and restart the instance. |
-| `DELETE` | `/instances/{id}` | Stop and delete the instance. |
-| `GET` | `/events` | Open the Server-Sent Events stream. |
-| `GET` | `/tcping?target=host:port` | Test TCP reachability from the master process. |
-
-Lifecycle actions accepted by `PATCH /instances/{id}`:
-
-| Action | Effect |
-| --- | --- |
-| `start` | Start a stopped child process. |
-| `stop` | Stop an active child process. |
-| `restart` | Stop and start the child process. |
-| `reset` | Reset runtime byte counters. |
+| `GET` | `/instances` | List instances. |
+| `POST` | `/instances` | Create and start an instance. |
+| `GET` | `/instances/{id}` | Read one instance. |
+| `PATCH` | `/instances/{id}` | Update metadata, policy, or lifecycle action. |
+| `PUT` | `/instances/{id}` | Replace the instance URL. |
+| `DELETE` | `/instances/{id}` | Stop and delete an instance. |
+| `GET` | `/events` | Subscribe to instance events. |
+| `GET` | `/tcping?target=host:port` | Test TCP reachability. |
+
+`PATCH /instances/{id}` accepts `start`, `stop`, `restart`, and `reset`.
 
-SSE frames use the event name `instance`:
+SSE messages use the event name `instance`:
 
 ```text
 event: instance
 data: {"type":"update","time":"2026-06-08T12:00:00Z","instance":{...},"logs":""}
 ```
 
-Event payload types are `initial`, `create`, `update`, `delete`, `log`, and
+Event types are `initial`, `create`, `update`, `delete`, `log`, and
 `shutdown`.
 
 ## Runtime Contract
 
-OpenCtrl supervises runtime binaries with a small process contract:
+OpenCtrl launches managed instances as:
 
 ```text
 <runtime-binary> <instance-url>
 ```
 
-For non-`master` instance schemes, point `bin` at a binary that understands
-those schemes. The master treats child URLs as opaque runtime configuration.
-
-Runtime binaries MUST:
-
-- accept the full instance URL as the first positional argument;
-- reject invalid configuration before starting long-running work;
-- stay in the foreground while the instance is active;
-- handle termination and exit within the master's 5-second grace period when
-  possible;
-- return a non-zero exit code for failures that should place the instance in
-  `error`;
-- avoid printing secrets from URLs, headers, keys, or tokens.
-
-Runtime binaries SHOULD:
+Runtime binaries must accept the full instance URL as the first argument, stay
+in the foreground while active, reject invalid configuration before long-running
+work starts, handle termination promptly, and return a non-zero exit code for
+failures that should move the instance to `error`.
 
-- emit newline-delimited logs to stdout or stderr;
-- emit checkpoints after the service is ready when metrics are available;
-- keep byte counters monotonic for the life of the process.
-
-Runtime binaries MAY:
-
-- define their own URL schemes and query parameters;
-- omit checkpoints when metrics are not meaningful;
-- print ordinary operational logs that should be visible to API clients.
-
-Checkpoint format:
+Runtime binaries should write newline-delimited logs to stdout or stderr. They
+may emit checkpoints for metrics:
 
 ```text
 CHECK_POINT|MODE=<n>|PING=<n>ms|POOL=<n>|TCPS=<n>|UDPS=<n>|TCPRX=<bytes>|TCPTX=<bytes>|UDPRX=<bytes>|UDPTX=<bytes>
 ```
 
-Non-checkpoint child output is forwarded to stdout and published as `log`
-events. If a line contains the substring `ERROR`, the instance is marked
-`error`.
+Non-checkpoint output is forwarded to stdout and published as `log` events. A
+line containing `ERROR` marks the instance as `error`.
 
-## State and Security
+## State
 
 State is stored beside the executable:
 
@@ -227,37 +147,23 @@ State is stored beside the executable:
 <executable-directory>/gob/openctrl.gob.backup
 ```
 
-Operational notes:
-
-- protect the API key printed by the master;
-- protect the state directory because `openctrl.gob` stores the API key;
-- use `tls=2` with a trusted certificate outside local-only deployments;
-- use a trusted `bin` path because managed instances execute that binary;
-- treat instance URLs as secrets when they contain credentials or tokens;
-- account for permissive CORS headers when exposing the API across origins.
+Protect the API key, state directory, runtime binary path, and instance URLs.
+Use `tls=2` for networked deployments.
 
 ## Release
 
-Build a local binary:
-
-```sh
-go build -trimpath -o ./bin/openctrl ./cmd/openctrl
-```
-
-Embed a version string:
-
 ```sh
 go build -trimpath \
   -ldflags="-s -w -X main.version=$VERSION" \
   -o ./bin/openctrl ./cmd/openctrl
 ```
 
-Tagged releases are built by GoReleaser for Darwin, FreeBSD, Linux, and
+Tagged releases are built with GoReleaser for Darwin, FreeBSD, Linux, and
 Windows on `amd64` and `arm64`.
 
 ## Documentation
 
-- [Master API and runtime contract](docs/master.md)
+See [docs/master.md](docs/master.md) for the full API and runtime contract.
 
 ## License
 

assets/openctrl.png

@@ -1,3 +1,8 @@
+// Command openctrl starts an OpenCtrl core from a URL-shaped configuration.
+//
+// The binary uses the URL scheme as the core selector. Today only master:// is
+// handled here; child protocol URLs are passed to managed child binaries by the
+// master package and are not parsed by the CLI entrypoint.
 package main
 
 import (
@@ -9,6 +14,10 @@ import (
 	"openctrl/v2/internal/master"
 )
 
+// version is replaced by release builds and remains "dev" for local builds.
+//
+// Keep this variable package-level so linker flags can override it without
+// changing code.
 var version = "dev"
 
 func main() {
@@ -17,6 +26,11 @@ func main() {
 	}
 }
 
+// start validates the CLI contract, parses the configuration URL, and runs the
+// selected core until it exits.
+//
+// The function is kept separate from main so tests can exercise argument
+// handling without terminating the process through os.Exit.
 func start(args []string) error {
 	if len(args) < 2 {
 		return fmt.Errorf("Main.start: missing configuration URL argument")
@@ -45,6 +59,11 @@ func start(args []string) error {
 	return nil
 }
 
+// exit prints the final runtime envelope before terminating with a non-zero
+// status code.
+//
+// Startup failures are intentionally one-line and machine-readable enough for
+// service managers while still being readable in a terminal.
 func exit(err error) {
 	errMsg := "none"
 	if err != nil {
@@ -57,6 +76,11 @@ func exit(err error) {
 	os.Exit(1)
 }
 
+// createCore maps the configuration scheme to the matching OpenCtrl core.
+//
+// This is the top-level dispatch boundary. Adding another core should happen
+// here, while adding another managed child protocol should generally not; child
+// protocols belong behind the master binary launch contract.
 func createCore(parsedURL *url.URL) (interface{ Run() }, error) {
 	switch parsedURL.Scheme {
 	case "master":