superbee 0.1.1 → 0.1.2-pre.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.1.1",
+  "version": "0.1.2-pre.2",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [

package/references/modeling-and-delivery.md

@@ -0,0 +1,62 @@
+# Modeling and delivery
+
+Read this only after the user accepts a durable domain-modeling change.
+
+## Inspect before choosing a representation
+
+Use the current CLI as the syntax authority:
+
+```sh
+superbee bundle locate
+superbee list --limit 50
+superbee kinds
+superbee recipes
+superbee link list --limit 100
+```
+
+Run the relevant command's `--help` before writing. Preserve source documents and existing domain
+definitions.
+
+## Choose the least structure that removes the recurring cost
+
+- **Generic document:** one important record or a representative example while the shape is still
+  uncertain. OKF documents do not need a governing Kind.
+- **Kind:** repeated instances need shared vocabulary, fields, lifecycle, sections, freshness, or
+  relationship rules. Create a Kind only when the repeated shape is already supported by evidence.
+- **Recipe:** multiple stable definitions should be reusable in other bundles. Recipes contain
+  definitions and guidance, never the user's instance data.
+- **View:** humans repeatedly need the same comparison, timeline, graph, board, dashboard, or
+  interactive decision surface. The underlying documents and relationships remain authoritative.
+- **Task/Roadmap:** accountable, sequenced coordination benefits from execution state and a governing
+  overview. Do not use them merely because their recipes are available.
+
+For a newly recognized domain, create one clearly labeled representative generic document first.
+Do not introduce a new Kind until the user has used that record or at least two existing records
+already demonstrate the same stable fields or relationships. When the current bundle already
+contains several examples that establish a stable repeated shape, creating the Kind and one valid
+instance together is appropriate.
+
+## Delivery loop
+
+1. State the recurring problem and the future outcome in the user's terms.
+2. Inspect existing vocabulary and avoid a competing source of truth.
+3. Keep unknown facts explicitly unknown; do not infer operational state from silence.
+4. Create the smallest model and one representative instance. Use a temporary recipe directory
+   plus `superbee recipe add <path>` when installing new Kind definitions, so normal validation and
+   expect-absent behavior apply.
+5. Relate the new record to its actual evidence, policies, decisions, or dependencies.
+6. Run `superbee status`, read the new record, and inspect its links. Repair only defects caused by
+   this change.
+7. Remove temporary authoring or staging directories, present the authoritative result, and give a
+   brief value receipt.
+
+Use `--body-file` for multiline Markdown. Use `superbee new "<Kind>" --help` for the exact fields
+of an installed Kind. Prefer semantic no-ops, actor attribution, and version-aware updates when the
+CLI exposes them.
+
+## Evolve from use
+
+Refine fields or relationships only after actual instances expose a recurring need. Package a
+recipe only after the definitions stabilize. Add a View only when repeated human interpretation
+cost is visible. Periodically consolidate or retire structure that no longer earns its cognitive
+cost.

package/references/recipes/review-workflow/references/view-authoring-v0.md

@@ -322,3 +322,21 @@ Bridge.watch(async function (events) {
   render(result.rows, events);
 }).catch(showStartupError);
 ```
+
+## Quiet startup and transport readiness
+
+Startup messages are optional. A View may render static content or remain quiet until human input;
+it does not have to send `hello`, subscribe, or make any other bridge request merely to prove that
+it loaded.
+
+The local web shell may use a shell-authenticated transport receipt after the iframe load event to
+confirm that the nonce response reached the host's completed-response boundary. That receipt stays
+outside the iframe and is **not authorization**: it grants no bridge or trusted-action access, and
+each data or action request still undergoes its own launch-currentness, capability, and exact-byte
+approval checks.
+
+The receipt proves transport completion, not pixels or script execution. With exact authored bytes
+and an opaque-origin iframe, browser cancellation after the response reaches the host's completion
+boundary may remain indistinguishable from successful delivery. The shell's bounded load diagnostic
+therefore cannot identify every response-stage failure without authored cooperation or a different
+isolation contract.

package/references/views/references/view-authoring-v0.md

@@ -322,3 +322,21 @@ Bridge.watch(async function (events) {
   render(result.rows, events);
 }).catch(showStartupError);
 ```
+
+## Quiet startup and transport readiness
+
+Startup messages are optional. A View may render static content or remain quiet until human input;
+it does not have to send `hello`, subscribe, or make any other bridge request merely to prove that
+it loaded.
+
+The local web shell may use a shell-authenticated transport receipt after the iframe load event to
+confirm that the nonce response reached the host's completed-response boundary. That receipt stays
+outside the iframe and is **not authorization**: it grants no bridge or trusted-action access, and
+each data or action request still undergoes its own launch-currentness, capability, and exact-byte
+approval checks.
+
+The receipt proves transport completion, not pixels or script execution. With exact authored bytes
+and an opaque-origin iframe, browser cancellation after the response reaches the host's completion
+boundary may remain indistinguishable from successful delivery. The shell's bounded load diagnostic
+therefore cannot identify every response-stage failure without authored cooperation or a different
+isolation contract.