Add local CLI auth surface

Author: robertohluna

README.md

@@ -526,6 +526,18 @@ mix compile
 mix optimal.reality_check
 ```
 
+Build the local `./optimal` command wrapper:
+
+```bash
+mix escript.build
+./optimal --help
+./optimal reality-check
+```
+
+That wrapper is for source checkouts. It delegates to `mix optimal.*` so native
+database dependencies load correctly. For production/API deployment, use the OTP
+release or container shape instead of treating the escript as the server binary.
+
 Create a markdown-operable workspace:
 
 ```bash
@@ -537,6 +549,15 @@ mix optimal.topology --workspace default:my-workspace
 Use `optimal.initiate` when starting from a messy dump. Use `optimal.setup` when
 you already know the workspace and starter Nodes you want.
 
+Local CLI commands are trusted local commands against the configured store. For
+apps, MCP servers, remote agents, or scripts that connect over HTTP/API, mint a
+scoped API key:
+
+```bash
+mix optimal.auth mint --name "Business OS" --workspace default:my-workspace
+mix optimal.auth env --name "Local Agent" --workspace default:my-workspace
+```
+
 Render wiki/export projections:
 
 ```bash

docs/guides/agent-cli-sop.md

@@ -167,6 +167,52 @@ preserve the dump
 This is how the engine handles noisy human language without corrupting the
 workspace.
 
+## Local CLI Auth Model
+
+The local CLI is a trusted local control surface.
+
+```text
+human/agent on the same machine
+  -> runs mix optimal.* or the local ./optimal wrapper
+  -> reads/writes the local configured store
+  -> records actor/service metadata where the command supports it
+```
+
+That path does not require an API key because it is equivalent to a developer
+or local agent running commands on the machine that owns the workspace.
+
+Use API keys when something connects over HTTP/API, MCP, a remote script, an
+external app, or a remote agent:
+
+```text
+external app / MCP server / remote agent / automation
+  -> gets scoped API key
+  -> sends Authorization: Bearer <key> or X-API-Key
+  -> API verifies tenant, principal, scopes, and workspace scope
+  -> backend applies lifecycle and audit rules
+```
+
+Create a key locally:
+
+```bash
+mix optimal.auth mint --name "Business OS" --workspace default:my-workspace
+mix optimal.auth env --name "Local Agent" --workspace default:my-workspace
+mix optimal.auth list
+mix optimal.auth revoke <key-id>
+```
+
+If the local `./optimal` wrapper was built in the checkout, the same commands
+can be run through it:
+
+```bash
+./optimal auth mint --name "Business OS" --workspace default:my-workspace
+./optimal auth env --name "Local Agent" --workspace default:my-workspace
+```
+
+Do not put raw API keys in markdown, Source Packages, package manifests, or
+Context Packages. Store them in shell environment, a local secret store, or the
+deployment secret manager.
+
 ## Retrieval Pattern
 
 Agents should request context from the engine, not scrape random files first.

docs/guides/installation-and-deployment.md

@@ -46,6 +46,26 @@ mix compile
 mix optimal.reality_check
 ```
 
+Build the local `./optimal` command wrapper:
+
+```bash
+mix escript.build
+./optimal --help
+```
+
+The wrapper is for source checkouts. It delegates to the same backend commands
+as `mix optimal.*` so native dependencies such as SQLite load through the normal
+Mix build. For example:
+
+```bash
+./optimal reality-check
+./optimal setup my-workspace --name "My Workspace"
+./optimal topology --workspace default:my-workspace
+```
+
+Do not treat the escript as the production database/server binary. For a
+long-running API or team runtime, use the OTP release or container deployment.
+
 Create a known structure:
 
 ```bash
@@ -110,6 +130,39 @@ stale context refresh schedule
 projection rebuild procedure
 ```
 
+## Local Auth Vs Remote Auth
+
+Local CLI commands are trusted local commands. They run on the machine that owns
+the checkout/store and do not need an API key:
+
+```text
+mix optimal.setup ...
+mix optimal.initiate ...
+mix optimal.topology ...
+mix optimal.rag ...
+```
+
+Anything connecting over HTTP/API, MCP, app integration, remote script, or
+remote agent should use a scoped API key:
+
+```bash
+mix optimal.auth mint --name "Business OS" --tenant default --workspace default:my-workspace
+mix optimal.auth env --name "Local Agent" --workspace default:my-workspace
+mix optimal.auth list
+mix optimal.auth revoke <key-id>
+```
+
+API clients send the token as either:
+
+```text
+Authorization: Bearer <token>
+X-API-Key: <token>
+```
+
+For production, set API auth to required and store keys in a secret manager or
+environment variables. Do not store keys in markdown, Source Packages, Context
+Packages, or generated packages.
+
 ## Environment Variables
 
 The default runtime reads these paths:
@@ -120,6 +173,7 @@ OPTIMAL_ENGINE_DB            SQLite path for local runtime
 OPTIMAL_ENGINE_CACHE         cache path
 OPTIMAL_ENGINE_TOPOLOGY      local workspace config path
 OPTIMAL_ENGINE_TOPOLOGY_FULL root topology config path
+OPTIMAL_ENGINE_API_KEY       API key used by external clients/agents
 OLLAMA_HOST                  local model server URL
 OPTIMAL_VLM_MODEL            local visual model name for configured adapters
 ```

docs/guides/mix-tasks.md

@@ -105,6 +105,7 @@ mix optimal.wiki check node-first-project --workspace default:my-workspace
 | Task | Purpose |
 | --- | --- |
 | `mix optimal.connector` | Connector registry/sync operations. |
+| `mix optimal.auth` | Mint, list, revoke, and delete API keys for apps, MCP servers, remote agents, and scripts. |
 | `mix optimal.api` | Start the HTTP API. |
 | `mix optimal.graph_ui` | Launch the graph visualizer against a running API. |
 | `mix optimal.compliance` | Compliance workflows. |
@@ -114,6 +115,15 @@ mix optimal.wiki check node-first-project --workspace default:my-workspace
 Tool, MCP, API, connector, script, and model outputs should flow through
 governance before becoming evidence, observations, Claims, or Facts.
 
+Local CLI use is trusted local access to the configured store. Use API keys for
+HTTP/API clients, MCP servers, remote agents, external apps, and automation:
+
+```bash
+mix optimal.auth mint --name "Business OS" --workspace default:my-workspace
+mix optimal.auth env --name "Local Agent" --workspace default:my-workspace
+mix optimal.auth list
+```
+
 ## Evaluation, Health, And Verification
 
 | Task | Purpose |
@@ -170,4 +180,3 @@ Default local data shape:
 .optimal/cache/
 workspace folders and markdown projections
 ```
-