umans-gate 0.1.2 → 0.1.5

package/CHANGELOG.md

@@ -7,6 +7,205 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-07-14
+
+### Added
+
+- **Service persistence** (`umans-gate service`): install, uninstall,
+  start, stop, restart, status, and logs subcommands for running
+  umans-gate as a managed service that starts on boot and survives
+  restarts. Platform support:
+  - **Linux**: systemd user unit with `enable-linger` for boot-start
+    without login. `Restart=always` for crash recovery. `EnvironmentFile`
+    with `chmod 600` for API key (never inline).
+  - **macOS**: launchd LaunchAgent with `RunAtLoad=true` and
+    `KeepAlive=true` for unconditional restart (including dashboard
+    Restart button).
+  - **Windows**: Windows Service via NSSM (bundled in win32 platform
+    packages) with `SERVICE_AUTO_START` and 10 MB log rotation.
+  - Service PATH includes common runtime directories (`~/.bun/bin`,
+    `/opt/homebrew/bin`, `/usr/local/bin`, etc.) so the shebang resolves
+    in minimal-PATH service environments.
+  - Pre-install validation: config validation + port availability check
+    before writing service files.
+  - `npx` detection: `service install` from npx throws a clear error
+    with install instructions.
+  - `umans-gate update` now stops the service before updating and
+    restarts it after.
+  - `umans-gate uninstall` removes the service before cleaning up the
+    binary.
+  - Standalone binary self-update: `umans-gate update` auto-downloads
+    and replaces the binary from the latest GitHub Release (previously
+    only printed the URL).
+  - Dashboard Restart button works automatically when running as a
+    managed service.
+
+### Fixed
+
+- **launchd KeepAlive**: changed from conditional dict
+  (`SuccessfulExit=false, Crashed=true`) to unconditional `true` so
+  the dashboard Restart button works on macOS (previously only worked
+  on Linux via `Restart=always`).
+- **NSSM bundling**: `scripts/pack-npm.sh` now downloads and includes
+  `nssm.exe` in `@codegiveness/umans-gate-win32-*` packages so
+  `service install` works on Windows out of the box.
+- **ESM compliance**: replaced `require("node:fs")` / `require("node:net")`
+  calls in `installer.ts` and `updater.ts` with static imports.
+
+## [0.1.4] - 2026-07-14
+
+### Changed
+
+- **npm package naming**: platform binary packages renamed from unscoped
+  `umans-gate-<target>` to scoped `@codegiveness/umans-gate-<target>`
+  (e.g. `@codegiveness/umans-gate-darwin-arm64`). This follows the
+  industry convention used by `@esbuild/*`, `@rollup/rollup-*`, and
+  `@swc/core-*` for platform-specific binary packages. The main package
+  `umans-gate` is unchanged — `optionalDependencies` now reference the
+  scoped packages.
+- **npm-shim.cjs**: updated binary resolution paths to find
+  `@codegiveness/umans-gate-<target>` in `node_modules/@codegiveness/`.
+- **pack-npm.sh**: main package now includes README.md, LICENSE, and
+  CHANGELOG.md in the published files so npm registry pages display
+  the current README. Added keywords, homepage, and bugs fields to
+  the generated package.json.
+- **Release workflow**: publish step globs updated to
+  `release/npm/@codegiveness/umans-gate-*/`.
+
+### Fixed
+
+- **Release workflow awk extraction**: the awk command extracting per-version
+  release notes from CHANGELOG.md self-terminated on the matching header line,
+  producing only `## [VERSION] - DATE` as release notes. Fixed with corrected
+  awk logic that extracts the full version section body.
+- **CodeQL workflow efficiency**: added `paths-ignore` for markdown, docs, and
+  LICENSE files — CodeQL no longer runs on doc-only changes (matching CI
+  workflow behavior).
+- **CI workflow professionalization**: split monolithic CI into `quality` job
+  (typecheck + lint + build, 3-OS matrix: ubuntu/macos/windows) and `test` job
+  (ubuntu-only). Dropped Bun 1.1.0 from matrix (caused 158 test failures on
+  ubuntu). Added dashboard asset build step before tests (`src/embedded-assets.ts`
+  has static imports to gitignored `dashboard/dist/`). Replaced fragile
+  `sleep(900)` in test helper with health-check polling (`GET /health`).
+  Added `--timeout 30000` to test command (bunfig.toml `timeout` key is not
+  respected by Bun).
+- **Stuck master CI runs**: `cancel-in-progress` was only enabled for
+  `pull_request` events — a stuck `in_progress` run held the concurrency
+  group lock indefinitely, blocking all master push runs (stayed `pending`
+  with 0 jobs). Fixed: `cancel-in-progress: true` for all events.
+- **CI permissions hardening**: added `permissions: contents: read`
+  (least-privilege) and `timeout-minutes: 15` to both CI jobs.
+- **Dependabot hardening**: configured major-version bump ignores for
+  critical dependencies (commander, lru-cache, @types/bun, react, react-dom,
+  lucide-react, @types/react, @types/react-dom, vite, tailwind-merge, sonner,
+  typescript, @vitejs/plugin-react, @base-ui/react). Closed 13 dangerous
+  major-bump PRs.
+- **Release workflow**: `--notes-file CHANGELOG.md` dumped the entire
+  changelog as release notes — now extracts only the matching version
+  section. Added `--frozen-lockfile` to all `bun install` steps. Added
+  `timeout-minutes: 20` to prevent hung release builds.
+- **Test helper singleton race condition**: `echo-upstream.ts` used a
+  module-level singleton server that would break under parallel test
+  execution. Refactored to per-instance servers with explicit lifecycle
+  management.
+- **CI dependency drift**: added `--frozen-lockfile` to all `bun install`
+  steps in CI to fail fast on lockfile drift.
+- **Stale draft releases**: deleted 5 stale draft releases from failed
+  release workflow runs.
+
+### Added
+
+- **Branch protection** on master: requires 4 CI checks (Quality
+  ubuntu/macos/windows + Tests), 1 code-owner review, linear history,
+  stale review dismissal, no force pushes.
+- **Repo settings professionalized**: squash-only merges, delete-branch-on-merge,
+  wiki disabled, discussions disabled, secret scanning enabled, push protection
+  enabled.
+- **CODEOWNERS** (`.github/CODEOWNERS`) for automated review routing.
+- **Dependabot update grouping**: minor and patch updates are now grouped into
+  a single PR per ecosystem (root npm, dashboard npm) to reduce PR noise.
+
+### Changed
+
+- **ROADMAP**: updated Current State from v0.1.0 → v0.1.3 with npm distribution,
+  self-update, platform binaries, and provenance as completed items. Added
+  umans-open-stack cross-reference section.
+- **CONTRIBUTING.md / GOVERNANCE.md**: fixed `main` → `master` branch references.
+- **PRODUCT.md**: repositioned from "Bun-based" to "npm-installable (powered by Bun)"
+  with npm-first success criteria.
+- **TROUBLESHOOTING.md**: added npm-first user commands alongside dev commands.
+- **bug_report.yml**: added install method field (npm/npx/standalone/source); Bun
+  version now conditional on dev-from-source only.
+- **ci.yml**: removed stale `main` from branch triggers (only `master` exists).
+- **package.json keywords**: expanded from 10 → 18 keywords for npm discoverability
+  (added `claude`, `prompt-engineering`, `observability`, `sqlite`, `bun`,
+  `developer-tools`, `api-proxy`, `prompt-caching`).
+- **ARCHITECTURE.md**: added umans-open-stack cross-reference with
+  playbook-to-implementation mapping table.
+
+### Security
+
+- **SECURITY.md**: added account security section — 2FA requirement for npm
+  publisher + GitHub org admins, token rotation policy, quarterly access review.
+
+## [0.1.3] - 2026-07-14
+
+### Fixed
+
+- **npm package republish**: v0.1.2 was published via the now-deleted
+  `publish.yml` workflow (raw `npm publish` on repo `package.json`), which
+  shipped `dist/cli.js` with a `#!/usr/bin/env bun` shebang and `engines: { bun:
+  ">=1.1.0" }` — **requiring Bun to run**. This contradicted the "no
+  prerequisites" promise. v0.1.3 republishes via `release.yml` which runs
+  `scripts/pack-npm.sh` to produce the correct shim-based package (`bin:
+  npm-shim.cjs` + 6 platform `optionalDependencies` with pre-compiled
+  standalone binaries). `npx umans-gate` now works without Bun installed.
+- **ARCHITECTURE.md**: fixed wrong file paths in umans-open-stack mapping table
+  (`src/gate.ts` → `src/limiter/gate.ts`, `src/vision.ts` → `src/vision/handoff.ts`).
+- **README.md**: removed misleading `.env.example` reference (file only has
+  `UMANS_API_KEY=`; reworded to reference config variables generally).
+- **README.md**: fixed `vision_*` incorrectly listed as hot-reloadable — moved
+  to `restartRequired` (matches `RESTART_REQUIRED_FIELDS` in `src/config.ts`).
+- **SECURITY.md**: softened "SLSA Level 3 provenance" to "npm provenance
+  attestation" for accuracy and consistency with ROADMAP.md.
+- **docs/proxy-modifications.md**: fixed stale "24h TTL" → "7-day TTL" and
+  "transcoded to JPEG" → "transcoded to the configured format (PNG/JPEG)".
+- **AGENTS.md**: fixed stale config field names `target` (removed from config)
+  and `stamp_cache_ttl` (replaced by `stamp_claude_code_enabled`).
+- **CHANGELOG.md**: removed duplicate entries between [Unreleased] and [0.1.3].
+- **MAINTAINERS.md**: populated template with actual maintainer (`@codegiveness`).
+- **Startup banner** (`src/banner.ts`): version is now read from `package.json`
+  instead of being hardcoded at `v0.1.0`. Every prior release printed the wrong
+  version on startup.
+- **`clean` script** (`package.json`): `capture.db` → `umans-gate.db` (3 file
+  suffixes). `bun run clean` now correctly removes the actual database.
+- **`biome.json`**: `capture.db*` → `umans-gate.db*` (stale entry from DB rename).
+- **ARCHITECTURE.md**: fixed ASCII diagram alignment after `capture.db` →
+  `umans-gate.db` rename (SQLite box widened to fit text, `┴` connector
+  aligned with proxy box `┬` above).
+- **Benchmark result files**: untracked 36 stale files across three benchmark
+  directories (`benchmark/vision-handoff/results/`, `benchmark/proxy-optimizations/results/`,
+  and `benchmark/concurrency-gate/results.json`) — they contained old
+  `umans-ai/umans-gate` URLs in vision-test descriptions and a partially-redacted
+  API key (`sk-f1qgI...tmJI`). Updated `.gitignore` to also match `results.json`
+  files directly in benchmark directories (not just `results/` subdirectories).
+- **README badge**: removed misleading "Runtime: Bun" badge (contradicts "No
+  prerequisites for npm/npx"). Added CodeQL badge.
+- **CI lint failures**: added `src/embedded-assets.ts` to `biome.json` ignore
+  list (generated file with long import lines that Biome wanted to reformat).
+  Auto-fixed `package.json` `files` array formatting (Biome wanted inline).
+  These two pre-existing lint errors caused ALL CI runs and ALL Dependabot PRs
+  to fail.
+- **Release workflow resilience**: `release.yml` now retries each npm publish
+  step 3 times with 15s delays. Platform package publish failures no longer
+  block the main shim from publishing (previously `win32-arm64` spam detection
+  failure prevented the entire release).
+
+### Added
+
+- **CodeQL code scanning** (`.github/workflows/codeql.yml`) — weekly automated
+  security analysis for JavaScript/TypeScript.
+
 ## [0.1.2] - 2026-07-14
 
 ### Fixed

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Umans AI
+Copyright (c) 2025 codegiveness
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,25 +1,35 @@
 # umans-gate
 
 [![npm version](https://img.shields.io/npm/v/umans-gate.svg)](https://www.npmjs.com/package/umans-gate)
+[![npm downloads](https://img.shields.io/npm/dm/umans-gate.svg)](https://www.npmjs.com/package/umans-gate)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Runtime: Bun](https://img.shields.io/badge/Runtime-Bun-fbf0df.svg)](https://bun.sh)
-[![CI](https://github.com/umans-ai/umans-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/umans-ai/umans-gate/actions/workflows/ci.yml)
+[![CI](https://github.com/codegiveness/umans-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/codegiveness/umans-gate/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/codegiveness/umans-gate/actions/workflows/codeql.yml/badge.svg)](https://github.com/codegiveness/umans-gate/actions/workflows/codeql.yml)
 
-> **Disclaimer:** This is a community project. The author is not an official
-> Umans developer — just a contributor building tools around the Umans API.
-> "umans" and related marks belong to their respective owners.
+> A capture proxy for LLM APIs. Point your harness at it, and every
+> request/response is stored in SQLite with a live inspection dashboard.
+>
+> **Personal-use project.** This software is intended for personal use
+> only. It is a community contribution and is not affiliated with,
+> endorsed by, or an official product of Umans.
 
-LLM capture proxy with Anthropic `cache_control` TTL stamping, vision handoff,
-concurrency gating, rate limiting, and a live inspection dashboard.
+**Setup in 30 seconds.**
 
-Point your LLM harness at `http://localhost:1945`, and every request/response is
-captured to SQLite with a live WebSocket-updating inspector UI at
-`http://localhost:1945/dashboard/`.
+```bash
+npx umans-gate
+```
+
+That's it. The proxy starts on `http://localhost:1945` and the inspector
+dashboard opens at `http://localhost:1945/dashboard/`. Point any
+Anthropic or OpenAI-compatible harness at the proxy URL — every
+request and response is captured automatically.
 
 ## Table of Contents
 
-- [Features](#features)
+- [Install](#install)
 - [Quick Start](#quick-start)
+- [Updating](#updating)
+- [Service Persistence](#service-persistence)
 - [Configuration](#configuration)
   - [Config Fields](#config-fields)
   - [Hot Reload and Restart](#hot-reload-and-restart)
@@ -32,50 +42,221 @@ captured to SQLite with a live WebSocket-updating inspector UI at
 - [Development](#development)
 - [Project Structure](#project-structure)
 - [Documentation](#documentation)
+- [Related Projects](#related-projects)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Features
-
-- **Capture proxy**: intercepts all LLM API traffic (Anthropic, OpenAI-compatible) and stores it in SQLite with optional zstd compression
-- **Stamp pipeline**: unified stamping orchestrator that applies TTL, `top_k`, `max_tokens`, `thinking`, `output_config`, `context_management`, and `temperature` stamps in the correct order — toggled by a single `stamp_claude_code_enabled` switch
-- **Vision handoff**: replaces image blocks with text descriptions generated by a vision model (`umans-flash`), enabling text-only models to "see" images. Descriptions are cached (7-day TTL) with persistent SQLite storage
-- **Concurrency gate**: semaphore + circuit breaker with intention-based reservations (main vs vision), hard cap, soft limit driven by `/v1/usage`, queue timeout, and over-subscription fallback
-- **Rate limiting**: sliding-window weighted rate limiter for pro-tier request limits, auto-derived from `/v1/usage` or explicitly configured
-- **Connection warmer**: periodic `/v1/models` pings keep TLS warm, skipping when real traffic occurred recently
-- **Usage tracking**: fetches and reconciles `/v1/usage` to size concurrency limits, detect rate-boxing, and manage priority demotion
-- **Live inspector dashboard**: React + shadcn/ui dashboard with WebSocket live updates
-- **SSE rendering**: streaming responses are captured and rendered with expandable event previews
-- **Ring buffer storage**: keeps the last N captures (default 200) with WAL mode SQLite
-- **Write-behind queue**: batched database writes to minimize blocking during streaming
-- **Worker-based capture pipeline**: offloads capture writes to a worker thread for non-blocking streaming
-- **Hop-by-hop header stripping**: correct HTTP proxy behavior
-- **Protocol flexibility**: configurable upstream HTTP/1.1 (default) or HTTP/2
+## Install
 
-## Quick Start
+**npm (recommended for end users):**
 
 ```bash
-# Install
-bun install
+npm install -g umans-gate
+umans-gate
+```
+
+**npx (no install, run once):**
+
+```bash
+npx umans-gate
+```
 
-# Start the proxy (reads config.json + env overrides)
+**Bun (for developers):**
+
+```bash
+git clone https://github.com/codegiveness/umans-gate.git
+cd umans-gate
+bun install
 bun src/cli.ts
+```
+
+> **No prerequisites for npm/npx.** The npm package bundles a pre-compiled
+> standalone binary for your platform. For development from source,
+> [Bun](https://bun.sh) ≥ 1.1.0 is required.
+
+### Platform Support
+
+Pre-compiled binaries are published for:
+
+| OS | Architecture | npm Package |
+|----|-------------|-------------|
+| macOS | arm64 (Apple Silicon) | `umans-gate-darwin-arm64` |
+| macOS | x64 (Intel) | `umans-gate-darwin-x64` |
+| Linux | x64 | `umans-gate-linux-x64` |
+| Linux | arm64 | `umans-gate-linux-arm64` |
+| Windows | x64 | `umans-gate-win32-x64` |
+| Windows | arm64 | `umans-gate-win32-arm64` |
+
+The main `umans-gate` package automatically detects your platform and
+installs the correct binary.
+
+## Quick Start
+
+1. **Start the proxy:**
+
+   ```bash
+   umans-gate
+   ```
+
+2. **Point your harness** to `http://localhost:1945` as the base URL:
+
+   ```bash
+   # Anthropic API
+   export ANTHROPIC_BASE_URL=http://localhost:1945
+
+   # OpenAI-compatible API
+   export OPENAI_BASE_URL=http://localhost:1945
+   ```
+
+3. **Open the inspector dashboard** at `http://localhost:1945/dashboard/`
+
+   Every request and response is captured to SQLite with live WebSocket
+   updates. The dashboard shows full request/response bodies, streaming
+   SSE events, timing, token economics, and more.
+
+4. **Set your API key** (optional but recommended):
+
+   ```bash
+   # Option A: environment variable
+   export UMANS_API_KEY=your-key-here
+
+   # Option B: config.json (persists across restarts)
+   umans-gate config show    # see current config + file path
+   # Edit config.json and set "umans_api_key"
+   # Or use the dashboard Config tab at /dashboard/
+   ```
+
+   Setting `UMANS_API_KEY` enables `/v1/usage` polling, concurrency gate
+   sizing, rate-limit validation, and vision handoff.
+
+### What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **Capture proxy** | Intercepts all LLM API traffic (Anthropic, OpenAI-compatible) and stores it in SQLite with optional zstd compression |
+| **Stamp pipeline** | Applies TTL, `top_k`, `max_tokens`, `thinking`, `output_config`, `context_management`, and `temperature` stamps — toggled by a single switch |
+| **Vision handoff** | Replaces image blocks with text descriptions from a vision model, enabling text-only models to "see" images. Descriptions are cached (7-day TTL) with persistent SQLite storage |
+| **Concurrency gate** | Semaphore + circuit breaker with intention-based reservations, hard cap, soft limit driven by `/v1/usage`, queue timeout, and over-subscription fallback |
+| **Rate limiting** | Sliding-window weighted rate limiter for pro-tier request limits, auto-derived from `/v1/usage` or explicitly configured |
+| **Connection warmer** | Periodic `/v1/models` pings keep TLS warm, skipping when real traffic occurred recently |
+| **Usage tracking** | Fetches and reconciles `/v1/usage` to size concurrency limits, detect rate-boxing, and manage priority demotion |
+| **Live inspector** | React + shadcn/ui dashboard with WebSocket live updates |
+| **SSE rendering** | Streaming responses are captured and rendered with expandable event previews |
+| **Ring buffer storage** | Keeps the last N captures (default 200) with WAL mode SQLite |
+| **Write-behind queue** | Batched database writes to minimize blocking during streaming |
+| **Worker-based capture** | Offloads capture writes to a worker thread for non-blocking streaming |
+| **Hop-by-hop header stripping** | Correct HTTP proxy behavior |
+| **Protocol flexibility** | Configurable upstream HTTP/1.1 (default) or HTTP/2 |
+
+## Updating
+
+```bash
+umans-gate update     # self-update (npm global or standalone binary)
+```
 
-# Or after build:
-bun run build
-./dist/cli.js
+The updater detects your install method (npm global, standalone
+executable, or dev) and performs the appropriate action. For npm global
+installs, it runs `npm update -g umans-gate`. For standalone binaries,
+it auto-downloads and replaces the binary from the latest GitHub Release.
+If the proxy is running as a managed service, the updater stops the
+service before updating and restarts it after.
+
+To check for updates without installing:
+
+```bash
+umans-gate update --check
+```
+
+### Uninstall
+
+```bash
+umans-gate uninstall   # removes service, config, database, and binary
+```
+
+The uninstaller first removes any installed service (systemd, launchd,
+or Windows service) before cleaning up the binary and config. Pass
+`--keep-config` to preserve `config.json` and the database.
+
+Or manually:
+
+```bash
+npm uninstall -g umans-gate
+rm -rf ~/.config/umans-gate
+```
+
+## Service Persistence
+
+`umans-gate` can install itself as a managed service that starts on boot
+and survives restarts — no external process manager required.
+
+### Install as a service
+
+```bash
+umans-gate service install
+```
+
+This creates a platform-appropriate service definition, enables it for
+auto-start on boot, and starts it immediately:
+
+| Platform | Service manager | Unit location |
+|----------|----------------|---------------|
+| Linux | systemd (user unit + linger) | `~/.config/systemd/user/umans-gate.service` |
+| macOS | launchd (LaunchAgent) | `~/Library/LaunchAgents/com.umans.gate.plist` |
+| Windows | Windows Service (via NSSM) | Registered with `sc.exe` |
+
+The service runs with `WorkingDirectory` set to your home directory and
+uses the same `config.json` as a foreground run. If an API key is set
+via environment variable (not in config.json), it is stored securely:
+systemd uses a separate `EnvironmentFile` with `chmod 600`; launchd
+stores it in the plist (also `chmod 600`); NSSM stores it in the
+Windows service registry. The key is never inlined in the systemd unit
+file.
+
+Use `--force` to overwrite an existing service definition:
+
+```bash
+umans-gate service install --force
+```
+
+### Service lifecycle commands
+
+```bash
+umans-gate service start      # start the service
+umans-gate service stop       # stop the service
+umans-gate service restart    # restart the service
+umans-gate service status     # show service status (running, PID, uptime)
+umans-gate service logs       # tail service logs (follow mode)
+umans-gate service logs -f    # same as above (alias)
+umans-gate service uninstall  # stop, disable, and remove the service
 ```
 
-Point your harness base URL to `http://localhost:1945` and open the inspector at `http://localhost:1945/dashboard/`.
+### How it works
+
+- **Linux**: A systemd user unit with `Restart=always` and
+  `loginctl enable-linger` so the service starts at boot without needing
+  to log in. The PATH includes common runtime directories (`/usr/local/bin`,
+  `~/.bun/bin`, `/opt/homebrew/bin`, etc.) so the shebang resolves.
+- **macOS**: A launchd LaunchAgent with `RunAtLoad=true` and
+  `KeepAlive=true` for unconditional restart. Loaded via `launchctl load`.
+- **Windows**: A Windows Service registered via NSSM (bundled in the
+  win32 platform package) with `SERVICE_AUTO_START` for boot-start and
+  automatic log rotation at 10 MB.
+
+### Dashboard restart button
+
+When running as a managed service, the dashboard's **Restart** button
+(`POST /dashboard/api/restart`) works automatically — the service
+manager restarts the process after `process.exit(0)` thanks to
+`Restart=always` / `KeepAlive`.
 
 ## Configuration
 
-> **⚠️ Dashboard-first:** The recommended way to change configuration is via
+> **Dashboard-first:** The recommended way to change configuration is via
 > the **Config** tab in the dashboard at `http://localhost:1945/dashboard/`.
 > Editing `config.json` directly works, but the dashboard validates against
-> the upstream `/v1/usage` hard cap, shows field descriptions, and can hot-reload
-> or restart the server for you. If you do edit the file, restart the server
-> afterward (the dashboard auto-reloads on save).
+> the upstream `/v1/usage` hard cap, shows field descriptions, and can
+> hot-reload or restart the server for you. If you do edit the file,
+> restart the server afterward (the dashboard auto-reloads on save).
 
 Configuration is loaded from a JSON file with environment variable overrides.
 
@@ -92,8 +273,8 @@ On first run, `loadConfig()` writes a `config.json` with defaults to the
 resolved path if it does not already exist. Existing configs are never
 overwritten.
 
-All env vars from `.env.example` have JSON equivalents using `snake_case`
-(e.g., `UPSTREAM_PROTOCOL` → `upstream_protocol`).
+All configuration variables have JSON equivalents using `snake_case`
+(e.g., `UPSTREAM_PROTOCOL` → `upstream_protocol` in `config.json`).
 
 ### Config Fields
 
@@ -149,13 +330,15 @@ hardcoded — not configurable.
 
 The dashboard's Config tab can save changes and trigger a hot reload
 via `POST /dashboard/api/config/reload`. Hot-reloadable fields (e.g.
-`stamp_claude_code_enabled`, `breaker_*`, `rate_limit_*`, `vision_*`)
+`stamp_claude_code_enabled`, `breaker_*`, `rate_limit_*`)
 apply live; fields marked `restartRequired` (e.g. `port`, `db_path`,
-`upstream_protocol`) require a server restart.
+`upstream_protocol`, `vision_*`) require a server restart.
 
 The dashboard also has a **Restart** button (`POST /dashboard/api/restart`)
-that calls `process.exit(0)`. This requires an external process manager
-to restart the server automatically:
+that calls `process.exit(0)`. When running as a managed service
+(`umans-gate service install`), the service manager restarts the
+process automatically. Without a service manager, you need an external
+process watcher:
 
 | Manager | Command |
 |---------|---------|
@@ -302,6 +485,7 @@ umans-gate/
 │   ├── model-policy.ts           # model-aware stamping decisions
 │   ├── compress.ts               # zstd body compression
 │   ├── vision-description-store.ts  # persistent vision description storage
+│   ├── updater.ts                # self-update logic
 │   ├── helpers.ts                # shared utilities
 │   ├── logger.ts                  # structured scoped logging
 │   ├── banner.ts                 # startup banner
@@ -318,7 +502,7 @@ umans-gate/
 │   │   ├── persistent-cache.ts   # SQLite-backed description cache
 │   │   ├── transcode.ts          # image transcoding
 │   │   ├── wrapper.ts            # description wrapper + policy
-│   │   └── sink.ts              # vision record sink
+│   │   └── sink.ts               # vision record sink
 │   ├── workers/                  # worker-based capture pipeline
 │   └── shared/                   # extracted domain helpers
 ├── dashboard/                    # React + shadcn/ui dashboard
@@ -327,22 +511,33 @@ umans-gate/
 │   ├── ARCHITECTURE.md           # system architecture
 │   ├── TROUBLESHOOTING.md         # troubleshooting guide
 │   ├── BENCHMARKS.md             # benchmark results
+│   ├── PRODUCT.md                # product positioning and users
 │   └── proxy-modifications.md    # proxy modification inventory
-├── benchmark/                    # benchmark scripts + results
+├── benchmark/                    # benchmark scripts
 ├── .github/                      # issue templates, workflows, PR template
 └── dist/                         # build output (gitignored)
 ```
 
 ## Documentation
 
+- [Documentation Index](docs/README.md) — curated reading guide
 - [Architecture](docs/ARCHITECTURE.md) — system design and data flow
 - [Proxy Modifications](docs/proxy-modifications.md) — complete inventory of proxy modifications
 - [Troubleshooting](docs/TROUBLESHOOTING.md) — common issues and solutions
 - [Benchmarks](docs/BENCHMARKS.md) — benchmark methodology and results
+- [Product](docs/PRODUCT.md) — product positioning and target users
 - [Dashboard Design System](dashboard/DESIGN.md) — design system documentation
 - [Changelog](CHANGELOG.md) — version history
 - [Contributing](CONTRIBUTING.md) — how to contribute
 - [Roadmap](ROADMAP.md) — future plans
+- [Security Policy](SECURITY.md) — vulnerability reporting and security practices
+
+## Related Projects
+
+- **[umans-open-stack](https://github.com/umans-ai/umans-open-stack)** — A
+  curated set of open source playbooks and tools tested with Umans. umans-gate
+  implements several patterns documented there: concurrency gating, vision
+  handoff, cache_control TTL stamping, and workflow orchestration.
 
 ## Contributing
 
@@ -351,4 +546,19 @@ testing, and release instructions.
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE).
+
+## Usage Rights
+
+This is a **personal-use project**. The source code is published under the MIT
+license for transparency and educational purposes. While the MIT license
+technically permits commercial use and redistribution, this project is not
+actively maintained as a product and is not intended for production deployment.
+
+**This is a community contribution and is not an official Umans product.**
+It is not affiliated with, endorsed by, or supported by Umans AI. All upstream
+service names, model names, and API endpoints referenced in this codebase
+belong to their respective owners.
+
+Use it, learn from it, fork it — but don't expect official support or
+warranties of any kind.