@plurnk/plurnk-service 0.64.0 → 0.68.0

package/.env.example

@@ -1,32 +1,32 @@
-# plurnk-service config — the shipped legend: every knob + its default.
+# ⚠ REFERENCE ONLY — ~/.plurnk/.env.example is OVERWRITTEN from the installed package on every
+# restart/update. Do NOT edit it; your edits are lost. Put YOUR config in ~/.plurnk/.env (yours,
+# seeded once, never touched) or ./.env. This file is the shipped legend: every knob + its default,
+# and the source of the derived --<knob> CLI flags (INSTALL.md is the agent-facing breakdown).
 #
-# On first run this file is copied to ~/.plurnk/.env.example, which is the cascade FLOOR.
-# Edit there (or layer ~/.plurnk/.env over it). This node_modules copy is the SEED + the
-# source of derived --<knob> CLI flags — it is NOT itself a runtime layer.
-#
-# Override order (low → high precedence):
-#   ~/.plurnk/.env.example   (the floor — override, don't remove!)
-#   < ~/.plurnk/.env         (your home config)
+# Cascade (low → high precedence — last writer wins):
+#   package .env.example     (the TRUE floor — evolves with the installed version)
+#   < ~/.plurnk/.env.example (this readable legend — refreshed from the package each boot)
+#   < ~/.plurnk/.env         (your home config — seeded once, yours to keep)
 #   < ./.env                 (per-project, current directory)
 #   < --env-file=… / --config=…
 #   < shell environment
-#   < --<knob> CLI flags
+#   < --<knob> CLI flags     (the 1:1 mirror: --service-max-turns <-> PLURNK_SERVICE_MAX_TURNS)
 # Feature-flag bools use `=== "1"` exactly, never `=== "true"`. `~/` expands to your home.
 
 # --- Storage ---
-PLURNK_DB_PATH=~/.plurnk/plurnk.db
+PLURNK_SERVICE_DB_PATH=~/.plurnk/plurnk.db
 
 # --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
 # sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
 # These are operator overrides — integers; unset = sqlrite/sqlite default. Uncomment to tune.
 # busy_timeout (ms): how long a writer waits on a lock before SQLITE_BUSY. 0 = immediate.
-# PLURNK_SQLITE_TIMEOUT=5000
+# PLURNK_SERVICE_SQLITE_TIMEOUT=5000
 # cache_size: positive = pages, negative = KiB of memory. Bigger = fewer disk reads on a hot db.
-# PLURNK_SQLITE_CACHE_SIZE=-16000
+# PLURNK_SERVICE_SQLITE_CACHE_SIZE=-16000
 # mmap_size: bytes of memory-mapped I/O (read perf on large file-backed dbs). 0 disables.
-# PLURNK_SQLITE_MMAP_SIZE=268435456
+# PLURNK_SERVICE_SQLITE_MMAP_SIZE=268435456
 # max_page_count: hard db-size ceiling in PAGES — a write past it errors (disk-fill guard).
-# PLURNK_SQLITE_MAX_PAGE_COUNT=524288
+# PLURNK_SERVICE_SQLITE_MAX_PAGE_COUNT=524288
 
 # --- Daemon transport ---
 PLURNK_HOST=127.0.0.1
@@ -35,6 +35,7 @@ PLURNK_PORT=3044
 # --- Client (read by the `plurnk` CLI from this shared home; the daemon ignores it) ---
 # The daemon WebSocket URL the client connects to (mirrors PLURNK_HOST/PORT above).
 # PLURNK_WS=ws://127.0.0.1:3044
+# Client-side knobs live under PLURNK_CLIENT_* (--session/--run/--yolo/--json…); see `plurnk --help`.
 
 # --- Model aliases ---
 # PLURNK_MODEL is the active provider for every loop (a client may override per loop
@@ -99,28 +100,31 @@ MODELSCOPE_BASE_URL=https://api-inference.modelscope.cn/v1
 # Operator turn ceiling. -1 (default) = no cap (loops end via SEND, budget,
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
 # per-call loop.run({maxTurns}) cannot exceed (min wins).
-PLURNK_MAX_TURNS=-1
+PLURNK_SERVICE_MAX_TURNS=-1
 # Per-emission op cap (runaway-loop guard). A client may tighten it per session via
 # session.create settings.maxCommands (min wins); never raise it past this (#232).
-PLURNK_MAX_COMMANDS=99
-PLURNK_RPC_TIMEOUT=30000
+PLURNK_SERVICE_MAX_COMMANDS=99
+PLURNK_SERVICE_RPC_TIMEOUT=30000
+# Proposal auto-cancel: a proposed (202) side-effecting op auto-cancels if no resolution arrives
+# within this many ms (loop/resolve RPC, in-tree YOLO listener, or this timeout). Default 300000 (5 min).
+PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=300000
 # Post-EXEC breath: after a turn fires a non-inline EXEC whose spawn is still in
 # flight at the turn boundary, wait this many ms before assembling the next packet
 # so a fast exec's output can land in it instead of a turn later. A fixed grace
 # beat, NOT a wait-for-completion (slow execs proceed + surface via the wake path).
 # 0 = off (the model sees fast-exec output a turn late, as today).
-PLURNK_EXEC_WAIT_MS=1000
+PLURNK_SERVICE_EXEC_WAIT_MS=1000
 # Teardown reap grace: when a loop/run tears down a background exec, the spawn gets a polite
 # signal first (SIGHUP, or the model's KILL[code]); a stream that IGNORES it is hard-killed
 # (SIGKILL, to the whole process group) this many ms later — so the reap can't wedge on a
 # signal-ignoring child. plurnk-execs refuses to bake this number; the consumer owns it.
-PLURNK_EXEC_KILL_GRACE_MS=2000
-PLURNK_LOOP_TIMEOUT=86400000
+PLURNK_SERVICE_EXEC_KILL_GRACE_MS=2000
+PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 
 # --- Engine rails ---
-PLURNK_MAX_STRIKES=3
-PLURNK_MIN_CYCLES=3
-PLURNK_MAX_CYCLE_PERIOD=4
+PLURNK_SERVICE_MAX_STRIKES=3
+PLURNK_SERVICE_MIN_CYCLES=3
+PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
 
 # --- Schemes ---
 # (Workspace root for file ops is per-session — supplied by the client
@@ -128,18 +132,18 @@ PLURNK_MAX_CYCLE_PERIOD=4
 # stored on sessions.project_root. No env-level default.)
 
 # --- Git integration ---
-# PLURNK_GIT_ALLOWED — hard ceiling for git membership + integration (repo telemetry,
+# PLURNK_SERVICE_GIT_ALLOWED — hard ceiling for git membership + integration (repo telemetry,
 # EXEC[git]). =1 permits it (then declared repos + per-session config decide; a client
 # may deny its own session via session.create settings.git:false, #232); =0 flatly
 # denies it service-wide, un-re-enableable (the sandbox/benchmark lockout).
-PLURNK_GIT_ALLOWED=1
-# PLURNK_GIT_AUTO — default repo declaration. =1 auto-declares an implicit `repo` at
+PLURNK_SERVICE_GIT_ALLOWED=1
+# PLURNK_SERVICE_GIT_AUTO — default repo declaration. =1 auto-declares an implicit `repo` at
 # project_root (no-op when it isn't a git tree); =0 declares nothing — clients add
 # repos explicitly via the `repo` overlay. SPEC §membership forest.
-PLURNK_GIT_AUTO=1
+PLURNK_SERVICE_GIT_AUTO=1
 
 # --- Reference docs (auto-READ at turn 1) ---
-# PLURNK_MD_<ALIAS>=<path> materializes <path>'s markdown as a plurnk://<ALIAS>.md
+# PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a plurnk://<ALIAS>.md
 # entry the model READs at turn 0 — an idiomatic way to inject standing context
 # (an ordinary entry + READ op, not a bespoke packet section). ~ expands to home;
 # relative paths resolve against the package root. A client may add its own docs
@@ -147,7 +151,7 @@ PLURNK_GIT_AUTO=1
 # with these env docs, keyed by alias — the client wins a collision (#231).
 # Commented out = no docs by default. (The operating policy is NOT a doc: readSystemPolicy
 # already renders ~/.plurnk/AGENTS.md as the ## Plurnk Service Policy section — pointing a
-# PLURNK_MD_* alias at it injects the same file twice.)
+# PLURNK_SERVICE_MD_* alias at it injects the same file twice.)
 # Turn-0 catalog preview, FIND-served (foisted as FIND(<scheme>:///**) per scheme) so a run
 # opens oriented, not blank. The model's OWN surface — known/unknown (memory), run (scratch),
 # plurnk (docs) — always foists FULL when the preview is on, never truncated: a partial view of
@@ -156,19 +160,19 @@ PLURNK_GIT_AUTO=1
 # (everything full); N = the first N files (memory still full); 0 = preview off entirely (the model
 # FINDs on demand). Servicewide default; a client overrides per session via session.create
 # settings.filesItems (#231).
-PLURNK_FILES_ITEMS=-1
+PLURNK_SERVICE_FILES_ITEMS=-1
 
 # Prompt-preview cap: the loop's prompt renders in user.prompt every turn, and a fat prompt
 # replays each turn (bloat). Show the first N CHARS of the body + a pointer to the full
 # prompt (always READable at its plurnk://prompt/<loop>/<seq> entry — nothing is lost).
 # -1 = no cap (render the full prompt every turn).
-PLURNK_PROMPT_PREVIEW_CHARS=1024
+PLURNK_SERVICE_PROMPT_PREVIEW_CHARS=1024
 
 # Session-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
 # — the fork-bomb / destabilization brake. -1 = no cap (default); only concurrency
 # is bounded, never lifetime, since sessions persist for months. A spawn/fork past
 # the ceiling fails hard (508 — no queue, no retry); the acting run counts itself.
-PLURNK_SESSION_RUNS_MAX_ACTIVE=-1
+PLURNK_SERVICE_SESSION_RUNS_MAX_ACTIVE=-1
 
 # --- Providers (universal knobs) ---
 # Native thinking (providers 0.31+, the activation/capacity split — a numeric budget
@@ -191,11 +195,11 @@ PLURNK_PROVIDERS_THINKING_CAPACITY=4096
 # partitions to EXACTLY 65536 prompt tokens (78848 − 4096 − 8192 − 1024).
 # COUPLING (F7): per-request numeric reasoning budgets are IGNORED by llama-server —
 # if thinking is enabled, the serving box's --reasoning-budget launch flag MUST equal
-# PLURNK_PROVIDERS_REASONING, or the reserve is fiction. The service warns at boot.
-PLURNK_PROVIDERS_CTX=78848
-PLURNK_PROVIDERS_REASONING=4096
-PLURNK_PROVIDERS_ASSISTANT=8192
-PLURNK_PROVIDERS_SAFETY=1024
+# PLURNK_SERVICE_REASONING, or the reserve is fiction. The service warns at boot.
+PLURNK_SERVICE_CTX=78848
+PLURNK_SERVICE_REASONING=4096
+PLURNK_SERVICE_ASSISTANT=8192
+PLURNK_SERVICE_SAFETY=1024
 
 # countTokens is a chars/2 UPPER BOUND (safe, never undercounts; calibration trues
 # up the residual, §tokenomics-ceiling-calibrates-to-usage). Exact counting arrives
@@ -207,10 +211,10 @@ PLURNK_PROVIDERS_SAFETY=1024
 # own vendor-specific overrides for narrower defaults, but they honor
 # this as the operator's universal ceiling.
 PLURNK_PROVIDERS_FETCH_TIMEOUT=600000
-# PLURNK_VERSION_POLL_TTL — how long (ms) discover caches its npm-registry version poll
+# PLURNK_SERVICE_VERSION_POLL_TTL — how long (ms) discover caches its npm-registry version poll
 # (service + client `latest`) before a background refresh. Best-effort; the poll never
 # blocks discover, and offline/registry-down omits `latest`. ~hourly is plenty. #235
-PLURNK_VERSION_POLL_TTL=3600000
+PLURNK_SERVICE_VERSION_POLL_TTL=3600000
 # Grammar-constrained sampling: SELECTS the GBNF variant the provider constrains
 # every generate() to, so capable backends (llama-server, detected via the
 # /v1/models fingerprint) can only sample valid plurnk DSL; others drop it silently.
@@ -218,15 +222,31 @@ PLURNK_VERSION_POLL_TTL=3600000
 # @plurnk/plurnk-grammar; an absolute/relative path is your own. =0 (or empty) disables.
 PLURNK_PROVIDERS_GBNF=plurnk.gbnf
 
-# GBNF debug, honored natively by @plurnk/plurnk-providers (>=0.13.0): validate the grammar locally
-# (fail-hard if malformed) and run UNCONSTRAINED, never sending it to the model. Dev aid; off by default.
-PLURNK_GBNF_DEBUG=0
+# GBNF filter mode (providers 0.33, renamed from PLURNK_GBNF_DEBUG; alias-scopable _<alias>):
+# validate the grammar locally (fail-hard if malformed) and run UNCONSTRAINED, never sending it.
+# Dev aid, off by default. Unset = normal constrained sampling.
+# PLURNK_PROVIDERS_GBNF_DEBUG=
 
 # Provider retry attempts (providers 0.7+): how many times generate() retries a
 # TRANSIENT failure (429 rate-limit, 5xx/network) with exponential backoff (base 2s
 # is a provider constant — the COUNT is the operator knob). REQUIRED, fail-hard if
 # unset. Terminal errors (auth, quota, model refusal) never retry. 0 = no retries.
 PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
+# Transient-retry backoff base (ms); attempt N waits DELAY·2^(N−1); a Retry-After header wins.
+PLURNK_PROVIDERS_RETRY_DELAY=2000
+# Boot capability-probe (providers 0.33, #34): retries + backoff base (ms) for the /v1/models
+# fingerprint that decides grammar transport. A flaky probe under load once silently disabled
+# the rails — retrying closes that. Prefer the deterministic LLAMA_SERVER pin below over probing.
+PLURNK_PROVIDERS_PROBE_ATTEMPTS=3
+PLURNK_PROVIDERS_PROBE_DELAY=250
+# Near-greedy decode: the default TEMPERATURE (every request, under caller sampling) + the
+# REPEAT_PENALTY floor wherever a grammar rides. Both required (providers 0.33).
+PLURNK_PROVIDERS_TEMPERATURE=0.2
+PLURNK_PROVIDERS_REPEAT_PENALTY=1.15
+# Pin a known llama-server box to llamacpp capabilities WITHOUT probing (providers 0.33, #34):
+# _<alias>=1 forces grammar transport + slot pinning + native /tokenize, no /v1/models race.
+# The deterministic cure for the silent-unconstrained class — set it per real llama-server alias.
+PLURNK_PROVIDERS_LLAMA_SERVER_turboderp=1
 # Override the model's reported context window in tokens. Provider modules
 # normally read this from the model/API; set this to force a specific
 # value (smaller for testing, larger for models that under-report). Unset
@@ -244,15 +264,24 @@ PLURNK_PROVIDERS_RETRY_ATTEMPTS=3
 # for "on, zero third-party". Example: =acme-execs-cobol,@firewolf/firepad
 PLURNK_PLUGINS_TRUSTED_ONLY=0
 
-# PLURNK_DOCS_EXCLUDE — comma list of scheme/exec names dropped from BOTH the teaching oneliner
+# PLURNK_SERVICE_DOCS_EXCLUDE — comma list of scheme/exec names dropped from BOTH the teaching oneliner
 # and the materialized pull-doc on load. The self-evident (plurnk/file) + retired (exec) names the
 # model needs no doc for. Empty → exclude nothing. Unknown names are inert (a filter, not a contract).
-PLURNK_DOCS_EXCLUDE="plurnk,file,exec"
+PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 
-# PLURNK_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
+# PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
 # (the cached prefix). Read per-turn (live edits); a set-but-unreadable path fails the turn HARD.
 # `~/` expands to home. Unset → no section. The pressure valve for "improve the packet" without a fork.
-# PLURNK_PACKET_INJECT="~/injection.md"
+# PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
+
+# PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Plurnk Service Policy
+# section. Unset = the seeded ~/.plurnk/AGENTS.md; a path = that file; EXPLICITLY empty = policy off.
+# PLURNK_SERVICE_POLICY=
+# PLURNK_SERVICE_PROJECT — a per-project policy markdown (relative to projectRoot). Unset = <root>/AGENTS.md.
+# PLURNK_SERVICE_PROJECT=
+# PLURNK_SERVICE_REQUIREMENTS — override the requirements.md recency-footer path (relative to the package
+# root). Unset = the packaged requirements.md.
+# PLURNK_SERVICE_REQUIREMENTS=
 
 # --- Semantic search (~query chunking) ---
 # Project Semantics tiles each entry into <=window chunks so a large body is fully
@@ -263,19 +292,46 @@ PLURNK_DOCS_EXCLUDE="plurnk,file,exec"
 # window — NO model-specific number is assumed, so it scales to whatever embedder you
 # install. Set a positive value ONLY to cap below the window (e.g. to sweep
 # granularity); it is clamped to the window either way.
-PLURNK_SEMANTIC_CHUNK_TOKENS=
+PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS=
 # Overlap fraction [0,1): trailing context re-covered at each chunk boundary so a
 # concept split across a cut still matches in both. ~0.15 is a standard RAG default.
-PLURNK_SEMANTIC_CHUNK_OVERLAP=0.15
-# embedBatch worker-pool size (read by @plurnk/plurnk-mimetypes-embeddings). Each worker holds
+PLURNK_SERVICE_SEMANTIC_CHUNK_OVERLAP=0.15
+# embedBatch worker-pool size (read by @plurnk/plurnk-mimetypes-embeddings, renamed to the
+# PLURNK_MIMETYPES_* family). Each worker holds
 # its own model copy — a memory↔throughput dial. -1 = one worker per core (match the box); a
 # positive integer pins an exact count. Explicit floor → the embedder is default-ON out of the box.
-PLURNK_EMBED_WORKERS=-1
+PLURNK_MIMETYPES_EMBED_WORKERS=-1
 # =1 forces the FTS-only path even with the embeddings package installed — the ~query
 # degrades to keyword ranking and no vectors are derived (no MiniLM pool spun up). For
 # hosts/runs that don't want vector search; the fast test lane sets it in .env.test.
-PLURNK_EMBED_DISABLE=0
+PLURNK_SERVICE_EMBED_DISABLE=0
+
+# --- Schemes: http (@plurnk/plurnk-schemes-http) ---
+# Render-path knobs, REQUIRED once an HTML fetch renders (byte-only fetches never read them);
+# these reproduce the old built-ins exactly. Optional Playwright/Chromium knobs below.
+PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT=30000
+PLURNK_SCHEMES_HTTP_SALVAGE_MIN_BODY_CHARS=200
+PLURNK_SCHEMES_HTTP_IDLE_TIMEOUT=900000
+# PLURNK_SCHEMES_HTTP_PLAYWRIGHT_WS=ws://localhost:9222
+# PLURNK_SCHEMES_HTTP_NO_SANDBOX=1
+# PLURNK_SCHEMES_HTTP_CHROMIUM_HEAP_MB=2048
+
+# --- Execs (@plurnk/plurnk-execs family) ---
+# Runtime registration ceiling (subtractive, execs 0.4.31+). A disabled tag is ABSENT — never
+# registered, never on the capability sheet (a de-register, distinct from a §3.2 deactivate).
+# PLURNK_EXECS_ONLY=sh,jq,search   # allowlist: register ONLY these tags (lowercase, csv); all else off
+# Per-tag kill-switch — UPPERCASE tag name (PLURNK_EXECS_<TAG>=0); omit to keep a runtime enabled.
+# PLURNK_EXECS_PYTHON=0
+# PLURNK_EXECS_BC=0
+# MCP bridge (execs-mcp 0.5, renamed from PLURNK_MCP_*) — one var per server; name IS the var.
+# PLURNK_EXECS_MCP_<server>         = <https url | stdio command line>
+# PLURNK_EXECS_MCP_<server>_ENV     = <json>   # stdio: env overlay (tokens)
+# PLURNK_EXECS_MCP_<server>_HEADERS = <json>   # http: request headers (auth)
+# PLURNK_EXECS_MCP_INSTALL=0                    # gate: may /mcp hotload add servers at runtime
+# Web search (execs-search) — SEARXNG_URL is the enable gate (unset ⇒ search unavailable).
+PLURNK_EXECS_SEARCH_SEARXNG_URL=
+# PLURNK_EXECS_SEARCH_LANGUAGE=en
+# PLURNK_EXECS_SEARCH_LIMIT=12
+# PLURNK_EXECS_SEARCH_TIMEOUT=10000
+# PLURNK_EXECS_SEARCH_SAFESEARCH=
 
-# --- Diagnostics ---
-PLURNK_DEBUG=0
-PLURNK_LOG_LEVEL=info

package/INSTALL.md

@@ -0,0 +1,69 @@
+# Configuring plurnk-service
+
+Agent guide. Read this, then generate a `~/.plurnk/.env` fit to the user's box and intent. `.env.example` is the terse machine floor — the authoritative flag list and defaults; this is its reasoning layer. Every claimed coupling below is enforced by a `test/intg` check, so it is current with the installed version.
+
+## Install
+
+```
+npm install -g @plurnk/plurnk-service
+plurnk-service start          # `migrate` first if the DB is uninitialized
+```
+
+First run creates `~/.plurnk/`: `.env` (yours, seeded once with a model picker — **edit this**), `AGENTS.md` (the operating policy, yours), `.env.example` + `INSTALL.md` (package-owned references, **refreshed every boot** — never edit them). No model ships active; a fresh daemon runs until `PLURNK_MODEL` is set.
+
+Optional vector search: `npm i @plurnk/plurnk-mimetypes-embeddings` (heavy native deps). Absent → `~query` degrades to FTS keyword ranking.
+
+## The cascade (where a value actually comes from)
+
+Lowest precedence first; the last writer wins:
+
+1. **package `.env.example`** — the true floor, evolves with the installed version.
+2. **`~/.plurnk/.env.example`** — the readable legend, refreshed from the package each boot (a reference, not a place to edit).
+3. **`~/.plurnk/.env`** — the user's home config, seeded once, theirs to keep. **Write generated config here.**
+4. **`./.env`** — per-project, current working directory.
+5. **`--env-file=<path>` / `--config=<path>`** — explicit layers.
+6. **shell environment** — beats every file.
+7. **`--<flag>` CLI args** — top layer, overrides all.
+
+CLI flags are the **1:1 mirror** of the env vars: strip `PLURNK_`, lowercase, `_`→`-`. `PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`; `PLURNK_MODEL` ↔ `--model`. The flag surface and `--help` are generated from `.env.example`, so a var and its flag never diverge. Feature-flag bools are `=== "1"` exactly (never `"true"`); `~/` expands to home.
+
+## The prefix law (who owns a flag)
+
+The prefix is the **owning package**: `PLURNK_SERVICE_*` (this daemon), `PLURNK_PROVIDERS_*`, `PLURNK_MIMETYPES_*`, `PLURNK_EXECS_*`, `PLURNK_SCHEMES_HTTP_*`, `PLURNK_CLIENT_*` (the CLI). **Bare `PLURNK_*` is reserved** for the front-door + cross-package set no single package owns: `PLURNK_MODEL[_*]`, `PLURNK_BASEURL_*`, `PLURNK_HOST`/`PLURNK_PORT`/`PLURNK_WS` (the connection rendezvous), and `PLURNK_PLUGINS_TRUSTED_ONLY` (the cross-family plugin gate). Vendor keys (`OPENAI_API_KEY`, `FIREWORKS_API_KEY`…) are vendor conventions — untouched.
+
+A bare flag is a signal: more than one component depends on it. A prefixed one is single-owner. When a flag is `REQUIRED`, an unset or old-named value **fails the boot loudly** naming the var — never a silent default.
+
+## Couplings (the edges an agent gets wrong)
+
+These are relationships *between* flags. Set them as a unit.
+
+- **The window partition is exact.** `promptBudget = min(PLURNK_SERVICE_CTX, real window) − REASONING − ASSISTANT − SAFETY`; `REASONING + ASSISTANT` is the per-call `max_tokens`. Shipped invariant: any window ≥ 77Ki partitions to **exactly 65536** prompt tokens (`78848 − 4096 − 8192 − 1024`). Reserves exceeding the window fail the boot. *(Pinned: `Engine.budget` / `shipped-defaults`.)*
+- **Reasoning capacity is one number in three places.** `PLURNK_SERVICE_REASONING` (the partition's reserve) **must equal** `PLURNK_PROVIDERS_THINKING_CAPACITY` (the provider's thinking cap) **must equal** the serving box's `--reasoning-budget` launch flag. llama-server ignores per-request numeric budgets, so only the launch flag clamps it; a mismatch makes the reserve fiction. The daemon warns at boot when thinking is on. *(Pinned: `shipped-defaults` asserts the first equality.)*
+- **Grammar rails need a llama-server backend.** With `PLURNK_PROVIDERS_GBNF` set (rails on), the daemon **verifies enforcement at boot** and fails hard if the backend returns unconstrained output. For a known llama-server alias, pin `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` — it transports the grammar deterministically instead of probing `/v1/models` (a probe race once silently disabled the rails). *(Pinned: `grammar-enforcement-verify`.)*
+- **A think-trained model must think somewhere.** `PLURNK_PROVIDERS_THINKING=off` reroutes a reasoning model's thought into the grammar's legal free zone as prose. Keep it `on` with a capacity; providers auto-clamp thinking on in-band grammar backends (fireworks), so one setting is right everywhere.
+
+## Profiles (examples, not a decision tree — adapt to the real box)
+
+- **Local GPU (llama-server).** `PLURNK_MODEL_local="openai/<name>"`, `OPENAI_BASE_URL=http://127.0.0.1:<port>`, `PLURNK_MODEL=local`, `PLURNK_PROVIDERS_LLAMA_SERVER_local=1`, thinking `on`/`4096` **with the box launched `--reasoning-budget 4096`**. Full rails, exact tokenization.
+- **Cloud, bring-your-own-key.** `PLURNK_MODEL_cloud="openrouter/<model>"`, `OPENROUTER_API_KEY=…`, `PLURNK_MODEL=cloud`. No `LLAMA_SERVER` pin (not llama-server); a `response_format`-grammar backend auto-clamps thinking to none.
+- **plurnk.ai endpoint.** `PLURNK_MODEL_plurnk="plurnk/plurnk"`, `PLURNK_API_KEY=…`, `PLURNK_MODEL=plurnk`.
+- **Headless / CI / constrained container.** `PLURNK_SERVICE_EMBED_DISABLE=1` (skip the embedder — a CPU-only box CPU-embedding a large corpus starves the loop), consider `PLURNK_SERVICE_MAX_TURNS=<n>` as a cost cap, `PLURNK_SERVICE_GIT_ALLOWED=0` to lock out git in a sandbox.
+
+## Flag sections (breakdown of `.env.example`)
+
+Each mirrors a `# --- section ---` in the floor; consult the floor for exact defaults.
+
+- **Storage** — `PLURNK_SERVICE_DB_PATH`, and the optional `PLURNK_SERVICE_SQLITE_*` passthroughs (sqlrite already sets a safe WAL posture; tune only for a hot/large DB).
+- **Daemon transport** — bare `PLURNK_HOST`/`PLURNK_PORT` (the daemon binds); bare `PLURNK_WS` is the client's dial string (the daemon ignores it).
+- **Model aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. The front door — keep these bare and short.
+- **Loop control / Engine rails** — `PLURNK_SERVICE_MAX_TURNS` (−1 = uncapped), `_MAX_COMMANDS`, `_MAX_STRIKES`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_RPC_TIMEOUT`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_WAIT_MS`, `_EXEC_KILL_GRACE_MS`, `_SESSION_RUNS_MAX_ACTIVE`. Guardrails; the shipped values are sane.
+- **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
+- **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-1 file catalog cap), `_PROMPT_PREVIEW_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT`/`_REQUIREMENTS` (policy + footer overrides; unset = the seeded/packaged defaults), `_MD_<alias>` (inject a markdown doc as a turn-0 entry).
+- **Providers** — `PLURNK_PROVIDERS_THINKING`/`_THINKING_CAPACITY`, `_TEMPERATURE`, `_REPEAT_PENALTY`, `_FETCH_TIMEOUT`, `_RETRY_ATTEMPTS`/`_RETRY_DELAY`, `_PROBE_ATTEMPTS`/`_PROBE_DELAY`, `_GBNF` (grammar variant), `_LLAMA_SERVER_<alias>`, `_CONTEXT_SIZE`, `_GBNF_DEBUG`. Alias-scopable: any knob takes a `_<alias>` suffix that wins over the bare fallback.
+- **The window partition** — `PLURNK_SERVICE_CTX`/`_REASONING`/`_ASSISTANT`/`_SAFETY` (see Couplings).
+- **Plugins** — bare `PLURNK_PLUGINS_TRUSTED_ONLY` (0/unset = load all installed; a value = `@plurnk/*` plus an allowlist).
+- **Semantic search** — `PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS`/`_CHUNK_OVERLAP` (service-side chunking), `PLURNK_SERVICE_EMBED_DISABLE` (FTS-only), `PLURNK_MIMETYPES_EMBED_WORKERS` (the embedder's pool — mimetypes-owned).
+- **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`/`_SALVAGE_MIN_BODY_CHARS`/`_IDLE_TIMEOUT` (required on the HTML render path), optional Playwright/Chromium knobs.
+- **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_MCP_<server>` bridges an MCP server; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+
+The client's own knobs live under `PLURNK_CLIENT_*` (`--session`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.

package/README.md

@@ -32,7 +32,7 @@ npm install -g @plurnk/plurnk-service
 plurnk-service start      # daemon (`migrate` initializes the DB)
 ```
 
-Config + state live in `~/.plurnk/` (created on first run): set `PLURNK_MODEL` and friends in `~/.plurnk/.env`; the DB defaults to `~/.plurnk/plurnk.db`. Provider-agnostic — point `PLURNK_MODEL` at any vendor. Full override cascade (`~/.plurnk` < `./.env` < `--env-file` < shell < `--flags`) is documented at the top of `.env.example`. Also exports `{ Engine, Daemon, SchemeRegistry }` for in-process embedding.
+Config + state live in `~/.plurnk/` (created on first run): put your config in `~/.plurnk/.env` (yours, seeded once); the DB defaults to `~/.plurnk/plurnk.db`. Provider-agnostic — point `PLURNK_MODEL` at any vendor. **[`INSTALL.md`](./INSTALL.md) is the config guide** — the cascade, the prefix taxonomy, the coupling matrix, and profiles for common deployments; `.env.example` is the terse machine floor it breaks down. Also exports `{ Engine, Daemon, SchemeRegistry }` for in-process embedding.
 
 ## Contract & siblings