Updates

pear-platform/hyper-bare-distributable-hint/docs/api.md

@@ -1,26 +1,89 @@
 # API: hyper-bare-distributable-hint
 
-**Protocol:** `bare-distributable-hint/v1` · **Export:** `HyperBareDistributableHint`
+**Protocol:** `bare-distributable-hint/v1` · **Export:** `HyperBareDistributableHint`, `HyperP2PBareDistributableHint`, `PROTOCOL`
+
+## Overview
+
+Local-only map of Pear/Bare app distributable layout hints keyed by `appId`. No Hyperswarm mesh — hints are process-local for tooling and runtime layout resolution before bundle fetch.
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| _(none)_ | — | — | Constructor accepts `opts = {}` but does not read fields |
 
 ## Methods
 
-### `setHint(...)`
+### `setHint(appId, layout)`
 
-Domain API.
+Stores `{ appId, layout, updatedAt }`.
 
-### `getHint(...)`
+- **Returns:** entry object
+- **Throws:** `assertNonEmpty` on `appId`; `layout must be an object`
+- **Emits:** `hint`
 
-Domain API.
+### `getHint(appId)`
 
-### `listHints(...)`
+- **Returns:** entry or `null`
+- **Throws:** `assertNonEmpty` on `appId`
 
-Domain API.
+### `listHints()`
 
+- **Returns:** array of all hint entries
 
-### `getStats()` / `ready()` / `close()`
+### `ready()` / `close()`
 
-Lifecycle helpers.
+`ready()` resolves immediately. `close()` emits `closed`.
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `hint` | `{ appId, layout, updatedAt }` |
+| `closed` | — |
+
+## getStats()
+
+| Field | Meaning |
+|-------|---------|
+| `set` | `setHint` call count |
+| `get` | `getHint` call count |
+| `hints` | Map size |
+| `protocol` | `bare-distributable-hint/v1` |
+| `mode` | always `local` |
+
+## Wire
+
+No gossip or wire messages. Protocol constant exists for registry alignment only.
+
+| type | fields | notes |
+|------|--------|-------|
+| — | — | local-only module |
+
+## Errors
+
+`assertNonEmpty` on empty `appId`. Invalid layout: `layout must be an object`.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 
 ## P2P
 
-Local-only.
+Not applicable. `getStats().mode` is `local`. Use `hyper-bare-bundle-bridge` or `hyper-pear-update-gossip` for mesh propagation.
+
+## Testing
+
+```bash
+cd modules/pear-platform/hyper-bare-distributable-hint && npm test
+```
+
+## Composition
+
+Feed hints into `hyper-bare-bundle-bridge.resolve` workflows and Pear runtime session metadata via `hyper-pear-runtime-session`.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## See also
+
+[`docs/architecture.md`](architecture.md).

pear-platform/hyper-bare-distributable-hint/docs/architecture.md

@@ -1,11 +1,30 @@
 # Architecture: hyper-bare-distributable-hint
 
+**Protocol:** `bare-distributable-hint/v1` · **Category:** pear-platform · **Mode:** local-only
+
+```mermaid
+flowchart LR
+  App --> Hint[HyperBareDistributableHint]
+  Hint --> Map[_hints Map]
+```
+
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| — | — | — | Local-only |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| — | — | — | No wire traffic; protocol id is registry metadata only |
 
-## State
+## State model
 
-In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
+- `_hints`: `Map<appId, { appId, layout, updatedAt }>`
+- `_stats`: `set`, `get` counters
+
+## Sequence
+
+1. `setHint` writes map and emits `hint`
+2. `getHint` / `listHints` read without side effects
+3. `close` clears lifecycle only (map retained until GC)
+
+## Composition
+
+`hyper-bare-bundle-bridge`, `hyper-pear-runtime-session`.