@plurnk/plurnk-service 1.7.0 → 1.9.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,23 @@
 #
 # 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=
+
+# Filesystem creation ceiling. none = deny new files; root = only project_root (default);
+# namespace = also permit canonical outside-root paths. Existing-member writes are unaffected.
+# A workspace may narrow this with settings.fileCreateScope, never widen it.
+PLURNK_SERVICE_FILE_CREATE_SCOPE=root
 
 # --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
 # sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
@@ -42,8 +48,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 +63,15 @@ 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
+# Capability residency is demand-owned. After the final lease, keep the
+# worker warm this many ms for quick reuse. 0 = no grace; -1 = no time bound.
+PLURNK_SERVICE_WORKER_WARM_MS=900000
+# Maximum lease-free worker Functionality snapshots retained process-wide. Active work is
+# exempt. 0 = retain none; -1 = no idle-LRU bound.
+PLURNK_SERVICE_WORKER_WARM_MAX=2
 # 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 +79,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 +145,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 +159,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,22 +201,29 @@ 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_SKILLS_CLI — the standard Agent Skills installer command line beneath the Worker
+# `skills` Functionality family (`add` installs, `remove` uninstalls, `discover {source}` lists).
+# The installed SKILL.md, never the CLI's output, is the evidence. Point it at a pinned binary
+# or a fixture; it is never taught to the model or run by a client.
+PLURNK_SERVICE_SKILLS_CLI="npx --yes skills"
+# PLURNK_SERVICE_SKILLS_REGISTRY_URL — the ecosystem registry behind `discover {query}`
+# (GET <url>/api/search?q=…). Empty disables registry search (501 registry-not-configured).
+PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
+
 # 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_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 +249,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,24 @@ 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`. Project names shadow global names. Plurnk
+bundles no skills, never copies anything into a universal root by itself, and
+keeps no separate skill registry.
+
+Skills are managed per Worker through the common Functionality lifecycle —
+`worker.skills.{list,discover,add,enable,disable,remove}` from a client, the
+generated `EXEC [skills]` family from the model. `add` installs through the
+standard ecosystem CLI (`PLURNK_SERVICE_SKILLS_CLI`, default `npx --yes skills`) into
+the chosen scope, `discover` searches the ecosystem registry
+(`PLURNK_SERVICE_SKILLS_REGISTRY_URL`, default `https://skills.sh`), and a skill you
+install with the CLI yourself is admitted at the next turn. Prefer the project
+scope; choose `global` only when you intend to share a 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 +93,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,9 +115,9 @@ 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`.
+- **Files and Git** — `PLURNK_SERVICE_FILE_CREATE_SCOPE=none|root|namespace` bounds new filesystem files (`root` by default); `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout) and `_GIT_AUTO` govern Git participation. A workspace may narrow creation with `settings.fileCreateScope`.
 - **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).
 - **Providers** — the portable provider knobs and defaults are defined by
   `@plurnk/plurnk-providers/.env.defaults`; any provider knob may take an alias
@@ -92,8 +129,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
@@ -59,7 +69,7 @@ The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`,
 
 ## The file sandbox
 
-Plurnk sees what Git or the client explicitly admits. The AGENTS.md policy path is injected separately as privileged policy, not as a file entry. A project file admitted by neither Git nor the client does not exist to the model, and an ignored secret can be neither read nor overwritten. New files can be created only inside the project and only where the result will remain visible; member edits are proposal-gated; an outside-root member is read-only unless the client explicitly granted it. `EXEC` deliberately reaches beyond this file sandbox, so its proposal policy is the machine perimeter. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
+Plurnk sees what Git or an ordinary `pick` admits. The AGENTS.md policy path is injected separately as privileged policy, not as a file entry. A path admitted by neither source does not exist to the model and cannot be overwritten. Accepted creation is exclusive and never orphaned: it is Git-added or receives an inspectable exact pick. Creation defaults to `project_root`, can be disabled or expanded to the canonical namespace by operator policy, and only an explicit pick overrides Git ignore. Member edits remain proposal-gated; an outside-root member is read-only unless a pick grants it. `EXEC` deliberately reaches beyond this file sandbox, so its proposal policy is the machine perimeter. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
 
 ## Tests