aimeat 1.36.0 → 1.37.0

package/dist/public/css/components/markdown.css

@@ -8,6 +8,8 @@
  *   all colors/spacing via theme.css variables.
  * @version-history
  *   v1.0.0 — 2026-06-19 — Initial: extracted the per-view duplicates into one global component sheet.
+ *   v1.1.0 — 2026-07-02 — Styles for the live memory embed (aimeat-memory fence → MemoryEmbed): .md-mem
+ *     container/header/refresh/table/notes.
  */
 
 .md-body {
@@ -65,3 +67,16 @@
 .md-body .md-img { max-width: 100%; height: auto; border-radius: 6px; margin: 0.6em 0; }
 .md-body hr,
 .md-body .md-hr { border: none; border-top: 1px solid var(--border); margin: 1.6em 0; }
+
+/* ── Live memory embed (```aimeat-memory fence → components/MemoryEmbed.js) ── */
+.md-body .md-mem { border: 1px solid var(--border); border-radius: 8px; padding: 0.5em 0.8em 0.7em; margin: 1em 0; background: var(--bg-dim); }
+.md-body .md-mem-head { display: flex; align-items: center; gap: 0.6em; font-size: 0.78rem; color: var(--muted); margin-bottom: 0.35em; }
+.md-body .md-mem-title { font-family: var(--font-mono, ui-monospace, Menlo, Consolas, monospace); overflow-wrap: anywhere; flex: 1; }
+.md-body .md-mem-upd { white-space: nowrap; }
+.md-body .md-mem-refresh { border: none; background: transparent; color: var(--muted); cursor: pointer; border-radius: 4px; padding: 0 0.3em; font-size: 0.9rem; line-height: 1.4; }
+.md-body .md-mem-refresh:hover { color: var(--text); background: var(--surface, var(--card)); }
+.md-body .md-mem table { margin: 0.3em 0 0; background: transparent; }
+.md-body .md-mem-note { color: var(--muted); font-size: 0.88rem; padding: 0.2em 0; }
+.md-body .md-mem-err { color: var(--warning, var(--muted)); }
+.md-body .md-mem-more { color: var(--muted); font-size: 0.78rem; margin-top: 0.3em; }
+.md-body .md-mem-value { font-size: 0.95rem; white-space: pre-wrap; overflow-wrap: anywhere; }

package/dist/public/css/views/agents-detail.css

@@ -4,6 +4,8 @@
  *   Uses agd- prefix to avoid collisions with other profile styles.
  *   All colors use CSS variables from theme.css.
  * @version-history
+ *   v1.14.0 -- 2026-07-03 -- Add Contracts sub-tab styles (.pf-agd-contracts, .agc-caps, .agc-list,
+ *     .agc-row, .agc-where, .agc-org, .agc-since) — agent-side contract-engagement visibility.
  *   v1.13.0 -- 2026-06-24 -- Secretary P5 (S-A): add .pf-agd-badge--specialist (specialist agent type badge).
  *   v1.12.0 -- 2026-06-22 -- Add .pf-agd-capwrap rule so the capabilities summary
  *     ("N tools · N skills · N langs") gets the card content inset (1rem) instead of
@@ -3646,3 +3648,18 @@
 .pf .pf-agd-json-bool { color: var(--accent, #E8564A); font-family: var(--font-mono, monospace); }
 .pf .pf-agd-json-null,
 .pf .pf-agd-json-empty { color: var(--text-muted, #9CA3AF); font-style: italic; }
+
+/* ── Contracts sub-tab — agent-side contract-engagement visibility (active / retired). ── */
+.pf .pf-agd-contracts { padding: 0.25rem 0; }
+.pf .pf-agd-contracts .agc-mt { margin-top: 1rem; }
+.pf .pf-agd-contracts .agc-caps { display: flex; flex-wrap: wrap; gap: 0.35rem; margin: 0.4rem 0 0.2rem; }
+.pf .pf-agd-contracts .agc-list { display: flex; flex-direction: column; gap: 0.35rem; margin-top: 0.4rem; }
+.pf .pf-agd-contracts .agc-row {
+  display: flex; align-items: center; justify-content: space-between; gap: 0.5rem;
+  padding: 0.45rem 0.7rem; border: 1px solid var(--border); border-radius: var(--radius-xs, 6px);
+  background: var(--card);
+}
+.pf .pf-agd-contracts .agc-row--retired { opacity: 0.72; }
+.pf .pf-agd-contracts .agc-where { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 0.4rem; font-size: 0.85rem; }
+.pf .pf-agd-contracts .agc-org { color: var(--text-dim); font-size: 0.78rem; }
+.pf .pf-agd-contracts .agc-since { color: var(--text-muted); font-size: 0.75rem; }

package/dist/public/css/views/portfolio.css

@@ -1,3 +1,14 @@
+/**
+ * @file portfolio.css
+ * @description Styles for the Portfolio view — builder wizard (.portfolio-container
+ *   column) and full-bleed public viewer (.portfolio-viewer-full).
+ * @usage Loaded by spa.html; classes consumed by public/views/portfolio.js.
+ * @version-history
+ *   v1.1.0 — 2026-07-03 — Full-bleed public viewer: .portfolio-viewer-full column fills
+ *     the viewport below the nav, slim toolbar, iframe flexes to remaining height.
+ *   v1.0.0 — 2026-03-06 — Initial portfolio builder + viewer styles.
+ */
+
 /* ── Portfolio View ────────────────────────────────────── */
 
 .portfolio-container {
@@ -248,6 +259,37 @@
   min-height: 60vh;
 }
 
+/* Full-bleed published-portfolio view: a flex column that fills the viewport
+   below the sticky nav; the iframe takes all remaining height and the
+   portfolio scrolls inside it. */
+.portfolio-viewer-full {
+  display: flex;
+  flex-direction: column;
+  height: calc(100vh - var(--nav-height, 64px));
+  height: calc(100dvh - var(--nav-height, 64px));
+}
+
+.portfolio-viewer-bar {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+  padding: 0.45rem 1rem;
+}
+
+.portfolio-viewer-owner {
+  color: var(--text-dim, #6B7280);
+  font-size: 0.9rem;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.portfolio-viewer-fs {
+  margin-left: auto;
+}
+
 .portfolio-viewer-frame {
   width: 100%;
   border: none;
@@ -256,6 +298,14 @@
   background: #fff;
 }
 
+/* Keep after the base .portfolio-viewer-frame rule — same specificity,
+   the override must win in the cascade. */
+.portfolio-viewer-frame-full {
+  flex: 1;
+  min-height: 0;
+  border-radius: 0;
+}
+
 .portfolio-not-found {
   text-align: center;
   padding: 4rem 2rem;
@@ -337,4 +387,5 @@
 .portfolio-publish-target { font-size: .85rem; color: var(--text-dim); margin-bottom: .75rem; }
 .portfolio-publish-url { font-family: monospace; word-break: break-all; }
 .portfolio-paste-actions { display: flex; gap: .6rem; margin-top: .5rem; flex-wrap: wrap; }
+.portfolio-badge-toggle { margin: -0.25rem 0 0.75rem; }
 .portfolio-preview-frame { margin-top: .75rem; min-height: 420px; width: 100%; border: 1px solid var(--border); border-radius: 8px; background: #fff; }

package/dist/public/css/views/profile.css

@@ -4,6 +4,10 @@
  *   wallet, memory, agents, extensions, packages, knowledge, generator, and
  *   edit panels. Consumes theme.css tokens so it flips with dark/light mode.
  * @version-history
+ *   v2.10.0 — 2026-07-03 — Contract-engagement chips: .pj-eng + .pj-retire-btn for the People panel.
+ *   v2.9.0 — 2026-07-02 — Workspace Apps strip: .pj-apps-strip/-head/-title/-hint/-grid, launch
+ *     cards .pj-app-card/-name/-desc/-meta/-missing, and the pin/unpin picker .pj-apps-picker(-row/
+ *     -name/-owner) + .pj-apps-empty.
  *   v2.8.0 — 2026-06-24 — Secretary P5 (S-C): .ext-instance-cfg-field/-label/-secret/-desc for the
  *     extension instance-create config form (masked secret fields).
  *   v2.7.0 — 2026-06-22 — Home "Usage & quotas" card: .pf-usage-card/.pf-usage-row/.pf-usage-bar/
@@ -1799,6 +1803,11 @@
   border: 1px solid var(--border-soft, #f0f0ec);
 }
 .pf-edit-hint { font-size: .75rem; color: var(--text-dim, #9CA3AF); }
+/* Directory opt-in checkbox row (member "phone book"). */
+.pf-edit-check { display: flex; align-items: flex-start; gap: .6rem; cursor: pointer; }
+.pf-edit-check input { margin-top: .2rem; flex-shrink: 0; }
+.pf-edit-check > span { display: flex; flex-direction: column; gap: .15rem; }
+.pf-edit-check-title { font-size: .9rem; }
 .pf-edit-error { font-size: .81rem; color: var(--danger, #ef4444); padding: 8px 12px; background: var(--danger-soft, #FEF2F2); border-radius: 8px; }
 .pf-edit-footer {
   display: flex; justify-content: flex-end; gap: 10px;
@@ -2173,6 +2182,10 @@
 .pj-contract-agents { border: 1px solid var(--border); border-radius: 10px; padding: 0.5rem 0.75rem; margin-bottom: 0.6rem; background: var(--card); }
 /* The per-contract one-click adopt action inside a contract-agent chip. */
 .pj-adopt-btn { margin-left: 0.4rem; padding: 0.1rem 0.5rem; font-size: 0.78rem; }
+/* A per-contract engagement group (state badge + its adopt/retire action). */
+.pj-eng { display: inline-flex; align-items: center; gap: 0.2rem; }
+/* Retire an active contract engagement — quiet, so it reads as secondary to the green "active" badge. */
+.pj-retire-btn { margin-left: 0.25rem; padding: 0.1rem 0.5rem; font-size: 0.78rem; color: var(--text-dim); }
 .pj-draft-form { margin: 0.4rem 0; }
 .pj-drafts { display: flex; flex-direction: column; gap: 0.3rem; margin-bottom: 0.3rem; }
 .pj-item { display: flex; align-items: center; gap: 0.5rem; padding: 0.35rem 0; }
@@ -3099,3 +3112,21 @@
 .dsc-item-meta { margin-top: .5rem; display: flex; flex-wrap: wrap; align-items: center; gap: .35rem; }
 .dsc-tag { font-size: .72rem; color: var(--muted); background: var(--bg-dim); border-radius: var(--radius-full); padding: .08rem .45rem; }
 .dsc-owner { margin-left: auto; font-size: .72rem; color: var(--muted); font-family: var(--mono); }
+
+/* ── Workspace Apps strip (pinned apps on the workspace Overview) ── */
+.pj-apps-strip { background: var(--card); border: 1px solid var(--border); border-radius: var(--radius); padding: .75rem .9rem; margin-bottom: 1rem; }
+.pj-apps-head { display: flex; flex-wrap: wrap; align-items: center; gap: .6rem; margin-bottom: .5rem; }
+.pj-apps-title { font-weight: 600; font-size: .95rem; }
+.pj-apps-hint { flex: 1; font-size: .78rem; color: var(--muted); }
+.pj-apps-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: .6rem; }
+.pj-app-card { background: var(--bg-dim); border: 1px solid var(--border); border-radius: var(--radius); padding: .6rem .75rem; cursor: pointer; transition: border-color .12s; }
+.pj-app-card:hover, .pj-app-card:focus-visible { border-color: var(--accent-border); box-shadow: var(--shadow-sm); }
+.pj-app-name { font-weight: 600; font-size: .9rem; }
+.pj-app-desc { margin-top: .25rem; font-size: .78rem; color: var(--text-dim); overflow: hidden; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }
+.pj-app-meta { margin-top: .35rem; font-size: .72rem; color: var(--muted); }
+.pj-app-missing { color: var(--warning, var(--muted)); }
+.pj-apps-empty { font-size: .82rem; color: var(--muted); padding: .25rem 0; }
+.pj-apps-picker { margin-top: .75rem; border-top: 1px solid var(--border); padding-top: .6rem; display: flex; flex-direction: column; gap: .45rem; }
+.pj-apps-picker-row { display: flex; align-items: center; gap: .6rem; padding: .35rem .5rem; background: var(--bg-dim); border: 1px solid var(--border); border-radius: var(--radius); }
+.pj-apps-picker-name { font-size: .87rem; }
+.pj-apps-picker-owner { flex: 1; font-size: .74rem; color: var(--muted); font-family: var(--mono); }

package/dist/public/js/services/agents.js

@@ -53,6 +53,15 @@ export async function adoptContractTask(agentName, { organismId, ws, contract })
   });
 }
 
+/** The agent's contract engagements across every organism/workspace (active + retired), enriched
+ *  with organism + workspace display names. Powers the agent-detail Contracts tab. Returns array. */
+export async function getAgentEngagements(agentName) {
+  try {
+    const data = await apiGet(`/v1/agents/${encodeURIComponent(agentName)}/engagements`);
+    return Array.isArray(data?.data?.engagements) ? data.data.engagements : [];
+  } catch { return []; }
+}
+
 /** List chat session agents (name starts with 'session-'). */
 export async function listChatSessions(owner) {
   const agents = await listAgents(owner);

package/dist/public/js/services/organisms.js

@@ -6,6 +6,9 @@
  *   resolve gate approvals.
  * @usage import * as orgService from '/js/services/organisms.js';
  * @version-history
+ *   v1.6.0 — 2026-07-02 — Workspace generator prompt + agent connect prompt teach rich document
+ *     markdown: mermaid diagrams and aimeat-memory LIVE data blocks (embed a memory key; fresh on
+ *     every open) so AI-authored documentspaces/documents use live embeds instead of static tables.
  *   v1.5.0 — 2026-06-24 — uploadFile(orgId, file): generic blob upload (any document/image) to an
  *     organism's private storage, returning {key,url,mime} — used by the Secretary doc/image intake.
  *   v1.4.0 — 2026-06-23 — Optional color tags: getAllColors()/saveColors() read/write the per-item
@@ -276,7 +279,7 @@ const GENERATOR_PROMPT = `You are the AIMEAT Workspace Architect. Design a works
 
 A workspace is a set of object types. Each type is one of two modes:
 - "records" — structured items with consistent fields, validated by a schema. Use this for trackable things: milestones, tasks, risks, contacts, decisions.
-- "document" — free-form markdown that grows organically, with no schema. Use this whenever the user asks for documents, a wiki, notes, guides, design docs, or an open / free-form format.
+- "document" — free-form markdown that grows organically, with no schema. Use this whenever the user asks for documents, a wiki, notes, guides, design docs, or an open / free-form format. Documents render rich markdown: \`\`\`mermaid fenced blocks become diagrams, and \`\`\`aimeat-memory fenced blocks become LIVE data (the block names a memory key; the document shows that key's current value — array of objects renders as a table — fresh on every open, so agent-maintained data belongs in a memory key + embed, not in pasted static tables). Mention these in a document space's "description" when the space is meant for dashboards or agent-fed reports.
 
 Respond with this shape:
 {
@@ -620,6 +623,12 @@ export async function saveWorkspaceReadme(orgId, wsId, readme) {
   return apiPut(`/v1/organisms/${encodeURIComponent(orgId)}/workspace?ws=${encodeURIComponent(wsId)}`, { ws: wsId, readme });
 }
 
+/** Replace the workspace's pinned-apps list (FULL replace; [] clears). Each entry references a
+ *  published app ({ owner, filename, label? }). Creator/admin only (enforced server-side). */
+export async function saveWorkspaceApps(orgId, wsId, apps) {
+  return apiPut(`/v1/organisms/${encodeURIComponent(orgId)}/workspace?ws=${encodeURIComponent(wsId)}`, { ws: wsId, apps });
+}
+
 /** Overwrite a workspace's manifest (e.g. edited name/summary/policy from Settings). */
 export async function saveManifest(orgId, wsId, manifest) {
   return apiPost('/v1/memory', { key: `${wsRoot(orgId, wsId)}.meta.manifest`, value: manifest, visibility: 'private' });
@@ -709,6 +718,29 @@ export async function revokeWorkspaceRole(orgId, ws, grantee) {
   return apiPost(`/v1/organisms/${encodeURIComponent(orgId)}/workspace-access/revoke`, { ws, grantee });
 }
 
+/* ── Contract engagements — the first-class (agent × contract × workspace) binding with an
+ * active/retired lifecycle. Adopt writes `active`; Retire flips to `retired` (kept as history).
+ * Distinct from the derived "active here" trace: the engagement is the deactivatable INTENT. ── */
+
+/** List the contract engagements declared in a workspace (active + retired). Returns array. */
+export async function getWorkspaceEngagements(orgId, ws) {
+  try {
+    const resp = await apiGet(`/v1/organisms/${encodeURIComponent(orgId)}/workspace/engagements?ws=${encodeURIComponent(ws)}`);
+    return Array.isArray(resp?.data?.engagements) ? resp.data.engagements : [];
+  } catch { return []; }
+}
+
+/** Activate (adopt) a contract engagement for one of your agents. `agent` = full GAII. */
+export async function activateEngagement(orgId, ws, agent, contract) {
+  return apiPost(`/v1/organisms/${encodeURIComponent(orgId)}/workspace/engagements`, { ws, agent, contract });
+}
+
+/** Retire a contract engagement — the agent's loop then skips this workspace (real off-switch).
+ *  Allowed for the agent's owner or the workspace creator. `agent` = full GAII. */
+export async function retireEngagement(orgId, ws, agent, contract) {
+  return apiPost(`/v1/organisms/${encodeURIComponent(orgId)}/workspace/engagements/retire`, { ws, agent, contract });
+}
+
 /* ── Public document-space sharing (meta.share) ──
  * Independent of the access roles above: this controls what PUBLISHED document-space pages are
  * readable by ANYONE with the public viewer link (no login). Creator/admin manages it. ── */
@@ -902,6 +934,10 @@ export async function buildAccessPrompt(orgId, orgName, wsId, ws, variant = 'hum
     `- Write/refresh a draft: aimeat_memory_write key="organism.${orgId}.w.${wsId}.{namespace}.{id}.draft" value={...}`,
     `- Attach a file/screenshot: aimeat_storage_upload key="organism.${orgId}.w.${wsId}.img.{name}"`,
     `    then embed it in a document's markdown as  ![alt](/v1/storage/<returned key>)`,
+    `- Live data in documents: a \`\`\`aimeat-memory fenced block (body: key: <memory key>, optional view: table|props|list,`,
+    `    fields: a,b and title: ...) renders that key's CURRENT value on every open — write changing data with`,
+    `    aimeat_memory_write as an array of objects (consistent field names) and embed the key instead of a static table;`,
+    `    re-writing the SAME key updates every document that embeds it. \`\`\`mermaid blocks render as diagrams.`,
     `- Publish a draft:     POST ${nodeUrl}/v1/organisms/${orgId}/publish   body { "ws":"${wsId}", "namespace":"...", "id":"..." }`,
     `    (snapshots .version.N + .latest, consumes the draft; may require operator approval if the publish gate is on)`,
   ].join('\n');

package/dist/public/llms-template.txt

@@ -274,6 +274,9 @@ entry: index.html
 | aimeat-social | `loadScript('/v1/libs/aimeat-social.js')` | Discussion boards |
 | aimeat-wallet | `loadScript('/v1/libs/aimeat-wallet.js')` | Morsel balance display |
 | aimeat-ai | `loadScript('/v1/libs/aimeat-ai.js')` | `AIMEAT.ai.complete/completeJson/isAvailable` — runs LLM completions using the user's own OpenRouter key (zero cost to AIMEAT, user-owned spend budget) |
+| aimeat-markdown | `loadScript('/v1/libs/aimeat-markdown.js')` | `AIMEAT.md.render(text, target)` — safe markdown INTO an element (returns an Element; never assign it to innerHTML — use the target param or `renderToString`). `await AIMEAT.md.renderRich(text, target)` adds task lists, footnotes, code highlighting, Mermaid and LIVE data embeds (an `aimeat-memory` fence naming a memory key renders as a fresh table on every open) |
+| aimeat-organism | `loadScript('/v1/libs/aimeat-organism.js')` | `AIMEAT.organism.list/workspaces/read/writeDraft/publish` — organisms & workspaces with a NORMALIZED read (published + drafts merged per item; the raw workspace GET returns them as separate maps) |
+| aimeat-editor | `loadScript('/v1/libs/aimeat-editor.js')` | `AIMEAT.editor.mount/toolbar/split` — CodeMirror 6 markdown editor with live preview (pairs with aimeat-markdown) |
 
 ### Key rules
 
@@ -470,6 +473,9 @@ The node serves browser-ready JavaScript libraries. Load them via `<script src="
 | aimeat-audio | `/v1/libs/aimeat-audio.js` | Audio: 6 instruments, custom synth, soundboard, sample loader |
 | aimeat-speech | `/v1/libs/aimeat-speech.js` | Speech: TTS, STT, voice commands, pluggable providers |
 | aimeat-ai | `/v1/libs/aimeat-ai.js` | LLM completions through the user's own OpenRouter key (`AIMEAT.ai.complete`, `completeJson`, `isAvailable`, `models`, `usage`). Server enforces daily USD budget + per-app quota; rejects with descriptive `err.code` (NO_API_KEY / QUOTA_EXHAUSTED / APP_QUOTA_EXHAUSTED / APP_NOT_ALLOWED / etc.). Pattern: **detect** with `isAvailable()`, **compose** the prompt yourself from app data, **call** with `app_id` so spend is attributable, **render** the result into an editable field so the human stays in the loop. Never bundle your own API key — use the user's. |
+| aimeat-markdown | `/v1/libs/aimeat-markdown.js` | Markdown rendering. `AIMEAT.md.render(text, target)` renders a safe dependency-free GFM subset INTO an element — it returns an Element, so never assign the result to innerHTML (that shows "[object HTMLDivElement]"); use the target param, appendChild, or `renderToString(text)`. `await AIMEAT.md.renderRich(text, target)` upgrades to full GFM (task lists, footnotes, highlighted code, Mermaid diagrams), sanitized, with automatic fallback to the safe subset when CDNs are unreachable. LIVE DATA EMBEDS: a fenced block with language `aimeat-memory` (body lines `key: <memory key>`, optional `owner: <gaii>` for public reads, `view: table/props/list/value/json`, `fields: a, b`, `title: ...`) renders the named memory key as a table/props/list — fetched at render time, so the document shows fresh agent-produced data on every open; access is the server's memory read (workspace rules + entry visibility) and denials render a placeholder. |
+| aimeat-organism | `/v1/libs/aimeat-organism.js` | Organisms & workspaces. `list()`, `workspaces(orgId)`, `read(orgId, wsId)` → `{ manifest, readmeText, spaces }` where each space's items merge published + draft per instance (`{ id, hasRealId, draft, latest, value, title, updatedAt, status }`) — the raw workspace GET returns `objects` (published) and `drafts` as SEPARATE maps; this lib does the merging, id resolution (value.id convention) and `_createdAt/_updatedAt/_version` metadata handling for you. `writeDraft`, `publish`, `revertToDraft`, `deleteObject` (needs the memory:delete scope — declare it via `<meta name="aimeat-scopes">`), `saveReadme`, `search`. Items with `hasRealId:false` cannot round-trip — render them read-only. Requires aimeat-auth. |
+| aimeat-editor | `/v1/libs/aimeat-editor.js` | Markdown editor: `AIMEAT.editor.mount(el, {value, onChange})` (CodeMirror 6 with textarea fallback), `toolbar(adapter)` for formatting buttons, `split(el, {value, onChange})` for editor + live preview rendered through aimeat-markdown. |
 
 ### Standard App Template
 
@@ -560,6 +566,278 @@ Key rules:
 - Do NOT add manual token entry fields. The auth library handles everything.
 - Do NOT modify the AIMEAT header nav bar.
 
+### Workspace App Template (app pinned to organism workspaces)
+
+A workspace app is a normal published app that WORKS ON a workspace's content. A workspace
+creator/admin pins it to the workspace (workspace Overview → Apps → Manage, or the
+`aimeat_workspace_update` MCP tool's `apps` param) and every member launches it from the
+workspace's Apps cards. Three things make it a workspace app:
+
+1. **Access = workspace access.** There is no app-side permission system: every read/write the
+   app makes runs as the signed-in user through `/v1/organisms/...` and is gated by the
+   workspace's own rules (membership, creator/admin, granted roles). If the user can read the
+   workspace they can use the app — never build your own gate.
+2. **Launch context rides the URL fragment.** The workspace launch card opens the app with
+   `#aimeat-ws={organismId}/{workspaceId}`. The fragment survives the app-origin redirect, so
+   parse `location.hash` on boot and pin the app to that workspace.
+3. **Launched bare → offer the pinned workspaces.** Without a fragment, list the workspaces the
+   user can access and prefer the ones this app is pinned to: `AIMEAT.organism.workspaces(orgId)`
+   returns `enrichment.apps` = the pinned `{owner, filename}` list.
+
+Use `aimeat-organism.js` for all content work — it does the objects/drafts merge, the `value.id`
+convention and `_meta` stripping for you (see the SDK table above).
+
+```html
+<!-- AIMEAT App Manifest
+name: workspace-notes
+version: 1.0.0
+description: Notes on a shared workspace — pin it to any workspace with a records space
+entry: index.html
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Workspace Notes</title>
+  <link href="/lib/daisyui@5.css" rel="stylesheet" type="text/css" />
+  <link href="/lib/aimeat-daisyui-bridge.css" rel="stylesheet" type="text/css" />
+  <script src="/lib/tailwindcss@4.js"></script>
+</head>
+<body class="bg-base-100 min-h-screen flex flex-col">
+  <nav class="navbar bg-base-200 shadow-sm px-4">
+    <div class="flex-1"><span class="text-lg font-bold">Workspace Notes</span>
+      <span id="ws-name" class="ml-3 text-sm opacity-70"></span></div>
+    <div class="flex-none"><span id="header-auth"></span></div>
+  </nav>
+  <div id="app" class="flex-1 p-4 max-w-2xl mx-auto w-full"><p>Loading…</p></div>
+  <script>
+    function loadScript(src) { return new Promise((res, rej) => { const s = document.createElement('script'); s.src = src; s.onload = res; s.onerror = rej; document.head.appendChild(s); }); }
+    const $app = () => document.getElementById('app');
+
+    // #aimeat-ws={organismId}/{workspaceId} — set by the workspace launch card.
+    function launchContext() {
+      const m = /[#&]aimeat-ws=([^/&]+)\/([^&]+)/.exec(location.hash || '');
+      return m ? { orgId: decodeURIComponent(m[1]), wsId: decodeURIComponent(m[2]) } : null;
+    }
+
+    // Which published app am I? Match my <title> against the public catalog — works on any
+    // origin (apex or app subdomain), no hardcoding.
+    async function discoverSelf() {
+      try {
+        const r = await fetch('/v1/apps'); const d = await r.json();
+        const me = (d?.data?.apps || []).find(a => a?.manifest?.name === document.title);
+        return me ? { owner: me.owner, filename: me.filename } : null;
+      } catch { return null; }
+    }
+
+    async function boot() {
+      await loadScript('/v1/libs/aimeat-auth.js');
+      await loadScript('/v1/libs/aimeat-organism.js');
+      AIMEAT.auth.mountLoginButton('#header-auth', { onLogin: start, onLogout: () => location.reload() });
+      // On the isolated APP ORIGIN the silent-SSO / consent-popup flows complete asynchronously and
+      // fire the 'login' EVENT (not the button's onLogin callback) — subscribe to both.
+      let started = false;
+      const startOnce = () => { if (!started) { started = true; start(); } };
+      AIMEAT.auth.on('login', startOnce);
+      const session = await AIMEAT.auth.login();
+      if (session) startOnce(); else if (!started) $app().innerHTML = '<p>Sign in to open a workspace.</p>';
+    }
+
+    async function start() {
+      const ctx = launchContext();
+      if (ctx) return openWorkspace(ctx.orgId, ctx.wsId);
+      // Launched bare: list accessible workspaces, pinned-here first.
+      const self = await discoverSelf();
+      const orgs = await AIMEAT.organism.list();
+      const rows = [];
+      for (const org of orgs) {
+        const wss = await AIMEAT.organism.workspaces(org.id).catch(() => []);
+        for (const w of wss) {
+          if (w.access === 'none') continue;
+          const pinned = !!self && (w.enrichment?.apps || []).some(a => a.owner === self.owner && a.filename === self.filename);
+          rows.push({ org, w, pinned });
+        }
+      }
+      rows.sort((a, b) => Number(b.pinned) - Number(a.pinned));
+      $app().innerHTML = '<h2 class="text-lg font-bold mb-2">Pick a workspace</h2>';
+      for (const r of rows) {
+        const btn = document.createElement('button');
+        btn.className = 'btn btn-outline btn-block justify-start mb-2';
+        btn.textContent = (r.pinned ? '📌 ' : '') + r.org.name + ' / ' + (r.w.name || r.w.id);
+        btn.onclick = () => { location.hash = '#aimeat-ws=' + encodeURIComponent(r.org.id) + '/' + encodeURIComponent(r.w.id); openWorkspace(r.org.id, r.w.id); };
+        $app().appendChild(btn);
+      }
+      if (!rows.length) $app().innerHTML += '<p>No accessible workspaces.</p>';
+    }
+
+    async function openWorkspace(orgId, wsId) {
+      const ws = await AIMEAT.organism.read(orgId, wsId);
+      document.getElementById('ws-name').textContent = ws.manifest?.name || wsId;
+      // First records-mode space is the notes home (documents work the same way).
+      const space = ws.spaces.find(s => (s.kind || 'records') !== 'document') || ws.spaces[0];
+      if (!space) { $app().innerHTML = '<p>This workspace has no spaces yet.</p>'; return; }
+      const el = $app(); el.innerHTML = '<h2 class="text-lg font-bold mb-2">' + space.name + '</h2>';
+      for (const item of space.items.sort((a, b) => b.updatedAt - a.updatedAt)) {
+        const card = document.createElement('div');
+        card.className = 'card bg-base-200 mb-2 p-3';
+        card.textContent = item.title + (item.status !== 'published' ? ' (' + item.status + ')' : '');
+        el.appendChild(card);
+      }
+      // Add form: draft + publish under the space's namespace. The server gates the write by
+      // workspace access; a gated workspace turns publish into a pending approval — show why.
+      const form = document.createElement('form'); form.className = 'mt-4 flex gap-2';
+      form.innerHTML = '<input class="input input-bordered flex-1" placeholder="New note…" required />' +
+                       '<button class="btn btn-primary">Add</button>';
+      form.onsubmit = async (e) => {
+        e.preventDefault();
+        const text = form.querySelector('input').value.trim(); if (!text) return;
+        const id = 'note-' + Date.now();
+        try {
+          await AIMEAT.organism.writeDraft(orgId, wsId, space.namespace, id, { id, title: text });
+          await AIMEAT.organism.publish(orgId, wsId, space.namespace, id);
+          openWorkspace(orgId, wsId);
+        } catch (err) { alert(err.message); }
+      };
+      el.appendChild(form);
+    }
+
+    boot();
+  </script>
+</body>
+</html>
+```
+
+Key rules for workspace apps:
+- NEVER build an app-side permission gate — the server enforces workspace access on every call.
+- Parse `#aimeat-ws=` on boot; keep the fragment when you navigate so reload stays pinned.
+- `writeDraft` + `publish` is the write loop; items with `hasRealId:false` are read-only.
+- A publish can return a pending approval when the workspace gates publishes — tell the user
+  instead of treating it as an error.
+
+### App-IAM Template (an app with its OWN users and BBS levels via aimeat-iam)
+
+Use this when the app needs its own permission system — its own user roster and levels,
+independent of workspaces. The app gets a per-app copy of the **aimeat-iam extension**: a
+server-side decision oracle whose state (roles, levels, assignments, command manifest) lives in
+the extension's own `ext:{name}` memory, sovereign and tamper-proof from the browser. The app
+never decides permissions itself — it ASKS the extension, and shows/hides UI from the answer.
+One model, two user kinds: a human GHII and an agent GAII are checked identically.
+
+**The model (BBS ordinal levels — LOWER number = MORE power):**
+- Roles carry capability lists and sit on levels: seeded `admin: 0 ['*']`,
+  `editor: 10 ['read','create','edit']`, `viewer: 20 ['read']` — all replaceable.
+- A **command manifest** maps app commands → required capability + mutation tier
+  (`read | write | irreversible`). The `irreversible` tier makes `needsConfirmation: true`,
+  so the UI knows to confirm — the manifest decides, not the UI author.
+- Unassigned users get `config.defaultRole` (seeded `viewer`).
+
+**Setup (once, by the app owner or their AI):**
+1. Install a copy of the aimeat-iam extension under your app's own name (convention:
+   `{your-app}-iam`) — via the aimeat-iam package, or `aimeat_extension_install` over MCP.
+2. `POST /v1/ext/{ext}/admin` with `{ "op": "claim" }` (records you as owner + seeds defaults),
+   then `{ "op": "setCommands", "commands": [...] }` and `{ "op": "assign", "ghii": "you@node",
+   "role": "admin" }` — claiming does NOT auto-assign a role.
+3. AI route: the `aimeat_iam_define` MCP tool validates a level schema + command manifest,
+   computes the level→command matrix, and returns ready-to-apply admin payloads
+   (`setRoles` / `setLevels` / `setCommands`).
+
+**The runtime contract (all calls need a signed-in session; `resp.data` is the answer):**
+
+```javascript
+const EXT = 'my-app-iam';   // your app's own extension instance
+const iam = async (action, body) => {
+  const r = await AIMEAT.auth.getSession().fetch('/v1/ext/' + EXT + '/' + action,
+    { method: 'POST', body: JSON.stringify(body || {}) });
+  if (r.ok === false) throw new Error(r.error?.message || action + ' failed');
+  return r.data;
+};
+
+// Gate EVERYTHING on check { command } — the decision is server-side:
+const me = await iam('check', { command: 'post' });
+// → { allowed, role, level, command, capability, tier, needsConfirmation }
+if (me.allowed) showComposer();
+if (me.needsConfirmation) askTheHumanFirst();   // irreversible tier
+
+// Owner-only user management. getState answers for ANY caller but reports isOwner —
+// gate the panel on state.isOwner (server truth, not a level guess); the mutating
+// ops (assign/revoke/set*) are enforced owner-only server-side regardless:
+const state = await iam('admin', { op: 'getState' });   // roles, levels, commands, assignments, isOwner
+await iam('admin', { op: 'assign', ghii: 'friend@node-id', role: 'editor' });
+await iam('admin', { op: 'revoke', ghii: 'friend@node-id' });
+
+// The roster doubles as a content index — assignments are PUBLIC extension memory:
+const assignments = await AIMEAT.data.getPublic('ext:' + EXT, 'iam.assignments') || {};
+// { "user@node": "role", ... } — everyone who can write is here, so read exactly
+// their public keys to aggregate shared content (each user writes their OWN key).
+```
+
+Key rules for app-IAM apps:
+- The extension is the ONLY permission truth; the app renders its answers. Never mirror the
+  rules into app JS — they would drift and can be bypassed anyway.
+- `check {permission}` (legacy role/permission mode) still works; prefer `check {command}` —
+  agents and humans then share one verb vocabulary with tiers.
+- Content pattern: each user writes their own public key (e.g. `my-app.posts`); readers
+  discover writers through `iam.assignments`. No shared-key write races, no extra backend.
+- Full working example: the "Club Board" proof app (packages/club-board in the AIMEAT repo).
+
+### Agent-Faced App Template (one app, two faces — humans use the UI, agents use MCP)
+
+Use this when AI agents should be first-class USERS of the app, working alongside humans.
+The trick: there is NO agent-specific backend. Both faces operate on the SAME workspace
+records — the human face is your app UI (the Workspace App Template above), the agent face
+is the standard MCP workspace tools (`aimeat_workspace_read` / `_write` / `_publish`) driven
+by a PROMPT your app generates. Access on both faces is the workspace's own access.
+
+Canonical example — a kanban the human fills and agents work:
+
+1. **The shared record.** One records space, contract-tagged so agents recognise it, with an
+   OPEN schema (agents may add fields without rejections):
+   ```
+   PUT /v1/organisms/{id}/workspace?ws={ws}
+   { "add_spaces": [{ "name": "task", "namespace": "shared.kanban", "mode": "records",
+                      "contract": "kanban", "description": "Tasks humans file and agents work" }],
+     "schemas": { "shared.kanban": { "type": "object", "required": ["id","title","status"],
+       "properties": { "id": {"type":"string"}, "title": {"type":"string"}, "brief": {"type":"string"},
+         "status": {"type":"string","enum":["todo","claimed","doing","done"]},
+         "assignee": {"type":"string"}, "deliverable": {"type":"string"}, "notes": {"type":"string"} } } } }
+   ```
+2. **The human face** is a normal workspace app: render columns by `status`, create tasks with
+   `status:"todo"`, let the human override any task — same `writeDraft` + `publish` loop the
+   agents use.
+3. **The agent face is a prompt, not code.** Put a "🤖 Copy agent prompt" button in the app that
+   emits the work loop with the ids baked in — the human pastes it into ANY MCP-connected agent:
+   ```
+   You work a kanban board in an AIMEAT workspace. Use your AIMEAT MCP tools.
+   Board: organism_id "<orgId>", ws "<wsId>", space "task".
+   A task is { id, title, brief, status: todo|claimed|doing|done, assignee, deliverable, notes }.
+   Work loop:
+   1. aimeat_workspace_read { organism_id, ws } — look at objects["task"].
+   2. Pick ONE task with status "todo" that matches your skills.
+   3. CLAIM: aimeat_workspace_write with the task re-written as status "claimed" +
+      assignee "<your GAII>", then aimeat_workspace_publish. Re-read after publishing —
+      if the assignee is not you, someone else won; pick another task.
+   4. Work. Record progress: status "doing" + a short note in `notes`, publish each update.
+   5. Finish: status "done" + WHERE THE RESULT LIVES in `deliverable` (a URL, a workspace
+      document id, or a memory key). Publish.
+   6. Repeat while matching "todo" tasks remain. Rules: one task at a time; keep every
+      existing field when re-writing; if a publish is gated, leave the draft for human review.
+   ```
+4. **Human control knobs come free from the workspace:** the publish gate turns every agent
+   publish into a pending human approval; workspace roles decide which members (and their
+   agents) may write at all.
+
+Key rules for agent-faced apps:
+- The claim convention (`assignee` + re-read after publish) resolves races without any
+  backend lock — first publish wins, losers stand down.
+- `deliverable` is a POINTER, never the payload — the work product lives where it belongs
+  (a document space, a memory key, a URL) and the board links to it.
+- Poll politely in the UI (the board changes while humans watch); agents poll via
+  `aimeat_workspace_read` on their own schedule.
+- Full working example: the "Agent Kanban" proof app (packages/agent-kanban in the AIMEAT
+  repo) — verified end-to-end: human files a task, an agent claims it (assignee + status),
+  progresses it, and finishes with a deliverable link the human clicks.
+
 ### Realtime / Multiplayer Template
 
 For apps that need live collaboration, multiplayer, or real-time sync.

package/dist/public/spa.html

@@ -269,6 +269,7 @@
       "/views/profile/organisms/participants-panel.js": "/views/profile/organisms/participants-panel.js",
       "/views/profile/organisms/workspace-comments.js": "/views/profile/organisms/workspace-comments.js",
       "/views/profile/organisms/sources-panel.js": "/views/profile/organisms/sources-panel.js",
+      "/views/profile/organisms/workspace-apps.js": "/views/profile/organisms/workspace-apps.js",
       "/views/profile/organisms/schema-form.js": "/views/profile/organisms/schema-form.js",
       "/views/profile/organisms/document.js": "/views/profile/organisms/document.js",
       "/views/command-palette.js": "/views/command-palette.js",
@@ -317,13 +318,32 @@
     import htm from 'htm';
     import { loadTranslations, t, getLocale, switchLocale, onLocaleChange } from '/js/i18n.js';
     import { initThemeSystem } from '/js/theme.js';
-    import { NotificationBell } from '/components/NotificationBell.js';
+    import { NotificationBell, openNotificationLink } from '/components/NotificationBell.js';
     import { CommandPalette } from '/views/command-palette.js';
     import { openAppSandboxed, isAppHtmlUrl } from '/js/app-sandbox.js';
     // generateStars no longer needed for light theme
 
     const html = htm.bind(h);
 
+    // ── Notification cold-open deep link ──
+    // A push-notification click can open '/v1/profile?tab=messages#inbox/<conversationId>' (or
+    // the bell's '#<tab>[/<rest>]' hash form) in a fresh window. Prime the landing page's
+    // sessionStorage contract ({tabId, slot} JSON — landing-page.js openView init) BEFORE the
+    // view mounts, plus the inbox thread key that inbox-tab.js consumes on mount. Overwriting the
+    // saved tab matters: landing-page prefers sessionStorage over ?tab=, so a stale value from
+    // earlier browsing would otherwise beat the deep link in a reused browser tab.
+    (() => {
+      if (location.pathname !== '/v1/profile') return;
+      const m = /^#([a-z]+)(?:\/(.+))?$/i.exec(location.hash || '');
+      const rawTab = new URLSearchParams(location.search).get('tab') || (m ? m[1] : '');
+      if (!rawTab) return;
+      const tabId = rawTab.toLowerCase() === 'inbox' ? 'messages' : rawTab;
+      try {
+        sessionStorage.setItem('aimeat-profile-tab', JSON.stringify({ tabId, slot: 'main' }));
+        if (tabId === 'messages' && m && m[2]) sessionStorage.setItem('aimeat.inbox.open', m[2]);
+      } catch { /* private mode — ?tab= still lands the tab */ }
+    })();
+
     // ── Error Boundary ──
     class ErrorBoundary extends Component {
       constructor(props) {
@@ -436,6 +456,19 @@
         }
       }, []);
 
+      // Push-notification clicks on an already-open window: the service worker (sw.js) focuses
+      // this window and posts the notification's target URL — deep-link it in place (tab switch,
+      // inbox thread) instead of a full reload.
+      useEffect(() => {
+        if (!('serviceWorker' in navigator)) return undefined;
+        const onSwMessage = (e) => {
+          if (!e.data || e.data.type !== 'aimeat-notification-click' || !e.data.url) return;
+          openNotificationLink(e.data.url, navigate);
+        };
+        navigator.serviceWorker.addEventListener('message', onSwMessage);
+        return () => navigator.serviceWorker.removeEventListener('message', onSwMessage);
+      }, [navigate]);
+
       // Initial load + popstate
       useEffect(() => {
         // Load initial route