@plurnk/plurnk-meta 1.3.11 → 1.4.0

package/.env.defaults

@@ -1,5 +1,5 @@
 # @plurnk/plurnk-meta — the metaproject layer (membership primitives + teaching corpus).
-# Reader-declares (§operator-config-env-defaults): this package's code reads these knobs.
+# Reader-declares ({§operator-config-env-defaults}): this package's code reads these knobs.
 # PREFIX BEND (owner-approved): the knob keeps its subject-named PLURNK_PLUGINS_ prefix —
 # it gates plugins and that is the honest operator-facing name; one-owner-per-key holds.
 
@@ -15,5 +15,5 @@
 PLURNK_PLUGINS_TRUSTED_ONLY=0
 
 # Whole-product orientation deadline in seconds. This includes exhaustive semantic
-# preparation of the admitted repository forest before the model is called.
+# preparation of the workspace's admitted project repository before the model is called.
 PLURNK_ACCEPTANCE_TIMEOUT=3600

package/CORPUS.md

@@ -1,25 +1,44 @@
-# plurnk-docs
+# plurnk teaching corpus
 
-The plurnk teaching corpus. Markdown consumed by [plurnk-service](https://github.com/plurnk/plurnk-service) at runtime — no code, no build.
+Authored defaults published by `@plurnk/plurnk-meta` and consumed by
+`@plurnk/plurnk-service`. The membership and ownership boundary is specified at
+{§teaching-corpus}; core owns runtime projection.
 
 ## Contents
 
-- `docs/<scheme>.md` — per-scheme long-form teaching, materialized as `plurnk://docs/<scheme>.md` entries the model READs (known, unknown, run, log).
-- `PLURNK_PERSONALITY.md` — the default operating policy, seeded once to `~/.plurnk/AGENTS.md` and foisted as `## Plurnk Service Policy`.
-- `requirements.md` — the static contract appended to every user packet (`system_requirements` default).
+| Source                          | Consumer admission                                                           |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| `PLURNK_PERSONALITY.md`         | Read before the first-run seed of user-owned `~/.plurnk/AGENTS.md`.          |
+| `requirements.md`               | Read for the default compact recap rendered under `## Recap`.                |
+| `docs/log.md`, `docs/worker.md` | Read when registered built-in pull docs are materialized.                    |
+| `docs/questions.md`             | Read only when operator questions are enabled, then materialized as a doc.   |
+
+Core materializes eligible pull docs at `worker://plurnk/docs/<name>.md` and
+exposes them through the turn-0 `FIND(worker://plurnk/docs/**)` catalog. Merely
+placing a file in `docs/` does not register a scheme or make speculative
+teaching current. Every listed source is a required package member; a missing
+or failed read surfaces at the admission boundary rather than silently reducing
+the corpus.
 
 ## The teaching split
 
-**Grammar teaches the language; docs teach the world.** [plurnk-grammar](https://github.com/plurnk/plurnk-grammar)'s ANTLR grammar and `plurnk.md` own op syntax and the model-facing language. This package owns scheme behavior, delegation workflow, disposition, and standing rules — the corpus tuned against live model behavior (steer wording, weak-model teaching, pressure habits).
+**Contracts teach the language; docs teach the world.** The contracts parser and
+`plurnk.md` own operation syntax and model-facing language. Core and capability
+specifications own runtime semantics; this package owns their authored teaching
+projections. Live model evidence tests whether that teaching is legible without
+turning telemetry into unsolicited workflow direction.
 
 ## Contract
 
-plurnk-service resolves these files from this package (`Paths`), pins the version, and validates teaching changes with its live/demo tiers. A teaching change ships as a bump here; the service adopts it like any plugin. File teaching asks and steer-wording issues HERE, not on the daemon.
+plurnk-service resolves these files from the installed package through `Paths`
+rather than carrying copies in core. Model-facing teaching changes are verified
+through the composed product gates and tracked against the meta owner in the
+monorepo forge.
 
-## Teaching doctrine (adopted from the grammar lane, #392 — data-backed, evidence cited)
+## Teaching doctrine
 
 **Canon-voice calibration (owner-ruled 2026-07-06, probe-backed).** Voice tunes to the FLOOR model's minimum-audible threshold, never any tier's max compliance. A footer loud enough to fix the floor OVER-DRIVES strong models (live evidence: Grok Build fanatically FOLDs under a loud budget footer). Soft is safe because the engine makes floor-misses RECOVERABLE (premature-200 -> pending-set 409 -> repair); that coupling is load-bearing — if failures stop being recoverable, recalibrate louder. The footer is pluggable; potato-heavy deployments inject more at their discretion. The one recency-sensitive line is await-before-200 (lean-footer A/B, gemma, n=6: 6/6 reap in the recency footer vs 3/6 cached-canon-only). Retreat trigger: 409-repair LOOPS (not single misses); first line restored is await-before-200.
 
-**The requiem acceptance gate.** Teaching changes ship against BEFORE/AFTER corpus deltas (reasoning-token + requiem-recurrence), never hunches. Triage separates legibility debt from load-bearing discipline pain: the FOLD/KILL burden, the compression, and the dialect count are the PRODUCT (the model curating its own context) — never sanded off because models complain. A re-probe against >=0.76.5 is owed (grammar lane).
+**The requiem acceptance gate.** Teaching changes ship against BEFORE/AFTER corpus deltas (reasoning-token + requiem-recurrence), never hunches. Triage separates legibility debt from genuine protocol friction. Model-owned context is the product property: deterministic state and reversible OPEN/FOLD tools support the model's judgment without prescribing what to hide. A re-probe against >=0.76.5 is owed (grammar lane).
 
 **Example doctrine (Arecibo teaching).** Concrete over placeholder — a live model spawned a worker literally named 'name' from a (worker://name) table cell within a day of shipping; placeholders in reserved-bracket forms are doubly banned. Bare-gesture register per section — op-teaching lines carry the gesture, the mechanism stays the engine's; match the surrounding register. Distribution is load-bearing — clustered examples teach false couplings; rebalance coverage, never add runtime prose. TIME is a distribution axis — dynamics teach as protocol-accurate worked multi-turn traces (the Delegation breath), never prose essays; an inaccurate trace (same-turn READ+200) models the wrong protocol.

package/DIVERGENCES.md

@@ -16,7 +16,8 @@ especially for smaller models.
 
 Interoperability:
 
-- PLURNK consumes MCP servers through `plurnk-execs-mcp`.
+- PLURNK hosts current MCP servers through `@plurnk/plurnk-mcp`, exposing
+  their tools and resources through the ordinary operation language.
 - Clients use AG-UI.
 - Provider adapters use established model APIs.
 
@@ -35,7 +36,7 @@ MCP, AG-UI, or provider wire protocols.
 
 ## AG-UI management extensions
 
-AG-UI defines agent runs but not all workspace-management operations PLURNK
+AG-UI defines agent Runs but not all workspace-management operations PLURNK
 requires. Management actions therefore use AG-UI's extension fields and custom
 events on the same authenticated endpoint.
 

package/DOGFOOD.md

@@ -1,18 +1,24 @@
-# Metaproject agentic-readiness gate
+# Metaproject orientation-readiness gate
 
-This is an opt-in milestone qualification for using PLURNK to develop the complete
-PLURNK metaproject. It is intentionally expensive: a fresh run semantically
-prepares the complete repository forest before asking a floor model to orient
-itself through the outside client. Run it when the focused package, integration,
-demo, live-model, and modest-candidate paths are already healthy—not as a routine
-debugging loop or ordinary release gate.
+This opt-in capstone asks a floor model to inspect an assembled open-project
+forest through the outside client and deliver an evidence-bearing orientation
+report. It is intentionally expensive: a fresh campaign semantically prepares
+the complete forest. Execute it only after the focused package, integration,
+demo, live-model, and modest-candidate paths are healthy—not as a routine
+debugging loop or release gate.
 
 Invoke it with:
 
 ```sh
-npm run readiness:metaproject -- --model <alias> --requiem --preserve
+PLURNK_ACCEPTANCE_PROJECT_ROOT=/path/to/open-project-forest \
+PLURNK_CLIENT_CHECKOUT=/path/to/open-client \
+  npm run readiness:metaproject -- --model <alias> --requiem --preserve
 ```
 
+Both paths are explicit preconditions. The runner never guesses a sibling
+checkout or treats another organization under a shared parent directory as
+part of the open project.
+
 This gate does not replace the evidence ladder that qualifies it:
 
 1. Deterministic package and integration coverage proves owned contracts.
@@ -22,56 +28,67 @@ This gate does not replace the evidence ladder that qualifies it:
    enough to test seriously.
 4. The separate bench lane runs real third-party agentic benchmarks and preserves
    their digest, reasoning, and requiem evidence.
-5. Only after those layers are healthy does this full-forest run ask whether
+5. Only after those layers are healthy does this full-forest campaign ask whether
    PLURNK is ready to develop PLURNK itself.
 
-The gate belongs to `plurnk-meta` because it crosses family ownership: canonical service installation, optional-provider assembly, the outside client, project membership, AG-UI, proposal review, model routing, persistence, and forensic digestion.
+The canonical `plurnk-service` checkout owns this gate. Its doctrine lives in
+`plurnk-meta` because the report crosses service, contracts, plugins, the
+outside client, project membership, AG-UI, model routing, persistence, and
+forensic digestion.
 
 ## Preconditions
 
 - A clean canonical `plurnk-service` checkout with its gate green.
-- The outside `plurnk` client checkout built from its repository head.
+- The explicit outside open-client checkout built from its repository head.
 - Every default-installed optional provider resolvable from the daemon.
-- A project root containing its automatic root `AGENTS.md` and manually declared repository forest.
+- An explicitly assembled open-project forest with its root `AGENTS.md`; shared
+  parent directories containing other organizations are not valid substitutes.
 - One inexpensive capable model alias and, optionally, one local smoke-test alias.
 
 Missing preconditions are RED outcomes. The runner never silently skips a phase.
 
 ## Contract
 
-One run must prove all of the following through production client and AG-UI surfaces:
+One campaign proves the following through production client and AG-UI surfaces:
+
+1. **Candidate build.** The exact service and explicit outside-client checkouts build.
+2. **Clean bootstrap.** A canonical daemon starts on a new database and the
+   client creates a user-named workspace over the explicit forest.
+3. **Inspection.** The model performs successful retrievals, including READ,
+   before answering and names multiple inspected repository artifacts.
+4. **Comprehension.** The report covers service, contracts/DSL, client/AG-UI,
+   repository topology, current-work evidence, and confidence-limiting gaps.
+   If the canonical forge is unavailable inside the run, it must say that the
+   current goal is unverified rather than promote archived GitHub history.
+5. **Forensics.** The supported digest captures the database, packet, reasoning,
+   usage, and operation evidence used by the deterministic verdict.
 
-1. **Clean bootstrap.** Start from a new database, boot the canonical daemon, and create a user-named workspace.
-2. **Membership.** Apply the equivalent of `/repo **`; `FIND **` succeeds and the canonical `plurnk-service/AGENTS.md` is readable.
-3. **Automatic doctrine.** The project-root `AGENTS.md` appears in the model system packet without an explicit pick.
-4. **Client YOLO (`--yolo`).** The loop surrenders a proposal to the client; the client synchronously accepts it, posts an explicit resume, and reaches a terminal result.
-5. **Loop auto (`--auto`).** Execution authority remains with the loop; its proposal resolves internally without a client review or resume round-trip.
-6. **Human review.** A proposal survives disconnect/reconnect and can be explicitly accepted or rejected.
-7. **Model hot-swap.** Two configured aliases run in the same workspace and their turns record the selected models.
-8. **Restart/resume.** After a daemon restart against the same database, the named workspace and worker retain their context and can complete another run.
-9. **Comprehension.** The capable-model orientation report identifies the architecture, repository topology, current goal, meta-worker role, and missing or contradictory context with named evidence. Writing memory without delivering the requested report is RED.
-10. **Forensics.** The database is digested through the supported digest tool and the preserved specimen contains enough evidence to audit every assertion above.
+Proposal modes, reconnect, model hot-swap, and restart/resume are not asserted
+by this executable slice. Expansion of the capstone remains tracked in #3.
 
 Passing individual package tests or receiving HTTP 200 is insufficient. The user-visible client must remain usable and the requested terminal deliverable must be present.
 
 ## Evidence
 
-Each run atomically claims `benchmarks/run<N>-dogfood/` and writes:
+Each preserved campaign atomically claims `benchmarks/run<N>-orientation/` and writes:
 
-- `workspace` — workspace and worker names;
+- `workspace` — the generated workspace name;
+- `prompt.md` — the exact orientation request;
+- `client.json` and `client.stderr.log` — the client result and diagnostics;
 - `service.stdout.log` and `service.stderr.log`;
-- `phases.json` — command, timing, exit status, and assertion results without secrets;
+- `phases.json` — commands, timings, and exit statuses without secrets;
+- `verdict.json` — lifecycle, publication, inspection, evidence, and coverage checks;
 - `plurnk.db` — the preserved database;
 - `digest/` — `digest.md`, `digest.json`, `reasoning.md`, and packet sections;
-- `requiem/` when an active provider is available.
+- requiem artifacts in `digest/` when `--requiem` is requested.
 
 The database is evidence, never the diagnostic interface. Assertions consume client output, AG-UI events, and digest artifacts.
 
 ## Posture
 
-- Run foreground and fail hard.
-- Report client YOLO and loop auto separately; they are different state machines at different ownership boundaries.
-- Preserve both passing and failing specimens until explicitly curated.
+- Execute in the foreground and fail hard.
+- Preserve every failing specimen; preserve passing specimens when requested.
 - Never reuse a database for a clean-bootstrap comparison.
 - A provider/configuration/install failure is a gate failure, not a skipped model test.
-- File every cross-family defect on `plurnk/plurnk-service` with its owning lane label and specimen path.
+- Never infer current work from an archived issue or an uninspected forge reference.
+- File every cross-family defect on the canonical forge with its owning lane label and specimen path.

package/PLURNK_PERSONALITY.md

@@ -1,24 +1,11 @@
-- You decompose non-trivial prompts into taxonomized, tagged, and topical worker:/// entries to resolve before acting.
-- You are concerned with user alignment, documentation alignment, specification alignment, and coverage alignment.
-- You don't code in response to inquiries and exploratory, open questions. You patiently educate, inquire, and align.
-- You ignore emotional subtext, sarcasm, and tone. You never apologize, but you are quick to affirm if you were incorrect.
-- You have no deadline. You're writing minimal, elegant code to be read. No pragmatic compromises or clever hacks.
-- You assume that your inference is stale on current events, software and service versions, or APIs. Check if unsure.
-- You answer prompts from primary sources when possible. Summaries and snippets point at information; they are not information.
-- You look for the modern standards, conventions, and best practices. Everything's been done before. Do it the right way.
-- You strive to translate your ephemeral inference into deterministic knowledgebase entries, scripts, or specifications.
-- You trust internal contracts, only building robust guards against bugs on external surfaces.
-- You disregard ambient updates on the state of your environment unless they pertain to your current focus.
-- Your commits add yourself, `Plurnk <plurnk@pm.me>` to the trailer. Branch freely, then merge if solo and PR if in a team.
-- **Knowledgebase:** Curate a taxonomized, tagged, and topical worker:/// mind map of everything known about the project.
-- **Plan:** Write a markdown checklist `- [x] Step 1\n- [ ] Step 2\n` in PLAN to list your prerogatives and priorities.
-- **MODE:** Your continuing turn's ops follow the MODE Pattern: Mutate state, Observe the result, Do actions, End the turn.
-- **Project:** Maintain a worker://~/project.md of project conventions, patterns, practices, and preferences.
-- **Log:** Distill everything that's not relevant to your current concern and pack it where you can find it later.
-- **Context:** Your Active Context is your workbench. FOLD, KILL, and distill to the knowledgebase to keep it relevant.
-- **Errors:** READ the row the error points at. You can OPEN the "model" log item to find your mistake.
-- **Workspace:** The Plurnk Service maintains your unlimited Extended Context forever. Curate, tag, and organize it well.
-- **Delegation:** If your work naturally decomposes, spawn workers for the separate tasks.
-- **Verification:** If your solution can be deterministically verified, prove your work before concluding.
-- **Judgment:** If the prompt or the user preferences conflict with these rules, bend or break them.
-- **Mission:** React and respond to the latest Plurnk Service User Prompts.
+- You align with the user before consequential architectural, contract, or cross-project decisions.
+- You answer inquiries and exploratory questions without changing code unless the user also asks for action.
+- You preserve reusable knowledge and working state in searchable, folksonomically tagged knowledgebase entries.
+- You verify unstable facts and answer from primary sources when possible.
+- You follow modern standards and conventions unless a deliberate product property requires otherwise.
+- You prove deterministically verifiable work before concluding.
+- You commit completed repository changes as `Plurnk <plurnk@pm.me>` before concluding.
+
+YOU MUST evaluate the prompt for completion conditions. If multiple conditions exist, maintain a Markdown checklist.
+YOU MUST evaluate the prompt for decomposability, delegating to WORKers if any work is naturally divisible.
+YOU MUST react and respond to the latest Plurnk Service User Prompts.

package/README.md

@@ -2,16 +2,20 @@
 
 The plurnk metaproject layer, published — what the family shares that no single member owns.
 
-**Membership primitives** (`import Meta from "@plurnk/plurnk-meta"`): the ONE implementation of trust, enumeration, and root resolution consumed by the daemon's plugin loader and env-defaults floor and by all four family-head scanners (schemes, mimetypes, providers, execs).
+**Membership primitives** (`import Meta from "@plurnk/plurnk-meta"`): the shared implementation of exact family identity, trust, attribution normalization, enumeration, and root resolution consumed by the four family-owned scanners (schemes, mimetypes, providers, execs). [SPEC.md](./SPEC.md) owns the complete contract ({§plugin-discovery}).
 
+- `Meta.declaresKind(manifest, kind)` — accepts one exact string family identity; arrays claim no family ({§plugin-family-kind}).
 - `Meta.isTrusted(packageName, env?)` — the `PLURNK_PLUGINS_TRUSTED_ONLY` gate: unset/`""`/`"0"` off; any value on, `@plurnk/*` always trusted plus a comma-separated allowlist.
+- `Meta.normalizeAttribution(raw, packageName)` — normalize an always-on package declaration, including the reserved `@plurnk/` namespace rule ({§plugin-attribution}).
+- `Meta.runtimeAttribution(source, context, packageName)` — pull and normalize an optional synchronous plugin hook for one provider emission attempt.
+- `Meta.composeAttributions(...lists)` — flatten, deduplicate, and sort opaque tag lists.
 - `Meta.packageDirs(nodeModulesDir)` — scope-agnostic, symlink-aware enumeration across Node's ancestor resolution chain as `{ dir, name }` candidates; the nearest package name wins. Ordering and filtering are the caller's policy.
 - `Meta.nearestNodeModules(fromDir)` — walk up to the nearest `node_modules` holding the ecosystem (witness: `@plurnk` scope); `null` when absent.
 
-**The teaching corpus**: `PLURNK_PERSONALITY.md` (the default operating policy the daemon seeds to `~/.plurnk/AGENTS.md`), `requirements.md` (the system-requirements contract appended to the user packet), and `docs/*.md` (per-scheme/exec teaching docs) — exported subpaths, resolved by the daemon at runtime (pull, don't copy). See `CORPUS.md`.
+**The teaching corpus**: authored policy, Recap, built-in scheme, and conditional question sources resolved from this installed package. Meta owns the source bytes and membership; core owns admission and projection. See [`CORPUS.md`](./CORPUS.md) and {§teaching-corpus}.
 
 **Family tooling** grows here (scaffolders, meta bins) — the published surface of the metaproject's management layer.
 
 [`DOGFOOD.md`](./DOGFOOD.md) defines the whole-product, outside-client acceptance gate for daily-driver and release readiness.
 
-Third-party plugin authors: your package is discovered by ANY scope + a `plurnk` manifest (`plurnk.kind`), enumerated by these primitives, and gated by the operator's trust knob — no registration with us required. MIT.
+Third-party plugin authors: your package is discovered under any scope through one string `plurnk.kind`, enumerated by these primitives, and gated before import by the operator's trust knob — no registration with us required. An admitted package may declare always-on `plurnk.attribution` tags and its loaded plugin object may decide per provider attempt whether to return additional tags from `attributions(context)` ({§plugin-attribution}). MIT.

package/SPEC.md

@@ -0,0 +1,112 @@
+# plurnk-meta — Specification
+
+Contract for facts shared across the open plurnk package family. Capability
+frameworks own their family-specific declarations and runtime interfaces; this
+package owns the installed-membership primitives they share and the published
+teaching sources listed below.
+
+## §teaching-corpus Published teaching sources
+
+The package owns the authored defaults and exact membership below. Consumers
+own admission, runtime projection, and model-facing placement; copying these
+sources into a consuming package would create a second teaching owner.
+
+| Source                          | Membership | Meta-owned content                                 | Core read boundary                                      |
+| ------------------------------- | ---------- | -------------------------------------------------- | ------------------------------------------------------- |
+| `PLURNK_PERSONALITY.md`         | Required   | First-run default operating policy                 | Policy bootstrap {§policy-sections}                     |
+| `requirements.md`               | Required   | Default compact operational recap                  | Default user-slot Recap {§requirements}                 |
+| `docs/log.md`, `docs/worker.md` | Required   | Deep reference prose for reserved built-in schemes | Pull-doc materialization {§schemes-directory}           |
+| `docs/questions.md`             | Required   | Conditional operator-question reference prose      | Enabled capability/teaching gate {§send-300-choices}    |
+
+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. Consumers
+resolve the exported membership exactly: they do not scan `docs/`, infer new
+members from filenames, or treat a missing required source as empty teaching.
+
+A file in `docs/` does not declare a capability. A built-in scheme document is
+eligible only when its basename matches a registered reserved scheme; plugin
+documentation remains owned by that plugin's manifest. `questions.md` is the
+one explicit non-scheme document consumer. Retired or unregistered names do not
+ship as speculative teaching. Manifest `documentation` is deliberately
+optional: an absent field contributes no pull doc, while a present field is the
+fallback only when meta owns no source for that scheme name.
+
+## §plugin-discovery Installed capability discovery
+
+```mermaid
+flowchart LR
+    graph[Installed Node dependency graph] --> enumerate[Meta.packageDirs]
+    enumerate --> scanner[Family-owned scanner]
+    manifest[package.json plurnk manifest] --> scanner
+    policy[Meta.isTrusted] --> gate{Trusted?}
+    scanner --> gate
+    gate -->|yes| attribution[Meta.normalizeAttribution]
+    attribution --> family[Family-owned validation, loading, and registry]
+    gate -->|no| skipped[Skipped-package evidence]
+    family --> host[Composed host]
+    skipped --> host
+```
+
+| Layer                 | Owns                                                                                                                              | Does not own                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `plurnk-meta`         | Node package enumeration, exact capability-family identity, the one trust predicate, and package-attribution normalization.       | Family fields, capability collisions, plugin imports, or presentation. |
+| Family implementation | Family-field validation, deterministic ordering/collisions, trust enforcement before any plugin import, and trusted code loading. | A second trust or attribution policy, or cross-family composition.     |
+| Composed host         | Cross-family arbitration and presentation of skipped-package evidence.                                                            | Re-parsing manifests or importing a declined package.                  |
+
+The installed dependency graph is the compatibility boundary. Enumeration is
+scope-agnostic and symlink-aware across Node's ancestor resolution chain; the
+nearest package with a given package name wins. Installing a package makes a
+valid declared capability discoverable. Environment values configure or bound
+installed capabilities; they never manufacture package existence.
+
+### §plugin-family-kind One package, one capability family
+
+`package.json#plurnk.kind` is one exact string. Arrays and other shapes claim no
+family. A package may declare multiple named capabilities inside its one
+family-owned collection.
+
+| `plurnk.kind` | Family-owned names                                       |
+| ------------- | -------------------------------------------------------- |
+| `"exec"`      | `runtimes[]`                                             |
+| `"mimetype"`  | `handlers[]`                                             |
+| `"provider"`  | singular `name`                                          |
+| `"scheme"`    | `schemes[]`; singular `name` is the one-scheme shorthand |
+
+Coordinated capabilities spanning families use explicit daemon-module
+composition ({§module-lifecycle}); a multi-kind manifest is not a parallel
+module mechanism.
+
+### §plugin-attribution Plugin-authored attribution tags
+
+| Surface                 | Contract                                                                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Static declaration      | Optional `plurnk.attribution` is one non-empty string or an array of non-empty strings. `null`, absence, and an empty array normalize to no tags. A declaration is an always-on source for the admitted package.                            |
+| Runtime declaration     | A loaded plugin object may implement synchronous `attributions(context)`, returning the same declaration shape, `null`, or `undefined`. The hook is pulled once for each provider emission attempt; returning no tags omits that source.     |
+| Hook context            | `workspaceId`, `workerId`, and `primaryWorkerId` are opaque strings; `loop`, `turn`, and `attempt` are positive sequence numbers. The hook receives no engine, database, trust, or mutation capability.                                      |
+| Trust                   | The family applies {§plugin-trust-boundary} before attribution validation or plugin import. Trust admits executable code; it does not make an authored tag truthful.                                                                        |
+| Normalization           | `Meta.normalizeAttribution(raw, packageName)` and `Meta.runtimeAttribution(source, context, packageName)` produce readonly ordered lists. A malformed trusted declaration, malformed hook, or thrown hook fails at the package boundary.    |
+| Namespace reservation   | A tag beginning `@plurnk/` is valid only when `packageName` also begins `@plurnk/`; a violating trusted package fails. Other tag vocabularies, collisions, and meanings are deliberately uninterpreted.                                      |
+| Discovery result        | Each family returns `packageAttributions`, keyed once by package name. Only non-empty static lists for packages represented after family admission are present.                                                                             |
+| Host composition        | The host flattens static and runtime lists from its admitted plugin objects, deduplicates and sorts the result, and treats it as an opaque folksonomy. It does not infer contribution, provenance, weight, trustworthiness, or causal value. |
+| Published projections   | Existing per-tag, per-handler, or name-keyed attribution fields may project the validated static declaration for 1.x compatibility; they do not own another policy.                                                                       |
+
+Manifest acquisition and static validation occur once in the family discovery
+path. A composed host consumes the admitted package map and loaded plugin
+objects without reopening a manifest or tracing tags through produced values.
+
+### §plugin-trust-boundary One policy, enforcement before import
+
+`Meta.isTrusted(packageName, env)` is the sole trust decision:
+
+- unset, empty, or `"0"` `PLURNK_PLUGINS_TRUSTED_ONLY` trusts every installed
+  package;
+- any other value trusts every `@plurnk/*` package plus the comma-separated
+  package-name allowlist in that value.
+
+Every family scanner applies that predicate after reading the inert package
+manifest and before importing or registering plugin code. An untrusted package
+does not crash discovery: the family result preserves its package identity as
+skipped evidence. The composed host decides how to present that evidence.
+Direct framework consumers receive the same safe load boundary and can choose
+their own presentation.

package/dist/index.d.ts

@@ -2,9 +2,38 @@ export interface PackageCandidate {
     dir: string;
     name: string;
 }
+export type PluginKind = "exec" | "mimetype" | "provider" | "scheme";
+export type PluginAttributionDeclaration = string | string[];
+export type PluginAttribution = readonly string[];
+export type PackageAttributions = ReadonlyMap<string, PluginAttribution>;
+export interface PluginAttributionContext {
+    readonly workspaceId: string;
+    readonly workerId: string;
+    readonly primaryWorkerId: string;
+    readonly loop: number;
+    readonly turn: number;
+    readonly attempt: number;
+}
+export interface PluginAttributionSource {
+    attributions?(context: PluginAttributionContext): PluginAttributionDeclaration | null | undefined;
+}
+export declare const TEACHING_CORPUS: Readonly<{
+    readonly personality: "PLURNK_PERSONALITY.md";
+    readonly requirements: "requirements.md";
+    readonly schemeDocs: Readonly<{
+        readonly log: "docs/log.md";
+        readonly worker: "docs/worker.md";
+    }>;
+    readonly questions: "docs/questions.md";
+}>;
+export type TeachingCorpusSource = typeof TEACHING_CORPUS.personality | typeof TEACHING_CORPUS.requirements | (typeof TEACHING_CORPUS.schemeDocs)[keyof typeof TEACHING_CORPUS.schemeDocs] | typeof TEACHING_CORPUS.questions;
 export default class Meta {
     #private;
+    static declaresKind(manifest: unknown, kind: PluginKind): boolean;
     static isTrusted(packageName: string, env?: Record<string, string | undefined>): boolean;
+    static normalizeAttribution(raw: unknown, packageName: string): PluginAttribution;
+    static runtimeAttribution(source: unknown, context: PluginAttributionContext, packageName: string): PluginAttribution;
+    static composeAttributions(...lists: readonly PluginAttribution[]): PluginAttribution;
     static packageDirs(nodeModulesDir: string): Promise<PackageCandidate[]>;
     static nearestNodeModules(fromDir: string): string | null;
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,gBAAgB;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,CAAC,OAAO,OAAO,IAAI;;IAIrB,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAKpG;IAkCD,OAAa,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyB5E;IAED,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;CACJ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,gBAAgB;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAIrE,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAC7D,MAAM,MAAM,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACpC,YAAY,CAAC,CAAC,OAAO,EAAE,wBAAwB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC;CACrG;AASD,eAAO,MAAM,eAAe;0BACX,uBAAuB;2BACtB,iBAAiB;;sBAR1B,aAAa;yBACV,gBAAgB;;wBASb,mBAAmB;EACvB,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAC1B,OAAO,eAAe,CAAC,WAAW,GAClC,OAAO,eAAe,CAAC,YAAY,GACnC,CAAC,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,UAAU,CAAC,GAC5E,OAAO,eAAe,CAAC,SAAS,CAAC;AAKvC,MAAM,CAAC,OAAO,OAAO,IAAI;;IACrB,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAGhE;IAKD,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAKpG;IAED,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAiBhF;IAKD,MAAM,CAAC,kBAAkB,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,wBAAwB,EACjC,WAAW,EAAE,MAAM,GACpB,iBAAiB,CAcnB;IAED,MAAM,CAAC,mBAAmB,CAAC,GAAG,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,CAIpF;IAkCD,OAAa,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyB5E;IAED,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;CACJ"}

package/dist/index.js

@@ -1,8 +1,10 @@
 // The metaproject layer's membership slice — the mechanics every discovery
-// surface shares (AGENTS §topology, core SPEC
-// §plugin-discovery / §operator-config-env-defaults):
+// surface shares ({§plugin-discovery} / {§operator-config-env-defaults}):
+//   - declaresKind:      the ONE package → capability-family representation.
 //   - isTrusted:          THE trust rule. One implementation; a second definition
 //                         of membership trust anywhere in the family is a bug.
+//   - normalizeAttribution:
+//                         one package declaration → one validated tag list.
 //   - packageDirs:        scope-agnostic, symlink-aware enumeration of the Node
 //                         resolution chain. Nearest package wins when npm splits
 //                         a deployment across nested node_modules directories.
@@ -17,7 +19,26 @@
 import { readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
+const SCHEME_TEACHING = Object.freeze({
+    log: "docs/log.md",
+    worker: "docs/worker.md",
+});
+// {§teaching-corpus} — the authored package membership is one exported fact;
+// consumers decide when and where each required source is projected.
+export const TEACHING_CORPUS = Object.freeze({
+    personality: "PLURNK_PERSONALITY.md",
+    requirements: "requirements.md",
+    schemeDocs: SCHEME_TEACHING,
+    questions: "docs/questions.md",
+});
+const RESERVED_ATTRIBUTION_PREFIX = "@plurnk/";
+const EMPTY_ATTRIBUTION = Object.freeze([]);
 export default class Meta {
+    static declaresKind(manifest, kind) {
+        if (typeof manifest !== "object" || manifest === null)
+            return false;
+        return manifest.kind === kind;
+    }
     // unset / "" / "0" → gate OFF: everything installed is trusted.
     // any other value  → gate ON: @plurnk/* always trusted, plus a comma-separated
     //                    allowlist; "1" (naming no real package) = on, zero third-party.
@@ -29,6 +50,50 @@ export default class Meta {
             return true;
         return value.split(",").map((s) => s.trim()).includes(packageName);
     }
+    static normalizeAttribution(raw, packageName) {
+        if (raw === undefined || raw === null)
+            return EMPTY_ATTRIBUTION;
+        const values = Array.isArray(raw) ? raw : [raw];
+        const firstParty = packageName.startsWith(RESERVED_ATTRIBUTION_PREFIX);
+        const tags = values.map((value) => {
+            if (typeof value !== "string" || value.length === 0) {
+                throw new Error(`plugin '${packageName}': plurnk.attribution must be a non-empty string or string[]`);
+            }
+            if (value.startsWith(RESERVED_ATTRIBUTION_PREFIX) && !firstParty) {
+                throw new Error(`plugin '${packageName}': '${RESERVED_ATTRIBUTION_PREFIX}' is reserved for `
+                    + `${RESERVED_ATTRIBUTION_PREFIX}-scoped packages — '${packageName}' cannot claim '${value}'`);
+            }
+            return value;
+        });
+        return Object.freeze(tags);
+    }
+    // {§plugin-attribution} — one synchronous runtime pull with the same shape
+    // and sole namespace reservation as the static declaration. Tags remain
+    // opaque; this boundary validates structure, not meaning.
+    static runtimeAttribution(source, context, packageName) {
+        if (source === null || source === undefined)
+            return EMPTY_ATTRIBUTION;
+        const hook = source.attributions;
+        if (hook === undefined)
+            return EMPTY_ATTRIBUTION;
+        if (typeof hook !== "function") {
+            throw new TypeError(`plugin '${packageName}': attributions must be a function when present`);
+        }
+        let raw;
+        try {
+            raw = hook.call(source, context);
+        }
+        catch (cause) {
+            throw new Error(`plugin '${packageName}': attributions() failed`, { cause });
+        }
+        return Meta.normalizeAttribution(raw, packageName);
+    }
+    static composeAttributions(...lists) {
+        if (lists.length === 0)
+            return EMPTY_ATTRIBUTION;
+        const tags = [...new Set(lists.flat())].toSorted();
+        return tags.length === 0 ? EMPTY_ATTRIBUTION : Object.freeze(tags);
+    }
     static async #packageDirsOne(nodeModulesDir) {
         let entries;
         try {

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/docs/log.md

@@ -1,18 +1,25 @@
-# `log://` — your worker's event history, and how to manage it
+# `log://` - your worker's event history
 
-Every operation you emit is recorded as a row at `log:///<loop>/<turn>/<seq>` — your working memory's ledger of what you've done and what came back. READ a row to recover an earlier op's actual result body (chain a matcher to extract a value). The engine writes it; you read and CURATE it.
+Every operation is recorded at `log:///<loop>/<turn>/<seq>`. The row identifies what happened and what came back. READ a row to retrieve its result body or apply a content matcher.
 
-## Two budget surfaces
+## Log and catalog
 
-- **The log** — every operation, in order. The curatable surface.
-- **The catalog** — `FIND(scheme:///**)` lists the entries a scheme holds, available to READ. Discovery, not history.
+- **Log** - operations and results in order.
+- **Catalog** - `FIND(scheme:///**)` lists the resources a scheme currently holds.
 
-## Curation — FOLD, OPEN, KILL
+## Visibility
 
-Your context carries a `tokensFree` budget; keeping it lean keeps reasoning sharp, since irrelevant tokens degrade signal. Three moves, all on the log:
+- **FOLD** hides an open row's body. The row and body persist, and the row remains listed.
+- **OPEN** reveals a folded row's body.
+- A row's `tokens` is the size of its body: its current packet weight when open and its OPEN cost when folded.
 
-- **FOLD** a row → contracts it to its one-line summary, reclaiming the body's tokens. Non-destructive — a folded row stays listed and re-OPENable. Your primary hygiene tool: fold a body the moment it's served its purpose, rather than carry a result you've already digested. Bulk-fold a matching range in one move — `FOLD(log:///**/get)<101,200>`.
-- **OPEN** a folded row → restores its full body, spending from `tokensFree`. To revisit a result you folded too early — or READ the row directly with a matcher.
-- **KILL** a row → erases it. Sparingly, for rows whose very existence (not just body) is noise.
+OPEN and FOLD change packet visibility, not history. Applying the current state again or targeting a bodyless row is a successful no-op.
 
-**Don't wait for the grinder.** When `tokensFree` runs low the engine's budget grinder folds for you to fit the turn — a mechanical last resort. Curating deliberately keeps the rows YOU value and avoids the overflow in the first place.
+## Deletion and capacity
+
+KILL permanently erases a log row.
+
+The Budget section reports only the packet ceiling, usage, percentage, and free capacity. Each
+log row carries its own token weight. If a packet exceeds its ceiling, the engine folds eligible
+open rows from the newest turn boundary; it never selects older history by relevance. Continued
+overflow follows the reported recovery or hard-413 contract.

package/docs/questions.md

@@ -1,5 +1,5 @@
 # Operator questions — `SEND[300]`
 
-Enabled here: you may ask the operator when a decision is genuinely theirs to make. `<<SEND[300]:question:SEND` asks an open question; `<<SEND[300]:question;choice;choice:SEND` offers choices. Asking parks your run; the answer arrives as the operator's next message — continue from it.
+Enabled here: you may ask the operator when a decision is genuinely theirs to make. `<<SEND[300]:question:SEND` asks an open question; `<<SEND[300]:question;choice;choice:SEND` offers choices. Asking parks your loop; the answer arrives as the operator's next message — continue from it.
 
 Choices are suggestions, never a constraint: the operator always has a free-text option regardless of what you list, so be ready for an answer outside your choices. Ask sparingly — one focused question carrying the context needed to answer it beats a chain of small asks.

package/docs/worker.md

@@ -1,11 +1,33 @@
-# `worker://` — sibling agent runs
+# `worker://` — workers and their entries
 
-Sibling agent runs in this workspace. `worker://self` is you; `worker://<name>` is a sibling. `WORK(worker://<name>):task` spawns a fresh worker named `<name>` with an empty log seeded only by `task`; `FORK(worker://<name>):task` branches *you* — a named clone that copies your log so far — down `task`; `SEND(worker://<name>):msg` messages a sibling, waking it if idle; `KILL(worker://<name>)` ends one. Siblings share this workspace's files and entries; only the conversation log is private. A worker is born from WORK/FORK, never EDIT — `EDIT(worker://<name>)` on the bare run is rejected.
+Workers inhabit one workspace. `worker://<name>` addresses a named worker; `worker://~` is the
+current-worker control sigil; `worker://~/path` addresses your private entries; `worker:///path`
+addresses the shared commons.
+`WORK(worker://<name>):task` spawns a fresh worker with an empty log. `FORK(worker://<name>):task`
+branches your current history. `SEND(worker://<name>):msg` messages a worker, waking it if idle;
+`KILL(worker://<name>)` ends one. Workers share project files and the commons, while private entries
+and conversation logs remain owner-scoped. A worker is born from WORK/FORK, never EDIT —
+`EDIT(worker://<name>)` on the bare worker is rejected.
 
-**Slash count is the discriminator.** `worker://<name>` — two slashes, no path — addresses the worker itself as authority: spawn, `SEND`, `KILL`. `worker://<name>/path` addresses an entry in its scratch — `READ(worker://worker/notes.md)` reads a sibling's, `EDIT(worker://self/todo.md):…` writes your own.
+**The path is the discriminator.** `worker://<name>` with no path addresses a literal worker name
+for WORK, FORK, SEND, READ, or KILL; `worker://~` addresses the caller for SEND or KILL.
+The control form is exact: a trailing slash, userinfo, port, query, fragment, or request metadata
+is invalid rather than ignored.
+`worker://<name>/path` addresses an ancestry-visible named entry; `EDIT(worker://~/todo.md):…`
+writes your own private entry.
 
-**WORK to delegate, FORK to branch:** for fan-out, WORK a distinct-named worker per job (each a fresh task); fork only to carry *your own* context down an alternate path.
+**WORK to delegate, FORK to branch.** For fan-out, WORK a distinct-named worker per job. Each gets
+a fresh task. FORK only to carry *your own* context down an alternate path.
 
-**Loop: spawn once → park → collect on wake.** `WORK(worker://worker):<task>`, then `SEND[102]<-1>:<why>:SEND` parks you (or `[102]<seconds>` to cap the wait). You wake when the worker concludes: its result arrives open in your log as a `SEND` from `worker://worker` — read it and continue. Or pull it — `READ(worker://worker)` returns the result, or `425` if it's still running. Spawn each worker exactly once; re-spawning it, or spawning more while you wait, piles up live workers and trips the active-run cap (`508`). Fan-out is the same shape: WORK all the names, park once, each conclusion wakes you with its delta.
+**Loop: spawn once → park → collect on wake.** Spawn with
+`<<WORK(worker://capital-checker):Find the capital of France from a primary source:WORK`, then
+`<<SEND[202]:Awaiting capital-checker.:SEND` parks you. You wake when the worker concludes: its
+result arrives open in your log as a `SEND` from `worker://capital-checker` — read it and continue.
+Or pull it: `READ(worker://capital-checker)` returns the result, or `425` while it is running. Spawn
+each worker exactly once. Fan-out uses distinct names, followed by one park. Each conclusion wakes
+you with its delta.
 
-**Concluding with live workers.** `SEND[200]` is refused (`409`) while you hold a live worker or open stream; the system packet lists them (`## Plurnk Service Child Runs`, `## Plurnk Service Child Streams`). Either `SEND[102]<seconds>` to await them, or `KILL(worker://<name>)` the ones you no longer need, then terminate — a same-turn `KILL` + `SEND[200]` concludes cleanly in one move.
+**Concluding with live workers.** `SEND[200]` is refused (`409`) while you hold a live worker or
+open stream. The system packet lists them under `## Active Child Workers` and `## Child Streams`.
+Either `SEND[202]` to await them or `KILL(worker://<name>)` the ones you no longer need. A same-turn
+KILL followed by `SEND[200]` concludes cleanly.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-meta",
-    "version": "1.3.11",
+    "version": "1.4.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, requirements, scheme docs), and the home for family tooling.",
     "license": "MIT",
     "type": "module",
@@ -11,6 +11,7 @@
         ".env.defaults",
         "dist/**/*",
         "README.md",
+        "SPEC.md",
         "DOGFOOD.md",
         "CORPUS.md",
         "PLURNK_PERSONALITY.md",
@@ -33,12 +34,22 @@
         "test:lint": "tsc --noEmit",
         "test:unit": "node --conditions=plurnk-dev --test src/**/*.test.ts",
         "test": "npm run test:lint && npm run test:unit",
+        "build:clean": "rm -rf dist",
         "build:dist": "tsc -p tsconfig.build.json",
-        "build": "npm run build:dist",
+        "build": "npm run build:clean && npm run build:dist",
         "prepack": "npm run build",
         "prepublishOnly": "npm audit --audit-level=moderate && npm test"
     },
     "publishConfig": {
         "access": "public"
+    },
+    "homepage": "https://github.com/plurnk/plurnk-service/tree/main/plurnk-meta#readme",
+    "bugs": {
+        "url": "https://repo.possumtech.com/plurnk/plurnk-service/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/plurnk/plurnk-service.git",
+        "directory": "plurnk-meta"
     }
 }

package/requirements.md

@@ -1,3 +1,3 @@
 YOU MUST ONLY use the Plurnk Service Grammar: <<OPsuffix[signal]?(target)?<scope>?:body?:OPsuffix
-Example turn: <<PLAN:Retrieve project document.:PLAN <<READ(project.md)::READ <<SEND[102]:Fetching project document.:SEND
+Example turn: <<PLAN:Locate the definition before changing it.:PLAN <<FIND(src/**):@createCoder:FIND <<SEND[102]:Next, read the definition and its callers.:SEND
 Close with SEND[200] only in a turn that performs no retrieval and has no surviving streams or workers.

package/docs/known.md

@@ -1,3 +0,0 @@
-# `known://` — your workspace
-
-The general-purpose workspace for entries you author. Use it to store and revisit notes, plans, drafts, and intermediate results across turns — EDIT to write, READ to retrieve, FIND to search, SEND to message an entry.

package/docs/unknown.md

@@ -1,3 +0,0 @@
-# `unknown://` — your open questions
-
-The staging ground for the questions you author. Use it to decompose a non-trivial prompt into taxonomized, tagged, and topical entries — each an open question to resolve before you act — EDIT to pose, READ to retrieve, FIND to search, SEND to message an entry. It's the working half of the `known:///` knowledgebase: unknown holds what you're still chasing, known holds what you've established.