@plurnk/plurnk-service 1.24.0 → 1.25.0

package/.env.defaults

@@ -1,9 +1,9 @@
 # @plurnk/plurnk-service — daemon configuration.
 # Active declarations are defaults; commented declarations are optional examples.
-# Put overrides in the shell, ./.env, or $XDG_CONFIG_HOME/plurnk/.env.
+# Put overrides in the shell or $XDG_CONFIG_HOME/plurnk/.env; a working directory's .env is not read.
 # Full installed reference: plurnk-service config defaults
 # Precedence (highest first): CLI flags > shell > --env-file* > --config >
-# ./.env > user .env > package defaults. Later explicit env files win.
+# user .env > package defaults. Later explicit env files win.
 # Service flags mirror these names: PLURNK_SERVICE_MAX_TURNS → --service-max-turns.
 
 # --- Storage ---
@@ -51,11 +51,12 @@ PLURNK_SERVICE_UNATTENDED_PROPOSALS=reject
 PLURNK_SERVICE_FILE_CREATE_SCOPE=root
 # Model-added membership: none | root | namespace. Workspaces may narrow it.
 PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=namespace
-# Operator members definitions enabled by default, JSON array of aliases; [] = none.
-PLURNK_MEMBERS_ENABLED=[]
-# A definition is PLURNK_MEMBERS_<alias>=<glob>; a leading ! excludes.
+# Enable declared membership rules by default; per-alias _ENABLED overrides this.
+PLURNK_MEMBERS_ENABLED=1
+# Lowercase aliases use _ for -. A leading ! in the glob excludes.
 # PLURNK_MEMBERS_docs=docs/**
 # PLURNK_MEMBERS_no_locks=!**/*.lock
+# PLURNK_MEMBERS_docs_ENABLED=0
 # Matched paths a members definition lists as its sample; the rest are counted.
 PLURNK_SERVICE_MEMBERS_SAMPLE=20
 # Git membership, status, and branch integration: 1 = permitted; 0 = denied service-wide.
@@ -193,16 +194,17 @@ PLURNK_SERVICE_FILES_ITEMS=-1
 # Scheme names omitted from discoverable references, comma-separated; empty = none.
 # Executable docs instead follow tool enablement. Plugin trust lives in plurnk-meta's defaults.
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
-# Agent Skills installer command, used by the service beneath skills add/remove/discover.
-PLURNK_SERVICE_SKILLS_CLI="npx --yes skills"
-# Skills search registry (GET /api/search?q=...); empty = registry search disabled.
-PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
-# Results one registry search asks for.
-PLURNK_SERVICE_SKILLS_REGISTRY_LIMIT=20
-# Deadline for one registry search, positive ms.
-PLURNK_SERVICE_SKILLS_REGISTRY_TIMEOUT_MS=30000
-# Deadline for one skills CLI run, positive ms.
-PLURNK_SERVICE_SKILLS_CLI_TIMEOUT_MS=120000
+# Skills, plugin and standalone MCP configuration roots, comma-separated, nearest first: project
+# (the workspace project's .agents), plurnk ($XDG_CONFIG_HOME/plurnk), global (~/.agents).
+PLURNK_SERVICE_ROOTS=project,plurnk,global
+# Agent Skills: whole source definitions override discovered skills by their exact standard name.
+# `_` in a key represents `-`; Unicode names work in .env or via `env 'KEY=value' command`.
+# PLURNK_SKILLS_code_review={"name":"code-review","source":"/srv/skills/code-review"}
+# Declared and discovered skills default enabled; per-name controls override this default.
+PLURNK_SKILLS_ENABLED=1
+# PLURNK_SKILLS_code_review_ENABLED=0
+# Deadline for one skills source fetch (git ls-remote, git clone, tar, unzip), positive ms.
+PLURNK_SERVICE_SKILLS_FETCH_TIMEOUT_MS=120000
 # Extra Markdown after language teaching, reread each turn; unreadable explicit paths fail.
 # PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
 # Policy Markdown: unset = $XDG_CONFIG_HOME/plurnk/AGENTS.md; empty = off; otherwise that path.

package/INSTALL.md

@@ -15,21 +15,33 @@ plurnk-service start
 ```
 
 First start seeds the user's configuration once. No model ships active;
-[choose a model route](https://github.com/plurnk/plurnk-service/blob/main/plurnk-providers/README.md#configure-a-model) before starting a model loop. The version-1 database
-baseline is disposable during development.
+[choose a model route](https://github.com/plurnk/plurnk-service/blob/main/plurnk-providers/README.md#configure-a-model) before starting a model loop.
+
+For an explicitly shared Linux daemon, the npm package includes an example
+[systemd user unit](./plurnk.service). Its comments cover manual installation,
+executable paths, environment, and logs. Installing the package never installs
+or enables the unit.
 
 | 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/` |
+| Plurnk-only Agent Skills | `$XDG_CONFIG_HOME/plurnk/skills/` |
+| Project / global MCP servers | `.agents/mcp.json` / `~/.agents/mcp.json` |
+| Plurnk-only MCP servers | `$XDG_CONFIG_HOME/plurnk/mcp.json` |
 
 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.
 
+Invalid optional configuration stays visible without removing the repair environment.
+`config check` is strict; ordinary startup keeps unrelated capabilities and client
+inspection available. Model providers are constructed and verified on selection or
+first use, not on startup. An invalid default never selects a different model:
+choose a valid model in the client or correct the daemon's configuration.
+
 ## Precedence
 
 Highest priority first ({§operator-config-precedence}):
@@ -40,10 +52,12 @@ Highest priority first ({§operator-config-precedence}):
 | 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. |
 
+A working directory's `.env` belongs to that directory's application and is never read. A project's
+variables reach its commands through the workspace environment (`/env import .env`).
+
 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
@@ -56,7 +70,8 @@ the owning declaration specifies its meaning.
 | --- | --- |
 | 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. |
+| MCPs, skills, outbound agents, schedules, membership | Workspace Functionality: list, discover, add, enable, disable, remove. Workers share the workspace's current selection. |
+| Command environment | `env` manages worker overrides or workspace defaults. It does not reconfigure the daemon; running processes keep their launch environment. |
 | 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. |
@@ -77,18 +92,79 @@ 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.
+Project names shadow Plurnk-only names, then user-global names, then
+service-provided skills. Agent Plugin skills join the same scope after standalone
+skills; npm bundles follow user-global roots. These are read-only configuration inputs;
+external edits appear at the next turn. Plurnk's own skill uses the same READ,
+discovery, and workspace enablement as other skills.
+
+`skills (add)` binds a source to this workspace, never installs into those roots.
+Local folders and `SKILL.md` files stay live references, with supporting files in
+place. Git/archive sources become workspace-owned copies retained across enable
+and restart until the source definition changes. `remove` forgets the workspace
+binding without deleting its source. READ is not execution; running a skill's
+script follows ordinary proposal policy. The [skills reference](worker:///_plurnk/plurnk/skills.md)
+covers discovery, source forms, and Git refs.
+
+## Resource definitions
+
+Supported standard sources, environment declarations, and live workspace changes
+feed the same family. Whole definitions replace lower definitions; omitted fields
+never inherit. Workspace overrides win over environment declarations, which win
+over discovered sources. Independent behavior controls cascade separately.
+
+```dotenv
+PLURNK_MCP_docs={"name":"docs","type":"streamable-http","url":"https://docs.example/mcp"}
+PLURNK_MCP_ENABLED=1
+PLURNK_MCP_docs_ENABLED=0
+```
+
+MCP, skills, outbound A2A, schedule, and members use this same naming pattern;
+their `.env.defaults` entries describe each family's definition and controls.
+Aliases use lowercase names, with `_` encoding `-`; skills retain their standard
+Unicode and digit-leading names. An empty definition is invalid, not a disable
+instruction. A control may precede the resource it will govern.
+
+| Action | Effect |
+| --- | --- |
+| Declare in configuration | Supply an inherited definition, enabled by default unless a control disables it. No workspace writes. |
+| `list` | Inspect the effective definition, ownership (`origin`), winning configuration input (`provenance`), enabledness, and runtime readiness without starting it. |
+| `discover` | Return inert candidates; nothing is added or enabled. |
+| `add` | Persist a workspace override and prepare it through the ordinary authorization policy. |
+| `disable` / `enable` | Change availability without forgetting the definition or updating fetched skill copies. |
+| `remove` | Forget the local override and restore the inherited definition and enabledness. Use `disable` to suppress an inherited entry. |
+
+Use the environment cascade for daemon/CI defaults and the subsystem actions for
+live workspace changes. A declared or enabled resource never bypasses capability
+or proposal policy. Unavailable resources retain their exact Problem in `list`.
+Configuration provenance names the definition's environment key, discovered
+`SKILL.md` path, or MCP JSON file and JSON Pointer, not a dotenv file or shadowed history. Local overrides are
+workspace-owned; removing one exposes its current inherited source again.
+
+## Native extensions
+
+Standard [Agent Plugins](https://agent-plugins.org/specification) keep their portable
+skills and MCP servers and may add one native capability under `extensions.ai.plurnk`.
+That declaration uses the family's existing loader and lifetime. For daemon lifecycle
+hooks, declare a module:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "example-plugin",
+  "extensions": { "ai.plurnk": { "kind": "module", "module": "ai.plurnk/plugin.js" } }
+}
+```
+
+Daemon modules load at startup from installed npm packages and selected user roots:
+`$XDG_CONFIG_HOME/plurnk/plugins/` before `~/.agents/plugins/`, then npm. The manifest name
+identifies a plugin across those sources. Project plugins never load native code into the daemon.
+`PLURNK_SERVICE_ROOTS` selects the directory roots; `PLURNK_PLUGINS_TRUSTED_ONLY` governs native
+imports, using the npm package name when present or the plugin name otherwise.
+Other native families (executors, schemes, providers, mimetypes and HTTP materializers)
+require npm installation and retain their own loading behavior.
+
+The module exports a lifecycle object or a no-argument factory. `setup` registers capabilities;
+`stop` drains producers; `close` releases registrations and observers. See {§module-lifecycle}.
+Native files and the optional configuration panel live under `ai.plurnk/`; its `.env.defaults`
+joins the ordinary floor. npm owns dependencies and delivery, not a second native declaration.

package/README.md

@@ -53,8 +53,8 @@ configuration guide.** A legacy mixed `~/.plurnk` is moved only by the explicit
 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
 imports `@plurnk/plurnk-service/digest`.
-The digest replaces its selected output directory; keep that directory separate
-from its input database. Overlapping input/output paths are refused.
+The digest requires a new or empty output directory, separate from its input
+database. Existing output and overlapping input/output paths are refused.
 
 ## Contract & siblings