@rubytech/create-maxy-code 0.1.23 → 0.1.26

package/dist/index.js

@@ -35,8 +35,20 @@ catch (err) {
     process.exit(1);
 }
 const INSTALL_DIR = resolve(process.env.HOME ?? "/root", BRAND.installDir);
-const LOG_DIR = resolve(process.env.HOME ?? "/root", BRAND.configDir, "logs");
+const PERSIST_DIR = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+const LOG_DIR = join(PERSIST_DIR, "logs");
 const LOG_FILE = join(LOG_DIR, `install-${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+// Task 048 — every `claude plugin` shellout must read/write the per-brand
+// CLAUDE_CONFIG_DIR that the systemd unit at port-resolution.ts:229,286 uses
+// at runtime. Without this override, the installer writes marketplaces and
+// enabledPlugins to $HOME/.claude/settings.json (user-default), and the
+// PTY spawned by the session-manager sees an empty config dir — the
+// onboarding skill never registers, `<onboarding-state>` resolves to
+// "Unknown skill: onboarding", and the operator is stuck at step 6.
+const CLAUDE_CONFIG_DIR = join(PERSIST_DIR, ".claude");
+function claudePluginEnv() {
+    return { ...process.env, CLAUDE_CONFIG_DIR };
+}
 /** Known brand hostnames in the Maxy ecosystem. Each brand ships a main unit
  *  (`<hostname>.service`) and a per-brand edge unit (`<hostname>-edge.service`,
  *  Task 662). Peer-brand detection matches only these filenames — stale units,
@@ -916,7 +928,10 @@ function installClaudeCode() {
         }
     }
     console.log("  Registering Claude plugin marketplaces...");
-    const marketplaceList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8" });
+    // Task 048 — pre-create the per-brand CLAUDE_CONFIG_DIR so the first
+    // `claude plugin marketplace add` has a directory to write into.
+    mkdirSync(CLAUDE_CONFIG_DIR, { recursive: true });
+    const marketplaceList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
     if (marketplaceList.stderr)
         process.stderr.write(marketplaceList.stderr);
     const listed = marketplaceList.stdout ?? "";
@@ -938,16 +953,16 @@ function installClaudeCode() {
     ];
     for (const { slug, marketplaceName } of MARKETPLACES) {
         if (listed.includes(marketplaceName)) {
-            logFile(`[plugin-marketplace] added ${slug} idempotent=true`);
+            logFile(`[plugin-marketplace] added ${slug} idempotent=true CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
             continue;
         }
-        const add = spawnSync("claude", ["plugin", "marketplace", "add", slug], { stdio: "pipe", encoding: "utf-8", timeout: 60_000 });
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", slug], { stdio: "pipe", encoding: "utf-8", timeout: 60_000, env: claudePluginEnv() });
         if (add.status === 0) {
-            logFile(`[plugin-marketplace] added ${slug} idempotent=false`);
+            logFile(`[plugin-marketplace] added ${slug} idempotent=false CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
         }
         else {
             const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
-            logFile(`[plugin-marketplace] ERROR add ${slug} exit=${add.status} stderr=${JSON.stringify(stderrShort)}`);
+            logFile(`[plugin-marketplace] ERROR add ${slug} exit=${add.status} stderr=${JSON.stringify(stderrShort)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
         }
     }
     console.log("  Configuring git to use HTTPS for GitHub (plugin install support)...");
@@ -956,10 +971,10 @@ function installClaudeCode() {
     // server in claude-agent.ts (with --cdp-endpoint) is the single correct path.
     // The plugin creates a shadow server that intermittently handles tool calls
     // without --cdp-endpoint, causing Chrome launch failures on ARM64.
-    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8" });
+    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
     if (pluginList.stdout?.includes("playwright")) {
         console.log("  Removing Playwright plugin (replaced by programmatic CDP server)...");
-        spawnSync("claude", ["plugin", "uninstall", "playwright"], { stdio: "inherit" });
+        spawnSync("claude", ["plugin", "uninstall", "playwright"], { stdio: "inherit", env: claudePluginEnv() });
     }
     // Ensure @playwright/mcp and all its dependencies (including playwright-core)
     // are cached. Wipe any stale npx cache for it first — killed installs on Pi
@@ -1922,20 +1937,23 @@ function registerLocalAndExternalPlugins() {
         }
     }
     // Add each local marketplace. Idempotence via `marketplace list` grep.
-    const mkList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8" });
+    // Task 048 — every `claude plugin …` call carries CLAUDE_CONFIG_DIR so
+    // marketplaces register into the per-brand config dir that the runtime
+    // session-manager unit reads from.
+    const mkList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
     const mkListed = mkList.stdout ?? "";
     for (const { name, dir } of localTrees) {
         if (mkListed.includes(name)) {
-            logFile(`[plugin-marketplace] added ${name} idempotent=true`);
+            logFile(`[plugin-marketplace] added ${name} idempotent=true CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
             continue;
         }
-        const add = spawnSync("claude", ["plugin", "marketplace", "add", dir], { stdio: "pipe", encoding: "utf-8", timeout: 60_000 });
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", dir], { stdio: "pipe", encoding: "utf-8", timeout: 60_000, env: claudePluginEnv() });
         if (add.status === 0) {
-            logFile(`[plugin-marketplace] added ${name} source=${dir} idempotent=false`);
+            logFile(`[plugin-marketplace] added ${name} source=${dir} idempotent=false CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
         }
         else {
             const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
-            logFile(`[plugin-marketplace] ERROR add ${name} source=${dir} exit=${add.status} stderr=${JSON.stringify(stderrShort)}`);
+            logFile(`[plugin-marketplace] ERROR add ${name} source=${dir} exit=${add.status} stderr=${JSON.stringify(stderrShort)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
         }
     }
     // Build the desired plugin list = (every local marketplace's plugins) +
@@ -1967,14 +1985,14 @@ function registerLocalAndExternalPlugins() {
     }
     desired.push(...externals);
     // Snapshot what's installed to compute the install set.
-    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8" });
+    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8", env: claudePluginEnv() });
     const installed = parsePluginList(pluginList.stdout ?? "");
     const { toInstall, alreadyInstalled } = computeInstallActions(desired, installed);
     for (const ref of alreadyInstalled) {
         logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=true`);
     }
     for (const ref of toInstall) {
-        const install = spawnSync("claude", ["plugin", "install", `${ref.name}@${ref.marketplace}`, "--scope", "user"], { stdio: "pipe", encoding: "utf-8", timeout: 120_000 });
+        const install = spawnSync("claude", ["plugin", "install", `${ref.name}@${ref.marketplace}`, "--scope", "user"], { stdio: "pipe", encoding: "utf-8", timeout: 120_000, env: claudePluginEnv() });
         if (install.status === 0) {
             logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=false`);
         }
@@ -2000,7 +2018,7 @@ function registerLocalAndExternalPlugins() {
         // The piped-stdin form: `echo '/<name>:configure <secret>' | claude --print`
         // is the documented one-shot configure path. We do not log the secret value.
         const cmd = `/${action.plugin.name}:configure ${action.secretValue}`;
-        const configure = spawnSync("claude", ["--print", "--input-format", "text"], { input: cmd, stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8", timeout: 60_000 });
+        const configure = spawnSync("claude", ["--print", "--input-format", "text"], { input: cmd, stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8", timeout: 60_000, env: claudePluginEnv() });
         if (configure.status === 0) {
             logFile(`[plugin-configure] ${action.plugin.name} ok env-var=${action.plugin.configureSecret}`);
         }
@@ -2009,6 +2027,35 @@ function registerLocalAndExternalPlugins() {
             logFile(`[plugin-configure] ERROR ${action.plugin.name} exit=${configure.status} stderr=${JSON.stringify(stderrShort)}`);
         }
     }
+    // Task 048 — post-install assertion. The per-brand CLAUDE_CONFIG_DIR is the
+    // only surface the runtime session-manager reads from; if any expected
+    // marketplace is missing under .claude/plugins/marketplaces/, the operator
+    // will hit "Unknown skill: onboarding" at step 6 of the bring-up. Fail the
+    // install loudly here rather than ship a broken PTY.
+    //
+    // Expected set = 3 Anthropic marketplace names (from the constant in
+    // installClaudeCode) + every parsed localTrees name. Hardcoding the
+    // Anthropic names keeps the assertion independent of `MARKETPLACES` scope.
+    const expectedMarketplaces = new Set([
+        "claude-plugins-official",
+        "knowledge-work-plugins",
+        "claude-for-financial-services",
+        ...localTrees.map(t => t.name),
+    ]);
+    const marketplacesDir = join(CLAUDE_CONFIG_DIR, "plugins", "marketplaces");
+    let actualMarketplaces;
+    try {
+        actualMarketplaces = readdirSync(marketplacesDir);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Plugin registration produced no marketplaces directory at ${marketplacesDir} — every marketplace add failed (${msg}). Check setup.log for [plugin-marketplace] ERROR lines.`);
+    }
+    const missing = [...expectedMarketplaces].filter(m => !actualMarketplaces.includes(m));
+    if (missing.length > 0) {
+        throw new Error(`Plugin registration incomplete: expected marketplaces ${JSON.stringify([...expectedMarketplaces])} but ${marketplacesDir} contains ${JSON.stringify(actualMarketplaces)}. Missing: ${JSON.stringify(missing)}. Check setup.log for [plugin-marketplace] ERROR lines.`);
+    }
+    logFile(`[plugin-marketplace] assertion ok marketplaces=${JSON.stringify(actualMarketplaces)} CLAUDE_CONFIG_DIR=${CLAUDE_CONFIG_DIR}`);
 }
 function buildPlatform() {
     log("9", TOTAL, "Installing dependencies and building...");

package/package.json

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

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

@@ -2,29 +2,52 @@
 name: admin
 description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver — single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name — the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), render-component, session-reset, session-resume, file-attach, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform."
 tools:
-  - system-status
-  - public-hostname
-  - brand-settings
-  - account-manage
-  - account-update
-  - admin-add
-  - admin-remove
-  - admin-list
-  - admin-update-pin
-  - agent-list
-  - agent-config-read
-  - logs-read
-  - plugin-read
-  - skill-load
-  - store-skill
-  - render-component
-  - session-reset
-  - session-resume
-  - file-attach
-  - action-pending
-  - action-approve
-  - action-reject
-  - action-edit
+  - name: system-status
+    publicAllowlist: false
+  - name: public-hostname
+    publicAllowlist: false
+  - name: brand-settings
+    publicAllowlist: false
+  - name: account-manage
+    publicAllowlist: false
+  - name: account-update
+    publicAllowlist: false
+  - name: admin-add
+    publicAllowlist: false
+  - name: admin-remove
+    publicAllowlist: false
+  - name: admin-list
+    publicAllowlist: false
+  - name: admin-update-pin
+    publicAllowlist: false
+  - name: agent-list
+    publicAllowlist: false
+  - name: agent-config-read
+    publicAllowlist: false
+  - name: logs-read
+    publicAllowlist: false
+  - name: plugin-read
+    publicAllowlist: false
+  - name: skill-load
+    publicAllowlist: false
+  - name: store-skill
+    publicAllowlist: false
+  - name: render-component
+    publicAllowlist: false
+  - name: session-reset
+    publicAllowlist: false
+  - name: session-resume
+    publicAllowlist: false
+  - name: file-attach
+    publicAllowlist: false
+  - name: action-pending
+    publicAllowlist: false
+  - name: action-approve
+    publicAllowlist: false
+  - name: action-reject
+    publicAllowlist: false
+  - name: action-edit
+    publicAllowlist: false
 hidden:
   - remote-auth-status
   - remote-auth-set-password
@@ -69,6 +92,10 @@ Tools are available via the `admin` MCP server.
 | Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
 | Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
 | Plain-English explanation | User asks to explain, define, or pre-empts ("explain in plain English", "what does X mean", "define X", "I don't understand", "what is this"), or admin is about to return a reply containing a term not in the operator's prior turn | `skills/plainly/SKILL.md` |
+| Manage admin users | User asks to add, remove, or list admins on this account, or change an admin PIN | `skills/admin-user-management/SKILL.md` |
+| Session reset / continue / resume | User asks to clear the session, start fresh, continue the last session, or pick up where they left off | `skills/session-management/SKILL.md` |
+| Commitment follow-through | A `<commitment-detected>` block appears in the prompt; the owner has just made a commitment that needs a backing mechanism | `skills/commitment-followthrough/SKILL.md` |
+| Show or download a file | User asks to view, attach, or download a file or document, or the current turn produces a document the owner needs to review | `skills/file-presentation/SKILL.md` |
 
 ## Hooks
 

package/payload/platform/plugins/admin/skills/admin-user-management/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: admin-user-management
+description: "Add, remove, list admins on this account, and update an admin PIN. Triggers when the owner asks to invite another admin, remove an admin, see who has admin access, or change a PIN."
+---
+
+# Admin user management
+
+This skill manages who has admin access to this account. It wraps four MCP tools and carries the discipline that keeps the three identity stores in lockstep. The owner (or any current admin) can manage admins; roles are labels only, with no capability differences enforced.
+
+## The four tools
+
+| Tool | Purpose |
+|---|---|
+| `admin-add` | Add a new admin. Requires a name. PIN is optional: omit it and a unique 4-digit PIN is generated. PIN must be at least 4 digits and unique across all users on the device. |
+| `admin-remove` | Remove an admin by `userId` (find IDs via `admin-list`). The last admin on the account cannot be removed. The user's device-level entry is retained so they can still administer other accounts. |
+| `admin-list` | List all admins on this account with names and roles. |
+| `admin-update-pin` | Update an admin's PIN. Defaults to the calling admin if no `userId` is given. PIN must be at least 4 digits and unique across all users on the device. |
+
+## The three-store invariant
+
+Admin identity lives in three places that must stay in lockstep:
+
+1. `account.json` `admins[]`: account-level role record.
+2. `users.json`: device-level PIN authentication. This is the source of truth at login.
+3. The Neo4j graph: `:AdminUser` + `:Person` + `OWNS` + `ADMIN_OF` edges. Display and graph identity.
+
+`admin-add` writes all three. `admin-update-pin` writes `users.json` only (the other stores carry no PIN). If any leg fails, the tool returns `is_error: true` and `server.log` carries a `[admin-auth-store] action=… userId=… result=fail store=…` line naming which leg failed and what was already written. When you see that line, tell the owner the record is half-written and may need manual reconciliation.
+
+## Never write `account.json` directly
+
+All account-level mutations (`tier`, `outputStyle`, `thinkingView`, `effort`, `enabledPlugins`, `admins[]`, agent settings) go through the dedicated MCP tools: `account-update`, `plugin-toggle-enabled`, `admin-add`, `admin-remove`. The pre-tool-use hook denies direct `Edit` or `Write` on `account.json` server-side; this rule is the explanation for the denial. `tier` and `purchasedPlugins` derive from a Rubytech-signed entitlement payload on commercial installs, so a hand-edit is silently void.
+
+## `admin-add` retries: re-pass any user-stated PIN
+
+If `admin-add` returns an error (tier cap reached, PIN collision) and the owner resolves the blocker (upgrade tier, remove an existing admin), the retried `admin-add` MUST re-pass the PIN the owner originally stated as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the owner asked for. The resulting `admin-update-pin` correction loop is exactly the failure mode this rule exists to prevent.
+
+## Standard flow
+
+1. Read the request. Identify which of the four operations applies.
+2. For `admin-add`, gather the name. The PIN is optional; if the owner stated one, use it; otherwise let the tool generate one. For `admin-remove`, call `admin-list` first if the owner did not give a `userId`.
+3. Call the tool.
+4. If the tool succeeds, confirm the result in plain English. Include the PIN in the reply for `admin-add` so the owner can share it with the new admin.
+5. If the tool returns an error, surface the failure and the `[admin-auth-store]` line from `server.log` if present. Do not retry the same call; resolve the underlying blocker first.
+
+## What this skill does not do
+
+It does not manage tier upgrades. It does not change account-level settings. It does not manage public agents or plugins. Each of those has its own skill.

package/payload/platform/plugins/admin/skills/commitment-followthrough/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: commitment-followthrough
+description: "Handles the platform-detected commitment signal: offers to track or automate the commitment, waits for owner confirmation, then picks the right backing mechanism (scheduled event, task, or workflow). Loads when the system prompt contains a `<commitment-detected>` block."
+---
+
+# Commitment follow-through
+
+This skill activates when the platform identifies that the owner has just made a commitment: something they said they would do. The skill's job is to offer the right backing mechanism, wait for the owner's confirmation, then create it. Without a backing mechanism, a commitment is a broken promise; with one, the agent can hold the owner to their word.
+
+## The trigger
+
+A `<commitment-detected>` block appears in the system prompt. The block names what the platform classifier extracted: the commitment text, the suggested mechanism (scheduled event, task, or workflow), and any time, recipient, or topic the classifier inferred.
+
+## How to offer
+
+Surface a brief, conversational offer. Name the commitment, name the suggested mechanism, and ask the owner to confirm, modify, or dismiss. One or two sentences. Not a form. Not a list of options. Examples:
+
+- "I'll set a reminder for Tuesday morning to chase the Acme invoice. Confirm?"
+- "Want me to create a task for the photo brief so it doesn't slip?"
+- "Shall I schedule the weekly check-in with Daniel on Mondays at 9?"
+
+## Never act without confirmation
+
+The owner must say "yes" or give specifics before any tool call. If they dismiss ("no thanks", "I'll handle it"), acknowledge briefly and continue with whatever they were discussing. Do not re-offer for the same commitment.
+
+If they modify ("make it next Monday instead"), incorporate the changes and confirm before creating.
+
+## The two-rule discipline
+
+This skill is the operator's side of the two-rule contract on commitments.
+
+1. **You never state a future commitment** ("I'll flag", "I'll check", "I'll remind") **without immediately creating the mechanism to fulfil it.** A commitment without a backing mechanism is a broken promise.
+2. **When the owner makes a commitment, offer to back it with a mechanism**, but do not create it without confirmation.
+
+Rule 1 is yours; rule 2 is this skill's job.
+
+## Picking the mechanism
+
+Use the most appropriate tool:
+
+- `schedule-event` for time-bound reminders (every Monday, on Tuesday, by Friday).
+- `task-create` for open-ended obligations (chase X, finish Y, prepare Z).
+- `workflow-create` for multi-step processes that recur (monthly close-out, new-instruction onboarding).
+
+## Verify executor capabilities before promising a workflow
+
+Before committing to build a workflow, check that every step maps to a capability the executor actually has. Tool steps need the named plugin and tool to exist. Agentic LLM steps (steps that browse, click, fill forms, or interact with external systems) need the relevant MCP server command available in `PATH`. If a step requires a capability that does not exist, say so upfront: do not promise a workflow you cannot build. The owner can either narrow the scope or wait for the capability to ship.
+
+## After creation
+
+Tell the owner what was created (task ID, scheduled event time, workflow name) so they have something they can reference, modify, or cancel later. Then resume the conversation.
+
+## Failure modes
+
+- **`<commitment-detected>` block names a mechanism that does not exist** (e.g. `workflow-create` while workflows are not enabled on this account). Surface the gap and offer the next-best mechanism.
+- **Owner approves but the create tool fails.** Surface the error literally. Do not silently substitute a different mechanism.
+
+## What this skill does not do
+
+It does not detect commitments itself; the platform does that and injects the block. It does not act on the owner's behalf without explicit confirmation. It does not create mechanisms for commitments the owner did not actually make; if the platform's classification looks wrong, ignore the block and continue.

package/payload/platform/plugins/admin/skills/file-presentation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: file-presentation
+description: "Render a file or document inline for the owner to view, edit, and download. Triggers when the owner asks to see, attach, or download a file, when content is generated that the owner needs to review (summary, report, draft), or when a downloadable artefact is the right output."
+---
+
+# File presentation
+
+This skill makes a file visible and downloadable inside the chat. It is the only sanctioned path for delivering file content to the owner. Synthesised content (a summary, a report, a draft) follows the same path: render via `document-editor` so the owner can review and download.
+
+## The trigger
+
+The owner asks to view, review, attach, or download a file or a document, or the current turn produces a document that the owner needs to see. Example phrasings:
+
+- "show me the file"
+- "attach the report"
+- "let me download that"
+- "preview the document"
+- "send me the brochure"
+- "save that as a markdown file"
+
+## How to render
+
+Call `render-component` with:
+
+```
+name: "document-editor"
+data: {
+  title: "<owner-facing title>",
+  content: "<the file content as markdown>"
+}
+```
+
+The component gives the owner a render-review-edit-download flow: they see the content inline, can edit it in place, and can download it as a `.md` file directly from the component. Do not use `memory-write`, `memory-ingest`, or other tools to deliver file content to the owner; those tools have different purposes and skipping the render-review-download flow takes control away from the owner.
+
+## Character sanitisation: the silent-failure rule
+
+The document-editor's markdown parser fails silently on these typographical characters:
+
+| Character | Unicode | Replace with |
+|---|---|---|
+| em-dash | U+2014 | hyphen with spaces |
+| en-dash | U+2013 | hyphen with spaces |
+| left curly double quote | U+201C | straight double quote |
+| right curly double quote | U+201D | straight double quote |
+| left curly single quote | U+2018 | straight single quote |
+| right curly single quote | U+2019 | straight single quote |
+| horizontal ellipsis | U+2026 | three periods |
+
+Strip and replace these characters in the `content` field before the `render-component` call. The owner does not see a partial render or a warning; the content just silently breaks at the offending character. Currency symbols (£, €), accented characters, and other Unicode are unaffected: use them normally.
+
+## When the file is a binary
+
+For PDF, image, audio, or any binary deliverable, use `file-attach` plus `render-component` with `name: file-attachment` and pass the returned path. The document-editor component is for editable markdown text only.
+
+## For static-site delivery
+
+When the owner has uploaded a `.zip` containing HTML and assets and wants it hosted, this skill is not the right path. Delegate to `content-producer` on turn one; the specialist owns the `unzip-attachment` then `publish-site` chain.
+
+## Failure modes
+
+- **Content is too large for the component** (typically over 50,000 characters of markdown). Surface the size and offer to split into sections, save as an attachment, or render only the first section with a follow-up for the rest.
+- **`render-component` returns an error.** Surface the error literally. Do not paste the content into chat as a fallback; the owner asked for the render-review-download flow, not a wall of text.
+- **The content contains characters the parser rejects after the sanitisation pass** (rare; usually a non-printable control character). Strip the offending characters and surface a one-line warning naming the position.
+
+## What this skill does not do
+
+It does not write the content to the graph. It does not save the content to disk. The component handles the download path; the owner downloads what they edited in the component.