@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/deep-research/skills/deep-research/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: deep-research
+description: >
+  Activate this skill when the user asks Claude to research a topic, find current information,
+  compare competitors, review literature, fact-check a claim, or answer any question that
+  benefits from live web sources. Trigger phrases include: "research", "find out", "what's
+  the latest on", "compare X and Y", "who is", "look into", "fact-check", "deep dive",
+  "what do we know about", "literature review", or any question where Claude's training
+  data may be stale or insufficient. This skill replicates Perplexity-style agentic web
+  research using only Claude models and Claude Code's native tooling — no external API keys
+  required.
+
+config:
+  citation_style: "inline"   # Options: inline | footnotes | cards | minimal
+  max_sources: 8             # Maximum sources to synthesise per query (4–12 recommended)
+  search_depth: "standard"   # Options: standard (3–5 searches) | deep (6–12 searches)
+  show_confidence: true      # Append confidence note (High / Medium / Low)
+  follow_up_questions: true  # Suggest 3 follow-up questions
+---
+
+# Deep Research Skill
+
+You are a research agent. Answer questions using live web sources, synthesise findings across multiple sources, and present results with full attribution. You do not guess. You search, read, extract, and cite.
+
+## Workflow
+
+**Phase 1 — Decompose.** Before searching, break the question into: core question, temporal dimension (breaking / recent / evergreen), perspective breadth, and 2–5 sub-questions. State your decomposition in 1–3 lines, then proceed without asking permission. After decomposition, read `references/research-modes.md` to select the appropriate research mode.
+
+**Phase 2 — Search.** Map sub-questions to targeted search queries. Read `references/search-strategy.md` for query crafting rules and source evaluation criteria.
+
+**Phase 3 — Fetch and extract.** For each source, fetch full page content, extract only what is relevant to the sub-question, note publication dates. See `references/search-strategy.md` for source quality hierarchy and staleness rules.
+
+**Phase 4 — Synthesise.** Write a structured response that directly answers the original question. Read `references/citation-styles.md` and apply the citation style from `config.citation_style`.
+
+**Phase 5 — Confidence.** If `show_confidence: true`, append a confidence assessment. See `references/citation-styles.md` for the High / Medium / Low criteria.
+
+**Phase 6 — Follow-ups.** If `follow_up_questions: true`, suggest 3 genuinely useful next questions. See `references/citation-styles.md`.
+
+## Hard Rules
+
+1. **Never fabricate citations.** If you cannot find a source for a claim, say so explicitly.
+2. **Never quote more than 15 words verbatim** from any single source.
+3. **One direct quote per source maximum.** Paraphrase everything else.
+4. **Do not recite training data as search results.** If relying on training knowledge, say: "(from training data, not verified live)".
+5. **Stale is worse than honest.** If you cannot find current information, state the most recent date you found and invite the user to check for updates.
+6. **No padding.** Every sentence must carry information. No filler, generic caveats, or restated conclusions.

package/payload/platform/plugins/deep-research/skills/deep-research/references/citation-styles.md

@@ -0,0 +1,52 @@
+# Citation Styles, Confidence, and Follow-ups
+
+## Citation Styles (Phase 4)
+
+Apply the style set in `config.citation_style`:
+
+### inline (default)
+> The company raised $120M in Series B funding [1], led by Andreessen Horowitz [2].
+> Sources: [1] techcrunch.com/... [2] a16z.com/...
+
+### footnotes
+> Prose with no inline markers. Full source list at end:
+> ---
+> **Sources**
+> 1. Title — domain.com/path (Date if known)
+> 2. Title — domain.com/path
+
+### cards
+> Each source rendered as a mini card:
+> ┌─────────────────────────────────────────┐
+> │ [1] Title of article                    │
+> │ Source: domain.com · Date: YYYY-MM-DD   │
+> │ Relevant finding: one-line summary      │
+> └─────────────────────────────────────────┘
+
+### minimal
+> The company raised $120M (techcrunch.com/...), led by a16z (a16z.com/...).
+
+## Confidence Assessment (Phase 5)
+
+If `show_confidence: true`, append a brief confidence assessment after the main answer:
+
+**Confidence: High / Medium / Low**
+- High: multiple independent sources agree, sources are recent and authoritative
+- Medium: sources partially agree, or primary sources are thin
+- Low: limited sources, conflicting information, or significant recency gaps
+
+Always flag explicitly if:
+- A key sub-question could not be answered from available sources
+- Important information may exist behind paywalls or login walls
+- The topic is moving fast and this answer may be stale within days/weeks
+
+## Follow-up Questions (Phase 6)
+
+If `follow_up_questions: true`, end with:
+
+**You might also want to ask:**
+1. [Specific follow-up question 1]
+2. [Specific follow-up question 2]
+3. [Specific follow-up question 3]
+
+Make these genuinely useful — the next natural step in the research, not generic variations of the original question.

package/payload/platform/plugins/deep-research/skills/deep-research/references/research-modes.md

@@ -0,0 +1,22 @@
+# Research Modes
+
+Adjust behaviour based on query type. Select the appropriate mode after Phase 1 decomposition.
+
+## General Research / Fact-finding
+
+- 3–5 sources is usually sufficient
+- Prioritise recency and source authority
+- Lead with the direct answer, then supporting evidence
+
+## Competitive / Market Intelligence
+
+- Always cover: (a) the company's own claims, (b) independent analyst or press coverage, (c) user sentiment (G2, Reddit, Trustpilot where relevant)
+- Structure output as: Overview → Key differentiators → Weaknesses/risks → Pricing (if findable) → Verdict
+- Flag if pricing is not publicly listed
+
+## Academic / Deep Literature Review
+
+- Prioritise peer-reviewed sources, preprints (arXiv, bioRxiv), and institutional reports
+- Note study size, methodology, and date for each source
+- Distinguish between consensus findings and contested/emerging claims
+- Use deep search depth — do not stop at 3 sources for academic queries

package/payload/platform/plugins/deep-research/skills/deep-research/references/search-strategy.md

@@ -0,0 +1,24 @@
+# Search Strategy and Source Evaluation
+
+## Query Crafting (Phase 2)
+
+Map each sub-question to one or more targeted search queries:
+
+- Keep queries short (3–6 words). Specific nouns beat vague phrases.
+- Vary query framing: try the direct question, a "site:domain" form, and a comparison form where relevant.
+- For competitive intelligence: always search the target company directly AND search for independent reviews/comparisons.
+- For literature/academic queries: search for primary papers, then for secondary summaries.
+- For fast-changing topics (pricing, funding, personnel): append the current year to queries.
+- Never repeat the same query twice. If a search returns poor results, rephrase — don't retry identical terms.
+
+## Source Fetching and Extraction (Phase 3)
+
+For each source returned:
+
+1. Fetch the full page content where possible, not just the snippet.
+2. Extract only what is relevant to the sub-question that drove this search.
+3. Note the publication date if visible.
+4. Flag sources older than 18 months as `[possibly outdated]`.
+5. Prefer: official docs, primary research, reputable press. Deprioritise: forums, SEO farms, undated pages.
+
+Do not quote large blocks verbatim. Paraphrase and extract the key claim or data point.

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

@@ -0,0 +1,52 @@
+---
+name: docs
+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"}}
+---
+
+# Maxy Documentation
+
+This plugin is the single source of truth for Maxy documentation. It ships with every install and is always the version the user has installed.
+
+Load the relevant reference when the user asks a how-to question, requests help with setup, reports an issue, or wants to understand how something works.
+
+## User Guide
+
+Load these when users ask about Maxy features or need guidance:
+
+- **Getting started** → `references/getting-started.md` — first run, what Maxy is, how to use it
+- **Plugins** → `references/plugins-guide.md` — what plugins are, how to install/remove them, the marketplace
+- **Memory** → `references/memory-guide.md` — how Maxy remembers things, what is stored, privacy
+- **Graph view** → `references/graph.md` — the admin `/graph` page: node/edge display, zoom-adaptive Conversation labels, filter chips, trashed nodes
+- **Contacts** → `references/contacts-guide.md` — adding, looking up, and managing contacts
+- **Telegram** → `references/telegram-guide.md` — Telegram setup, the bot, daily use
+- **Settings** → `references/settings.md` — output style, effort level, account preferences
+- **Access Control** → `references/access-control.md` — who can chat with your public agent, invitations, authentication
+- **Projects** → `references/projects-guide.md` — creating projects, tracking health, phase transitions, completing
+- **Troubleshooting** → `references/troubleshooting.md` — common issues and how to resolve them
+
+## Platform Reference
+
+Load these when performing admin tasks or diagnosing platform behaviour:
+
+- **Platform architecture** → `references/platform.md` — how the platform works, agent types, the plugin model
+- **Platform internals** → `references/internals.md` — retrieval pipeline, embedding infrastructure, guard layers, query classification, memory-rank, graph expansion, keyword subscriptions, context assembly, inbound message screening, and tool call audit trail. Load when answering architecture questions, assessing whether a capability exists, diagnosing retrieval behaviour, or reviewing security and privacy features.
+- **Cloudflare** → `references/cloudflare.md` — dashboard-first tunnel setup, the `cloudflared`-CLI-only tool surface, single-recovery-path (re-login) for every wrong-account failure.
+- **Deployment** → `references/deployment.md` — Pi setup, Cloudflare tunnel, start script
+
+## References
+
+- references/getting-started.md
+- references/plugins-guide.md
+- references/memory-guide.md
+- references/graph.md
+- references/contacts-guide.md
+- references/telegram-guide.md
+- references/settings.md
+- references/access-control.md
+- references/projects-guide.md
+- references/troubleshooting.md
+- references/platform.md
+- references/internals.md
+- references/cloudflare.md
+- references/deployment.md

package/payload/platform/plugins/docs/references/access-control.md

@@ -0,0 +1,73 @@
+# Access Control
+
+## What It Is
+
+Access control determines who can chat with your public agent. By default, anyone with your public URL can start a conversation. You can restrict this so only invited people have access.
+
+## Access Modes
+
+Each public agent has one of three access modes:
+
+| Mode | Who can chat |
+|------|-------------|
+| Open (default) | Anyone with the URL. No login required. |
+| Gated | Invitation only. Visitors must be invited by you and authenticate before the chat loads. |
+| Paid | Same as gated — visitors must be invited and authenticated. The label distinguishes paying clients from free invitees, for your own tracking. |
+
+Gated and paid work identically — the difference is a label for your records. Both require visitors to authenticate before they can see the chat.
+
+## How to Set It Up
+
+Tell {{productName}}: "Set my public agent to gated access" or "Make the coaching agent invitation-only."
+
+{{productName}} changes the access mode. The next visitor to your public URL will see a login screen instead of the chat.
+
+## Inviting Visitors
+
+Tell {{productName}} who to invite: "Invite sarah@client.co to the coaching agent" or "Give Tom access to my public agent — his number is 07700 900123."
+
+{{productName}} creates an invitation and sends a magic link (email) or OTP (phone). The visitor clicks the link, sets a password, and gains access.
+
+## What Visitors Experience
+
+- **First visit (invited):** The visitor receives an email or message with a link. Clicking it takes them to your public URL where they set a password. After that, they're in the chat.
+- **Return visits:** The visitor enters their email/phone and password to log in.
+- **Expired access:** If their access period has passed, they see an expiry message with the date.
+- **No invitation:** If someone reaches a gated URL without an invitation, they see a login screen with a note that access requires an invitation.
+
+## Managing Access
+
+All access management is done through conversation with {{productName}}:
+
+- "Who has access to my coaching agent?" — lists active visitors
+- "Revoke Sarah's access" — permanently deactivates her access
+- "Extend Tom's access by 30 days" — pushes the expiry date forward
+- "Set all access to expire after 90 days" — applies a default expiry to new invitations
+
+Revoked access is permanent — the visitor cannot log in again unless re-invited.
+
+## Visitor Identity
+
+When a visitor is authenticated, your public agent knows their name and contact details. It can personalise responses ("Welcome back, Sarah") without needing to ask.
+
+## Action Approval
+
+External-facing actions — sending emails, WhatsApp messages, Telegram messages, and erasing contacts — require your approval before {{productName}} executes them. This is human oversight as required by the EU AI Act.
+
+When {{productName}} needs to send a message or perform a consequential action, it drafts the action and queues it for your review. You'll see it in your next chat turn:
+
+- "Approve it" — {{productName}} executes the action immediately
+- "Reject it" — the action is cancelled
+- "Change the subject to X" — {{productName}} modifies the action and executes the edited version
+
+Internal operations (creating tasks, updating contacts, searching memory) execute automatically without approval.
+
+### Changing the Policy
+
+Tell {{productName}} to change which actions require approval:
+
+- "Auto-send follow-up emails from now on" — emails execute without approval
+- "Require approval for all WhatsApp messages" — restores the default gating
+- "What actions currently require my approval?" — lists the current policy
+
+Changes are per-account and take effect immediately.

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

@@ -0,0 +1,80 @@
+# Admin Session — restart survival and SDK-resume contract
+
+The admin PIN-gated session-store is the in-memory `Map<sessionKey, Session>` at [`platform/ui/app/lib/claude-agent/session-store.ts`](../../../ui/app/lib/claude-agent/session-store.ts). Every `systemctl --user restart {brand}.service` (notably the one `setup-tunnel.sh` arms 3 s after `step=done` via `systemd-run --on-active=3s`) wipes that Map. This reference documents how an admin session survives the restart without forcing PIN re-entry, and how the SDK conversation chain is preserved across the gap.
+
+## Signed sessionKey
+
+`POST /api/admin/session` mints sessionKeys as HMAC-signed tokens (same primitive as `remote-auth.ts`'s `__remote_session` cookie, generalised to `session-store.ts`):
+
+```
+v1.<base64url(payloadJson)>.<base64url(hmac-sha256(secret, payloadJson))>
+
+payload = { v: "adm", a: <accountId>, u: <userId>, c: <createdAtMs>, n: <16-byte hex nonce> }
+```
+
+The HMAC secret lives at `~/.${brand}/credentials/admin-session-secret` (mode `0o600`, parent dir `0o700`), self-provisioned on first read via the `wx`-create pattern from [`remote-auth.ts::getSecret`](../../../ui/app/lib/remote-auth.ts). The secret is separate from `REMOTE_SESSION_SECRET_FILE` (the `__remote_session` cookie key) — two token surfaces, two security domains, no token-confusion attack across schemas.
+
+**Validation path.** `validateSession(sessionKey, 'admin')`:
+
+1. In-memory `Map.get(sessionKey)` hit → existing behaviour (age check, grant check, return ok).
+2. Map miss AND `agentType === 'admin'` → `tryRehydrateAdminSession(sessionKey)`:
+   - Parse `v1.…` token, verify HMAC against the on-disk secret (timing-safe compare).
+   - Schema-validate the payload (`v === 'adm'`, all required fields present).
+   - TTL check: `Date.now() - payload.c <= 24h`. Expired → return `{kind: 'expired', ageMs}` → caller projects onto the existing `session-expired-age` rejection.
+   - Otherwise, re-register the in-memory entry with `{agentType: 'admin', accountId, userId, wantsPriorConversation: true}` and return `{kind: 'ok', …}`.
+3. Map miss with no valid token → `session-not-registered` (existing legacy `crypto.randomUUID()` sessionKeys land here).
+
+**Observability.** `[session-rehydrate-from-token] sessionKey=… accountId=… userId=… ageMs=…` fires once per successful rehydrate in `server.log`. A tampered token fails HMAC and returns `invalid-token` silently (no log line — would otherwise be a noise/attack-amplifier surface); the request's downstream `[session] middleware-reject status=401 code=session-not-registered` is sufficient.
+
+## SDK-resume contract on PIN-rebind
+
+The Anthropic SDK is stateless against its own JSONL: every cold-create with `resume: <agentSessionId>` reads `${CLAUDE_CONFIG_DIR}/projects/<encoded-cwd>/<agentSessionId>.jsonl` verbatim. The Maxy graph (`Conversation.agentSessionId`) is just the pointer into the JSONL, not a parallel transcript. The PIN-rebind contract preserves this:
+
+1. **Rehydrate** restores `(accountId, userId)` into the in-memory session. `conversationId` and `agentSessionId` are empty.
+2. **Chat-route first POST** (`platform/ui/server/routes/admin/chat.ts`):
+   - `consumeWantsPriorConversation(sessionKey)` returns true → look up prior admin conversation.
+   - `getMostRecentAdminConversationForUser(accountId, userId)` returns `{conversationId, agentSessionId}` for the most recent admin Conversation node carrying a non-null `agentSessionId`.
+   - `setConversationIdForSession(sessionKey, conversationId)` binds the prior `conversationId` so the operator's chat lands in the SAME conversation, not a new one.
+   - `setAgentSessionId(sessionKey, agentSessionId)` seeds the in-memory session's pointer; subsequent `invokeAdminAgent`'s `getAgentSessionId(sessionKey)` returns this value naturally.
+3. **`invokeAdminAgent`** passes `resume: <priorAgentSessionId>` to the SDK options. The SDK opens its on-disk JSONL for that session id and continues from there.
+
+No `<previous-context>` prompt-stuffing. No Neo4j transcript replay. The SDK reads its own JSONL — the only canonical source of multi-block content (`thinking` with signed signatures, `tool_use`/`tool_result` chains, multi-modal blocks) the graph cannot losslessly reconstruct.
+
+## PIN-rebind vs `/sessions/new`
+
+The `wantsPriorConversation` marker is the discriminator between continuity and explicit fresh-start:
+
+| Trigger | Marker set? | Chat-route behaviour |
+|---|---|---|
+| Signed-token rehydrate post-restart (`tryRehydrateAdminSession`) | yes | Resume prior conversation |
+| Explicit PIN re-entry (`POST /api/admin/session`, `createAdminSession`) | yes | Resume prior conversation |
+| Operator clicks "New conversation" (`POST /api/admin/sessions/new`) | NO | Cold-mint new conversation |
+
+Single-shot: the chat-route consumes the marker on the first POST, so subsequent chats in the same session continue with the bound `conversationId` naturally.
+
+## Observability summary
+
+Per chat POST, one `[client-acquire]` line lands in the per-conversation stream log at `{accountDir}/logs/claude-agent-stream-<conversationId>.log`:
+
+```
+[client-acquire] sessionKey=<sk12>… resume=<priorAgentSessionId8|none> reason=<warm|cold|pin-rebind>
+```
+
+- `warm` — pool entry still alive (no restart in between)
+- `cold` — fresh mint (no prior admin conversation, or `/sessions/new`)
+- `pin-rebind` — post-restart resume of prior admin conversation
+
+The pre-existing `[client-cold-create resumedFrom=<id>]` line from `client-pool.ts` fires once per actual SDK subprocess spawn; combined with `[client-acquire]` it gives a complete shape of every acquire-and-spawn event.
+
+Diagnostic grep:
+
+```bash
+grep -E '\[session-rehydrate-from-token\]|\[client-acquire\] reason=pin-rebind' ~/.${brand}/logs/server.log
+grep '\[client-acquire\]' ~/.${brand}/logs/claude-agent-stream-*.log
+```
+
+## Out of scope
+
+- Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.
+- Multi-user PIN identity carry-forward across the same signed token — the token is bound to one `userId`; rotating PINs mints a fresh token.
+- Replacing `systemctl restart` with in-process cloudflared reload — separate task. The restart-survival contract documented here is the operator's safety net while that rewrite is pending.

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

@@ -0,0 +1,44 @@
+# Admin Chat Attachments
+
+What you can drag-and-drop into the admin chat window, what happens to each file, and the size caps.
+
+## Accepted file types
+
+| Type | MIME | Notes |
+|------|------|-------|
+| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | Rendered inline by the agent when relevant. |
+| PDF | `application/pdf` | The agent reads the text; scanned PDFs go via OCR if available. |
+| Plain text, Markdown, CSV, HTML | `text/plain`, `text/markdown`, `text/csv`, `text/html` | Read directly. |
+| Calendar | `text/calendar` | Ingested into the graph if the agent finds a reason to keep it. |
+| Voice note | `audio/*` | Transcribed before the message is routed to the agent. |
+| **Zip archive** | `application/zip`, `application/x-zip-compressed` | Unpacked by the agent after safety checks. See below. |
+
+Anything else is refused at upload time with a message naming the type.
+
+## Size caps
+
+- **Per file:** 50 MB. Enforced at the upload endpoint — files over this limit never reach disk.
+- **Per message:** up to 5 files.
+- **Uncompressed contents of a single zip:** 100 MB. A zip whose declared uncompressed total is over this limit is refused before any byte is extracted (decompression-bomb guard).
+
+## What happens with a zip archive
+
+When you drop a `.zip` into chat, the agent:
+
+1. **Checks the archive is safe.** It refuses archives that try to write outside their own extraction folder, contain symlinks, are password-protected, or declare more than 100 MB of uncompressed content. You'll see the exact reason in chat if any check fails.
+2. **Extracts it to a fresh folder.** Contents land under `{your-account-dir}/extracted/{id}/` — one folder per archive, never mixed.
+3. **Lists what's in it.** The agent tells you the top-level entries, the total file count, and the uncompressed size.
+4. **Asks before doing anything else.** For each class of file (text/markdown, images, PDFs, other), it proposes one next step — for example "ingest these notes into memory" or "re-attach the images back to chat so you can see them" — and waits for you to say yes.
+
+Nothing is ingested, sent, or acted on automatically. The extraction is local and visible; you decide what happens next.
+
+## What is **not** supported
+
+- `tar`, `tar.gz`, `7z`, `rar` — zip only. If you have one of these, unzip/convert locally and upload the zip (or the extracted files directly).
+- Nested archives — a zip-inside-a-zip is extracted one level; you can ask the agent to unpack the inner one afterwards.
+- Password-protected zips — the agent will tell you to unlock locally and re-upload.
+- Uploads larger than 50 MB — split the archive, or upload the individual files.
+
+## Where the files live
+
+Uploads go to `{install-dir}/data/uploads/{account-id}/{file-id}/` — outside the platform wipe zone, so they survive re-installs. Extracted zip contents go to `{account-dir}/extracted/{file-id}/`. Both are local to your device.

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

@@ -0,0 +1,111 @@
+# Cloudflare Tunnel — the dashboard is the source of truth
+
+Each installation has its own Cloudflare account. Sign-in is OAuth in the device's VNC browser; `cloudflared` writes `cert.pem` to the brand's config directory. The agent never reads or mutates Cloudflare account state directly — whatever you see in your logged-in dashboard is the single source of truth. When something needs doing on the account side (adding a domain, deleting a stray entry, switching accounts), the agent relays the click-paths; you run them in your browser.
+
+## Identity model
+
+| Concept | Source |
+|------|--------|
+| **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
+| **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
+| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. When the scrape returns an unexpected count (e.g. 1 on a two-zone account), the stream log's per-poll `phase=dom-scrape-poll n=<k> count=<n> domains=[…]` trajectory + the on-disk HTML dump at `~/{configDir}/logs/list-cf-domains-<ts>-count<n>-<mode>-pid<pid>.html` (earlier platform fixes — written on every scrape outcome, not just empty ones) give the operator everything they need to triage the cause without re-running. |
+| **CDP port the scrape attaches to** | `brand.json` (`cdpPort`, stamped at install time) — the same brand-scoped port `vnc.sh` binds Chromium to. `list-cf-domains.sh <brand>` requires the brand arg; the helper reads `${MAXY_PLATFORM_ROOT}/config/brand.json` (no silent default). Missing brand arg, missing brand.json, or missing `cdpPort` field each exit 1 with one of three named reasons (`brand-arg-missing`, `brand-config-missing`, `cdp-port-unresolved`); the route maps all three to `field=config` so the form renders a config card naming the brand instead of a Retry button — retrying would re-fire the same wrongly-resolved spawn. |
+| **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `tunnel.state`, `alias-domains.json`. |
+
+There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, run `reset-tunnel.sh` (which deletes the cert and every tunnel on the current account), then run `setup-tunnel.sh` again — `cloudflared tunnel login` inside the setup script will pick a fresh account when you sign in.
+
+## Setup flow
+
+Ask the agent to set up Cloudflare. The agent first confirms the domain is already on your Cloudflare account (if not, it quotes the dashboard click-path — see below) and then renders a single form in chat. The form collects everything in one submission:
+
+- **Admin address** — the hostname that will serve the admin chat (e.g. `admin.yourdomain.com`).
+- **Public address** — optional hostname for the public agent (e.g. `public.yourdomain.com` or `chat.yourdomain.com`).
+- **Proxy apex** — optional bare-domain hostname (e.g. `yourdomain.com`) that should also serve the public agent.
+- **Admin password** — the password used to gate remote access to the admin surface.
+
+When you submit, the `/api/admin/cloudflare/setup` endpoint runs — in strict order — `setRemotePassword`, launches a `cloudflare-setup` action (earlier platform fixes: `systemd-run --user` transient unit wrapping `setup-tunnel.sh <brand> <port> <hostname...>`), and registers a post-exit handler that writes alias-domains for every non-`public.*` public or apex hostname (so e.g. `chat.yourdomain.com` is classified as public by `isPublicHost`) and closes the audit Task. When the post-exit handler observes the systemd-run unit gone before its terminal status was sampled (a known systemd-run cgroup race), it consults `tunnel.state` on disk and verifies the tunnel identity matches the form you submitted; if so, the audit Task closes `completed` despite the missed observation. Otherwise it closes `failed` with `endpoint-died-pre-reconcile` and the boot reconciler may still recover the Task at next restart. The script runs end-to-end:
+
+- `cloudflared tunnel login` — OAuth browser sign-in. The VNC browser opens the Cloudflare authorize page; pick the account that owns your domain, click Authorize. `cert.pem` lands.
+- Tunnel resolution from operator-supplied identity (operator-selected-tunnel fix). The form populates a tunnel-select dropdown from `GET /api/admin/cloudflare/tunnels` (which calls `cloudflared tunnel list --output json` on your logged-in account). You either pick an existing tunnel from the list or type a name to create a new one. The form posts EXACTLY ONE of `{tunnelId, tunnelName}`; the script enforces the same constraint as defence in depth. Pre-fix the script derived `${BRAND}-$(hostname -s)` locally; that broke the operator-state-is-authoritative doctrine and silently created orphan tunnels whenever the device hostname changed. Stream log emits `step=tunnel-resolve source=operator-selected|operator-created tunnel_id=… tunnel_name=…` once the UUID is known.
+- **Zone pre-flight** — for every non-apex hostname the script queries `1.1.1.1` for the registrable parent's NS records and refuses the whole run if they don't point at Cloudflare. Stream log: `step=zone-preflight result=ok|error zones_on_account=… missing_parent_for=…`. Catches "domain not on Cloudflare"; does not catch "domain on a different Cloudflare account than `cert.pem` is bound to" — that case surfaces later via `tunnel-status`.
+- `cloudflared tunnel route dns` for each subdomain hostname. Apex hostnames cannot be routed this way — the script prints an **ACTION REQUIRED** block naming the exact dashboard record to add or edit. Stream log emits `step=route-dns hostname=… tunnel_id=…` before the call and `step=route-dns hostname=… result=ok|apex-skip|error` after; on error the bounded cloudflared stderr (≤400 chars) rides in the same phase line. **The script does not parse cloudflared's stdout** — exit code is the sole decision signal, so all three legitimate cloudflared output shapes (new record, overwrite, idempotent "already configured") are treated as success.
+- `config.yml` and `tunnel.state` written under `${CFG_DIR}`.
+- **Step-7 onboarding completion persisted** — the script writes `${ACCOUNT_DIR}/onboarding/step7-complete` (a JSON marker with the completion timestamp and tunnel ID) before arming the restart. Stream log: `step=onboarding-persist result=ok|error reason=<r>`. The marker is consumed by the next admin session's first state read and advances `OnboardingState.currentStep` to 7. Without this, the service restart below would SIGTERM the admin agent before it could persist step-7 completion, and the next session would re-ask the Cloudflare question you just finished. Both invocation surfaces (the form-driven action and the agent-via-Bash path) declare `ACCOUNT_DIR` explicitly because `systemd-run --user` does not inherit parent env — when ACCOUNT_DIR isn't reaching the script you'll see `result=skipped reason=no-account-dir` in the stream log instead of `result=ok`.
+- **Post-restart resume contract** — when the script exits cleanly, the form fires a client-side resume event. The chat hook ([useAdminChat.ts](../../../../platform/ui/app/useAdminChat.ts)) waits for the brand-service to come back via `/api/health` (down-then-up), re-binds the conversation to the new server process, and sends the "Cloudflare setup completed" marker as a normal hidden chat POST that re-invokes the agent in a fresh session. No relay queue, no boot-drain, no banner. Diagnostic: `grep '\[admin-resume\] reason=post-restart' ~/{configDir}/logs/server.log` (expect one line per restart cycle), `grep '\[client-event\] kind=post-restart-resume' ~/{configDir}/logs/server.log` for the operator-visible client trace. See `.docs/web-chat.md` "Post-restart resume contract" for the full client/server contract.
+- `systemctl --user restart ${BRAND}.service` — restarts the platform service so the new tunnel spawns via the service's `ExecStartPre=resume-tunnel.sh`.
+- Post-restart verification — `ps -ef | grep '[c]loudflared'` confirms the connector is alive, then `curl -I https://<hostname>` against each subdomain (up to 60 s per host) confirms a non-530 response.
+
+When the endpoint returns, the form surfaces the script's output and the agent relays it verbatim in chat, including any `ACTION REQUIRED` block. If something fails along the way, the form stays open with a field-scoped error (admin label, public label, password, or script exit) so you can correct and retry without re-entering everything.
+
+## Getting a domain on Cloudflare
+
+The tunnel needs a domain on the Cloudflare account the device will sign into. Two paths, both in your browser:
+
+**Option A: Buy a new domain through Cloudflare.** Navigate to cloudflare.com → Domains and buy one. Cloudflare sets everything up.
+
+**Option B: Add an existing domain.** In the dashboard: Websites → Add a site. Cloudflare imports the existing DNS records; review them to confirm your website and email entries are preserved. Cloudflare gives you two nameservers; replace the registrar's nameservers with those. Propagation is usually minutes (up to 24 hours); the zone shows **Active** when ready.
+
+Existing website traffic continues to work during and after the switch. Only DNS resolution changes owners.
+
+## Reset / account switch
+
+Ask the agent to reset Cloudflare. The agent invokes `reset-tunnel.sh` on the device:
+
+- Deletes every tunnel on the brand's current Cloudflare account (via the bound cert).
+- Wipes the brand's `${CFG_DIR}`.
+- Exits with the number of tunnels deleted.
+
+The script does **not** stop token-mode connector processes, delete stray misrouted CNAMEs in the dashboard, or touch the platform service. If any of those apply (agent will flag them), the agent guides you through the manual cleanup — `pkill -f 'cloudflared.*tunnel run --token'` on the device, or deleting the stray CNAME in the dashboard.
+
+After reset, run setup again. The fresh `cloudflared tunnel login` will pick whichever Cloudflare account you sign into.
+
+## Manual runbook
+
+When the scripted flow fails partway, or you want to walk through every step yourself, there's a step-by-step runbook at `plugins/cloudflare/references/manual-setup.md`. The runbook mirrors `setup-tunnel.sh` verbatim — every scripted step corresponds to a numbered runbook step with isolated command blocks, success conditions, and troubleshooting. Pick up the runbook at whichever step the script failed in.
+
+## Dashboard operations the CLI cannot do
+
+The CLI cannot add a domain, switch accounts, edit an apex CNAME, or delete stray records. `plugins/cloudflare/references/dashboard-guide.md` has one numbered click-path per operation. The agent quotes the relevant steps verbatim when you need to do one of these things.
+
+## Troubleshooting
+
+### Tunnel won't start
+
+Ask the agent to check. The agent reads `systemctl --user status ${BRAND}.service` and `~/{configDir}/cloudflared/logs/cloudflared.log`. Common states:
+
+- **No cloudflared process running** — the service's `ExecStartPre=resume-tunnel.sh` exited cleanly but did not spawn the connector. Usually means `tunnel.state` is missing or `config.yml` was written with empty variables. The agent will re-run `setup-tunnel.sh`.
+- **`tunnel not found`** — the UUID in `config.yml` does not match any tunnel on the currently-bound account. Usually follows an account switch that didn't reset local state. The agent invokes `reset-tunnel.sh` and then a fresh setup.
+
+### URL returns 530
+
+DNS propagation or account mismatch. Wait 30–60 seconds and retry first. If the 530 persists:
+
+- The domain may be on a Cloudflare account different from the one `cert.pem` is bound to — re-running `setup-tunnel.sh` re-validates.
+- The UDP buffer for QUIC may be undersized on this device — check `cloudflared.log` for `failed to sufficiently increase receive buffer size`.
+
+### URL returns connection refused
+
+The tunnel is live but nothing is listening on the platform port. Start the platform service: `systemctl --user start ${BRAND}.service`.
+
+### Admin hostname serves the public agent
+
+`admin.yourdomain` is being misclassified as public. The platform UI treats a host as public when either (a) the hostname starts with `public.`, or (b) the hostname appears in `${CFG_DIR}/alias-domains.json`. Older install flows wrote every routed hostname into `alias-domains.json`; the pollution survives across reinstalls.
+
+The agent reads `alias-domains.json`, removes the offending `admin.*` entry, and the platform UI hot-reloads — no restart needed. See `plugins/cloudflare/references/reset-guide.md` § "Remove a rogue entry from alias-domains.json" for the exact `jq` command.
+
+### DNS not resolving
+
+The most common cause is wrong nameservers on the domain. The domain must use Cloudflare's nameservers, not the registrar's defaults. In the dashboard: Websites → your domain → status must say **Active**, not **Pending**. If Pending, follow the dashboard's nameserver instructions and wait for propagation.
+
+### Remote login issues
+
+- 5 failed login attempts → 15-minute lockout — wait for expiry.
+- The remote password is set during Cloudflare Tunnel onboarding — the agent asks for one in chat and stores it deterministically. The browser form at `/__remote-auth/setup` remains available for resets on the local network.
+
+## What the agent does and does not do
+
+**Does:** invokes `setup-tunnel.sh` / `reset-tunnel.sh` via Bash, quotes click-paths from the reference files verbatim, verifies external reachability with `curl -I`.
+
+**Does not:** drive the Cloudflare dashboard via Playwright, synthesise alternative `cloudflared` flag sequences, call any Cloudflare API or SDK, write or edit `cert.pem` / `tunnel.state` / `config.yml` / `alias-domains.json` directly.
+
+When a script or command fails, the agent reports the failure and cites the relevant recovery step. It does not improvise.

package/payload/platform/plugins/docs/references/contacts-guide.md

@@ -0,0 +1,102 @@
+# Contacts Guide
+
+## What a Contact Is
+
+A contact is a Person node in {{productName}}'s memory graph. Each person has a first name and at least one identifier — email address, phone number, or both. Optional fields include last name and job title. Contacts are linked to conversations, other people, and business context.
+
+## Adding a Contact
+
+Tell {{productName}} naturally:
+
+- "Add John Smith to my contacts — he's a potential client I met at the conference"
+- "Create a contact for sarah@acme.com, her name is Sarah Chen, she's the head of procurement at Acme"
+- "Add Hazel to contacts, phone +27747309676, she's a virtual assistant"
+
+{{productName}} will extract the details and confirm the record before saving.
+
+Required: first name and at least one of email or phone number. Everything else is optional but useful.
+
+## Looking Up a Contact
+
+Ask naturally:
+
+- "What do you know about John Smith?"
+- "Look up Sarah Chen"
+- "Find the contact from Acme procurement"
+- "Look up +27747309676"
+
+{{productName}} searches by name, email, phone number, or any detail you provide.
+
+## Updating a Contact
+
+Tell {{productName}} what changed:
+
+- "Update John Smith's email to john@newcompany.com"
+- "Add a note to Sarah Chen's record: prefers evening calls"
+- "John Smith is now at Horizon Capital, not Acme"
+
+## Listing Contacts
+
+- "List all my contacts"
+- "Show me everyone from Acme"
+- "Who are my contacts in fintech?"
+
+## Deleting a Contact
+
+To remove a single contact from the graph:
+
+- "Delete Dan from my contacts"
+- "Remove the duplicate contact for Sarah Chen"
+- "Delete the contact with email dan@example.com"
+
+{{productName}} will confirm which Person record matches, then remove the Person node and its direct relationships (e.g. links to conversations, other people) using a graph detach-delete. The contact is gone after confirmation — this cannot be undone.
+
+This is different from GDPR erasure (`contact-erase`). Deleting a contact removes the Person node from the graph only. GDPR erasure cascades across all data stores — access credentials, conversations, messages, and emails — to satisfy an Article 17 right-to-erasure request. Use "delete" for routine contact cleanup; use "erase all data" when fulfilling a data subject's erasure request.
+
+## The Waitlist
+
+For businesses using {{productName}}'s public agent: when a visitor expresses interest in signing up, the public agent collects their name and email in conversation. The waitlist plugin's scheduled extraction job processes these conversations and creates Person nodes with status `waitlist`.
+
+Each waitlist-extracted Person is linked to the source conversation two ways: as a scalar `sessionId` on the Person record (used by data exports) and as a `PARTICIPATES_IN` graph edge (used by the graph view). Both are set atomically when the extraction runs, so the Person appears on `/graph` next to the conversation they were extracted from rather than as a standalone dot.
+
+To review the waitlist: "Show me the waitlist" or "Who's on the waitlist?"
+
+## Exporting Contact Data (GDPR Subject Access)
+
+When a person requests a copy of all data held about them, ask {{productName}}:
+
+- "Export all data we hold on john@example.com"
+- "Show me everything we know about +447700900123"
+
+{{productName}} gathers the Person record, access credentials, conversation history, and emails into a single structured document. The output is self-contained — it can be handed directly to the data subject to satisfy an Article 15 request.
+
+## Erasing Contact Data (GDPR Right to Erasure)
+
+When a person requests deletion of all their data, ask {{productName}}:
+
+- "Delete all data we hold on john@example.com"
+- "Erase everything for Sarah Chen"
+
+{{productName}} first shows a preview of what would be deleted (counts per data type). Confirm the deletion to proceed. The erasure cascade covers:
+
+- The Person record itself
+- All access credentials (AccessGrant nodes)
+- Conversations and messages attributed to the contact
+- Emails sent to or from the contact's email address
+
+The deletion is permanent and irreversible. A receipt is returned listing exactly what was removed.
+
+Note: server logs may contain residual references to the contact's identifiers. Manual log review is recommended for complete erasure.
+
+## Stored Fields
+
+| Field | Description |
+|-------|-------------|
+| `givenName` | First name (required) |
+| `familyName` | Last name (optional) |
+| `email` | Email address (identifier — at least one of email or telephone required; used to deduplicate) |
+| `telephone` | Phone number (identifier — at least one of email or telephone required; used to deduplicate) |
+| `jobTitle` | Job title or role |
+| `source` | Where this contact came from (e.g. "public.maxy.bot", "telegram", "manual") |
+| `status` | Contact status (e.g. "active", "prospect", "waitlist") |
+| `createdOn` | When the record was created |