@plurnk/plurnk-service 1.16.4 → 1.17.0

package/INSTALL.md

@@ -1,147 +1,93 @@
 # Configuring plurnk-service
 
-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.
+Each package's `.env.defaults` is its authoritative configuration reference.
+`plurnk-service config defaults` prints the complete installed catalog, including
+comments and optional examples. Inside Plurnk, READ
+`skill://plurnk/.env.defaults` for the same catalog. Neither exposes effective
+environment values or creates another configuration file.
 
-## Install
+## Install and locate
 
 ```sh
 npm install -g @plurnk/plurnk-service
-plurnk-service migrate        # apply the disposable version-1 schema baseline
+plurnk-service migrate
 plurnk-service start
 ```
 
-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 embedding artifact includes its local model and the exact counters required by supported hosted profiles. An explicitly disabled or unavailable embedder makes `~query` fall back to FTS keyword ranking. Set `PLURNK_EMBEDDING_MODEL` to a standard provider/model route or declared model alias to use a hosted or operator-run embedding endpoint instead; provider endpoints and credentials use the same provider configuration as generation. A custom profile whose counter is not built in may add the optional `@plurnk/plurnk-mimetypes-tokenizers` catalog.
-
-Every supported source-language grammar ships with the service. Structural
-search and code-graph extraction need no additional language installation;
-each grammar's WASM is loaded only when parsing that language.
-
-## The cascade (where a value actually comes from)
-
-Higher-priority source classes override lower ones ({§operator-config-precedence}):
-
-| Priority | Source                                 | Role                                                                                       |
-|---------:|----------------------------------------|--------------------------------------------------------------------------------------------|
-|        1 | Installed packages' assembled defaults | Versioned floor; one owner per key. A collision fails boot naming both owners.             |
-|        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.                                                         |
-
-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)
-
-Family prefixes identify the semantic owner: `PLURNK_SERVICE_*` (this daemon), `PLURNK_PROVIDERS_*`, `PLURNK_MIMETYPES_*`, `PLURNK_EXECS_*`, `PLURNK_SCHEMES_HTTP_*`, `PLURNK_AGUI_*` (the AG-UI module), and `PLURNK_CLIENT_*` (the CLI). Bare `PLURNK_*` names are reserved for front-door or cross-family concepts such as model aliases, endpoint binding, and plugin trust. Even a cross-family key has one physical reader and one `.env.defaults` owner; “shared” never means duplicate implementations. Vendor keys (`OPENAI_API_KEY`, `FIREWORKS_API_KEY`, and peers) retain their vendor conventions.
-
-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.
-
-- **One generation envelope derives input capacity.** The provider resolves
-  model input/output limits, the effective context window, one total output
-  budget, and an optional reasoning subset. Its resulting input capacity drives
-  both physical request admission and Core's model-independent curation gauge;
-  Core has no second token budget or packing margin. Request-shaped token
-  evidence remains provider-owned ({§tokenomics-window-partition}).
-  `PLURNK_SERVICE_PROMPT_PROJECTION_<alias>` assigns a stable percentage of
-  that gauge to automatic prompt bodies; it never limits stored prompt size
-  ({§prompt-projection}).
-- **Reasoning is part of output.** `PLURNK_PROVIDERS_OUTPUT_BUDGET_<alias>` is
-  the complete response ceiling, including hidden reasoning. Optional
-  `PLURNK_PROVIDERS_REASONING_BUDGET_<alias>` is a strict subset; unset leaves
-  depth provider-adaptive. Activation remains the independent
-  `PLURNK_PROVIDERS_REASONING_<alias>` contract.
-- **Local GBNF is optional.** The PLURNK language is always parsed normally.
-  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
-  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`, `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)
-
-- **Local GPU (llama-server).** `PLURNK_MODEL_local="openai/<name>"`, `OPENAI_BASE_URL=http://127.0.0.1:<port>`, `PLURNK_MODEL=local`, `PLURNK_PROVIDERS_GBNF_local=plurnk.qwen.gbnf` for Qwen's template-prefilled `<think>` protocol (or `plurnk.gemma.gbnf` when Gemma generates a complete Harmony channel). The provider detects llama-server, verifies its GBNF transport, and derives input capacity from the detected window and configured output envelope. Add `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only when the endpoint cannot be fingerprinted reliably.
-- **Cloud, bring-your-own-key.** `PLURNK_MODEL_cloud="openrouter/<model>"`, `OPENROUTER_API_KEY=…`, `PLURNK_MODEL=cloud`. No local GBNF or `LLAMA_SERVER` pin.
-- **plurnk.ai endpoint.** `PLURNK_MODEL_plurnk="plurnk/plurnk"`, `PLURNK_API_KEY=…`, `PLURNK_MODEL=plurnk`.
-- **Headless / CI / constrained container.** A CPU-only box should NOT disable semantic search — it should select a hosted embedder with `PLURNK_EMBEDDING_MODEL=<provider>/<model>` or an embedding alias. The route inherits the standard provider endpoint and credential contract; a local OpenAI-compatible GPU endpoint uses the same alias and `PLURNK_BASEURL_<alias>` convention as generation. Weak hardware is the target workload, not a reason to shed capability; `PLURNK_SERVICE_EMBED_DISABLE=1` exists for test lanes that deterministically assert non-semantic behavior, nothing else. 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 the service's `.env.defaults`)
-
-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 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 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`.
-- **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), `_RECAP` (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
-  suffix that wins over the bare fallback.
-- **Provider envelope and prompt projection** —
-  `PLURNK_PROVIDERS_CONTEXT_WINDOW`/`_OUTPUT_BUDGET` and optional
-  `_REASONING_BUDGET` derive physical input capacity.
-  `PLURNK_SERVICE_PROMPT_PROJECTION` assigns the automatic prompt-body share
-  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_EMBEDDING_MODEL` (optional provider route/alias), and `PLURNK_EMBEDDING_WORKERS` (the local embedder pool — mimetypes-owned).
-- **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
-  keeps the signal off), `OTEL_SERVICE_NAME` (default `plurnk-service`),
-  `OTEL_SDK_DISABLED` (opt out), and the OTLP exporters' own
-  `OTEL_EXPORTER_OTLP_*` settings. An unconfigured daemon never loads the OTel
-  SDK. Prompts, reasoning, file bodies, URLs, secrets, and plugin payloads are
-  never exported.
-
-The client's own knobs live under `PLURNK_CLIENT_*` (`--workspace`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.
+First start seeds the user's configuration once. No model ships active;
+choose a model route before starting a model loop. The version-1 database
+baseline is disposable during development.
+
+| Resource | Default location |
+| --- | --- |
+| User configuration | `$XDG_CONFIG_HOME/plurnk/.env` (`~/.config/plurnk/.env`) |
+| Operating policy | `$XDG_CONFIG_HOME/plurnk/AGENTS.md` |
+| Database | `$XDG_DATA_HOME/plurnk/plurnk.db` (`~/.local/share/plurnk/plurnk.db`) |
+| Project configuration | `.env` in the service's working directory |
+| Project / global Agent Skills | `.agents/skills/` / `~/.agents/skills/` |
+
+Use `plurnk-service config` for paths and precedence, `config edit` to edit the
+user file, and `config check` to validate it. An old `~/.plurnk` is not read
+implicitly; `plurnk-service paths migrate` relocates it with the daemon stopped.
+
+## Precedence
+
+Highest priority first ({§operator-config-precedence}):
+
+| Source | Rule |
+| --- | --- |
+| Service CLI flags | Explicit values win over all environment layers. |
+| Initial shell environment | Preserved over files. |
+| `--env-file` / `--env-file-if-exists` | Repeatable; later files win. The optional form skips absent files. |
+| `--config=<path>` | One explicit service configuration file. |
+| `./.env` | Service working-directory configuration. |
+| `$XDG_CONFIG_HOME/plurnk/.env` | User configuration. |
+| Installed packages' `.env.defaults` | Set-if-unset floor; duplicate key ownership fails boot. |
+
+For a service-owned variable, strip `PLURNK_`, lowercase, and replace `_` with
+`-` to obtain its CLI flag: `PLURNK_SERVICE_MAX_TURNS` → `--service-max-turns`.
+Plugin settings remain environment/configuration values; they do not extend the
+service CLI. Boolean flags use `1` and `0`. An empty value is not an unset value;
+the owning declaration specifies its meaning.
+
+## Choose the right scope
+
+| Change | Owner and effect |
+| --- | --- |
+| Startup defaults or installed plugin configuration | The daemon's environment cascade. A remote client's shell does not change it. |
+| Model, reasoning, child model | Worker selections persist. Set them through client controls; changing a startup default does not retarget an existing Worker. |
+| MCPs, skills, agents | Workspace Functionality: list, discover, add, enable, disable, remove. Workers share the workspace's current selection. |
+| External capabilities | Service policy is a ceiling; workspace policy can narrow it for every worker. Hiding a doc does not grant or revoke authority. |
+| Proposal review / YOLO | Decides who accepts or rejects an admitted operation. Automatic acceptance never overrides capability or resource permissions. |
+| File creation and membership | Separate policies. Creating an out-of-root file, admitting a new file, and editing an existing member are distinct decisions. |
+| User-facing behavior | Operating policy; use configuration for runtime controls. |
+
+The [model chapter](skill://plurnk/references/models.md) covers alias tuning,
+reasoning and output budgets, local endpoints, caching, and connectivity.
+The defaults catalog groups the remaining settings by their owning subsystem:
+permissions, loop limits, residency, execution, context, indexing, MCP, A2A,
+hooks, HTTP, and content handling. Search the catalog for that subsystem instead
+of relying on a second list of knobs here.
+
+For file-access questions, inspect the generated
+[members reference](worker:///_plurnk/plurnk/members.md) alongside the file
+creation/membership defaults. Client controls inspect effective capabilities;
+a model cannot widen their ceiling by changing its policy prose.
+
+## Skills
+
+Project names shadow global names, which shadow service-provided skills.
+Plurnk's own skill uses the same discovery, READ, and workspace enablement as
+installed skills. It is not copied into a universal root.
+
+Clients use `workspace.skills.{list,discover,add,enable,disable,remove}`; models use
+the generated `skills` executor. `discover` returns candidates without
+installation. `add` installs through the standard skills CLI into the chosen
+project or global scope; `remove` uninstalls a workspace-origin installation.
+Service-provided entries can be disabled, not uninstalled through that action.
+An external installer changes the available catalog at the next turn.
+
+Project installation is local to that project. Global installation intentionally
+shares the skill with other compatible agents using `~/.agents/skills/`.
+Supporting files stay in their original tree, including script siblings.
+READ is not execution; running a script follows ordinary proposal policy.

package/README.md

@@ -11,14 +11,14 @@ The exact model-facing language and operation set are owned by
 [`plurnk.md`](https://github.com/plurnk/plurnk-service/blob/main/plurnk-contracts/plurnk.md). In brief, an agent can:
 
 - inspect and modify admitted project files and durable worker entries;
-- search lexical, structural, graph, and embedding-derived indexes;
+- search lexical, structural, and graph indexes;
 - run registered executors and observe their runtime-named streams;
 - delegate to workers, communicate, and collect their results; and
 - curate its addressable log with scoped or whole-item `KILL` operations.
 
 ## Lifecycle model
 
-Workspace = the shared world (one filesystem + membership overlay). Worker = one actor and its private history over that world. Loop = one queued-to-terminal unit of work within a worker; each loop contains turns, and every model turn leads with `PLAN`. Workers fork and message each other — many clients, many workers, one workspace.
+Workspace = the shared world (one filesystem + membership overlay). Worker = one actor and its history over that world. Loop = one queued-to-terminal unit of work within a worker; each loop contains turns, and each model turn ends with a TASK inventory that determines its workflow outcome. Workers fork and message each other — many clients, many workers, one workspace.
 
 ## Integration
 
@@ -26,11 +26,15 @@ Clients use AG-UI management actions and AG-UI Run streams exposed by
 `@plurnk/plurnk-agui`. Core supplies an in-process daemon seam; it does not open
 a second client transport.
 
+`models.list` locally lists catalog routes, configuration readiness, and each
+route's accepted `capabilities.reasoningPolicies`. `worker.reasoning.get`
+reports the choices shared by a worker's selected model and spawn override.
+
 ## Start
 
 ```sh
 npm install -g @plurnk/plurnk-service
-plurnk-service migrate    # apply the disposable version-1 schema baseline
+plurnk-service migrate    # apply the disposable schema baseline (its chapters, in order)
 plurnk-service start      # daemon
 ```
 
@@ -63,9 +67,9 @@ imports `@plurnk/plurnk-service/digest`.
 
 The daemon can emit OpenTelemetry traces and low-cardinality metrics through the standard `OTEL_*` environment ({§observability-boundary}): `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal, `OTEL_SERVICE_NAME` names the service, and `OTEL_SDK_DISABLED` opts out. Unconfigured, the daemon never loads the SDK. The boundary observes lifecycle (workspace, loop, turn, provider, parse, dispatch, proposal, stream, digest) without ever recording prompts, reasoning, file bodies, URLs, secrets, or plugin payloads.
 
-## Semantic search
+## Full-text search
 
-The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`, whose local model and built-in hosted profiles carry their own exact counters, so `FIND`'s `~query` uses embedding cosine ranking without a separate package install. `PLURNK_SERVICE_EMBED_DISABLE=1` explicitly selects FTS keyword ranking; a missing required embedding artifact is a broken installation and refuses startup. A standard provider route can replace the included local model through the same provider configuration used for generation; custom profiles may add the optional general tokenizer catalog. See [`INSTALL.md`](./INSTALL.md).
+`FIND`'s `~query` uses native SQLite FTS5: words, quoted phrases, prefixes, Boolean expressions, and proximity queries, ranked by BM25. It searches the same readable content as READ, returns source coordinates, and uses ordinary integer result paging. No inference endpoint, model artifact, or extra search package is required.
 
 ## The file sandbox