@plurnk/plurnk-meta 1.20.0 → 1.21.0

package/SPEC.md

@@ -18,6 +18,11 @@ sources into a consuming package would create a second teaching owner.
 | `docs/worker.md`                | Required   | Deep reference prose for the reserved worker scheme | Pull-doc materialization {§schemes-directory}           |
 | `skills/plurnk/SKILL.md`         | Required   | Standard Plurnk skill entry and chapter directory | Service-provided skill {§plurnk-skill} |
 
+Every teaching source, and every package's `docs/*.md`, is written to
+`TEACHING.md`, the style rule for model-facing prose: mechanism over advice,
+one owner per claim, knobs by name, shapes over purposes, one home per
+mechanism, no contract tags on a page.
+
 Required is a package-membership statement, not unconditional packet
 projection. Each source is read only at its consuming boundary; absence or an
 unrelated read failure fails that boundary with the original cause. An empty

package/docs/worker.md

@@ -9,165 +9,125 @@ an entry rather than controlling that worker.
 
 | Address | Meaning | Model access |
 | --- | --- | --- |
-| `worker://reviewer` | Named worker | WORK/FORK create; SEND messages; READ collects; KILL terminates. |
-| `message://reviewer/ab3d5678` | Retained message | READ/FIND/COPY inspect; SEND replies. Neither EDIT nor KILL changes its source. |
-| `ops://reviewer/1` | What that loop said, or how it ended | READ/FIND/COPY inspect; source is immutable. |
-| `worker://reviewer/example.md` | Named scratch entry | Read and write from any worker in the workspace. |
+| `worker://alice` | Named worker | WORK/FORK create; SEND messages; READ collects; KILL terminates. |
+| `message://alice/ab3d5678` | Retained message | READ/FIND/COPY inspect; SEND replies. Neither EDIT nor KILL changes its source. |
+| `ops://alice/1` | What that loop said, or how it ended | READ/FIND/COPY inspect; source is immutable. |
+| `worker://alice/example.md` | Named scratch entry | Read and write from any worker in the workspace. |
 | `worker:///example.md` | Shared commons entry | Read and write. |
 
-The packet names your worker, its parent (`null` at a root), and the loop and turn you are producing under `## Worker`, below the log. Addresses are literal and keep
-the same meaning when passed to another worker. All scratch belongs to the
-workspace; its namespace does not require a namesake worker. Generated
-references live under `worker:///_plurnk/`; reference
-refreshes may replace those generated documents. EDIT creates or changes an
-entry, never a worker. An unscoped EDIT creates the entry from its body;
-KILL with an entry path deletes that entry, not its worker.
-
-````EDIT (worker://reviewer/scratch/greet.mjs) <!-- create the entry from the body -->
-export const greet = (name) => `hello ${name}`;
-
-console.log(greet("world"));
-````
-
-Control addresses contain only scheme and authority: no trailing slash,
-userinfo, port, query, or fragment. Messages and loop outcomes have separate
-addresses; neither is a scratch entry or an actor control.
+The packet's `## Worker` block, below the log, names your worker, its parent
+(`null` at a root), and the loop and turn you are producing. Addresses are
+literal and keep the same meaning when passed to another worker. Scratch
+belongs to the workspace; a namespace does not require a namesake worker.
+Generated references live under `worker:///_plurnk/`, and reference refreshes
+may replace them. EDIT creates or changes an entry, never a worker; KILL with
+an entry path deletes that entry, not its worker. A control address is scheme
+and authority only: no trailing slash, userinfo, port, query, or fragment.
+Messages and loop outcomes have their own addresses; neither is a scratch
+entry or an actor control.
 
 An entry whose source has a readable projection (HTML, a notebook) carries it
 beside the source as `#readable`, text/markdown, in its own line coordinates;
-the default channel stays the source. Patterns match the channel they address:
-`page.html` matches the markup, `page.html#readable` the Markdown. The
-projection follows every source write and is never written itself.
-
-## Turn sources
-
-| Address | Read-only source in the named worker's history |
-| --- | --- |
-| `ops://<worker>/<loop>/<turn>` | The exact submitted program, including interstitial text. |
-| `reasoning://<worker>/<loop>/<turn>` | Original provider reasoning when exposed, or a harness turn's authored rationale. |
-| `note://<worker>/<loop>/<turn>/<item>` | The literal NOTE body, from the program or exposed reasoning; the receipt gives its address. |
-
-The worker name is required. Any worker in the workspace can READ these sources;
-SEND an address to share a note deliberately. `log:///` remains your own context.
-READ brings the selected source into your log; KILL of that READ curates only
-its log projection, never the original evidence. No later reasoning is added
-automatically after initialization's example READ.
-
-A READ can retain your current turn's reasoning: the source exists when your
-OPs execute. The packet's `## Worker` block names the coordinate you are
-producing. For example, as `worker://reviewer` on `"loop":1,"turn":3`:
+the default channel stays the source, and a pattern matches the channel it
+addresses. The projection follows every source write and is never written
+itself.
 
-````READ (reasoning://reviewer/1/3) <1,-1>
-````
-
-The ordinary READ receipt appears in subsequent packets. A turn that produced
-no reasoning reads empty; a turn that has not happened returns a missing-source
-result. READ never requests inference.
+## Delegation
 
-NOTE retains working memory without changing the loop state. Only NOTE also
-executes from exposed reasoning; quoted examples and other reasoned operations
-remain data. Notes are ordinary log items: KILL or trim their log projection
-when no longer useful. Their read-only sources remain searchable and
-READable, including after log curation or a FORK.
+WORK starts a fresh log with the task body as its prompt; FORK copies your
+history and named scratch into the new name, then diverges. Embedded addresses
+are preserved verbatim. Both share the workspace. An omitted address allocates
+a short worker name, reported in the receipt; an explicit name cannot replace
+an existing worker, even after it finishes. Names match
+`[A-Za-z0-9][A-Za-z0-9_-]{0,62}` and are case-sensitive. SEND to an existing
+worker gives it a follow-up task. `[{"env": {...}}]` on WORK or FORK is the
+child's starting environment (`env.md`).
+
+Parents observe a direct child's mutations, messages, executor invocations, and
+worker launches, including failed actions, as rows in their own log.
+Exploration and context curation (NOTE, READ, FIND, BARE, WAIT, and log KILL)
+stay with the child, including READs of executor output. These observations
+never wake the parent; replies and child conclusions retain their ordinary
+delivery and wake behavior.
 
-````FIND (note://reviewer/**) /parser/
-````
+## Lifecycle
 
-````READ (note://reviewer/1/3/2) <1,-1>
-````
+Ordinary operations keep the loop working while children run; WAIT joins their
+activity. With live work (a child or an open stream) the loop parks and wakes
+when that work settles, when a message arrives, or on an open stream's
+observation cadence; without live work it continues at once. Several WAITs in
+one turn are one park, and what a WAIT names is its label; scope and metadata
+decorations are ignored.
+
+A wake ends the suspension, not its held work; a further WAIT waits again.
+Waking retains the loop's messages, turn allowance, and remaining execution
+time; parked time does not consume execution time. A turn containing only a
+parameterless KILL requests completion: its body answers the Open Messages, or
+is empty when an already-delivered answer stands. While live work remains, that
+KILL joins it without cancelling it and delivers no final answer.
+
+Each child task's conclusion wakes its waiting parent and arrives once, as an
+`_plurnk` READ of `ops://alice/1` carrying what the child said: the
+execution outcome, not another message, and not delivered again as a reply. A
+failure retains its status and Problem. READ that address with a scope to
+inspect more of the exact result, even after the child starts another task.
+Bare `READ (worker://alice)` collects the current result instead, naming its
+exact source in `resource`; while the child is running it returns `425`. A
+result does not imply that every task in that worker has finished.
 
-## Delegation
+`KILL (worker://<name>)` cancels that worker and its descendants, including
+queued work and unread messages. History remains readable; a later SEND can
+start new work.
 
-Parents passively observe child mutations, messages, executor invocations, and
-worker launches, including failed actions. Exploration and context
-curation (NOTE, READ, FIND, BARE, WAIT, and log KILL) stay with the child, including
-READs of executor output. These observations never wake the parent; replies and
-child conclusions retain their ordinary delivery and wake behavior.
+## Messages
 
 Open Messages names unanswered messages; an arrival receipt's `resource` links
-to the same source. SEND to that address answers that message. A targetless SEND
-answers your observed Open Messages, or your loop's original message when none
-remain open. A concluding parameterless KILL uses the same reply routing for its
-body; no preceding SEND is needed to answer those messages. An empty targetless
-SEND delivers nothing. SEND to a worker control address gives it
-new work instead. Curation of a message's log occurrences never deletes the
-source or changes whether it was answered. Another worker may answer it;
-the assigned worker and original sender receive that reply without a new request.
-
-**WORK to delegate, FORK to branch.** WORK starts a fresh log with your task
-prompt; FORK copies your history and named scratch into its new name, then
-diverges. Embedded addresses are preserved verbatim. Both share the workspace.
-Omit the address to allocate a short worker name, reported in the receipt;
-explicit names cannot replace an existing worker, even after it finishes.
-Names match `[A-Za-z0-9][A-Za-z0-9_-]{0,62}` and are case-sensitive.
-A path outside the `worker://` scheme is the child's prompt resource, as for
-BARE: `WORK (specs/feature.md)` reads the file whole as the task,
-an inline body follows it after a blank line, and the child is auto-named.
-Use SEND to give an existing worker a follow-up task.
-
-SEND accepts `[{"attachments":["report.pdf","worker:///example.md"]}]`.
-It delivers send-time copies through ordinary resource links, not native media
-injection; the recipient READs what it needs. Missing sources fail before
-delivery. The same option works on a targetless reply.
-
-A SEND takes no scope. To deliver a message later or on a cadence, to a worker
-or to yourself, add a rule with the `schedule` family; it arrives as an
+to the same source. SEND to that address answers that message. A targetless
+SEND answers your observed Open Messages, or your loop's original message when
+none remain open; a concluding parameterless KILL uses the same reply routing
+for its body. An empty targetless SEND delivers nothing. SEND to a worker
+control address gives it new work instead. Curation of a message's log
+occurrences never deletes the source or changes whether it was answered.
+Another worker may answer it; the assigned worker and original sender receive
+that reply without a new request.
+
+SEND accepts `[{"attachments":["report.pdf","worker:///example.md"]}]`:
+send-time copies delivered through ordinary resource links, not native media
+injection; the recipient READs what it needs, and a missing source fails before
+delivery. The same option works on a targetless reply. A SEND takes no scope;
+delivery later or on a cadence is the `schedule` family's, arriving as an
 ordinary message from `schedule://<alias>`.
 
 ## BARE inference
 
-BARE makes one isolated call to the child model, not a persistent worker.
-It receives no parent history or tools. Give it a prompt resource, an inline
-prompt, or both; resource text precedes an inline body with a blank line between.
+BARE makes one isolated call to the child model, not a persistent worker. It
+receives no parent history or tools. Its prompt is the fence body.
 
-````BARE (worker://reviewer/question.md)
-````
-````BARE
-What is the capital of Germany?
-````
+```BARE
+A self-contained prompt.
+```
 
-The resource supplies its complete current READ text, not a preview. Neither
-prompt form is truncated to fit; provider capacity still applies. A failed
-source read returns its error without making an inference call.
+The prompt is not truncated to fit; provider capacity still applies.
 Consecutive BARE calls run concurrently and settle before the turn continues.
 Their answers are ordinary BARE receipts, visible in the next packet.
 
-## Lifecycle
+## Turn sources
 
-**Continue or wait.** Ordinary operations keep the loop working while children
-run; WAIT joins their activity:
-
-````WORK (worker://capital-checker)
-Find the capital of France from a primary source
-````
-
-````WAIT
-Await capital-checker's answer.
-````
-
-WAIT continues the same loop: with live work—a child or an open stream—the
-loop parks and wakes when that work settles, when a message arrives, or on an
-open stream's observation cadence; without live work it continues at once.
-Several WAITs in one turn are one park, and what a WAIT names is its label.
-Scope and metadata decorations are ignored. To wake later with nothing in flight,
-add a rule with the `schedule` family targeting yourself.
-
-A wake ends the suspension, not its held work. Submit WAIT to wait again. Waking
-retains the loop's messages, turn allowance, and remaining execution time;
-parked time does not consume execution time. After observing the work's results,
-conclude with a turn containing only parameterless KILL. Its body answers the Open
-Messages, or may be empty when an already-delivered answer stands. Premature
-completion delivers no final answer. It joins remaining live work without cancelling it.
-
-Each child task's conclusion wakes its waiting parent and arrives as an
-`_plurnk` READ of `ops://capital-checker/1`, carrying what the child said. This is the
-execution outcome, not another message, and it arrives once: an answer to the task you
-delegated is not delivered again as a separate reply. A failure retains its status and Problem.
-READ that address with a scope to inspect more of the exact result, even after
-the child starts another task. Bare `READ (worker://capital-checker)` collects
-the current result instead, naming its exact source in `resource`. While the child is running it returns
-`425`; ordinary operations continue and WAIT explicitly joins.
-A result does not imply that every task in that worker has finished.
+| Address | Read-only source in the named worker's history |
+| --- | --- |
+| `ops://<worker>/<loop>/<turn>` | The exact submitted program, including interstitial text. |
+| `reasoning://<worker>/<loop>/<turn>` | Original provider reasoning when exposed, or a harness turn's authored rationale. |
+| `note://<worker>/<loop>/<turn>/<item>` | The literal NOTE body, from the program or exposed reasoning; the receipt gives its address. |
 
-`KILL (worker://<name>)` cancels that worker and its descendants, including
-queued work and unread messages. History remains readable; a later SEND can start new work.
+The worker name is required. Any worker in the workspace can READ these
+sources; `log:///` remains your own context. READ brings the selected source
+into your log, and KILL of that READ curates only its log projection, never the
+original evidence. The current turn's reasoning exists when its OPs execute, so
+`READ (reasoning://alice/1/3) <1,-1>` from `worker://alice` on loop 1,
+turn 3 retains it; a turn that produced no reasoning reads empty, and a turn
+that has not happened returns a missing-source result. READ never requests
+inference. NOTE retains working memory without changing the loop state; only
+NOTE also executes from exposed reasoning, while quoted examples and other
+reasoned operations remain data. Notes are ordinary log items whose read-only
+sources stay searchable (`FIND (note://alice/**) /parser/`) and READable
+after curation or a FORK.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-meta",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "The plurnk metaproject layer, published: plugin-membership primitives (the ONE trust rule, scope-agnostic symlink-aware enumeration, deployment-root resolution), the project teaching corpus (personality, Recap, scheme docs), and the home for family tooling.",
   "keywords": [
     "plurnk",

package/skills/plurnk/SKILL.md

@@ -9,11 +9,11 @@ description: Configure Plurnk, select and tune models, and look up its worker an
 | --- | --- |
 | Configuration cascade, persistence, permissions, skills | [Configuration](references/configuration.md) |
 | COPY/MOVE operands, source regions, destination placement | [Copy and move](references/copy-move.md) |
-| Model routes, reasoning, context, local endpoints | [Models](references/models.md) |
+| Model routes, reasoning, output and context limits, cost | [Models](references/models.md) |
 | Every installed package's settings and defaults | [Complete .env.defaults](.env.defaults) |
 | Worker hierarchy, messaging, and delegation | [Worker reference](worker:///_plurnk/plurnk/worker.md) |
 | Which project files you can see, and why a file is missing | [Membership](worker:///_plurnk/plurnk/members.md) |
-| Agent Skills, MCP servers, and A2A agents: when to reach for one, how to add one | `worker:///_plurnk/plurnk/skills.md`, `mcp.md`, `a2a.md` |
+| Agent Skills, MCP servers, and A2A agents: what each is and how one is added | `worker:///_plurnk/plurnk/skills.md`, `mcp.md`, `a2a.md` |
 | Running code: the shell and each interpreter's body, stdin, arguments, exit status | `worker:///_plurnk/plurnk/sh.md`, `node.md`, `python3.md`, … |
 | Enabled MCP server invocations and schemas | `worker:///_plurnk/tools/` |
 | Built-in executors and scheme references | `worker:///_plurnk/plurnk/` |