@rubytech/create-maxy-code 0.1.243 → 0.1.246
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/payload/platform/docs/superpowers/plans/2026-06-04-public-agent-knowledge-delivery.md +230 -0
- package/payload/platform/neo4j/schema.cypher +0 -5
- package/payload/platform/plugins/admin/mcp/dist/index.js +3 -4
- package/payload/platform/plugins/admin/mcp/dist/index.js.map +1 -1
- package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md +19 -22
- package/payload/platform/plugins/admin/skills/public-agent-manager/SKILL.md +38 -72
- package/payload/platform/plugins/cloudflare/.claude-plugin/plugin.json +1 -1
- package/payload/platform/plugins/cloudflare/PLUGIN.md +10 -7
- package/payload/platform/plugins/cloudflare/references/api.md +166 -0
- package/payload/platform/plugins/cloudflare/references/d1-data-capture.md +157 -0
- package/payload/platform/plugins/cloudflare/references/dashboard-guide.md +6 -6
- package/payload/platform/plugins/cloudflare/references/hosting-sites.md +66 -0
- package/payload/platform/plugins/cloudflare/references/manual-setup.md +5 -3
- package/payload/platform/plugins/cloudflare/skills/cloudflare/SKILL.md +72 -0
- package/payload/platform/plugins/docs/references/cloudflare.md +4 -4
- package/payload/platform/plugins/docs/references/deployment.md +1 -1
- package/payload/platform/plugins/docs/references/internals.md +3 -6
- package/payload/platform/plugins/memory/PLUGIN.md +2 -2
- package/payload/platform/scripts/setup-account.sh +16 -8
- package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/http-server.js +1 -32
- package/payload/platform/services/claude-session-manager/dist/http-server.js.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/jsonl-tail.d.ts +12 -0
- package/payload/platform/services/claude-session-manager/dist/jsonl-tail.d.ts.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/jsonl-tail.js +1 -1
- package/payload/platform/services/claude-session-manager/dist/jsonl-tail.js.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/pty-spawner.d.ts +7 -33
- package/payload/platform/services/claude-session-manager/dist/pty-spawner.d.ts.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/pty-spawner.js +150 -132
- package/payload/platform/services/claude-session-manager/dist/pty-spawner.js.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/system-prompt.d.ts +2 -1
- package/payload/platform/services/claude-session-manager/dist/system-prompt.d.ts.map +1 -1
- package/payload/platform/services/claude-session-manager/dist/system-prompt.js +39 -6
- package/payload/platform/services/claude-session-manager/dist/system-prompt.js.map +1 -1
- package/payload/platform/templates/agents/public/IDENTITY.md +9 -62
- package/payload/platform/templates/specialists/agents/personal-assistant.md +2 -2
- package/payload/server/{chunk-ZY6W3UA2.js → chunk-JMEX5NRX.js} +1 -22
- package/payload/server/maxy-edge.js +1 -1
- package/payload/server/server.js +7 -21
- package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md +0 -55
- package/payload/platform/templates/agents/public/SOUL.md +0 -19
- package/payload/platform/templates/agents/public/config.json +0 -9
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: platform-architecture
|
|
3
3
|
description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
|
|
4
|
-
content-hash: sha256:
|
|
4
|
+
content-hash: sha256:bff8fac482b70e56a1d4dd32167987663f0282ce43f4659d9c8c5cb592f77cd9
|
|
5
5
|
brand: maxy-code
|
|
6
6
|
product-name: Maxy
|
|
7
7
|
---
|
|
@@ -645,7 +645,7 @@ macOS is the lightweight surface. Compared with the Pi install, the macOS path d
|
|
|
645
645
|
|
|
646
646
|
- **No cgroup / resource decoupling.** Pi installs decouple Claude Code's cgroup from systemd's session scope so a closed VNC viewer cannot reap the long-running agent. macOS uses launchd, which is already per-user and does not have the same cleanup pathology, so the work is unnecessary.
|
|
647
647
|
- **No VNC.** The admin UI is the surface. You drive it from a browser on the same machine or any device on the LAN; there is no display server to bootstrap.
|
|
648
|
-
- **No `cloudflared` tunnel by default.** Pi installs ship a tunnel because the device is typically headless and on a residential network. On a Mac the LAN URL is usually enough; if you want a public URL, install `cloudflared` separately and run `cloudflared tunnel login` from the terminal.
|
|
648
|
+
- **No `cloudflared` tunnel by default.** Pi installs ship a tunnel because the device is typically headless and on a residential network. On a Mac the LAN URL is usually enough; if you want a public URL, install `cloudflared` separately and run `cloudflared tunnel login` from the terminal. The tunnel uses the CLI's interactive `tunnel login` flow; other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master.
|
|
649
649
|
|
|
650
650
|
## Smoke checklist
|
|
651
651
|
|
|
@@ -677,7 +677,7 @@ The doc is brand-aware. Examples use the default brand `maxy-code`; substitute `
|
|
|
677
677
|
- Raspberry Pi 5, 16GB RAM (canonical) — Pi 4 8GB works but the first install runs slower.
|
|
678
678
|
- Ubuntu Server 24.04 LTS, 64-bit, freshly imaged with Raspberry Pi Imager. Earlier Ubuntu / Pi OS releases are not part of the supported matrix.
|
|
679
679
|
- The pi has a wired or Wi-Fi route to the internet and an SSH-reachable user with sudo (the username does not matter — Rubytech images ship `admin` by default).
|
|
680
|
-
- A Cloudflare account whose dashboard you can sign into in a web browser.
|
|
680
|
+
- A Cloudflare account whose dashboard you can sign into in a web browser. The tunnel signs in via `cloudflared tunnel login` (OAuth, in the Pi's VNC browser after install); DNS/Pages/D1 use the Cloudflare API with a token the agent mints from a master token you provision once.
|
|
681
681
|
- A connected monitor or a working VNC viewer for the one-time `cloudflared tunnel login` step. After that step the Pi runs headless.
|
|
682
682
|
|
|
683
683
|
For Hetzner Cloud, see [hetzner.md](hetzner.md). The apt path, systemd user-service, and Cloudflare flow are the same; the difference is that a cloud VM has no physical display and no LAN to the operator, so the noVNC browser is reached over SSH port-forwarding for the one-time Cloudflare bootstrap.
|
|
@@ -749,9 +749,9 @@ The installer also wires `loginctl enable-linger <user>` so the user-service sur
|
|
|
749
749
|
|
|
750
750
|
## 4. Bootstrap the Cloudflare tunnel
|
|
751
751
|
|
|
752
|
-
The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare auth happens once, interactively, in a browser the operator drives.
|
|
752
|
+
The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare tunnel auth happens once, interactively, in a browser the operator drives. The tunnel's only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success. Other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master — see the `cloudflare` plugin.
|
|
753
753
|
|
|
754
|
-
Open the Pi's VNC browser at `http://<hostname>.local:<port>/vnc` (or over the LAN at whichever port the install log printed for noVNC). In the chat surface, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `
|
|
754
|
+
Open the Pi's VNC browser at `http://<hostname>.local:<port>/vnc` (or over the LAN at whichever port the install log printed for noVNC). In the chat surface, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `cloudflare` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the VNC browser and authorises the cert against the right Cloudflare account.
|
|
755
755
|
|
|
756
756
|
Setup is done when, and only when, `curl -I https://<hostname>.<your-zone>` issued from outside the local network returns `HTTP/2 200`. No state file, no `tunnel run` exit code, and no "service is active" claim substitutes for the live HTTPS response.
|
|
757
757
|
|
|
@@ -798,7 +798,7 @@ npx -y @rubytech/create-realagent-code@latest --uninstall
|
|
|
798
798
|
## What this install does not do
|
|
799
799
|
|
|
800
800
|
- **No SCP / rsync.** The Pi is reached over npm only. Updates are `npx -y @rubytech/create-maxy-code@latest …` again, never a file push from the operator's laptop.
|
|
801
|
-
- **
|
|
801
|
+
- **Tunnel auth is OAuth; the API is permitted for the rest.** The tunnel's only auth path is `cloudflared tunnel login` in the Pi's VNC browser. DNS, Pages, and D1 use the Cloudflare API with a short-lived narrow token the agent mints from an operator-provisioned master token (see the `cloudflare` plugin); tokens are never written to a project tree or echoed.
|
|
802
802
|
- **No shared state across brands.** Two brands on one Pi each have their own Neo4j port, systemd unit, VNC display, websockify port, tunnel, and persist directory. They do not share DNS, ports, or filesystem state.
|
|
803
803
|
|
|
804
804
|
## Smoke checklist
|
|
@@ -807,7 +807,7 @@ Fresh-Pi smoke pass criteria:
|
|
|
807
807
|
|
|
808
808
|
1. Install on a clean Ubuntu Server 24.04 image with no prior Maxy footprint completes, prints a LAN URL, and the systemd user-service is `active (running)`.
|
|
809
809
|
2. The LAN URL `http://<hostname>.local:<port>` opens the admin UI and the chat surface is interactive.
|
|
810
|
-
3. Cloudflare setup driven by the `cloudflare` plugin's `
|
|
810
|
+
3. Cloudflare setup driven by the `cloudflare` plugin's `cloudflare` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from outside the LAN.
|
|
811
811
|
4. Reboot — both URLs are reachable again after boot without any manual action.
|
|
812
812
|
5. Install a second brand with a different `--hostname`; both brands' admin UIs are reachable on their own ports / public URLs and neither has touched the other's state.
|
|
813
813
|
6. Uninstall removes the systemd unit, the Avahi service file, and the persist directory.
|
|
@@ -949,9 +949,9 @@ After the Cloudflare tunnel is provisioned, close the SSH session — every surf
|
|
|
949
949
|
|
|
950
950
|
## 5. Bootstrap the Cloudflare tunnel
|
|
951
951
|
|
|
952
|
-
The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare auth happens once, interactively, in the noVNC browser the operator drives over the SSH forward from step 4.
|
|
952
|
+
The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare tunnel auth happens once, interactively, in the noVNC browser the operator drives over the SSH forward from step 4. The tunnel's only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success. Other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master — see the `cloudflare` plugin.
|
|
953
953
|
|
|
954
|
-
In the noVNC browser session, open the admin UI at `http://localhost:<port>`. In chat, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `
|
|
954
|
+
In the noVNC browser session, open the admin UI at `http://localhost:<port>`. In chat, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `cloudflare` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the noVNC browser and authorises the cert against the right Cloudflare account.
|
|
955
955
|
|
|
956
956
|
Setup is done when, and only when, `curl -I https://<hostname>.<your-zone>` issued from the operator's laptop returns `HTTP/2 200`. No state file, no `tunnel run` exit code, and no "service is active" claim substitutes for the live HTTPS response.
|
|
957
957
|
|
|
@@ -993,7 +993,7 @@ npx -y @rubytech/create-realagent-code@latest --uninstall
|
|
|
993
993
|
## What this install does not do
|
|
994
994
|
|
|
995
995
|
- **No SCP / rsync.** Updates are `npx -y @rubytech/create-maxy-code@latest …` again, never a file push from the operator's laptop.
|
|
996
|
-
- **
|
|
996
|
+
- **Tunnel auth is OAuth; the API is permitted for the rest.** The tunnel's only auth path is `cloudflared tunnel login` in the noVNC browser over SSH forward. DNS, Pages, and D1 use the Cloudflare API with a short-lived narrow token the agent mints from an operator-provisioned master token (see the `cloudflare` plugin).
|
|
997
997
|
- **No shared state across brands.** Two brands on one server each have their own Neo4j port, systemd unit, VNC display, websockify port, tunnel, and persist directory.
|
|
998
998
|
- **No public IPv4 exposure.** The Hetzner firewall opens port 22 only; every operator-facing surface is fronted by the Cloudflare tunnel.
|
|
999
999
|
|
|
@@ -1004,7 +1004,7 @@ Fresh-Hetzner smoke pass criteria:
|
|
|
1004
1004
|
1. Provision a CAX31 with Ubuntu 24.04 arm64 and an SSH key; SSH in as `root`, create `admin`, switch.
|
|
1005
1005
|
2. Install completes on the clean image, prints a loopback URL, and the systemd user-service is `active (running)`.
|
|
1006
1006
|
3. The noVNC page reached over `ssh -L 8080:localhost:<novnc-port>` displays the admin UI.
|
|
1007
|
-
4. Cloudflare setup driven by the `cloudflare` plugin's `
|
|
1007
|
+
4. Cloudflare setup driven by the `cloudflare` plugin's `cloudflare` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from the operator's laptop.
|
|
1008
1008
|
5. Reboot the server; both `<hostname>.service` and `<hostname>-cloudflared.service` come back up; the public URL is reachable again without any manual action.
|
|
1009
1009
|
6. Install a second brand with a different `--hostname`; both brands' admin UIs are reachable on their own public hostnames and neither has touched the other's state.
|
|
1010
1010
|
7. Uninstall removes the systemd unit and the persist directory.
|
|
@@ -1017,7 +1017,7 @@ Source: https://docs.getmaxy.com/cloudflare.md
|
|
|
1017
1017
|
|
|
1018
1018
|
# Cloudflare Tunnel — the dashboard is the source of truth
|
|
1019
1019
|
|
|
1020
|
-
Each installation has its own Cloudflare account.
|
|
1020
|
+
Each installation has its own Cloudflare account. The **tunnel** sign-in is OAuth: the agent invokes `cloudflared tunnel login` via Bash; the Cloudflare Authorize URL streams into the admin chat PTY and the native terminal renders it as a clickable link. Click it, authorise in your own browser, and `cloudflared` writes `cert.pem` to the brand's config directory. For **everything else** (DNS, Pages, D1, Access) the agent uses the Cloudflare API, authenticated by a short-lived narrow token it mints from a master token you provision once in the dashboard (an advanced step the agent never automates). Some account-side jobs — adding a domain, switching accounts — are still easiest in your browser, and the agent relays those click-paths; the rest it can do directly via the API.
|
|
1021
1021
|
|
|
1022
1022
|
## Identity model
|
|
1023
1023
|
|
|
@@ -1025,10 +1025,10 @@ Each installation has its own Cloudflare account. Sign-in is OAuth: the agent in
|
|
|
1025
1025
|
|------|--------|
|
|
1026
1026
|
| **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
|
|
1027
1027
|
| **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
|
|
1028
|
-
| **Domain scope** (which zones the operator can route) |
|
|
1028
|
+
| **Domain scope** (which zones the operator can route) | The operator picks the zone in the dashboard during OAuth or names it in chat; the agent can also enumerate zones via the API with a minted read-scoped token. |
|
|
1029
1029
|
| **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `alias-domains.json`. |
|
|
1030
1030
|
|
|
1031
|
-
|
|
1031
|
+
Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
|
|
1032
1032
|
|
|
1033
1033
|
## Setup flow
|
|
1034
1034
|
|
|
@@ -1114,7 +1114,7 @@ The most common cause is wrong nameservers on the domain. The domain must use Cl
|
|
|
1114
1114
|
|
|
1115
1115
|
**Does:** invokes `cloudflared` directly via Bash, following `plugins/cloudflare/references/manual-setup.md` step by step; quotes click-paths from the reference files verbatim; verifies external reachability with `curl -I` and surfaces the response.
|
|
1116
1116
|
|
|
1117
|
-
**Does not:** drive the Cloudflare dashboard via Playwright, synthesise alternative `cloudflared` flag sequences not in the runbook,
|
|
1117
|
+
**Does not:** drive the Cloudflare dashboard via Playwright, browser-automate master-token creation, synthesise alternative `cloudflared` flag sequences not in the runbook, write or echo any API token, write or edit `cert.pem` / `config.yml` directly outside the runbook's instructions.
|
|
1118
1118
|
|
|
1119
1119
|
When a command fails, the agent reports the failure and cites the relevant recovery step. It does not improvise.
|
|
1120
1120
|
|
|
@@ -2907,7 +2907,7 @@ When `search` is true and `query` is non-null, the rewritten query replaces the
|
|
|
2907
2907
|
|
|
2908
2908
|
### Knowledge retrieval gate
|
|
2909
2909
|
|
|
2910
|
-
|
|
2910
|
+
The public agent is toolless by construction (Task 615): it has no `memory-search`, no graph access mid-turn, and no tools of any kind. KNOWLEDGE.md (when present) plus SOUL are assembled into the agent's system prompt at spawn time and are the entire knowledge surface. Every `role=public` spawn (webchat, whatsapp, telegram) resolves an empty allowlist and runs in `dontAsk` (Task 506) with a per-spawn `permissions.deny` covering every native, harness, and memory-MCP tool (Task 612). The spawner anchors the empty allowlist with a single non-native deny-basis token (`mcp__none__deny-basis`) so `--allowed-tools` is always present and native-excluding (Task 609) — without it, `dontAsk` would have nothing to deny against and the brand `allow:["*"]` would re-open native tools.
|
|
2911
2911
|
|
|
2912
2912
|
### Observability
|
|
2913
2913
|
|
|
@@ -3024,10 +3024,7 @@ The final step in the retrieval pipeline is injecting retrieved content into the
|
|
|
3024
3024
|
|
|
3025
3025
|
Public agents run on the same native Claude Code PTY surface as the admin, dispatched through the channel PTY-bridge with `role: 'public'`. The agent's directory files (IDENTITY.md, SOUL.md, KNOWLEDGE.md, KNOWLEDGE-SUMMARY.md when present) are assembled into the system prompt at spawn time. There is no per-turn server-side knowledge injection.
|
|
3026
3026
|
|
|
3027
|
-
|
|
3028
|
-
|
|
3029
|
-
- **`liveMemory: false`** — `memory-search` is excluded from the per-spawn `--allowed-tools` allowlist. The agent has no graph access mid-conversation; KNOWLEDGE.md is the ceiling of factual knowledge.
|
|
3030
|
-
- **`liveMemory: true`** — `memory-search` is in the allowlist. The agent decides at message time whether to call it; reads run against the graph with `ALLOWED_SCOPES=public` so only public-scoped nodes return. KNOWLEDGE.md and the live `memory-search` surface are complementary — the baked file covers evergreen facts; the live tool covers the long-tail public-scoped lookups.
|
|
3027
|
+
The public agent is toolless by construction (Task 615): `memory-search` and every other tool are excluded from the per-spawn `--allowed-tools` allowlist on every public channel, and a per-spawn `permissions.deny` blocks them outright (Task 612). The agent has no graph access mid-conversation; KNOWLEDGE.md is the ceiling of factual knowledge.
|
|
3031
3028
|
|
|
3032
3029
|
### KNOWLEDGE.md staleness guard
|
|
3033
3030
|
|
|
@@ -3131,7 +3128,7 @@ The SDK's per-tool override is `_meta["anthropic/alwaysLoad"]: true` on each MCP
|
|
|
3131
3128
|
|
|
3132
3129
|
Each `claude` PTY spawn registers every callable MCP server and every dispatchable subagent before the operator's first turn. **Platform MCP servers come from one channel — installed plugins — for admin and specialist spawns (Task 502).** Claude Code's plugin system serves every plugin MCP tool under the long prefix `mcp__plugin_<plugin>_<server>__<tool>` (for platform plugins `plugin == server == directory`), which is the canonical name the admin `--allowed-tools` argv and every specialist `tools:` frontmatter bind to. Admin spawns no longer write a per-spawn `.mcp.json` or pass `--mcp-config`; the per-account env (`ACCOUNT_ID`, `USER_ID`, `NEO4J_URI`, `NEO4J_PASSWORD`, `PLATFORM_ROOT`, `CLAUDE_CONFIG_DIR`) rides the PTY env block.
|
|
3133
3130
|
|
|
3134
|
-
**Public agents are the one exception.** A public-facing web agent
|
|
3131
|
+
**Public agents are the one exception.** A public-facing web agent is toolless by construction (Task 615), so public spawns retain the per-spawn `mcp-config.json` (`--mcp-config <path>`) but register **zero** servers in it — the file carries an empty `mcpServers`. Combined with the empty `--allowed-tools`, the `dontAsk` mode, and the per-spawn `permissions.deny` (Task 612), no tool reaches an anonymous visitor on any channel. `--strict-mcp-config` (which only ever guarded auto-discovery of a project `.mcp.json`) is retained on the public per-spawn path so no project file is discovered either; it is dropped from admin spawns that no longer pass `--mcp-config`.
|
|
3135
3132
|
|
|
3136
3133
|
For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents directory (`platform/plugins/*/agents/`, `premium-plugins/*/agents/`) — both roles — plus the per-account specialists directory `<accountDir>/specialists/agents/` (admin only). Claude Code's `subagent_type` dispatch reads the agent file off disk via the added directories; without `--add-dir` the dispatcher returns "no matching agent."
|
|
3137
3134
|
|
|
@@ -3284,7 +3281,7 @@ Grep for both in `~/.<brand>/logs/install-*.log`. Absence after a clean install
|
|
|
3284
3281
|
|
|
3285
3282
|
The first user-domain write the agent attempts (e.g. recording who the operator is) hits the graph-write gate's `Write blocked (no-admin-user)` or `Write blocked (no-local-business)` error. The agent then asks the persona question, persists the answer through the `business-profile` skill or `profile-update.personFields`, and proceeds. The error itself is the signal — grep `Write blocked` in `~/.<brand>/logs/server.log` to confirm.
|
|
3286
3283
|
|
|
3287
|
-
Cloudflare, WhatsApp, Telegram, and any other dormant capability surfaces on owner request via the `<dormant-plugins>` sentinel the manager injects per-spawn. Execution is the existing plugin skill (`cloudflare:
|
|
3284
|
+
Cloudflare, WhatsApp, Telegram, and any other dormant capability surfaces on owner request via the `<dormant-plugins>` sentinel the manager injects per-spawn. Execution is the existing plugin skill (`cloudflare:cloudflare`, etc.) — no banner, no per-step flag.
|
|
3288
3285
|
|
|
3289
3286
|
### Per-spawn system-prompt sentinels
|
|
3290
3287
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Public Agent Manager
|
|
2
2
|
|
|
3
|
-
Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge,
|
|
3
|
+
Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge, and model.
|
|
4
4
|
|
|
5
5
|
## Agent Directory Structure
|
|
6
6
|
|
|
@@ -8,13 +8,15 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
|
|
|
8
8
|
|
|
9
9
|
| File | Purpose | Required |
|
|
10
10
|
|------|---------|----------|
|
|
11
|
-
| `config.json` | Model,
|
|
12
|
-
| `IDENTITY.md` | Boundaries, behavioural rules | Yes |
|
|
13
|
-
| `SOUL.md` | Personality
|
|
14
|
-
| `KNOWLEDGE.md` |
|
|
11
|
+
| `config.json` | Model, display name, status, image identity, knowledge keywords | Yes |
|
|
12
|
+
| `IDENTITY.md` | Boundaries, behavioural rules — copied verbatim from the Rubytech template | Yes |
|
|
13
|
+
| `SOUL.md` | Personality and role — tone, voice, warmth, greeting; plus the agent's job: give basic public info and capture the visitor's contact details for human follow-up (the chat equivalent of the landing-page contact form) | Yes |
|
|
14
|
+
| `KNOWLEDGE.md` | The business's public-facing facts at landing-page detail — pricing, FAQs, services | Yes |
|
|
15
15
|
| `KNOWLEDGE-SUMMARY.md` | Auto-generated summary when KNOWLEDGE.md exceeds context budget | No |
|
|
16
16
|
| `assets/` | Per-agent images (logo, avatar, icon) | No |
|
|
17
17
|
|
|
18
|
+
`SOUL.md` and `KNOWLEDGE.md` are authored entirely client-side by you at agent creation and must be **non-empty before the agent goes active** — a public spawn whose SOUL or KNOWLEDGE is empty or missing is refused at spawn (the visitor sees an unavailable state, never a dud agent), so neither ships as a template nor is seeded by the installer. `IDENTITY.md` is copied verbatim from the Rubytech-controlled template, never drafted.
|
|
19
|
+
|
|
18
20
|
## Slug Rules
|
|
19
21
|
|
|
20
22
|
- Lowercase a-z, 0-9, hyphens only
|
|
@@ -29,9 +31,7 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
|
|
|
29
31
|
"slug": "sales",
|
|
30
32
|
"displayName": "Sales Agent",
|
|
31
33
|
"model": "claude-haiku-4-5",
|
|
32
|
-
"plugins": ["sales"],
|
|
33
34
|
"status": "active",
|
|
34
|
-
"liveMemory": false,
|
|
35
35
|
"knowledgeKeywords": [],
|
|
36
36
|
"image": "/agent-assets/sales/agent-image.png",
|
|
37
37
|
"imageShape": "circle",
|
|
@@ -39,11 +39,9 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
|
|
|
39
39
|
}
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
###
|
|
43
|
-
|
|
44
|
-
Controls whether the public agent gets `memory-search` at message time. When `true`, the per-spawn `--allowed-tools` allowlist includes `memory-search` so the agent can hit the graph during a turn — scoped to `scope: "public"` nodes via `ALLOWED_SCOPES=public` on the spawn env. When `false` (default), the agent runs with only the baked KNOWLEDGE.md and has no graph access mid-conversation.
|
|
42
|
+
### Toolless by construction
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
The public agent has no tools (Task 615). It cannot search the graph, read files, run commands, or load skills mid-conversation. Everything it knows is the KNOWLEDGE.md and SOUL assembled into its system prompt at spawn time. There is no operator toggle for this — it is the fixed posture for every public agent on every channel. If the agent needs to surface graph content created after deployment, refresh its KNOWLEDGE.md (see Update knowledge below); the agent itself never reaches the live graph.
|
|
47
45
|
|
|
48
46
|
### knowledgeKeywords
|
|
49
47
|
|
|
@@ -61,7 +59,7 @@ An optional image (avatar, icon, or logo) displayed in the public chat header in
|
|
|
61
59
|
|
|
62
60
|
**Fallback chain:** agent image → account brand logo → platform default icon. When no image is configured, the existing brand logo behaviour is preserved.
|
|
63
61
|
|
|
64
|
-
During creation (Step
|
|
62
|
+
During creation (Step 6) and editing, offer image upload when the user has an image ready. Use the `agent-image` tool with `action: "set"`, providing the file path and the appropriate shape. If the user wants the agent's name shown in the header, set `showAgentName: true` in config.json.
|
|
65
63
|
|
|
66
64
|
### Knowledge Tagging
|
|
67
65
|
|
|
@@ -79,50 +77,23 @@ Present as a `select` field within the agent configuration `form` during creatio
|
|
|
79
77
|
| Sonnet | `claude-sonnet-4-6` | Balanced. Nuanced conversation, qualification, support. | Standard |
|
|
80
78
|
| Opus | `claude-opus-4-7` | Maximum intelligence. Complex sales, consultative selling. | Premium |
|
|
81
79
|
|
|
82
|
-
### Plugin Selection
|
|
83
|
-
|
|
84
|
-
Present available plugins as a `multi-select` component. Selected plugin names are stored in `config.json`. The platform filters embedded plugins per-agent at runtime — only plugins whose `metadata.platform.embed` includes `"public"` are actually embedded.
|
|
85
|
-
|
|
86
|
-
Only present plugins from the curated list below. Before presenting, verify each plugin's directory exists under `$PLATFORM_ROOT/plugins/` (premium plugins are only available when delivered). Omit any plugin whose directory is absent.
|
|
87
|
-
|
|
88
|
-
**Core (always available):**
|
|
89
|
-
|
|
90
|
-
| Plugin | Description |
|
|
91
|
-
|--------|-------------|
|
|
92
|
-
| `sales` | Buying signal detection, closing techniques, objection handling |
|
|
93
|
-
| `docs` | User guide and platform documentation |
|
|
94
|
-
|
|
95
|
-
**Premium — Real Agent (only when delivered):**
|
|
96
|
-
|
|
97
|
-
| Plugin | Description |
|
|
98
|
-
|--------|-------------|
|
|
99
|
-
| `buyers` | Buyer enquiry handling and educational guides |
|
|
100
|
-
| `estate-coaching` | Agent coaching and performance development |
|
|
101
|
-
| `estate-sales` | Real estate sales methodology |
|
|
102
|
-
| `estate-teaching` | Training and educational content |
|
|
103
|
-
|
|
104
80
|
## SOUL.md Scope Enforcement
|
|
105
81
|
|
|
106
|
-
SOUL.md is
|
|
82
|
+
SOUL.md is personality and role. When the user provides content for SOUL.md, route content that belongs elsewhere to the correct file:
|
|
107
83
|
|
|
108
84
|
- **Facts, pricing, services, FAQs** → KNOWLEDGE.md
|
|
109
|
-
- **Engagement
|
|
110
|
-
- **Boundaries
|
|
85
|
+
- **Engagement and qualification — how the agent draws out what the visitor needs and captures their contact details for human follow-up** → SOUL.md (this is the agent's role; the public agent is toolless, so there are no plugins to embed)
|
|
86
|
+
- **Boundaries and procedural rules** → IDENTITY.md (Rubytech-controlled and copied verbatim — the agent's hard limits live there, not in SOUL)
|
|
111
87
|
|
|
112
|
-
SOUL.md answers "what does this agent feel like to talk to?" — tone, warmth, formality,
|
|
88
|
+
SOUL.md answers "what does this agent feel like to talk to, and what is it here to do?" — tone, warmth, formality, greeting, and the role of giving basic public info and capturing contact details. SOUL.md must not restate constraints from IDENTITY.md. When user-provided content could belong to either file, apply this test: "does this restrict what the agent does?" → IDENTITY.md. "Does this describe how the agent sounds?" → SOUL.md. If content does both (e.g. "always respond politely"), route to SOUL — the constraint is a consequence of tone, not an operational boundary. Present SOUL.md via `document-editor` for the user to review and approve. Follow the document-editor encoding constraint in IDENTITY.md when generating content.
|
|
113
89
|
|
|
114
90
|
## KNOWLEDGE.md Population
|
|
115
91
|
|
|
116
92
|
KNOWLEDGE.md is the public agent's baked, static knowledge surface — the facts the agent should always have on hand without a tool call. It is assembled into the system prompt at invocation time.
|
|
117
93
|
|
|
118
|
-
Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. The agent
|
|
119
|
-
|
|
120
|
-
- **`liveMemory: false`** — KNOWLEDGE.md is the agent's only knowledge source. No graph access mid-conversation. Every gap in KNOWLEDGE.md is a question the agent cannot answer.
|
|
121
|
-
- **`liveMemory: true`** — KNOWLEDGE.md remains the baked, evergreen surface, and `memory-search` is also in the allowlist so the agent can hit the graph at message time. The memory MCP server runs with `ALLOWED_SCOPES=public` so only `scope: "public"` nodes come back; anything not marked public is invisible regardless of how the agent queries.
|
|
122
|
-
|
|
123
|
-
When `liveMemory: true`, treat KNOWLEDGE.md and `memory-search` as complementary, not alternatives. KNOWLEDGE.md owns the agent's evergreen facts (pricing, services, FAQs, contact info). `memory-search` is for the long-tail, public-scoped lookups the agent reaches for during a conversation (a named listing, a specific person, a current availability slot).
|
|
94
|
+
Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. The public agent is toolless (Task 615): KNOWLEDGE.md is its **only** knowledge source. There is no graph access mid-conversation. Every gap in KNOWLEDGE.md is a question the agent cannot answer, so the KNOWLEDGE.md you build below is the whole of what the agent will know — populate it thoroughly.
|
|
124
95
|
|
|
125
|
-
All `memory-search` queries for knowledge population use admin permissions — do not pass `agentSlug`. The `agentSlug` parameter is a runtime enforcement mechanism for the public agent's MCP server, not an admin-time discovery tool. At creation time, the agent may have zero tagged nodes — searching with `agentSlug` would return nothing.
|
|
96
|
+
The `memory-search` calls described below are **your** admin-time tool for populating KNOWLEDGE.md, not something the public agent ever runs. All `memory-search` queries for knowledge population use admin permissions — do not pass `agentSlug`. The `agentSlug` parameter is a runtime enforcement mechanism for the public agent's MCP server, not an admin-time discovery tool. At creation time, the agent may have zero tagged nodes — searching with `agentSlug` would return nothing.
|
|
126
97
|
|
|
127
98
|
Query `memory-search` multiple times with targeted terms across all categories relevant to the agent's role. A single broad query will miss knowledge stored under specific labels or entity types. Common categories:
|
|
128
99
|
|
|
@@ -144,10 +115,9 @@ The system prompt must leave room for conversation. After assembling all files,
|
|
|
144
115
|
```
|
|
145
116
|
IDENTITY.md: 800 tokens
|
|
146
117
|
SOUL.md: 400 tokens
|
|
147
|
-
sales plugin: 2,100 tokens
|
|
148
118
|
KNOWLEDGE.md: 8,200 tokens
|
|
149
119
|
─────────────────────────
|
|
150
|
-
Total:
|
|
120
|
+
Total: 9,400 / 40,000 (24%)
|
|
151
121
|
```
|
|
152
122
|
|
|
153
123
|
Warn if total exceeds 50% of the model's context window.
|
|
@@ -156,7 +126,7 @@ Warn if total exceeds 50% of the model's context window.
|
|
|
156
126
|
|
|
157
127
|
### Create from Template
|
|
158
128
|
|
|
159
|
-
When template context is provided (a path to a template directory containing `template.json
|
|
129
|
+
When template context is provided (a path to a template directory containing `template.json` and a `SOUL.md` seed), the Create operation pre-populates its steps from the template. The user reviews and approves every file — the template is a starting point, not an automatic deployment.
|
|
160
130
|
|
|
161
131
|
Read the template's `template.json` and seed files. If `template.json` is unreadable or missing required fields (`suggestedSlug`, `displayName`), report the error and fall back to the standard Create flow.
|
|
162
132
|
|
|
@@ -164,12 +134,11 @@ The following Create steps are modified when a template is provided:
|
|
|
164
134
|
|
|
165
135
|
- **Step 1** — use `suggestedSlug` from `template.json` as the initial slug. If an agent already exists at that slug, ask the user to choose a different name.
|
|
166
136
|
- **Step 2** — skip. The agent name and role come from `template.json` `displayName` and `description`.
|
|
167
|
-
- **Step
|
|
168
|
-
- **Step 5** — present the template's `
|
|
169
|
-
- **Step 6** —
|
|
170
|
-
- **Step 7** — pre-populate form defaults: `model` from `template.json` (or `claude-haiku-4-5` if absent), `liveMemory` from `template.json` (or `false`), `knowledgeKeywords` from `template.json` (or empty).
|
|
137
|
+
- **Step 4** — unchanged: `IDENTITY.md` is always the Rubytech-controlled template copied verbatim, never the agent template's own identity.
|
|
138
|
+
- **Step 5** — present the template's `SOUL.md` content via `document-editor` instead of drafting from conversation. The user can edit before approving.
|
|
139
|
+
- **Step 6** — pre-populate form defaults: `model` from `template.json` (or `claude-haiku-4-5` if absent), `knowledgeKeywords` from `template.json` (or empty).
|
|
171
140
|
|
|
172
|
-
All other steps (
|
|
141
|
+
All other steps (3, 7-12) proceed identically — knowledge discovery, direct tagging, KNOWLEDGE.md generation, config write, budget check, and confirmation are unchanged.
|
|
173
142
|
|
|
174
143
|
After creation, no template metadata persists in the agent's files. The resulting agent is indistinguishable from one created manually. The user owns it completely.
|
|
175
144
|
|
|
@@ -177,12 +146,10 @@ After creation, no template metadata persists in the agent's files. The resultin
|
|
|
177
146
|
|
|
178
147
|
1. **Pre-creation check** — verify the target directory (`agents/{slug}/`) does not exist or is empty before proceeding. If remnant files exist from a prior incomplete deletion, flag the issue to the user: show what files remain and offer to clean them up before starting fresh. Do not silently inherit stale files — a leftover `config.json` from a previous agent would bypass the creation gate.
|
|
179
148
|
2. Ask for the agent's name (becomes the slug) and role description
|
|
180
|
-
3. Present available
|
|
181
|
-
4. **
|
|
182
|
-
5. Present `
|
|
183
|
-
6. Present
|
|
184
|
-
7. Present agent configuration via a single `form` component with these fields:
|
|
185
|
-
- `liveMemory` (`checkbox`): label "Live memory", description explaining the trade-off — when on, the agent can call `memory-search` mid-turn against public-scoped graph content; leave off if KNOWLEDGE.md fully covers the agent's role
|
|
149
|
+
3. **Knowledge discovery** — search the graph with admin permissions (no `agentSlug` — the agent doesn't exist yet) to find available knowledge. Present available content grouped by category for the user to select.
|
|
150
|
+
4. **Install `IDENTITY.md`** — copy the Rubytech-controlled template verbatim to `agents/{slug}/IDENTITY.md`. It is fixed (the toolless public directive — Task 615) and is never drafted, edited, or presented for review.
|
|
151
|
+
5. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality and role from user conversation — tone plus the job of giving basic public info and capturing the visitor's contact details). Write on approval. Must be non-empty; an empty SOUL is refused at spawn.
|
|
152
|
+
6. Present agent configuration via a single `form` component with these fields:
|
|
186
153
|
- `knowledgeKeywords` (`text`): label "Knowledge keywords (max 5, comma-separated)", placeholder with examples relevant to the agent's role
|
|
187
154
|
- `model` (`select`): label "Model", options with descriptions:
|
|
188
155
|
- `claude-haiku-4-5` — "Haiku — Fast, cost-effective. FAQ, routing, high-volume."
|
|
@@ -192,30 +159,30 @@ After creation, no template metadata persists in the agent's files. The resultin
|
|
|
192
159
|
The `model` field should have a `defaultValue` of `"claude-haiku-4-5"`.
|
|
193
160
|
Wait for the user's response before proceeding.
|
|
194
161
|
After the form is submitted, ask the user if they have an image (avatar, icon, or logo) for the agent. If yes, ask the user to provide the file and select the shape (circle for avatars/icons, rounded for logos), then use the `agent-image` tool to upload it.
|
|
195
|
-
|
|
162
|
+
7. **Direct slug tagging (optional, gated)** — keyword subscriptions (configured in Step 6) and direct slug tagging are independent routing mechanisms. Keyword subscriptions route content by topic — any matching node is visible, now or in the future. Direct slug tagging routes specific nodes by identity — only explicitly tagged nodes are visible via the slug search path. Neither implies the other.
|
|
196
163
|
|
|
197
164
|
Ask the user whether any specific knowledge nodes should be tagged with this agent's slug. Explain that direct tagging makes specific nodes always visible to this agent regardless of keyword matches, and is useful for content that doesn't match any keyword but should still be available. If keyword subscriptions already cover the desired content, tagging is unnecessary.
|
|
198
165
|
|
|
199
|
-
- If the user approves: present the knowledge discovery results from Step
|
|
166
|
+
- If the user approves: present the knowledge discovery results from Step 3 for selection, read each node's current `agents` array first, and confirm the new slug-tag set with the user. The recorder folds the slug onto each node's `agents` array in its next turn.
|
|
200
167
|
- If the user declines: skip tagging entirely. Do not propose tagging without explicit approval.
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
168
|
+
8. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow. KNOWLEDGE.md is required and must be non-empty; an empty or missing KNOWLEDGE is refused at spawn.
|
|
169
|
+
9. Write `config.json` with selected model, status "active", and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
|
|
170
|
+
10. Check context budget — auto-summarise if over threshold
|
|
171
|
+
11. **Project the agent into the graph** — delegate to the `specialists:database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
|
|
172
|
+
12. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
|
|
206
173
|
|
|
207
174
|
### List
|
|
208
175
|
|
|
209
176
|
Read `defaultAgent` from `account-manage` to identify the current default. Read all directories under `agents/`. For each, read `config.json` and estimate total token budget. Present as a structured summary, marking the default agent:
|
|
210
177
|
|
|
211
178
|
**sales** — Sonnet Standard * default
|
|
212
|
-
|
|
179
|
+
11,500 / 200,000 tokens (6%) · active
|
|
213
180
|
|
|
214
181
|
**support** — Haiku Low cost
|
|
215
|
-
|
|
182
|
+
3,200 / 40,000 tokens (8%) · active
|
|
216
183
|
|
|
217
184
|
**public** — Haiku Low cost
|
|
218
|
-
|
|
185
|
+
9,800 / 40,000 tokens (25%) · active
|
|
219
186
|
|
|
220
187
|
### Clone
|
|
221
188
|
|
|
@@ -235,10 +202,9 @@ For knowledge scope changes:
|
|
|
235
202
|
- Show currently tagged nodes (search `memory-search` without `agentSlug`, identify results whose `agents` property contains the agent's slug) and active keyword subscriptions (from `config.json`).
|
|
236
203
|
- Allow adding/removing direct tags. Read each node's current `agents` array first, confirm the change with the operator, and the recorder updates the arrays in its next turn.
|
|
237
204
|
- Allow adding/removing keyword subscriptions (update `knowledgeKeywords` in `config.json`).
|
|
238
|
-
- Allow toggling `liveMemory` on/off (update `config.json`).
|
|
239
205
|
- After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
|
|
240
206
|
|
|
241
|
-
**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `
|
|
207
|
+
**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `knowledgeKeywords` or direct-tag mutations), delegate to `specialists:database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
|
|
242
208
|
|
|
243
209
|
### Delete
|
|
244
210
|
|
|
@@ -274,7 +240,7 @@ Invoke the agent with `[New session. Greet the visitor.]` and stream the respons
|
|
|
274
240
|
|
|
275
241
|
## Runtime Surface
|
|
276
242
|
|
|
277
|
-
Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. They
|
|
243
|
+
Public agents run on the same native Claude Code PTY as the admin, dispatched via `dispatchOnce` with `role: 'public'`. They are toolless by construction (Task 615): no filesystem access, no MCP tools, no subagents, no `memory-search`. Every public spawn resolves an empty `--allowed-tools`, runs in `dontAsk`, and carries a per-spawn `permissions.deny` covering every native, harness, and memory-MCP tool on every channel. Everything the agent needs to say comes from its directory files (IDENTITY.md, SOUL.md, KNOWLEDGE.md) assembled into the system prompt at invocation time — nothing else is reachable.
|
|
278
244
|
|
|
279
245
|
## URL Routing
|
|
280
246
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudflare",
|
|
3
|
-
"description": "Cloudflare
|
|
3
|
+
"description": "Cloudflare operations — tunnel setup/reset, DNS, Pages hosting, D1 data capture, and dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, calling the Cloudflare API with a minted narrow token, or quoting a dashboard click-path the operator performs themselves.",
|
|
4
4
|
"version": "0.1.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Rubytech LLC"
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: cloudflare
|
|
3
|
-
description: Cloudflare
|
|
3
|
+
description: Cloudflare operations — tunnel setup/reset, DNS, Pages hosting, D1 data capture, and dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, calling the Cloudflare API with a minted narrow token, or quoting a dashboard click-path the operator performs themselves.
|
|
4
4
|
tools: []
|
|
5
5
|
mcp-manifest: skip
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Cloudflare Tunnel
|
|
9
9
|
|
|
10
|
-
Each installation has its own Cloudflare account.
|
|
10
|
+
Each installation has its own Cloudflare account. Two auth paths serve two operation classes. **Tunnel** auth is OAuth: the operator signs in via `cloudflared tunnel login` (issued by the agent through Bash); `cloudflared` writes `cert.pem` to the brand-scoped config directory. **API** auth (DNS, zones, Pages, D1, Access, token mint) is the master token: the operator provisions one fully-scoped master token in the dashboard (an advanced, operator-guided step the agent never automates), stored at the account-scoped secrets file; the agent reads it only to mint a narrowly-scoped, short-lived token per operation and exports that ephemeral token for the one call. Account state is brand-isolated and the master token never leaves the secrets file — see `references/api.md`.
|
|
11
11
|
|
|
12
12
|
## When to activate
|
|
13
13
|
|
|
@@ -25,20 +25,23 @@ Each installation has its own Cloudflare account. The operator signs in with OAu
|
|
|
25
25
|
|
|
26
26
|
## Operator-facing surface
|
|
27
27
|
|
|
28
|
-
The plugin registers no agent-facing MCP tools. Every Cloudflare operation is the agent invoking `cloudflared` directly via Bash,
|
|
28
|
+
The plugin registers no agent-facing MCP tools. Every Cloudflare operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, or calling the Cloudflare API with a minted narrow token, with stdout/stderr streamed verbatim into the PTY chat (secrets redacted). The OAuth URL printed by `cloudflared tunnel login` is linkified by the native PTY; the operator clicks it in their own browser. There is no shell-script wrapper, no orchestrator state machine, no MCP-tool surface.
|
|
29
29
|
|
|
30
30
|
### Skills
|
|
31
31
|
|
|
32
32
|
| Skill | Purpose |
|
|
33
33
|
|---|---|
|
|
34
|
-
| [
|
|
34
|
+
| [cloudflare/SKILL.md](skills/cloudflare/SKILL.md) | The entry point for every Cloudflare operation. Routes each operation class to its reference, names the outcome contracts (tunnel external HTTP 200; hosting deployed URL; D1 round-trip), and states the tool-discipline + secret-redaction rules that bind the agent. |
|
|
35
35
|
|
|
36
36
|
### References
|
|
37
37
|
|
|
38
38
|
| Reference | Topics |
|
|
39
39
|
|---|---|
|
|
40
|
-
| [manual-setup.md](references/manual-setup.md) |
|
|
41
|
-
| [
|
|
40
|
+
| [manual-setup.md](references/manual-setup.md) | Tunnel runbook — Steps 0–7 with isolated `cloudflared` command blocks. The agent reads the relevant step before issuing each command. |
|
|
41
|
+
| [api.md](references/api.md) | Cloudflare API library — canonical docs URL + curated endpoint map (DNS, zones, tunnels, token create/verify), the advanced master-token creation walkthrough, the account-scoped secrets-file storage convention, and the agent's mint-narrow-token discipline. |
|
|
42
|
+
| [d1-data-capture.md](references/d1-data-capture.md) | Form → Pages Function → D1 store → read/sweep. The Pages-Edit **and** D1-Edit token-scope requirement, `wrangler d1 create`/`execute --remote`, the `swept` column. |
|
|
43
|
+
| [hosting-sites.md](references/hosting-sites.md) | Deploy a static or Next.js site to Cloudflare Pages via `wrangler pages deploy`. |
|
|
44
|
+
| [dashboard-guide.md](references/dashboard-guide.md) | Click-paths for operations the operator prefers to do by hand — sign in, switch accounts, add a site, edit an apex CNAME, verify nameservers, delete a tunnel, manage CNAME records, author an Access policy. |
|
|
42
45
|
| [reset-guide.md](references/reset-guide.md) | Decision tree for reset vs. patch, the exact `pkill` incantation for token-mode connectors, and the dashboard cleanup paths for stray records and rogue entries. |
|
|
43
46
|
|
|
44
47
|
The agent loads these references on demand via `plugin-read` as the conversation requires. They are not auto-injected into the system prompt.
|
|
@@ -55,4 +58,4 @@ The setup-done claim only fires when `curl -I https://<hostname>` issued from ou
|
|
|
55
58
|
|
|
56
59
|
## Discipline
|
|
57
60
|
|
|
58
|
-
|
|
61
|
+
The agent's permitted surfaces are: direct `cloudflared` and `wrangler` invocations via Bash following the references; Cloudflare API calls authenticated by a freshly-minted narrow token (the master token stays in the secrets file, never on a command line that echoes, never in chat); the reference files; and live verification (`curl -I` for tunnels, the deployed URL for hosting, a `SELECT` for D1). Out of bounds: Playwright or Chrome DevTools driving the dashboard, browser-automating master-token creation, WebSearch-for-CF-recipes, ad-hoc `cloudflared` flag invention not in the runbook, and writing or echoing any token. When a step fails, the agent reports the exact output (secrets redacted), cites the recovery step from `references/reset-guide.md`, and stops.
|