@plurnk/plurnk-service 1.7.0 → 1.8.0

package/.env.defaults

@@ -1,8 +1,7 @@
 # ⚠ REFERENCE — this is @plurnk/plurnk-service's shipped .env.defaults: the operative floor
-# for its knobs and the source of the derived --<knob> CLI flags (INSTALL.md is the agent-facing
-# breakdown). ~/.plurnk/.env.defaults is the ASSEMBLED catalog (every installed package's file),
-# machine-owned and regenerated each boot — do NOT edit either. Put YOUR config in ~/.plurnk/.env
-# (yours, seeded once, never touched) or ./.env.
+# for its knobs and source of the derived --<knob> CLI flags. Run
+# `plurnk-service config defaults` for the complete owner-labelled installed aggregate. Put user
+# overrides in $XDG_CONFIG_HOME/plurnk/.env (seeded once, never overwritten), ./.env, or the shell.
 #
 # THE STANDARD (every plurnk package, third-party included): ship a `.env.defaults` at your
 # package root declaring YOUR knobs (prefix = your package's name); the file IS the documentation.
@@ -12,16 +11,18 @@
 #
 # Source classes (low → high precedence; higher classes win):
 #   assembled .env.defaults floor  (this file + every installed member's, uniqueness-checked)
-#   < ~/.plurnk/.env               (your home config — seeded once, yours to keep)
+#   < $XDG_CONFIG_HOME/plurnk/.env (your user config — seeded once, yours to keep)
 #   < ./.env                       (per-project, current directory)
 #   < --env-file=… / --config=…
 #   < shell environment
 #   < --<knob> CLI flags           (the 1:1 mirror: --service-max-turns <-> PLURNK_SERVICE_MAX_TURNS)
-# Ordering among repeated explicit files is currently unspecified (#84).
+# Later repeated explicit files win.
 # Feature-flag bools use `=== "1"` exactly, never `=== "true"`. `~/` expands to your home.
 
 # --- Storage ---
-PLURNK_SERVICE_DB_PATH=~/.plurnk/plurnk.db
+# Empty derives $XDG_DATA_HOME/plurnk/plurnk.db (default ~/.local/share/plurnk/plurnk.db).
+# An explicit non-empty path overrides it; `~/` expands to home.
+PLURNK_SERVICE_DB_PATH=
 
 # --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
 # sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
@@ -42,8 +43,9 @@ PLURNK_HOST=127.0.0.1
 PLURNK_PORT=3044
 
 # --- Loop control ---
-# Optional default child-provider alias. Unset = each WORK/FORK child inherits
-# its spawning loop's provider. Clients may override this per top-level loop.
+# Optional default child-model selector (declared alias or provider/model route).
+# Unset = each WORK/FORK child inherits its spawning loop's model. Clients may
+# override this per top-level loop.
 # PLURNK_MODEL_CHILD=fast
 # Operator turn ceiling. -1 (default) = no cap (loops end via SEND, provider capacity,
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
@@ -56,6 +58,9 @@ PLURNK_SERVICE_MAX_TURNS=-1
 PLURNK_SERVICE_MAX_COMMANDS=-1
 # Live & demo test harness story timeout (ms) — 10 minutes (600000ms).
 PLURNK_SERVICE_LIVE_TIMEOUT=600000
+# {§crash-only-stop} — the daemon's settle deadline on stop(): past this the
+# shutdown abandons its waits instead of hanging forever on a wedged child.
+PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
 # Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
 # a finite positive value auto-cancels unattended (outcome=timeout). Every other explicit
 # value is invalid and fails at the proposal lifecycle owner.
@@ -63,15 +68,21 @@ PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
 # Turn-hold runtimes: while a listed runtime's stream is in flight the cycle pauses (no next
 # turn) until it concludes. Bounded by _HOLD_MS, fail-open at the cap. Empty = no holds.
 # A bare name holds all of that runtime's spawns; `<runtime>:<effect>` holds only
-# that effect class.
-PLURNK_SERVICE_EXEC_HOLD=search,images,videos,news,map,music,it,science,social,downloadable
+# that effect class. The retired web-search family names are gone; declare operator
+# runtimes explicitly.
+PLURNK_SERVICE_EXEC_HOLD=
 PLURNK_SERVICE_EXEC_HOLD_MS=300000
+# Effect admission overrides ({§effect-policy-tunable}): comma-separated
+# <effect>:<policy> entries (host/read/pure → propose/auto). Unlisted effects
+# keep the default map (host proposes; read/pure auto-run). Empty = defaults.
+PLURNK_SERVICE_EFFECT_POLICY=
 # Optimistic worker settlement: before model dispatch, allow newly started
 # streams or a completion wake with live siblings this many ms to quiesce.
 # Settlement ends immediately at quiescence and never extends its first
 # deadline; survivors follow the monitored lifecycle. 0 = off.
 PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
-# Exec poll backoff (#521, {§exec-poll}): a parked exec with NO explicit `<,P>` cadence is no longer
+# Exec poll backoff ({§exec-poll}, https://github.com/plurnk/plurnk-service/issues/521):
+# a parked exec with NO explicit `<,P>` cadence is no longer
 # park-blind-forever — the loop wakes on an exponential backoff so the model regains a turn to read
 # partial output and re-park a slow long-runner or KILL a stuck one. Wake N fires at BASE·2^min(N,TURNS-1)
 # seconds (60,120,240,…,7680), then holds at the cap. An explicit `<,P>` wins; `<,0>` opts out (blind).
@@ -123,12 +134,7 @@ PLURNK_SERVICE_GIT_ALLOWED=1
 # PLURNK_SERVICE_GIT_AUTO — automatic project-repository membership. =1 includes the Git
 # repository containing project_root; =0 leaves `pick` as the only membership source.
 PLURNK_SERVICE_GIT_AUTO=1
-# PLURNK_SERVICE_GIT_ISO - git READ backend. Default (0) uses the native Git
-# binary. =1 explicitly selects the slower, in-process isomorphic-git backend
-# for a deployment that cannot spawn Git. The two backends never fail over.
-PLURNK_SERVICE_GIT_ISO=0
-# Maximum stdout/stderr payload accepted from one native Git subprocess. The
-# optional in-process reader does not use this bound.
+# Maximum stdout/stderr payload accepted from one native Git subprocess.
 PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
 
 # Ordinary bounded OPEN-body projection. READ/FIND results and PLAN working
@@ -142,17 +148,6 @@ PLURNK_SERVICE_PREVIEW_CHARS=2560
 # line anchor. 0 authenticates only the addressed line.
 PLURNK_SERVICE_LINE_ANCHOR_CONTEXT_LINES=2
 
-# --- Reference docs (auto-READ at turn 0) ---
-# PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a
-# worker://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
-# per workspace via workspace.create settings.mdDocs (content, not a path); those UNION
-# 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 ## Policy section — pointing a
-# PLURNK_SERVICE_MD_* alias at it injects the same file twice.)
 # Turn-0 catalog preview so a run opens oriented, not blank. Folder-capable schemes use
 # FIND(<scheme>:///*): direct entries plus exact dir/** summaries carrying each subtree's
 # recursive item and token counts. Curated kernel docs remain recursive, demonstrating both
@@ -195,10 +190,9 @@ PLURNK_SERVICE_PROMPT_PROJECTION=25%
 # (PLURNK_PLUGINS_TRUSTED_ONLY lives in @plurnk/plurnk-meta — reader-declares: the
 # trust rule's one implementation lives there and so does its knob.)
 
-# PLURNK_SERVICE_DOCS_EXCLUDE — comma list of scheme/exec names dropped from BOTH the teaching oneliner
-# and the materialized pull-doc on load. The default names are omitted from this generic
-# catalogue because their teaching is owned elsewhere. Empty → exclude nothing. Unknown names
-# are inert (a filter, not a contract).
+# PLURNK_SERVICE_DOCS_EXCLUDE — comma list of scheme names dropped from BOTH the teaching oneliner
+# and its materialized pull-doc on load. Executable tools instead use their one enablement policy,
+# so an enabled tool is always discoverable. Empty → exclude nothing. Unknown names are inert.
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 
 # PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
@@ -207,10 +201,9 @@ PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 # PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
 
 # PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Policy
-# section. Unset = the seeded ~/.plurnk/AGENTS.md; a path = that file; EXPLICITLY empty = policy off.
+# section. Unset = the seeded $XDG_CONFIG_HOME/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 — Recap source override (relative to the package root).
 # Unset = the packaged requirements.md.
 # PLURNK_SERVICE_REQUIREMENTS=
@@ -236,12 +229,6 @@ PLURNK_SERVICE_MAX_EMBED_SIZE=0
 # hosts/runs that don't want vector search; the Mock bootstrap and constrained benchmarks set it.
 PLURNK_SERVICE_EMBED_DISABLE=0
 
-# Which exec runtimes the search gate treats as searches — the per-turn cap and identical-query
-# dedup apply to these (the search family delegates page fetches to the entry() sink; {§exec-entry-sink}).
-PLURNK_SERVICE_SEARCH_RUNTIMES=search
-# Per-turn search flood cap: the (N+1)th search EXEC in one turn is refused 429 (dedup of
-# identical queries is unconditional and separate — it strikes and serves the prior results).
-PLURNK_SERVICE_SEARCH_MAX_PER_TURN=3
 # Comma-separated file pathname patterns omitted from search derivations. Content remains directly
 # readable. Patterns without `/` match the basename; patterns with `/` match the full pathname.
 # Uses body-matcher glob syntax; the first match is the observable exclusion reason. Empty = none.

package/INSTALL.md

@@ -1,6 +1,10 @@
 # Configuring plurnk-service
 
-Operator guide. Put machine-specific choices in `~/.plurnk/.env`. Each installed package's `.env.defaults` is the authoritative list and floor for the knobs that package owns; the daemon assembles those files into the read-only `~/.plurnk/.env.defaults` catalog on every boot.
+Operator guide. Put machine-specific choices in
+`$XDG_CONFIG_HOME/plurnk/.env` (normally `~/.config/plurnk/.env`). Each
+installed package's `.env.defaults` is the authoritative list and floor for
+the knobs that package owns. `plurnk-service config defaults` projects the
+complete owner-labelled catalog on demand; no generated copy is persisted.
 
 ## Install
 
@@ -10,7 +14,14 @@ plurnk-service migrate        # apply the disposable version-1 schema baseline
 plurnk-service start
 ```
 
-First start creates `~/.plurnk/`: `.env` (yours, seeded once with a model picker — **edit this**), `AGENTS.md` (the operating policy, yours), `.env.defaults` + `INSTALL.md` (package-owned references, **refreshed every boot** — never edit them). No model ships active; the daemon can boot without one, but model loops fail until `PLURNK_MODEL` selects a declared alias.
+First start creates `$XDG_CONFIG_HOME/plurnk` with `.env` (yours, seeded once
+with three model profiles—**edit this**) and `AGENTS.md` (the operating policy,
+yours). Durable SQLite data defaults to `$XDG_DATA_HOME/plurnk/plurnk.db`. No
+model ships active; the daemon can boot without one, but model loops fail until
+`PLURNK_MODEL` selects a declared alias or exact provider/model route. Use `plurnk-service config`, `config
+edit`, `config defaults`, and `config check` to inspect and maintain the one
+environment cascade. A pre-XDG `~/.plurnk` is never read implicitly; stop the
+old daemon and run `plurnk-service paths migrate` once.
 
 The default service includes local embeddings. An explicitly disabled or unavailable embedder makes `~query` fall back to FTS keyword ranking. Set `PLURNK_MIMETYPES_EMBED_BASE_URL` to use a remote OpenAI-compatible embedding endpoint instead.
 
@@ -21,14 +32,20 @@ Higher-priority source classes override lower ones ({§operator-config-precedenc
 | Priority | Source                                 | Role                                                                                       |
 |---------:|----------------------------------------|--------------------------------------------------------------------------------------------|
 |        1 | Installed packages' assembled defaults | Versioned floor; one owner per key. A collision fails boot naming both owners.             |
-|        2 | `~/.plurnk/.env`                       | User configuration, seeded once and never overwritten. **Write generated config here.**    |
+|        2 | `$XDG_CONFIG_HOME/plurnk/.env`          | User configuration, seeded once and never overwritten.                                    |
 |        3 | `./.env`                               | Configuration for the current working directory.                                           |
 |        4 | `--config=<path>`                      | One explicit service configuration file.                                                   |
 |        5 | `--env-file*`                          | Repeatable explicit files; later files win. The `-if-exists` form skips absent files.       |
 |        6 | Shell environment                      | Process-level operator values.                                                              |
 |        7 | `--<flag>`                             | Highest-priority service CLI value.                                                         |
 
-`~/.plurnk/.env.defaults` is the regenerated assembled catalog, not another input layer. The service CLI mirrors only the `PLURNK_*` variables declared by the service package's own `.env.defaults`: strip `PLURNK_`, lowercase, and replace `_` with `-` (`PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`). Installed plugin knobs remain available through env/config files and the assembled catalog without implicitly expanding the service executable's CLI ({§operator-config-cli-flags}). Feature-flag booleans use `1`, not `true`; `~/` expands to home.
+The service CLI mirrors only the `PLURNK_*` variables declared by the service
+package's own `.env.defaults`: strip `PLURNK_`, lowercase, and replace `_` with
+`-` (`PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`). Installed plugin
+knobs remain available through env/config files and `config defaults` without
+implicitly expanding the service executable's CLI
+({§operator-config-cli-flags}). Feature-flag booleans use `1`, not `true`;
+`~/` expands to home.
 
 ## The prefix law (who owns a flag)
 
@@ -36,6 +53,26 @@ Family prefixes identify the semantic owner: `PLURNK_SERVICE_*` (this daemon), `
 
 When a value is required, an unset or retired name fails boot naming the violated key rather than selecting a silent default.
 
+## Agent Skills
+
+Plurnk reads the standard universal roots: project skills from
+`.agents/skills/<name>/SKILL.md`, then user-global skills from
+`~/.agents/skills/<name>/SKILL.md`. Package-bundled skills form
+the final layer; the default installation includes an attributed, pinned
+`find-skills`. Project names shadow global names, which shadow bundled names.
+Plurnk never copies a bundled skill into the shared global root and does not
+maintain a separate skill registry.
+
+Use the ecosystem CLI when you deliberately install something. A project
+installation is the ordinary default:
+
+```sh
+npx skills add <owner/repo@skill> --agent universal --yes
+```
+
+Add `--global` only when you intend to share that skill with every compatible
+agent using the universal user root.
+
 ## Couplings (the edges an agent gets wrong)
 
 These are relationships *between* flags. Set them as a unit.
@@ -58,12 +95,14 @@ These are relationships *between* flags. Set them as a unit.
   Local llama-server users may set `PLURNK_PROVIDERS_GBNF_<alias>`; transport
   and enforcement are verified at boot. Cloud and endpoint-managed aliases
   leave it unset. A configured PLURNK rail requires reasoning `adaptive` or
-  `on`; pairing it with `off` is invalid. Pin
+  a fixed effort; pairing it with `off` is invalid. Pin
   `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` only when a llama-server cannot be
   fingerprinted reliably.
 - **A reasoning model must reason somewhere.**
-  `PLURNK_PROVIDERS_REASONING_<alias>` selects `off`, `adaptive`, or `on`.
-  An explicit `on` also requires a positive provider reasoning budget.
+  `PLURNK_PROVIDERS_REASONING_<alias>` selects `off`, `adaptive`, `low`,
+  `medium`, or `high`. A fixed effort may require a positive provider reasoning
+  budget when the provider exposes manual token allocation rather than an
+  effort control.
 
 ## Profiles (examples, not a decision tree — adapt to the real box)
 
@@ -78,7 +117,7 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 
 - **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 client surface (the AG-UI+ listener, bound by the plurnk-agui module at boot). Production is single-listener; every first-party client rides it.
-- **Model aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. Optional `PLURNK_MODEL_CHILD=<alias>` selects WORK/FORK descendants; unset inherits the spawning loop's provider. The front door — keep these bare and short.
+- **Model selection** — bare `PLURNK_MODEL` selects a declared alias or exact provider/model route; `PLURNK_MODEL_<alias>` defines an optional friendly route and tuning scope; `PLURNK_BASEURL_<alias>` overrides that alias's endpoint. `PLURNK_MODEL_CHILD` accepts the same selector vocabulary for WORK/FORK descendants; unset inherits the spawning loop's provider.
 - **Loop control / engine rails** — `PLURNK_SERVICE_MAX_TURNS` (−1 = uncapped), `_MAX_COMMANDS`, `_MAX_STRIKES`, `_EMISSION_ATTEMPTS`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_HOLD`, `_OPTIMISTIC_WAIT_MS`, `_EXEC_POLL_SEC`/`_TURNS`, `_EXEC_KILL_GRACE_MS`, `_WORKSPACE_WORKERS_MAX_ACTIVE`.
 - **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
 - **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-0 shallow file-map cap), `_PREVIEW_LINES`/`_PREVIEW_CHARS`, `_LINE_ANCHOR_CONTEXT_LINES`, `_EDIT_RECEIPT_REVISION_CHARS`/`_CONTEXT_LINES`, `_BRANCH_RECEIPT_REVISION_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT` (policy overrides), `_REQUIREMENTS` (Recap-source override), `_MD_<alias>` (materialized reference entry).
@@ -92,8 +131,8 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
   of that provider-derived curation gauge.
 - **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`, `_TTL_MS`, optional `# TAVILY_API_KEY=`, and `PLURNK_SCHEMES_HTTP_TAVILY_DEPTH`/`_TAVILY_TIMEOUT_MS`.
-- **Execs** - `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+- **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`, `_TTL_MS`, optional `# PLURNK_SCHEMES_HTTP_MATERIALIZER=` (a materializer plugin id).
+- **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; web discovery is an MCP attachment (`PLURNK_MCP_<server>`), not an executor.
 - **Hooks** — `PLURNK_HOOKS_COMMAND` plus JSON `PLURNK_HOOKS_ARGS` invokes one exact no-shell command for the core events selected by `PLURNK_HOOKS_EVENTS`; see `@plurnk/plurnk-hooks/README.md`.
 - **Observability** — standard `OTEL_*` env ({§observability-boundary}):
   `OTEL_TRACES_EXPORTER`/`OTEL_METRICS_EXPORTER` (`otlp` or `console`; unset

package/README.md

@@ -34,7 +34,17 @@ plurnk-service migrate    # apply the disposable version-1 schema baseline
 plurnk-service start      # daemon
 ```
 
-Config + state live in `~/.plurnk/` (created on first start): put your config in `~/.plurnk/.env` (yours, seeded once); the DB defaults to `~/.plurnk/plurnk.db`. Declare a provider/model as `PLURNK_MODEL_<alias>=<provider>/<model-id>`, then select that alias with `PLURNK_MODEL=<alias>`. **[`INSTALL.md`](./INSTALL.md) is the config guide** — the cascade, prefix ownership, coupled settings, and profiles; each installed package's `.env.defaults` supplies its exact machine floor.
+Configuration follows XDG at `$XDG_CONFIG_HOME/plurnk` (normally
+`~/.config/plurnk`); durable data defaults to `$XDG_DATA_HOME/plurnk` (normally
+`~/.local/share/plurnk`). First start seeds the user-owned `.env` and
+`AGENTS.md` once. Select an exact route with
+`PLURNK_MODEL=<provider>/<model-id>`, or declare a reusable/tuned
+`PLURNK_MODEL_<alias>=<provider>/<model-id>` and select its alias. Run
+`plurnk-service config defaults` for
+the complete installed option catalog and `plurnk-service config check` to
+validate without contacting a provider. **[`INSTALL.md`](./INSTALL.md) is the
+configuration guide.** A legacy mixed `~/.plurnk` is moved only by the explicit
+`plurnk-service paths migrate` command.
 
 The 1.x package retains its frozen root library barrel for SemVer compatibility;
 it is not the client boundary and gains no new APIs. Programmatic forensic use