grix-connector 4.2.3 → 4.2.5

package/dist/default-skills/grix-egg/SKILL.md

@@ -1,39 +1,93 @@
 ---
 name: grix-egg
-description: 'Install a Grix egg skill package into your own skill directory. Use when you receive an instruction containing a line like "技能包: <URL>" and are asked to install / incubate it as a skill for yourself.'
-trigger: "当收到含「技能包: <URL>」的安装指令、要求把虾蛋技能包装进自己的技能目录时"
+description: "Grix egg market — the FIRST entry when the user wants a new agent or assistant for some purpose: search published eggs (skill and persona packages) by the business description with `grix_egg_search` / `grix_egg_get`, present matches, then install the chosen egg yourself from the download URL `grix_egg_get` returns (skill package into your own skill directory, or persona package into a new agent via grix-admin); only when nothing fits do you fall back to grix-admin to create a bare agent. Also handles the platform install instruction (a line like \"技能包: <URL>\")."
+trigger: 'When the user wants to create a new agent / assistant for a role or business need, asks what ready-made eggs (skills, personas) exist, or when you receive an install instruction containing a "技能包: <URL>" line'
 ---
 
-# Grix Egg — Skill Package Self-Install
+# Grix Egg
 
-For an agent like you, incubating an egg means exactly one thing: **installing a
-skill package into your own skill directory** so you can use it from then on.
+Two jobs, in the order they happen:
 
-When you receive an install instruction containing a `技能包: <URL>` line, use
-this skill to install it, self-check, and send back an install-status card. The
-whole job is done by you on this machine — no other agent installs it for you,
-and the main agent cannot touch your skill directory.
+1. [Discovery](#part-1--discovery-find-an-egg-before-creating-an-agent) — the
+   user wants a new agent: find a ready-made egg first.
+2. [Self-install](#part-2--self-install-技能包-url) — install a skill package
+   into your own skill directory, from a URL you got via `grix_egg_get` or
+   from the platform's `技能包: <URL>` instruction.
 
-## What the instruction gives you
+## Part 1 — Discovery: find an egg before creating an agent
 
-- `技能包: <URL>` — download URL of the skill package to install (always present).
-- `install_id: <ID>` — the ID of this install; echo it verbatim in the status card (always present).
-- `grix agent id: <ID>` — your own grix agent id; use it as `target_agent_id` in the status card (may be present).
+When the user describes an agent they want ("帮我建一个跟进外贸询盘的助手",
+"I need a bot that reviews PRs"), **do not** go to `grix-admin` yet. Search the
+egg market first; a published egg gives them a tested skill set or persona in
+one tap.
 
-## What you must do
+### Search strategy
 
-1. Extract the download URL after `技能包:`.
-2. Determine your own skill directory: it is **the parent of the directory this grix-egg skill lives in**. E.g. if this skill is at `~/.codex/skills/grix-egg/`, the skill directory is `~/.codex/skills/`; at `~/.claude/skills/grix-egg/` it is `~/.claude/skills/`, and so on.
-3. Download and unpack the skill package.
-4. Copy every unpacked skill (any directory containing a `SKILL.md`) into your skill directory, whole directory at a time.
-5. Confirm the new skill's `SKILL.md` now exists in your skill directory.
-6. **Send back the install-status card** (see below) so the platform can close out this install as success/failure.
-7. Then tell the user, in one natural-language sentence, which skill(s) were installed.
+The backend matches keywords term-by-term (AND) against name + description +
+category, so a whole sentence returns nothing. Instead:
 
-## Steps 2–5: install (run in shell)
+1. Distill the description into **2–4 short keywords**: the role noun, the
+   domain, the core action (e.g. `外贸`, `询盘`, `报价`; `code review`, `PR`).
+2. Call `grix_egg_search` **once per keyword** (`pageSize` 10), in the user's
+   language and `locale`. Merge the results, rank by number of keyword hits
+   then `install_count`.
+3. If keywords return nothing, browse by category: search with no keyword
+   and a likely `categoryId` (categories come back in `category_id` /
+   `category_name` of any result, or run a broad search first).
+4. Optionally `grix_egg_get` the top candidates for the full description and
+   `version_desc`.
 
-Replace the two angle-bracket placeholders with real values, then run.
-`SKILLS_DIR` is the parent of the directory this skill lives in.
+### Present candidates
+
+Show at most 3–5 eggs, each with: name (+ emoji), one-line description,
+category, `install_count`, and what it can do for the user:
+
+- `can_create_agent: true` — hatches into a **new agent** (persona + skills).
+- `existing_agent_client_types` non-empty — installs as a **skill into an
+  existing agent** of those client types.
+
+Ask the user which one to hatch. Do not invent capabilities that are not in
+the egg description.
+
+### Install the chosen egg
+
+`grix_egg_get` returns the package URLs: `skill_zip_url` (+ `skill_zip_sha256`)
+and `persona_zip_url` (+ `persona_zip_sha256`). No App round-trip is needed.
+
+- **Skill into yourself** (`existing_agent_client_types` includes your client
+  type): download `skill_zip_url`, verify the sha256 when present, then run the
+  Part 2 script with that URL. There is no `install_id` in this path, so skip
+  the status card and just report the installed skill(s).
+- **New agent** (`can_create_agent: true`): create and bind the agent with
+  `grix-admin` (`create-and-connector-bind`), then apply `persona_zip_url` to
+  it the same way the platform's `人格包: <URL>` instruction would.
+- No egg fits, or the user explicitly wants a blank agent → hand over to
+  `grix-admin` (`create-and-connector-bind`) and say clearly that no
+  ready-made egg matched.
+
+If the platform itself sends a `技能包: <URL>` instruction (the owner hatched
+from the App), run Part 2 — that path carries an `install_id` and needs the
+status card.
+
+## Part 2 — Self-install (`技能包: <URL>`)
+
+Incubating an egg means exactly one thing for you: **installing a skill
+package into your own skill directory**. The whole job runs on this machine;
+no other agent installs it for you.
+
+The instruction gives you:
+
+- `技能包: <URL>` — download URL of the package (always present).
+- `install_id: <ID>` — echo it verbatim in the status card (always present).
+- `grix agent id: <ID>` — your own agent id; use as `target_agent_id` in the
+  status card (may be present).
+
+Steps: (1) extract the URL; (2) your skill directory is **the parent of the
+directory this skill lives in** (e.g. `~/.claude/skills/grix-egg/` →
+`~/.claude/skills/`); (3) download, unpack, copy every directory containing a
+`SKILL.md` into it, overwriting a same-name skill; (4) confirm the new
+`SKILL.md` exists; (5) send the status card; (6) tell the user in one sentence
+which skill(s) were installed.
 
 ```bash
 set -e
@@ -45,7 +99,6 @@ curl -fsSL "$URL" -o "$TMP/skill.zip"
 mkdir -p "$TMP/unpacked"
 unzip -o -q "$TMP/skill.zip" -d "$TMP/unpacked"
 
-# Copy every skill directory containing a SKILL.md into the skill directory
 found=0
 while IFS= read -r -d '' f; do
   d="$(dirname "$f")"
@@ -53,7 +106,7 @@ while IFS= read -r -d '' f; do
   found=1
 done < <(find "$TMP/unpacked" -name SKILL.md -print0)
 
-# Fallback: SKILL.md sits loose at the unpack root — create a skill directory named after its `name` and move everything in
+# Fallback: SKILL.md sits loose at the unpack root
 if [ "$found" -eq 0 ] && [ -f "$TMP/unpacked/SKILL.md" ]; then
   name="$(grep -m1 '^name:' "$TMP/unpacked/SKILL.md" | sed 's/^name:[[:space:]]*//')"
   [ -z "$name" ] && name="egg-skill"
@@ -61,38 +114,29 @@ if [ "$found" -eq 0 ] && [ -f "$TMP/unpacked/SKILL.md" ]; then
   cp -R "$TMP/unpacked/." "$SKILLS_DIR/$name/"
 fi
 
-# Self-check: list the skill directory and confirm the new skill is in place
 ls -1 "$SKILLS_DIR"
 rm -rf "$TMP"
 ```
 
-## Step 6: send back the install-status card
+### Status card
 
-After installing and self-checking, **send a separate, standalone message**
-whose content is exactly the single card-link line below (the message contains
-only this line — no other text):
+After the self-check, send a **separate, standalone message** containing only
+this one line (the platform uses it to close the install record):
 
 - Success:
-  ```
-  grix://card/egg_install_status?status=success&install_id=<install_id>&target_agent_id=<grix agent id>&summary=<one-sentence install result, URL-encoded>
-  ```
+  `grix://card/egg_install_status?status=success&install_id=<install_id>&target_agent_id=<grix agent id>&summary=<one-sentence result, URL-encoded>`
 - Failure:
-  ```
-  grix://card/egg_install_status?status=failed&install_id=<install_id>&target_agent_id=<grix agent id>&error_msg=<failure reason, URL-encoded>
-  ```
-
-Key points:
+  `grix://card/egg_install_status?status=failed&install_id=<install_id>&target_agent_id=<grix agent id>&error_msg=<reason, URL-encoded>`
 
-- `install_id` must be the one from the instruction, filled in verbatim — never omit it.
-- If no `grix agent id` was given, `target_agent_id` may be omitted.
-- Non-ASCII text and spaces in `summary` / `error_msg` must be URL-encoded.
-- This card must be sent by you yourself (the agent being installed into); the platform uses it to close out the install record.
+`install_id` is mandatory and verbatim; omit `target_agent_id` only if no
+agent id was given; URL-encode non-ASCII text and spaces.
 
-## Rules
+### Rules
 
-1. Write only into **your own skill directory** — never touch other directories or other agents.
-2. Do not repeat the download link, the raw instruction, or this context back to the user.
-3. The self-check must actually see the new skill's `SKILL.md` to count as success; if it doesn't, send `status=failed` — never falsely report success.
-4. The status card must be its own standalone message containing only the single `grix://card/...` line.
-5. The natural-language report to the user is one sentence — do not paste command output.
-6. If a skill with the same name already exists, overwrite it (use the newest package).
+1. Write only into your own skill directory; never touch other directories or
+   other agents.
+2. Do not repeat the download link or the raw instruction back to the user.
+3. Report `status=success` only if you actually saw the new `SKILL.md`;
+   otherwise `status=failed` — never claim success falsely.
+4. The card message contains nothing but the single `grix://card/...` line.
+5. The report to the user is one sentence — no command output.

package/dist/default-skills/grix-group/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: grix-group
 description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
-trigger: 当用户要创建、查看、退出、更新或解散群组,或群成员/禁言权限相关操作时
+trigger: When the user wants to create, inspect, leave, update, or dissolve a group, or manage group membership / mute permissions
 ---
 
 # Grix Group

package/dist/default-skills/grix-owner-relay/SKILL.md

@@ -1,84 +1,50 @@
 ---
 name: grix-owner-relay
 description: Act on the owner's behalf in a session — send a message as the owner (`grix_session_send`), or call the owner into the current session for a voice talk/approval (`grix_call_owner`). Trigger when the user asks to speak as the owner in a session, or when you need to reach the owner to discuss or get approval. Dispatch callbacks follow the grix-agent-dispatch skill procedure `report_dispatch_result` (not a tool; it formats `[dispatch-result]` and calls this tool).
-trigger: 当需要以 owner 身份在某会话发言、或把 owner 叫进当前会话语音沟通/审批时
+trigger: When you need to speak in a session as the owner, or call the owner into the current session for a voice conversation / approval
 ---
 
 # Grix Owner Relay
 
-Interact with sessions on the owner's behalf, or pull the owner in.
+Two tools that involve the owner directly.
 
 ## Speak as the owner — `grix_session_send`
 
-Send a message into a session **as the owner** — it shows up as if the owner
-themselves sent it, **not** as you (the agent).
+Sends a message into a session **as the owner** — it appears as the owner's
+own words, **not** as you (the agent).
 
-- `session_id` (required) — target session ID.
-- `content` (required) — message text to send as the owner (max 10000 chars).
-- `quoted_message_id` (optional) — message ID in the **same** target session to
-  quote/reply to. Required for dispatch callbacks so the dispatcher is
-  quote-woken.
+- `session_id` (required) — target session ID. The owner must be a member of
+  it; otherwise the send is rejected with an owner-not-member error.
+- `content` (required) — message text (max 10000 chars).
+- `quoted_message_id` (optional) — ID of a message in the **same** target
+  session to quote/reply to.
 
-### When to use it
+Requires the **Send as Owner** permission scope. If the call is rejected for a
+missing permission or non-membership, surface the error as-is so the owner can
+fix it; never work around it with `grix_message_send`. Your own membership in
+the target session is not checked and is irrelevant.
 
-To relay on the owner's behalf into a session where the message must appear as
-the owner's own words. Typical case: you were dispatched to work somewhere and
-need to drop a note to the owner (or to others) in a session of theirs.
+### Use it only when the message must appear as the owner's
 
-**First-class use case: dispatch callback.** When you were dispatched via
-`grix-agent-dispatch`, follow the skill procedure `report_dispatch_result` in
-that skill (exactly 6 parameters; **not** a tool name). It formats `content`
-as **only** the `[dispatch-result]` wire block (no `@` line), and calls this
-tool with `session_id` = `callback_session_id` and
-`quoted_message_id` = the dispatcher anchor from the task pointer. Do not
-hand-roll the wire template in the task text; if you must call this tool
-directly for a dispatch callback, still send **only** that block plus the
-quote id — no extra instructions, explanations, or requests outside the
-block.
-
-**Dispatch callbacks always go through this tool, even when you are a member
-of the callback session.** A message sent as yourself cannot quote-wake the
-dispatcher agent, so membership is irrelevant — never fall back to
-`grix_message_send` for a callback. If the call is rejected for missing
-permission, surface the error as-is so the owner can grant the scope; do not
-work around it.
-
-### Before you call it, make sure
-
-1. You genuinely want to **impersonate the owner**, not speak as yourself
-   (dispatch callbacks are exactly such a case).
-2. The owner is a member of the target session (otherwise the send is
-   rejected with an owner-not-member error — surface it, don't retry blindly).
-
-### Never use it for
-
-- ❌ **Sending your own ordinary reply in a conversation.** Reply normally
-  instead (or use `grix_message_send` to send as yourself). Using
-  `grix_session_send` for ordinary chatter makes *your* answer appear as the
-  *owner's* words. The one exception is the structured dispatch callback
-  (`report_dispatch_result`), which must always go through this tool.
-- ❌ As a generic substitute for sending a message as yourself — use
-  `grix_message_send` for that.
-
-To send as yourself (the agent), use the `message-send` skill
-(`grix_message_send`).
+- ✅ Dispatch callbacks: the `report_dispatch_result` procedure in
+  `grix-agent-dispatch` (a skill procedure with exactly 6 parameters, **not** a
+  tool name) builds a `[dispatch-result]` block and sends it through this
+  tool with `quoted_message_id` set and no `@` line. That skill owns the
+  format; follow it there.
+- ✅ Relaying a note the owner asked you to send under their name.
+- ❌ Your own ordinary replies — reply normally, or use `grix_message_send`
+  (skill `message-send`) to send as yourself. Using this tool for ordinary
+  chatter makes *your* answer appear as the *owner's* words.
 
 ## Call the owner in — `grix_call_owner`
 
-Bring the owner into a session for a voice conversation — use this when you need
-to discuss something or get an approval/review during your work. It sends the
-owner an offline notification; tapping it lands them in the conversation and
-auto-starts a voice-brain call.
+Brings the owner into a session for a voice conversation — use it when you
+need to discuss something or get an approval/review during your work. The
+owner receives an offline notification; tapping it lands them in the
+conversation and auto-starts a voice-brain call.
 
 - `session_id` (required) — the session to call the owner into.
 
-## Rules
-
-1. `grix_session_send` requires the owner to be a member of the target session,
-   plus the **Send as Owner** permission scope. Your own membership in the
-   target session is irrelevant and is not checked. If the call is rejected for
-   missing permission, surface the error as-is — the owner can grant the scope;
-   never work around it with `grix_message_send`.
-2. `grix_call_owner` requires the owner to have configured a voice brain and is
-   rate-limited per session. Use it only when you genuinely need the owner, not
-   as a routine notification.
+Requires the owner to have configured a voice brain, and is rate-limited per
+session. Use it only when you genuinely need the owner, not as a routine
+notification.

package/dist/default-skills/grix-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: grix-query
 description: Use the typed `grix_query` tool for Grix contact lookup, keyword search, session search, favorited-session search, and session message history lookup. Trigger when users ask to find contacts, search conversations, list visible or favorited sessions, or inspect recent messages in a known session.
-trigger: 当用户要查找联系人、搜索会话、列出可见会话或收藏会话、或查看某个已知会话的历史消息时
+trigger: When the user wants to find contacts, search sessions, list visible or favorited sessions, or read message history of a known session
 ---
 
 # Grix Query

package/dist/default-skills/grix-skill-library/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: grix-skill-library
+description: Manage the owner's custom skill library on the Grix platform with `grix_skill_get` (list or read a skill's SKILL.md) and `grix_skill_set` (create, overwrite, or delete a skill by name). The library syncs to every machine the owner runs an agent on. Trigger when the user asks to save something as a reusable skill, list or show their skills, edit an existing skill, or delete one.
+trigger: When the user wants to list, read, create, update, or delete one of their custom Grix skills, or turn a procedure into a reusable skill
+---
+
+# Grix Skill Library
+
+The owner's custom skills live in the Grix platform and auto-sync to a
+per-machine `grix/skills` directory on every host where the owner runs an
+agent. These two tools manage that library only; whether and when an agent
+loads a synced skill is up to the owner (system prompt or conversation).
+
+## Tools
+
+- `grix_skill_get` — `name` (optional). With a name: returns that skill's full
+  `SKILL.md` text. Without: lists the library (names + versions).
+- `grix_skill_set` — `name` (required, max 100 chars, unique per owner; also
+  the synced directory name) and `content` (required, full `SKILL.md` text,
+  max 256 KB). An existing name is overwritten. An empty `content` string
+  **deletes** the skill.
+
+## Skill format
+
+`content` is a standard `SKILL.md`: YAML frontmatter with `name` (matching
+the `name` argument) and a one-line `description` that says what the skill
+does and when to use it, then a Markdown body with the procedure — inputs,
+steps, rules, and how to report. Write it for an agent that has no other
+context. Keep it focused on one job; do not embed secrets, machine-specific
+paths, or credentials.
+
+## Workflow
+
+1. **Create**: confirm the name and what the skill should do; draft the
+   `SKILL.md`; call `grix_skill_set`. Before overwriting, call
+   `grix_skill_get` with the name to check whether it already exists and
+   tell the user if it does.
+2. **Edit**: `grix_skill_get` the current content first, apply the change to
+   that text, then `grix_skill_set` the full revised text — never send a
+   partial body.
+3. **Delete**: confirm with the user, then `grix_skill_set` with the name and
+   `content: ""`.
+4. **List / show**: `grix_skill_get` without a name, or with the name.
+
+## Rules
+
+1. Never guess a skill name — list first if unsure.
+2. Overwrite and delete are irreversible; confirm before either when the
+   user did not explicitly ask for it.
+3. After a successful set, tell the user the skill is saved and will sync to
+   their machines; do not paste the whole content back unless asked.
+4. On a permission or scope error, report it as-is; do not retry.

package/dist/default-skills/grix-widget-visitor-ban/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: grix-widget-visitor-ban
 description: Ban a widget visitor session with the typed `grix_widget_visitor_ban` tool — blocks the visitor's chat session and automatically adds the session's most recent init IP to the owner's global IP ban list (7-day expiry by default). Trigger when the owner asks to ban, block, or kick an abusive/spamming widget visitor.
-trigger: 当用户要封禁、拉黑或踢掉某个骚扰/滥用的 widget 访客会话时
+trigger: When the owner wants to ban, block, or kick an abusive or spamming widget visitor session
 ---
 
 # Grix Widget Visitor Ban

package/dist/default-skills/message-send/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: message-send
 description: "Send a message into a specific Grix session by session ID, including cross-session and proactive sends. For replying to the current event use the reply/complete tools instead. Trigger words: send DM, DM, send message, notify, message another session."
-trigger: 当用户要主动给某个指定会话发消息、跨会话发送、或通知另一个会话时
+trigger: When the user wants to proactively message a specific session, send across sessions, or notify another session
 ---
 
 # Message Send

package/dist/default-skills/message-unsend/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: message-unsend
 description: "Silently recall/unsend an already-sent message in a Grix session. After execution, end immediately without replying any confirmation text. Trigger words: recall, unsend, delete message, withdraw message."
-trigger: 当用户要撤回、收回、删除一条已经发出的消息时
+trigger: When the user wants to recall, retract, or delete a message that was already sent
 ---
 
 # Message Unsend

package/dist/default-skills/tailnet-file-share/SKILL.md

@@ -1,88 +1,54 @@
 ---
 name: tailnet-file-share
-description: Turn a local file into a tailnet link — images render as inline previews, everything else gets a download link. Trigger when the user asks to view, send, share, download, or export any file on this machine.
-trigger: 当用户要求查看、发送、分享、下载、导出本机上的任何文件时
+description: Deliver a local file to the user — as a native chat attachment (`grix_file_upload`) or as a tailnet download/preview link (`grix_file_link`). Trigger when the user asks to view, send, share, download, or export any file on this machine.
+trigger: When the user asks to view, send, share, download, or export any file on this machine
 ---
 
 # Tailnet File Share
 
-When the user wants to view or obtain a file on this machine (images, logs, reports, build artifacts, exported data, etc.), you must:
+When the user wants a file that lives on this machine (image, log, report,
+build artifact, exported data, …), never paste its path or contents. Pick one
+of two tools and hand over the result.
 
-1. Call the `grix_file_link` tool with the file's absolute path.
-2. Copy the tool's `markdown` field into your reply verbatim — do not modify it.
-   - Image files (jpg/png/gif/webp/svg, etc.): the tool returns `![filename](url)`, which renders as an inline image preview in chat.
-   - Other files: the tool returns `[filename](url)`, which the user clicks to download.
-3. Do not print the raw file path, and do not paste or paraphrase the file contents.
-4. The link is bound to this machine's tailnet-internal address and is unreachable from the public internet. The user can reopen it any time, so under normal circumstances there is no expiry to worry about and none to mention — just send the link.
+## 1. Choose the tool
 
-## When to use `grix_file_upload` (native attachment) instead
+| Scenario | Tool |
+|---|---|
+| The file should appear as a proper attachment in the chat — especially images or videos the user will look at inline; ≤ 50 MB | `grix_file_upload` |
+| File > 50 MB, a clickable download link is enough, or it is an arbitrary local artifact | `grix_file_link` |
 
-Besides `grix_file_link` there is a `grix_file_upload` tool: it uploads a local
-file to the Grix platform, where it appears in the target session as a **native
-attachment message** (images/videos display inline in chat — no tailnet, no
-certificate install needed). It supports images, videos, documents, and
-archives, up to 50 MB per file. Choose by scenario:
+`grix_file_upload` uploads to the Grix platform; the attachment renders
+natively (images/videos inline) with no tailnet or certificate involved.
+Supports images, videos, documents, archives up to 50 MB per file.
 
-- The file should be a proper attachment in the chat (especially sending images or videos for the user to look at) → use `grix_file_upload`.
-- The file is large (>50 MB), a clickable download link is all that's needed, or it's an arbitrary local-path artifact → use `grix_file_link`.
+`grix_file_link` serves the file over HTTPS from this machine's tailnet
+address. The link is unreachable from the public internet, stays valid
+indefinitely, and the user can reopen it any time — do not mention expiry.
 
-## HTTPS and the one-time trust-certificate install
+## 2. Call it and relay the result
 
-Download links are HTTPS (`https://…`), signed on the fly by a self-signed CA
-built into this machine with a 10-year validity. The tool result also returns
-`ca_install_url` — the install link for the root CA certificate.
+- `grix_file_upload`: `file_path` (absolute) and `session_id` (the current
+  chat's session unless the user names another); optional `caption` and
+  `reply_to_message_id`. The tool delivers the attachment — do not also send
+  a link.
+- `grix_file_link`: `file_path` (absolute); leave `ttl_ms` unset. Copy the
+  tool's `markdown` field into your reply **verbatim**:
+  - images (jpg/png/gif/webp/svg …) come back as `![filename](url)` and
+    render as an inline preview;
+  - everything else comes back as `[filename](url)` for download.
 
-- **The first time you send a file link to a given user** (or whenever they report "the link won't open / certificate not trusted / not secure"), send them `ca_install_url` as the "install trust certificate" link along with the steps below.
-- Each device only needs this **once**; afterwards, for 10 years, every download link from this machine is warning-free, and no reinstall is needed even if the tailnet IP changes.
+Do not print the raw file path and do not paraphrase the file contents.
 
-Install guidance to send the user (pick the one matching their device):
+If `grix_file_link` fails (e.g. Tailscale is not connected), tell the user the
+local file path so they can retrieve it themselves.
 
-- **iPhone / iPad**: open `ca_install_url` in Safari — it prompts "This website is trying to download a configuration profile" → Allow → a "Profile Downloaded" entry appears at the top of Settings; tap it to install → then go to Settings → General → About → Certificate Trust Settings and turn the switch on for that certificate (enable full trust). This step is mandatory, otherwise the system still won't trust it. (iOS must use Safari; other browsers won't trigger profile installation. The server already returns a `.mobileconfig` based on the device, so no manual parameters are needed.)
-- **Mac**: click the link to download the `.crt` → double-click to open it in Keychain Access → find the certificate → double-click → expand "Trust" → set "When using this certificate" to "Always Trust".
-- **Android**: tap `ca_install_url` to download the `.crt` → Settings → Security → Encryption & credentials → Install a certificate → CA certificate, and pick the downloaded file (recent Android versions do not support one-tap install from the browser; the Settings route is required).
-- **Windows**: double-click the `.crt` → "Install Certificate" → choose the store location → "Place all certificates in the following store" → select "Trusted Root Certification Authorities".
+## 3. If the link does not open (`grix_file_link` only)
 
-If the `grix_file_link` call fails (e.g. Tailscale is not connected), tell the
-user the local file path and let them retrieve it themselves.
-
-## Scope (important): this CA only covers `grix_file_link`'s own service
-
-The built-in CA above and the certificates it issues **only make the download
-service started by `grix_file_link` (this machine's tailnet address) trusted by
-the device**. It does not cover — and cannot fix — other services the user
-starts themselves.
-
-When the user has **started their own HTTPS service on the tailnet** (a
-self-hosted site / API / media server, etc.) and the browser reports a
-certificate error, be clear that this is a separate matter:
-
-- A device only trusts "certificates issued by a CA it has personally installed". A self-hosted service uses its own CA (e.g. mkcert), which the device never installed, so it reports `not trusted / impersonation / NET::ERR_CERT_AUTHORITY_INVALID` — this has nothing to do with whether the Grix CA is installed.
-- There are only two ways to make a self-hosted service trusted:
-  1. Have that service sign its certificate with a CA the device already trusts, and keep the leaf certificate's validity **≤ 398 days** (otherwise, even with the CA trusted, it reports `NET::ERR_CERT_VALIDITY_TOO_LONG`);
-  2. Or simply don't have the user run their own HTTPS — share the files via `grix_file_link` instead, served by the built-in service, automatically trusted and with compliant validity.
-- Note: the Grix built-in CA's **private key stays only on the machine running the connector and is never handed out** (`ca_install_url` serves the public certificate only, not the private key). So only services **on the same machine as the connector** can borrow this CA for signing; services on other machines must bring their own CA and install it once per device.
-
-In short: if it can be sent via `grix_file_link`, send it that way — it's the
-least trouble. Certificate trust for self-hosted services is outside this
-skill's responsibility and must be solved on that service's side.
-
-## Two trust paths: inside the Grix app vs. the system browser (diagnose this first)
-
-The same link opened **in the Grix app** and **in a system browser (Safari /
-Chrome)** goes through two entirely independent certificate-trust mechanisms,
-with different errors and different fixes. When a user reports "won't open /
-certificate error", first find out which path they were on.
-
-- **Inside the Grix app** (image previews, in-app downloads, etc. use the app's own network stack): the app has a built-in trust rule — if the link is a tailnet address (`100.64.0.0/10` range) and the certificate's issuer name contains `Grix Tailnet Local CA`, it is allowed through, and **the user does not need to install any certificate on the device**. So `grix_file_link` links generally work out of the box in the app with zero install. If it still won't open in the app, it's most likely not a tailnet IP, or the issuer name doesn't match — not a "certificate not installed" problem.
-- **System browser (Safari / Chrome)**: this goes through the phone's / computer's system trust store, which has nothing to do with the app's rule. The root CA must be installed as described in *HTTPS and the one-time trust-certificate install* above (on iOS, install the `.mobileconfig` and enable full trust; on Android, go through Settings; and so on). `NET::ERR_CERT_AUTHORITY_INVALID`, "impersonation", and `NET::ERR_CERT_VALIDITY_TOO_LONG` in the user's screenshots are almost always this path — guide them to install the CA.
-
-The same distinction applies to **self-hosted services**, decided by where the user wants to view it:
-
-- Only needs to display **inside the Grix app**: the self-hosted service does not have to distribute a private key to the user, and no certificate install is needed — it only needs to ① be served on a tailnet IP, and ② have its CA's issuer name carry `Grix Tailnet Local CA`, and the app will trust it.
-- Needs to open in a **system browser**: the app's rule does not apply; that service's own CA must still be installed on each device (see *Scope* above).
-
-Note: the in-app rule is **a string match on the issuer name**, not a binding to
-a specific CA's public-key fingerprint. It is a convenience trade-off within a
-private tailnet only and **is not a hard security boundary** — anyone on the
-same tailnet can have the app trust them simply by naming their CA with the same
-prefix. Do not treat it as a trust root that stands up to an attacker.
+Links open inside the Grix app with no setup. In a system browser
+(Safari/Chrome) the device must trust this machine's root CA once: the tool
+result includes `ca_install_url`. The first time you send a link to a user, or
+whenever they report "won't open / certificate not trusted / not secure", send
+`ca_install_url` with the per-device steps in
+[references/certificate-trust.md](references/certificate-trust.md). That file
+also explains why the CA does not cover the user's own self-hosted HTTPS
+services.

package/dist/default-skills/tailnet-file-share/references/certificate-trust.md

@@ -0,0 +1,64 @@
+# Certificate trust for `grix_file_link` links
+
+Download links are HTTPS, signed on the fly by a self-signed root CA built
+into this machine (10-year validity). The tool result returns
+`ca_install_url`, the install link for that root CA's **public** certificate.
+
+## Two independent trust paths — diagnose this first
+
+- **Inside the Grix app** (image previews, in-app downloads): the app has a
+  built-in rule — a link on a tailnet address (`100.64.0.0/10`) whose
+  certificate issuer name contains `Grix Tailnet Local CA` is allowed through.
+  No certificate install is needed. If a link still fails in the app, the
+  cause is a non-tailnet IP or a mismatched issuer name, not a missing
+  certificate.
+- **System browser (Safari / Chrome)**: uses the device's system trust store,
+  which knows nothing about the app rule. The root CA must be installed once
+  per device. `NET::ERR_CERT_AUTHORITY_INVALID`, "impersonation", and
+  `NET::ERR_CERT_VALIDITY_TOO_LONG` in a user's screenshot are almost always
+  this path.
+
+Note: the in-app rule is a string match on the issuer name, not a pin on a
+specific CA key. It is a convenience inside a private tailnet, not a security
+boundary.
+
+## One-time install per device (system browser path)
+
+Each device needs this once; afterwards every link from this machine is
+warning-free for 10 years, even if the tailnet IP changes. Send the step
+matching the user's device:
+
+- **iPhone / iPad**: open `ca_install_url` in **Safari** (other browsers do
+  not trigger profile install) → "This website is trying to download a
+  configuration profile" → Allow → Settings shows "Profile Downloaded" at the
+  top; tap it to install → then Settings → General → About → Certificate
+  Trust Settings → enable full trust for the certificate. The last step is
+  mandatory. The server returns a `.mobileconfig` automatically.
+- **Mac**: download the `.crt` → double-click to open in Keychain Access →
+  find the certificate → double-click → expand "Trust" → set "When using this
+  certificate" to "Always Trust".
+- **Android**: download the `.crt` → Settings → Security → Encryption &
+  credentials → Install a certificate → CA certificate → pick the file
+  (recent Android versions require the Settings route).
+- **Windows**: double-click the `.crt` → "Install Certificate" → "Place all
+  certificates in the following store" → "Trusted Root Certification
+  Authorities".
+
+## Self-hosted HTTPS services are out of scope
+
+The built-in CA only makes `grix_file_link`'s own download service trusted. A
+service the user runs themselves (site / API / media server on the tailnet)
+uses its own CA that the device never installed, so the browser reports
+`not trusted / NET::ERR_CERT_AUTHORITY_INVALID` regardless of the Grix CA.
+
+Ways to make such a service trusted:
+
+1. Sign its certificate with a CA the device already trusts, keeping the leaf
+   validity ≤ 398 days (longer triggers `NET::ERR_CERT_VALIDITY_TOO_LONG`).
+   The Grix CA's private key never leaves the machine running the connector
+   (`ca_install_url` serves only the public certificate), so only services on
+   that same machine could borrow it.
+2. For in-app viewing only: serve on a tailnet IP with an issuer name
+   containing `Grix Tailnet Local CA` — the app rule then applies, but system
+   browsers still need that service's CA installed.
+3. Simplest: share files through `grix_file_link` instead.

package/dist/mcp/stream-http/security.js

@@ -1 +1 @@
-function a(o){const e=new Set([`http://127.0.0.1:${o.serverPort}`,`http://localhost:${o.serverPort}`,...o.allowedOrigins]),t=new Set([`127.0.0.1:${o.serverPort}`,`localhost:${o.serverPort}`,...o.allowedHosts]);return{validateRequest(s){const r=i(s,e);if(!r.ok)return r;const n=l(s,t);return n.ok?{ok:!0}:n}}}function i(o,e){const t=o.headers.origin;return t?e.has(t)?{ok:!0}:{ok:!1,statusCode:403,message:`Origin not allowed: ${t}`}:{ok:!0}}function l(o,e){const t=o.headers.host;return t?e.has(t)?{ok:!0}:{ok:!1,statusCode:403,message:`Host not allowed: ${t}`}:{ok:!1,statusCode:403,message:"Missing Host header"}}export{a as createSecurityPolicy};
+function a(e){const t=new Set([`http://127.0.0.1:${e.serverPort}`,`http://localhost:${e.serverPort}`,...e.allowedOrigins]),o=new Set([`127.0.0.1:${e.serverPort}`,`localhost:${e.serverPort}`,...e.allowedHosts]);return{validateRequest(s){const r=i(s,t);if(!r.ok)return r;const n=l(s,o);return n.ok?{ok:!0}:n}}}function i(e,t){const o=e.headers.origin;return o?t.has(o)?{ok:!0}:{ok:!1,statusCode:403,message:`Origin not allowed: ${o}`}:{ok:!0}}function l(e,t){const o=e.headers.host;return o?t.has(o)?{ok:!0}:{ok:!1,statusCode:403,message:`Host not allowed: ${o}`}:{ok:!1,statusCode:403,message:"Missing Host header"}}export{a as createSecurityPolicy};