@rubytech/create-maxy-code 0.1.116 → 0.1.118

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.116",
+  "version": "0.1.118",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/neo4j/schema.cypher

@@ -1100,3 +1100,108 @@ FOR (h:CloudflareHostname) REQUIRE (h.accountId, h.hostnameValue) IS UNIQUE;
 
 CREATE INDEX cloudflare_hostname_account IF NOT EXISTS
 FOR (h:CloudflareHostname) ON (h.accountId);
+
+// ----------------------------------------------------------
+<<<<<<< HEAD
+// Estate-agent ontology (Task 358) — Listing-centric model
+// documented at platform/plugins/memory/references/schema-estate-agent.md.
+//
+// These declarations exist primarily so the memory-write validator's
+// parseLabelsFromSchemaCypher() registers each label on a fresh deploy
+// where no node of the label has yet landed — without them, the first
+// :Listing write from the listing-curator agent is rejected as "unknown
+// label" against an empty db.labels() set.
+//
+// Idempotency contracts mirror schema-estate-agent.md:
+//   :Listing / :Viewing / :Offer — (accountId, sourceSystem, sourceId)
+//   :Property                    — (accountId, slug)
+//   :ImageObject                 — (accountId, listingSlug, url) for the
+//                                  estate-agent variant, (accountId, name,
+//                                  contentUrl) for the brand-asset variant.
+//                                  Because the two writers use different
+//                                  natural keys, only an accountId index is
+//                                  declared at the schema level — uniqueness
+//                                  is enforced at write time by the curator
+//                                  / brand-asset writer's MERGE clause.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT listing_account_source_unique IF NOT EXISTS
+FOR (l:Listing) REQUIRE (l.accountId, l.sourceSystem, l.sourceId) IS UNIQUE;
+
+CREATE INDEX listing_account IF NOT EXISTS
+FOR (l:Listing) ON (l.accountId);
+
+CREATE INDEX listing_status IF NOT EXISTS
+FOR (l:Listing) ON (l.status);
+
+CREATE INDEX listing_type IF NOT EXISTS
+FOR (l:Listing) ON (l.listingType);
+
+CREATE VECTOR INDEX listing_embedding IF NOT EXISTS
+FOR (l:Listing) ON (l.embedding)
+OPTIONS {
+  indexConfig: {
+    `vector.dimensions`: 768,
+    `vector.similarity_function`: 'cosine'
+  }
+};
+
+CREATE CONSTRAINT property_account_slug_unique IF NOT EXISTS
+FOR (p:Property) REQUIRE (p.accountId, p.slug) IS UNIQUE;
+
+CREATE INDEX property_account IF NOT EXISTS
+FOR (p:Property) ON (p.accountId);
+
+CREATE CONSTRAINT viewing_account_source_unique IF NOT EXISTS
+FOR (v:Viewing) REQUIRE (v.accountId, v.sourceSystem, v.sourceId) IS UNIQUE;
+
+CREATE INDEX viewing_account IF NOT EXISTS
+FOR (v:Viewing) ON (v.accountId);
+
+CREATE CONSTRAINT offer_account_source_unique IF NOT EXISTS
+FOR (o:Offer) REQUIRE (o.accountId, o.sourceSystem, o.sourceId) IS UNIQUE;
+
+CREATE INDEX offer_account IF NOT EXISTS
+FOR (o:Offer) ON (o.accountId);
+
+CREATE INDEX image_object_account IF NOT EXISTS
+FOR (i:ImageObject) ON (i.accountId);
+
+// :PostalAddress (schema:PostalAddress) — shared address nodes documented in
+// schema-base.md. Address rows are deliberately accountId-free (one address
+// can be shared across customers / orders / listings); writers MERGE on the
+// formatted address triple. Declared here so a fresh deploy registers the
+// label before the first :PostalAddress write lands.
+CREATE INDEX postal_address_postcode IF NOT EXISTS
+FOR (a:PostalAddress) ON (a.postalCode);
+=======
+// AEOAudit — Answer Engine Optimisation audit history (Task 354).
+// Written by the aeo plugin's aeo-audit-page tool when invoked
+// with persist=true. Append-only audit trail; each invocation
+// produces a new node. Linked via
+// (KnowledgeDocument)-[:HAS_AEO_AUDIT]->(AEOAudit) when the audit
+// targets a stored document, otherwise standalone keyed on
+// (accountId, target, runAt).
+//
+// Properties: accountId, auditId (uuid), target (url or
+// '(inline html)'), score (0-100), heuristicsJson (serialized
+// per-heuristic result), runAt, createdByAgent, createdBySession,
+// createdAt.
+//
+// Monitor-related labels (:AEOPrompt, :AEOCheck, :AEOCitation) are
+// intentionally NOT declared in v1 — the multi-engine monitor is
+// filed as a follow-up task and the schema will land with it.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT aeo_audit_id_unique IF NOT EXISTS
+FOR (a:AEOAudit) REQUIRE a.auditId IS UNIQUE;
+
+CREATE INDEX aeo_audit_account IF NOT EXISTS
+FOR (a:AEOAudit) ON (a.accountId);
+
+CREATE INDEX aeo_audit_target IF NOT EXISTS
+FOR (a:AEOAudit) ON (a.target);
+
+CREATE INDEX aeo_audit_run_at IF NOT EXISTS
+FOR (a:AEOAudit) ON (a.runAt);
+>>>>>>> worktree-task-354-aeo-plugin

package/payload/platform/plugins/.claude-plugin/marketplace.json

@@ -9,6 +9,11 @@
       "source": "./admin",
       "version": "0.1.0"
     },
+    {
+      "name": "aeo",
+      "source": "./aeo",
+      "version": "0.1.0"
+    },
     {
       "name": "business-assistant",
       "source": "./business-assistant",

package/payload/platform/plugins/admin/PLUGIN.md

@@ -1,5 +1,6 @@
 ---
 name: admin
+surface: platform
 description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, file-attach, wifi, action-approval tools (action-pending, action-approve, action-reject, action-edit), and session-retrospective-mark-complete (the deterministic sentinel the session-end Stop hook reads via JSONL grep to release the retrospective gate; admin calls it once per session after running the three-pass retrospective) for managing the Maxy platform."
 tools:
   - name: system-status

package/payload/platform/plugins/aeo/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "aeo",
+  "description": "Answer Engine Optimisation. Emits schema.org JSON-LD for typed graph entities, generates llms.txt + llms-full.txt for the site, and audits pages against eight AEO heuristics with one rewrite suggestion per fail. Writes :AEOAudit history nodes when audits are persisted.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "aeo": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ]
+    }
+  }
+}

package/payload/platform/plugins/aeo/PLUGIN.md

@@ -0,0 +1,81 @@
+---
+name: aeo
+description: "Answer Engine Optimisation. Emits schema.org JSON-LD for typed graph entities, generates llms.txt + llms-full.txt for the site, and audits pages against eight AEO heuristics with one rewrite suggestion per fail. Writes :AEOAudit history nodes when audits are persisted."
+tools:
+  - name: aeo-emit-jsonld
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: aeo-write-llms-txt
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: aeo-audit-page
+    publicAllowlist: false
+    adminAllowlist: true
+skills:
+  - skills/structured-answer/SKILL.md
+always: false
+embed: false
+metadata: {"platform":{}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/aeo/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: aeo
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
+    AGENT_SLUG: ${AGENT_SLUG}
+mcp-manifest: auto
+---
+
+# AEO (Answer Engine Optimisation)
+
+This plugin makes the platform's content legible to answer engines — Claude, ChatGPT, Perplexity, Google AI Overviews, Bing Copilot. Classical SEO ranks links; AEO shapes the page so the answer-engine extractor lifts the right answer.
+
+## The three surfaces
+
+1. **JSON-LD** (`aeo-emit-jsonld`). Every typed graph entity that backs a page can be projected to a `<script type="application/ld+json">` block. The mapper covers `Organization`, `LocalBusiness`, `Person`, `Service`, `Product`, `Article`, `FAQPage`, `RealEstateListing`, `Event`. Other labels fall through to `schema:Thing` and are flagged as a doc gap.
+
+2. **llms.txt** (`aeo-write-llms-txt`). The site emits `/llms.txt` (index of pages, one link per line) and `/llms-full.txt` (concatenated full text). Format follows the current draft at `https://llmstxt.org/`. Source is `KnowledgeDocument` nodes with a `url` property. Pages without a `url` are skipped and counted in the response.
+
+3. **Audit** (`aeo-audit-page`). Run the eight-heuristic scorecard against a URL or raw HTML. Each heuristic returns pass / warn / fail with one rewrite suggestion per fail. Score is `100 * (passes + 0.5 * warns) / 8`. Pass `persist: true` with a `targetKnowledgeDocumentId` to record an `:AEOAudit` node linked back to the document.
+
+## The eight heuristics
+
+| Heuristic | Pass | Warn | Fail |
+|---|---|---|---|
+| `h1-present` | one `<h1>` | more than one | none |
+| `jsonld-present` | one or more JSON-LD blocks, all parse | some parse | none, or all unparseable |
+| `structured-answer` | first `<p>` after `<h1>` is ≤280 chars | first `<p>` is over 280 chars | no `<p>` after `<h1>` |
+| `faq-section` | `FAQPage` JSON-LD on page | FAQ text but no JSON-LD | nothing FAQ-like |
+| `meta-description` | 80–160 chars | present but outside range | absent |
+| `canonical-url` | `<link rel="canonical">` present | — | absent |
+| `og-tags` | `og:title` and `og:description` both set | — | one or both missing |
+| `heading-hierarchy` | no level skips | — | h1→h3 or similar jump |
+
+`structured-answer` is the highest-impact: answer engines lift the structured-answer span verbatim. A page can fail every other heuristic and still get cited if the first paragraph cleanly answers the question.
+
+## Persistence model
+
+The plugin only writes `:AEOAudit` nodes (when `persist: true`). It does not own the entities it reads — `KnowledgeDocument`, `Organization`, `Person`, etc. belong to the memory plugin. Edges written:
+
+- `(:KnowledgeDocument)-[:HAS_AEO_AUDIT]->(:AEOAudit)`
+
+The audit nodes carry `accountId`, `target` (URL or `(inline html)`), `score`, `heuristicsJson` (full result), `runAt`, `createdByAgent`, `createdBySession`. They form an append-only audit history; aggregate trend queries (score-over-time) walk this set.
+
+## What this plugin does not do
+
+- No LLM API calls. There is no monitor in v1. The "is my brand cited when a customer asks Claude / ChatGPT / Perplexity / Gemini" question depends on multi-engine answer harvesting that runs differently under maxy-code's no-API-key architecture, and is filed as a follow-up task.
+- No automatic emission. `aeo-emit-jsonld` returns a script block; wiring it into the platform's page render path is per-renderer work, also filed as a follow-up.
+- No publish-hook regeneration of `llms.txt`. The tool runs on demand. Hooking it into the publish event is a follow-up.
+- No prose authoring. AEO audits structure; it does not rewrite content. Writer-craft owns voice.
+
+## See also
+
+- User guide: `platform/plugins/docs/references/aeo.md`
+- Structured-answer template: `platform/plugins/aeo/skills/structured-answer/SKILL.md`
+- Schema declaration: `platform/neo4j/schema.cypher` (search `AEOAudit`)
+- Schema reference: `platform/plugins/memory/schema-base.md` (search `AEOAudit`)

package/payload/platform/plugins/aeo/mcp/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@maxy/aeo",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "neo4j-driver": "^5.28.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.2"
+  }
+}

package/payload/platform/plugins/aeo/mcp/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/__tests__/**/*.test.ts"],
+    testTimeout: 10_000,
+  },
+});

package/payload/platform/plugins/aeo/skills/structured-answer/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: structured-answer
+description: Use when authoring or auditing a page whose primary purpose is to answer a single question — service pages, FAQ entries, "what is X" pages, comparison pages. Defines the page shape that answer engines lift verbatim. Triggers include "make this AEO-friendly", "structure this for Claude / ChatGPT", "audit this page for answer-engine pickup".
+---
+
+# Structured-answer page template
+
+Answer engines (Claude, ChatGPT, Perplexity, Google AI Overviews, Bing Copilot) lift a single short span when they cite a page. That span is almost always the first paragraph after the H1, when it is short and direct. Every other element on the page either supports the lift or gets ignored.
+
+## The shape
+
+```
+<head>
+  <title>{question or topic} — {site name}</title>
+  <meta name="description" content="{80–160 char summary of the answer}">
+  <link rel="canonical" href="{this page's URL}">
+  <meta property="og:title" content="{question or topic}">
+  <meta property="og:description" content="{same as meta description}">
+  <script type="application/ld+json">{ emit via aeo-emit-jsonld }</script>
+</head>
+
+<body>
+  <h1>{question or topic}</h1>
+  <p>{≤280 characters. The answer. One sentence preferred. Names the entity, states the answer, ends on a fact.}</p>
+
+  <h2>{follow-up section}</h2>
+  <p>{details, examples, links}</p>
+
+  <h2>Frequently asked questions</h2>
+  <!-- emit FAQPage JSON-LD with 3–5 Question / Answer pairs -->
+</body>
+```
+
+## Why this works
+
+- The H1 names the question; the first `<p>` is the answer. Engines treat that pair as a structured Q/A.
+- The `<p>` is short enough to be lifted whole. Longer paragraphs get truncated mid-sentence.
+- The JSON-LD repeats the structured data in a parser-friendly form so engines that index pre-render don't have to scrape the DOM.
+- The FAQ section adds a second class of lift target — engines often cite an FAQ answer when the page's main question is too broad.
+
+## What breaks the lift
+
+- A multi-sentence first paragraph. The engine truncates and the citation reads like a fragment.
+- Marketing prose before the answer ("In today's fast-moving world…"). The engine lifts the marketing prose, not the answer.
+- The H1 stating the brand instead of the question. "Acme Plumbing" is not a question; "How much does a boiler service cost?" is.
+- Missing JSON-LD. Engines that pre-render the page still index the DOM, but they down-weight pages without structured data.
+- Skipped heading levels. Engines use heading hierarchy to decide which content is the answer and which is supporting detail.
+
+## How to audit
+
+Run `aeo-audit-page` against the URL or HTML. Eight heuristics return pass / warn / fail. Treat any `fail` as a blocker — the rewrite suggestion in the response is concrete. Treat `warn` as a polish target.
+
+To record the audit on the document for trend analysis, pass `persist: true` with the document's `elementId` as `targetKnowledgeDocumentId`. The plugin writes an `:AEOAudit` node linked via `HAS_AEO_AUDIT`.

package/payload/platform/plugins/docs/PLUGIN.md

@@ -1,5 +1,6 @@
 ---
 name: docs
+surface: platform
 description: "Comprehensive user guide and platform documentation for Maxy. Load references when users ask how-to, setup, or troubleshooting questions. Also contains platform architecture references for admin use."
 metadata: {"platform":{"always":true,"embed":["public","admin"],"pluginKey":"docs"}}
 ---

package/payload/platform/plugins/docs/references/admin-session.md

@@ -79,7 +79,7 @@ PreToolUse hook `platform/plugins/admin/hooks/askuserquestion-investigate-gate.s
 
 ## Spawn-with-`initialMessage` wrapper
 
-The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/admin/claude-sessions.ts`](../../../ui/server/routes/admin/claude-sessions.ts) is the single canonical entry point for any caller — UI click handler or programmatic — that needs to open an admin PTY session with a first user prompt. Direct calls to the session-manager's `/spawn` are not allowed; the wrapper owns the per-spawn enrichment (`aboutOwner`, `dormantPlugins`, `activePlugins`, `specialistDomains`, `tunnelUrl`) and the `senderId` resolution from the admin session cookie. The session manager binds to `127.0.0.1` only so the wrapper is the sole authorised caller; any ad-hoc spawn that bypasses it duplicates this contract and is a bug.
+The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/admin/claude-sessions.ts`](../../../ui/server/routes/admin/claude-sessions.ts) is the single canonical entry point for any caller — UI click handler or programmatic — that needs to open an admin PTY session with a first user prompt. Direct calls to the session-manager's `/spawn` are not allowed; the wrapper owns the per-spawn enrichment (`aboutOwner`, `dormantPlugins`, `activePlugins`, `specialistDomains`, `tunnelUrl`) and the `senderId` resolution from the admin session cookie. The session manager binds to `127.0.0.1` only so the wrapper is the sole authorised caller; any ad-hoc spawn that bypasses it duplicates this contract and is a bug. `dormantPlugins` is `installed − enabledPlugins` with one exclusion: PLUGIN.md frontmatter `surface: platform` (admin, docs) marks platform-shell plugins that ship with every install and are never opt-in features, so they never surface in the `<dormant-plugins>` nudge.
 
 **Body schema.** `{channel?, permissionMode?, initialMessage?, specialist?, model?}` for the cookie path (Sidebar — `senderId` resolved from the admin session cookie, `hidden: false`). `permissionMode` accepts one of five values matching Claude Code's CLI: `'default'`, `'acceptEdits'`, `'plan'`, `'auto'`, `'bypassPermissions'`. The Stop-hook loopback caller adds `adminSessionId` and uses three overrides: `specialist: 'database-operator'`, `model: 'haiku'`, plus `initialMessage`. The wrapper rejects nothing structurally on the cookie path — string fields are coerced or defaulted (`channel` → `'browser'`, `permissionMode` → undefined, `initialMessage` → null if empty/whitespace). The loopback path refuses with `400 admin-session-id-required` if `adminSessionId` is missing or non-UUID, and `404 admin-session-not-found` if the manager has no StoredSession for it.
 

package/payload/platform/plugins/docs/references/aeo.md

@@ -0,0 +1,87 @@
+# AEO (Answer Engine Optimisation) — user guide
+
+The AEO plugin shapes the site for answer engines (Claude, ChatGPT, Perplexity, Google AI Overviews, Bing Copilot). It does three things: emits schema.org JSON-LD from typed graph entities, generates `/llms.txt` and `/llms-full.txt`, and audits any page against eight heuristics.
+
+## When to use it
+
+- A new page is being authored and you want it to be cited when customers ask an answer engine about your service.
+- An existing page is not being cited. Audit it to find the structural reasons.
+- You're standing up a new site and want the `llms.txt` pair generated so answer engines can index your content directly.
+
+## The tools
+
+### `aeo-emit-jsonld`
+
+Generates a `<script type="application/ld+json">` block for a typed entity. Two modes:
+
+- **From the graph.** Pass `entityId` (Neo4j elementId of an `Organization`, `Person`, `Service`, `Product`, `CreativeWork`, `FAQPage`, `RealEstateListing`, or `Event`). The tool resolves the entity, maps the label to its schema.org type, and emits the block.
+- **Inline.** Pass `label` (one of the supported page types) plus a `properties` object. Use this when the page isn't backed by a stored entity (yet) but you want the JSON-LD shape.
+
+Returns the parsed JSON-LD object and a ready-to-inline script block string. Inline the script in your page `<head>`.
+
+### `aeo-write-llms-txt`
+
+Generates the `llms.txt` / `llms-full.txt` pair for the account. Source is every `KnowledgeDocument` for the account that has a `url` property. Returns both files as strings plus a count of pages skipped because they had no URL.
+
+Wire the output to your site host. Convention: `/llms.txt` (index) and `/llms-full.txt` (concatenated content), served as `text/plain`. Format follows the current draft at `https://llmstxt.org/`.
+
+### `aeo-audit-page`
+
+Runs the eight-heuristic audit. Pass either `url` (the tool fetches) or `html` (you supply the rendered content). Returns:
+
+```
+{
+  "score": 0–100,
+  "heuristics": [
+    {
+      "name": "structured-answer",
+      "status": "pass" | "warn" | "fail",
+      "detail": "first <p> after <h1> is 142 chars",
+      "suggestion": "Add one ≤280-character <p> immediately after the <h1>…"
+    },
+    …
+  ],
+  "target": "<url or '(inline html)'>",
+  "audit": { "runAt": "<iso>", "elementId": "<set when persisted>" }
+}
+```
+
+Pass `persist: true` plus `targetKnowledgeDocumentId` to write the result as an `:AEOAudit` node linked to the document.
+
+## The eight heuristics
+
+| Heuristic | What it checks |
+|---|---|
+| `h1-present` | exactly one `<h1>` |
+| `jsonld-present` | at least one parseable JSON-LD block |
+| `structured-answer` | first `<p>` after `<h1>` is ≤280 chars |
+| `faq-section` | `FAQPage` JSON-LD on the page |
+| `meta-description` | 80–160 char `<meta name="description">` |
+| `canonical-url` | `<link rel="canonical">` present |
+| `og-tags` | `og:title` and `og:description` both set |
+| `heading-hierarchy` | no level skips (h1→h3 etc.) |
+
+`structured-answer` is the highest-impact: that one paragraph is what gets lifted into the engine's answer. A page can fail every other heuristic and still be cited if this one passes.
+
+## Observability
+
+Every tool emits a single log line per invocation:
+
+- `[aeo-emit-jsonld] entityId=… schemaType=… source=graph|inline`
+- `[aeo-llms-txt] site=… pages=… skippedNoUrl=… indexBytes=… fullBytes=…`
+- `[aeo-audit] target=… score=… fails=… warns=…`
+
+Diagnostic path: `grep -E '^\[aeo-' platform-logs/*.log | grep <urlOrEntityId>`.
+
+## What this plugin does not do (yet)
+
+- **No monitor.** Tracking whether your brand is cited by Claude / ChatGPT / Perplexity / Gemini requires multi-engine answer harvesting that has to fit maxy-code's no-API-key architecture. Filed as a follow-up.
+- **No auto-emission on page render.** `aeo-emit-jsonld` is callable on demand. Wiring it into the platform's page-generator render path is per-renderer work, filed as a follow-up.
+- **No publish-hook regeneration of `llms.txt`.** The tool runs on demand. Hooking it into the publish event is a follow-up.
+
+## See also
+
+- Plugin manifest: `platform/plugins/aeo/PLUGIN.md`
+- Structured-answer template: `platform/plugins/aeo/skills/structured-answer/SKILL.md`
+- Schema declaration: `platform/neo4j/schema.cypher` (search `AEOAudit`)
+- Spec source: `https://llmstxt.org/`

package/payload/platform/plugins/docs/references/deployment.md

@@ -85,7 +85,7 @@ Every PTY spawn injects an `--append-system-prompt` block composed of these sent
 | `<about-owner>` | upstream `loadUserProfile` + `formatProfileSummary` (UI process) | sentinel renders the prose body with `NOTHING (operator-data source unavailable: \`<reason>\`)` on line one; spawn proceeds |
 | `<specialist-domains>` | `<accountDir>/specialists/agents/*.md` frontmatter (UI process) | sentinel omitted when set is empty |
 | `<plugin-manifest>` | enabled plugins' PLUGIN.md frontmatter + skill SKILL.md frontmatter (UI process) | sentinel omitted when set is empty |
-| `<dormant-plugins>` | installed-minus-enabled set from `platform/plugins/` and `account.json` | sentinel omitted when set is empty |
+| `<dormant-plugins>` | installed-minus-enabled set from `platform/plugins/` and `account.json`, excluding plugins whose PLUGIN.md frontmatter sets `surface: platform` (platform-shell — ships with every install, never opt-in). Absent `surface` field defaults to `feature` (dormant-eligible). | sentinel omitted when set is empty |
 
 Diagnostic line per spawn (`~/.<brand>/logs/server.log`):
 

package/payload/platform/plugins/email/PLUGIN.md

@@ -70,6 +70,12 @@ Manages the agent's own dedicated email account — IMAP for reading, SMTP for s
 - **Graph history** (`email-graph-query`) — stored Email nodes in Neo4j. Use for recall, semantic search, email history questions.
 - **General knowledge** (`memory-search`) — cross-type knowledge graph. Use when the question spans all memory, not just emails.
 
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| [email-composition](skills/email-composition/SKILL.md) | Conversational wrapper for drafting replies, new emails, and inbox triage. Orchestrates the five `email-*` tools with human-in-the-loop approval on every send. |
+
 ## References
 
 | Reference | Topics |

package/payload/platform/plugins/email/skills/email-composition/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: email-composition
+description: "Conversational wrapper around the email plugin tools. Activate when the operator asks to reply to an email, draft a new email, follow up on a thread, or triage outstanding inbox items (e.g. 'reply to Sarah about X', 'email Joel about Y', 'what's outstanding in my inbox'). Orchestrates `email-graph-query`, `email-search`, `email-read`, `email-send`, `email-reply`. Every send is operator-approved — never auto-sends."
+---
+
+# Email composition
+
+Conversational wrapper around the existing `email-*` tools. Drafting, threading, triage. **Human-in-the-loop only — every send is explicitly approved by the operator.** No drip sequences, no scheduled sends, no automatic categorisation.
+
+## When to activate
+
+Activate when the operator asks for any of:
+
+- **Reply to a known thread.** "Reply to Sarah's email about the lease." "Draft a reply to that thread from Joel."
+- **New outbound email.** "Email Joel about the viewing." "Send a note to the team about Friday."
+- **Follow-up on a topic.** "Follow up with everyone from yesterday's viewings."
+- **Inbox triage.** "What's outstanding in my inbox?" "Anything I need to deal with?"
+
+Do **not** activate for:
+
+- Listing or searching emails as the end-goal (no draft intent) — let `email-search` / `email-graph-query` answer directly.
+- Setup, status checks, OTP extraction, auto-respond config — those are direct tool calls.
+- Any automated send loop. If the operator asks for drip / scheduled / broadcast sends, decline and explain that this skill is human-in-the-loop only.
+
+## Flow — reply to an existing thread
+
+### 1. Identify the thread
+
+Pick the right retrieval path:
+
+- **Graph history first** (`email-graph-query`) — for "reply to Sarah's email about the lease": the operator is naming a known correspondent and topic. Fast, semantic, covers the operator's full email history.
+- **Live IMAP** (`email-search` or `email-read`) — for "that email that just came in" or "today's reply from Joel": the operator is naming a recent message that may not yet be in the graph.
+
+If the search returns **multiple plausible threads**, do not guess. Surface 3-5 candidates with sender, subject, date, and a one-line summary, and ask which one. Emit narration `[email-composition] ambiguous-thread candidates=<n>`.
+
+If the search returns **zero matches**, ask the operator to refine (different correspondent? different subject phrasing? wider date range?). Do not invent a thread.
+
+Once the thread is locked, emit narration `[email-composition] thread-identified messageId=<id> subject="<subject>"`.
+
+### 2. Load thread context
+
+Pull the full thread — the current message plus parent messages — via `email-read` or `email-graph-query`. Reply to the actual position of the conversation, not a stripped-down summary. Quote-stripped one-line summaries miss the question the operator is actually being asked.
+
+If the thread has **attachments** that the draft will reference, list the attachment names in the draft presentation and ask whether to forward them. The five existing tools do not currently forward attachments inline — surface this so the operator can manually re-attach if needed.
+
+### 3. Detect skip conditions
+
+Before drafting, check the inbound for:
+
+- **Out-of-office / vacation autoreply.** Skip. Flag to the operator: "this looks like an OOO autoreply — no draft." Do not propose a reply.
+- **Unsubscribe / list-management mail** (List-Unsubscribe header, "to unsubscribe click here" body). Skip. Flag to the operator.
+- **Hostile or grief tone.** Draft cautiously and flag the tone in the presentation: "this reads as hostile / grief-related — please review carefully before sending." Never auto-soften without surfacing the tone judgement.
+
+### 4. Retrieve voice exemplars (conditional)
+
+If the `voice-mirror` plugin is installed and the operator has a style-card on file, fetch it plus 3-5 prior replies in the same register (recipient, subject area, formality) and condition the draft on them. If `voice-mirror` is **not** installed, draft in a **neutral British business register** — polite, concise, no slang, no transatlantic spellings — and state explicitly in the presentation: "drafted in neutral British business voice (voice-mirror not installed)."
+
+### 5. Draft
+
+Compose the reply. Anchor to:
+
+- The specific question or position in the parent message.
+- The operator's voice (from voice-mirror) or the neutral British business register.
+- Any decisions the operator has already stated in this conversation (e.g. "say yes to the price, no to the timeline").
+
+Keep drafts tight. Email is not a wall-of-text medium.
+
+### 6. Present
+
+Show the draft inline with:
+
+- **To** — recipient address (the original sender, unless the operator asked for `replyAll`).
+- **Cc / Bcc** — empty unless the operator explicitly named one. Never copy people forward from the original thread without being asked.
+- **Subject** — the threaded subject (the original with `Re:` if not already prefixed; `email-reply` handles this).
+- **Body** — the draft.
+- **Notes** — any flags from step 3 (tone, attachments, OOO skip-already-applied).
+
+Emit narration `[email-composition] draft-presented recipient=<addr> subjectPrefix="<first-60-chars>"`.
+
+**Do not call `email-reply` at this step.** The send is not yet approved.
+
+### 7. Edit loop
+
+The operator may:
+
+- **Approve** ("send it", "looks good", "yes"). Proceed to step 8.
+- **Edit verbally** ("make it shorter", "drop the second paragraph", "say yes to the price but not the timeline"). Apply the edit and re-present. Stay in the loop until approval or abandonment.
+- **Abandon** ("never mind", "I'll do it myself"). Emit `[email-composition] send-aborted reason=operator-abandoned`. Do not send.
+
+Every operator edit is downstream feedback for `voice-mirror` — if the plugin is installed, record the edit via its feedback channel so the next draft is closer to the operator's voice. If voice-mirror is absent, no feedback is recorded.
+
+### 8. Send
+
+On **explicit** approval, call `email-reply` with:
+
+- `messageId` — the parent message ID from step 1. This is the threading anchor; `email-reply` populates `In-Reply-To` and `References` from it so the reply lands inside the existing thread, not as a new conversation.
+- `replyAll` — only if the operator asked for it. Default is false (reply to sender only).
+- Subject and body from the approved draft.
+
+Emit narration `[email-composition] send-confirmed`.
+
+Confirm to the operator that the send happened by quoting the `email-reply` tool's success line (it includes the sent `messageId` and the resolved `In-Reply-To`).
+
+If `email-reply` errors, surface the error verbatim; do not silently retry. The operator decides whether to fix and retry or abandon.
+
+## Flow — new outbound email
+
+Same as the reply flow with two differences:
+
+1. **No thread context load** (step 2 skipped). Instead, ask the operator for the recipient (if not already named), the topic, and any constraints (formal vs casual, length, things to include or exclude).
+2. **Send via `email-send`**, not `email-reply`. There is no parent `messageId` because this is a new conversation.
+
+Multi-recipient drafting: if the operator names a single person, use that address. If the operator names a group ("email the team", "everyone from yesterday's viewings"), ask which addresses to include — list candidates if you can resolve them from the graph, otherwise ask the operator to enumerate. Do not invent recipients.
+
+## Flow — triage variant
+
+When the operator asks "what's outstanding in my inbox" / "anything I need to deal with" / "what's unread":
+
+1. Call `email-read` for the last N unread messages (default N = 10; operator can specify "last 25", "today's", etc.).
+2. For each message, return a one-line summary with a recommended action:
+   - **Reply** — needs a response.
+   - **File** — informational, can be archived.
+   - **Ignore** — autoreply, newsletter, list mail, OOO.
+3. Emit narration `[email-composition] triage-returned n=<count>`.
+4. Wait for the operator to pick one. When they do ("reply to #3", "draft a response to the Joel one"), drop into the reply flow at step 1 (thread already identified — use the `messageId` from the triage list).
+
+The triage variant **never auto-drafts**. It returns the list and waits.
+
+## Edge cases
+
+| Situation | Behaviour |
+|-----------|-----------|
+| Multiple threads match the operator's description | Surface 3-5 candidates and ask. Never guess. |
+| CC / BCC in the original thread | Reply to sender only by default. Ask explicitly before copying others. |
+| `replyAll` requested | Pass `replyAll: true` to `email-reply`. Otherwise omit (defaults false). |
+| Original thread has attachments referenced in the draft | List attachment names; ask whether to forward. |
+| Inbound is an out-of-office autoreply | Skip. Flag to operator. Do not draft. |
+| Inbound is a list / unsubscribe mail | Skip. Flag to operator. Do not draft. |
+| Inbound is hostile or grief-related | Draft cautiously; flag tone in the presentation. Operator must review explicitly. |
+| `voice-mirror` plugin absent | Draft in neutral British business register; state the absence in the presentation. |
+| `email-reply` returns an error after approval | Surface the error verbatim. Operator decides whether to fix and retry or abandon. Do not silent-retry. |
+
+## Out of scope
+
+Hard boundaries — never offer these in this skill, even if asked:
+
+- **Drip sequences** — multi-step automated send chains. Decline; refer to a future task.
+- **Scheduled / delayed sends** — there is no "send at 9am tomorrow" path. The operator triggers the send when they approve.
+- **List broadcasts** — bulk sends to managed subscriber lists. Not this skill.
+- **Inbox auto-categorisation / labelling** — triage is on demand only.
+- **Calendar follow-up auto-writes** — if a reply confirms a meeting, mention it and let the operator decide whether to write a calendar entry separately.
+- **New MCP tools** — this skill orchestrates the existing five (`email-graph-query`, `email-search`, `email-read`, `email-send`, `email-reply`). Nothing else.
+
+## Observability
+
+The skill emits narration at each major step so a session log makes the full draft → approval → send chain greppable:
+
+| Step | Narration |
+|------|-----------|
+| Thread locked | `[email-composition] thread-identified messageId=<id> subject="<subject>"` |
+| Multiple matches | `[email-composition] ambiguous-thread candidates=<n>` |
+| Draft shown | `[email-composition] draft-presented recipient=<addr> subjectPrefix="<first-60-chars>"` |
+| Send approved | `[email-composition] send-confirmed` |
+| Send abandoned | `[email-composition] send-aborted reason=<why>` |
+| Triage list returned | `[email-composition] triage-returned n=<count>` |
+
+The underlying `[email-send]` / `[email-reply]` / `[email-search]` / `[email-graph-query]` / `[email-read]` tool logs confirm the actual tool calls. Absence of an expected tool tag after `draft-presented` + operator approval is the failure signal — the skill said it sent but didn't.
+
+Diagnostic on Pi:
+
+```
+grep -E '\[email-(composition|reply|send|search|graph-query|read)\]' <session-log>
+```
+
+returns the full chain for any thread.
+
+## Dependencies
+
+- **Required:** `email` plugin (`email-graph-query`, `email-search`, `email-read`, `email-send`, `email-reply`).
+- **Optional:** `voice-mirror` plugin. If installed, drafts use the operator's style-card and edits are captured as feedback. If absent, drafts fall back to a neutral British business register.