@homespunapps/mcp 1.0.1 → 1.4.2

package/dist/tools.d.ts

@@ -39,6 +39,18 @@ export interface ToolEnv {
         markdown?: string;
         version?: string;
     }>;
+    /**
+     * Whether tool handlers may touch the HOST filesystem on behalf of the
+     * caller (readFileSync for html_path / file_path, writeFileSync for
+     * out_path). When absent or true, host filesystem access is allowed: the
+     * stdio / local CLI is a trusted local host, so this preserves the existing
+     * convenience of passing a local path. When explicitly false, host
+     * filesystem access is DENIED. The hosted multi-tenant relay sets this to
+     * false so an authenticated remote agent can never read or write the relay
+     * container's own files (a local file inclusion / exfiltration vector),
+     * e.g. deploy_app html_path=/app/.env.
+     */
+    hostFsReads?: boolean;
 }
 /** One registered tool: name, human/LLM description, Zod input shape, handler. */
 export interface ToolDef {

package/dist/tools.js

@@ -95,6 +95,11 @@ function str(args, key) {
     const v = args[key];
     return typeof v === "string" && v !== "" ? v : undefined;
 }
+/** Read a boolean arg; undefined when absent or not a boolean. */
+function bool(args, key) {
+    const v = args[key];
+    return typeof v === "boolean" ? v : undefined;
+}
 /** True for a non-null, non-array plain object (`{"type":"object"}` land). */
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -156,12 +161,22 @@ const deployAppShape = {
     html: z
         .string()
         .min(1)
-        .describe("The app's UI as a complete HTML document (single file, up to the relay's size cap)."),
+        .optional()
+        .describe("The app's UI as a complete HTML document (single file, up to the relay's size cap), sent INLINE. Provide EITHER this or `html_path`. Inline is required for a hosted/remote connector that has no filesystem. If both are given, inline `html` wins."),
+    html_path: z
+        .string()
+        .optional()
+        .describe("ABSOLUTE path to the app's HTML document, read on the MCP-SERVER host (the machine running this connector: the relay for a hosted connector, or your CLI host for a locally-run one), NOT on the remote agent's machine. Alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. Only works when the file is local to the MCP server, so it helps a locally-run connector, not a hosted/remote one (where the path will not exist and you get a clean error, so pass inline `html` there). If both `html` and `html_path` are given, inline `html` wins."),
+    dry_run: z
+        .boolean()
+        .optional()
+        .describe("Validate only: run the full manifest + asset-shape validation, the compat gate (for a redeploy), and the schedule-timezone advisory, then return { ok, warnings, compat?, breaks? } WITHOUT creating a version or mutating anything. An invalid manifest returns the SAME error a real deploy would; a narrowing redeploy reports the compat break instead of applying it. `check` is an accepted alias."),
+    check: z.boolean().optional().describe("Alias for `dry_run`."),
     manifest: jsonObjectSchema.describe("The x-homespun-manifest capability document (a JSON object). Eight extension keys: app metadata; collections (+ per-collection write/read/delete role lists); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules). Call get_skill for the full grammar before authoring one from scratch."),
     visibility: z
         .enum(["private", "link", "public"])
         .optional()
-        .describe("CREATE only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the URL and always gets a server-generated unguessable slug; 'private' and 'public' accept an owner-chosen `slug`."),
+        .describe("CREATE only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the returned share_url, whose #k= fragment carries a secret key that can be reset (rotate it via the apps tool, action share_link_rotate) to cut off everyone with the old link; a 'link' app always gets a server-generated unguessable slug. 'private' and 'public' accept an owner-chosen `slug`."),
     slug: z
         .string()
         .optional()
@@ -267,17 +282,18 @@ const appsShape = {
         "list",
         "show",
         "update",
+        "share_link_rotate",
         "delete",
         "wake",
         "domain_set",
         "domain_status",
         "domain_remove",
     ])
-        .describe("list: YOUR owning human's apps. show/update/delete/wake: act on one app (app_id). domain_set/domain_status/domain_remove: manage the app's ONE custom domain (app_id; domain_set also needs domain)."),
+        .describe("list: YOUR owning human's apps. show/update/delete/wake: act on one app (app_id). share_link_rotate: rotate a 'link' app's share token, returning a new share_url (the old link stops working); also generates one if the app has none yet. domain_set/domain_status/domain_remove: manage the app's ONE custom domain (app_id; domain_set also needs domain)."),
     app_id: z
         .string()
         .optional()
-        .describe("Required for show/update/delete/wake/domain_set/domain_status/domain_remove."),
+        .describe("Required for show/update/share_link_rotate/delete/wake/domain_set/domain_status/domain_remove."),
     status: z
         .enum(["active", "dormant", "archived", "all"])
         .optional()
@@ -298,6 +314,10 @@ const appsShape = {
         .enum(["private", "link", "public"])
         .optional()
         .describe("update only. The new visibility (slug is immutable)."),
+    timezone: z
+        .string()
+        .optional()
+        .describe("update only. The app's IANA timezone for `schedules` reminders (e.g. Europe/Berlin). An app that declares schedules with no timezone fires reminders at 08:00 UTC."),
     domain: z
         .string()
         .optional()
@@ -305,8 +325,8 @@ const appsShape = {
 };
 const membersShape = {
     action: z
-        .enum(["add", "list", "remove"])
-        .describe("add: invite-or-attach a member by email (app_id+email). list: the app's owner + members (app_id). remove: drop a member (app_id+human_id)."),
+        .enum(["add", "list", "set_role", "remove", "roles"])
+        .describe("add: invite-or-attach a member by email (app_id+email; optional custom_role). list: the app's owner + members (app_id). set_role: change an existing member's custom role in place without signing them out (app_id+human_id+custom_role, null to clear). remove: drop a member (app_id+human_id). roles: the app's declared roles with, per collection, the EFFECTIVE access a holder has (separately for members and grant-link holders, whose role floors differ) plus how many members and live grant links hold each role (app_id)."),
     app_id: z.string().min(1).describe("The app id."),
     email: z
         .string()
@@ -316,14 +336,71 @@ const membersShape = {
         .enum(["member"])
         .optional()
         .describe("add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here)."),
+    custom_role: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("add (optional) and set_role (required). A DECLARED custom role (an x-homespun-manifest.roles key) attached to the member ALONGSIDE their base member powers. A built-in/reserved role or an undeclared role is rejected. Omit on add for an ordinary member; pass null on set_role to clear the role back to a plain member."),
     human_id: z
         .string()
         .optional()
-        .describe("remove only. The Human id to remove — see list's `humanId` field. The app owner cannot be removed."),
+        .describe("remove and set_role. The Human id to target — see list's `humanId` field. The app owner can be neither removed nor re-roled."),
+};
+const ingestShape = {
+    action: z
+        .enum(["list", "rotate"])
+        .describe("list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name)."),
+    app_id: z.string().min(1).describe("The app id."),
+    name: z
+        .string()
+        .optional()
+        .describe("rotate only. The manifest ingest hook name to rotate (an x-homespun-manifest.ingest[].name). See list's `name` field."),
 };
 // ===========================================================================
 // Consolidated management tools
 // ===========================================================================
+const grantsShape = {
+    action: z
+        .enum(["mint", "list", "revoke"])
+        .describe("mint: create a grant link carrying a declared custom role (app_id+role). list: the app's grant links (app_id). revoke: revoke one link (app_id+grant_id)."),
+    app_id: z.string().min(1).describe("The app id."),
+    role: z
+        .string()
+        .optional()
+        .describe("mint only. A DECLARED custom role for the app (an x-homespun-manifest.roles key). A built-in role (owner/member/agent/anyone) is rejected: a grant can never escalate."),
+    mode: z
+        .enum(["once", "multi"])
+        .optional()
+        .describe("mint only. once: one-time link, claimed by the first browser that opens it (a real per-person link; later opens by others are inert). multi (default): a shared link, capped by max_uses within expiry."),
+    max_uses: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("mint only (multi mode). Cap total claims; omit for unlimited within expiry. Ignored for once (forced to 1)."),
+    label: z
+        .string()
+        .optional()
+        .describe("mint only. Optional owner label shown in the grant list."),
+    ttl_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("mint only. Grant lifetime in seconds; defaults to the server default (30 days) and is clamped to the server max."),
+    pin_row_key: z
+        .string()
+        .optional()
+        .describe("mint only. Optional narrowing pin to a single row key. NARROWS within the role (never widens). Mutually exclusive with pin_where."),
+    pin_where: z
+        .array(z.unknown())
+        .optional()
+        .describe("mint only. Optional narrowing pin as Wave C2 where conditions ({field, op, value}[]). NARROWS within the role (never widens). Mutually exclusive with pin_row_key."),
+    grant_id: z
+        .string()
+        .optional()
+        .describe("revoke only. The grant link id (see list's `id` field)."),
+};
 const attachmentsShape = {
     action: z
         .enum([
@@ -338,7 +415,7 @@ const attachmentsShape = {
         "revoke_token",
         "list_tokens",
     ])
-        .describe("Binary attachment operations. upload: send bytes as an attachment inline; pass `content_base64` (base64 bytes, no filesystem) when you have bytes but no local file (e.g. an image you generated) or you are a hosted/remote agent, or `file_path` (absolute, read on the RELAY host) when the file is local to the relay; scope agent|app. presign + finalize: the LARGE-FILE path (e.g. a video). presign returns a { put_url, attachment_id }, then YOU PUT the raw bytes to put_url over HTTP out-of-band (bytes never pass through this tool / the model context as base64), then finalize confirms it. download: fetch bytes by attachment_id to out_path (absolute) or return base64. show: metadata only. list: the agent's attachments. delete: soft-delete. mint_token: mint a /b/<token> capability URL (returned ONCE). revoke_token / list_tokens: manage those tokens."),
+        .describe("Binary attachment operations. PREFER presign + finalize for any real image or media (anything beyond a tiny icon): presign returns a { put_url, attachment_id }, then YOU PUT the raw bytes to put_url over HTTP out-of-band, so the bytes NEVER enter the model context and cost NO tokens. upload with `content_base64` sends the bytes INLINE in the tool-call arguments, which loads them into the model context and costs tokens PROPORTIONAL TO FILE SIZE (even a few-hundred-KB image is very costly); use it only as a fallback for small assets or clients that cannot PUT out-of-band. upload: `content_base64` (base64 bytes, no filesystem) when you have bytes but no local file, or `file_path` (absolute, read on the RELAY host) when the file is local to the relay; scope agent|app. presign + finalize: (1) presign with { mime, size, sha256, scope }, (2) PUT the bytes to put_url out-of-band, (3) finalize confirms it (re-sniffs + re-checks the bytes). download: fetch bytes by attachment_id to out_path (absolute) or return base64. show: metadata only. list: the agent's attachments. delete: soft-delete. mint_token: mint a /b/<token> capability URL (returned ONCE). revoke_token / list_tokens: manage those tokens."),
     size: z
         .number()
         .int()
@@ -360,7 +437,7 @@ const attachmentsShape = {
     content_base64: z
         .string()
         .optional()
-        .describe("upload: the file bytes as base64, uploaded WITHOUT any filesystem access. This is the upload path for hosted / remote agents (e.g. an image you just generated): pass it when you have bytes but no file on the relay host. If both `content_base64` and `file_path` are given, `content_base64` wins. The relay sniffs the real type and enforces the same size/allowlist/quota checks as a file upload."),
+        .describe("upload: the file bytes as base64, sent INLINE with no filesystem access. WARNING: the base64 rides in the tool-call arguments and enters the MODEL CONTEXT, costing tokens PROPORTIONAL TO FILE SIZE (a few-hundred-KB image is already very costly, and it compounds on every retry). PREFER presign + finalize for any real image or media whenever the client can do an out-of-band HTTP PUT; reserve `content_base64` for small assets (a tiny icon) or clients that cannot PUT out-of-band. If both `content_base64` and `file_path` are given, `content_base64` wins. The relay sniffs the real type and enforces the same size/allowlist/quota checks as a file upload."),
     scope: z
         .enum(["agent", "app"])
         .optional()
@@ -412,8 +489,8 @@ const tasteShape = {
 };
 const keyShape = {
     action: z
-        .enum(["list", "revoke"])
-        .describe("The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). revoke: self-destruct the agent's OWN key — it stops working immediately and is irreversible (requires confirm:true)."),
+        .enum(["list", "revoke", "mint"])
+        .describe("The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). mint: mint a NEW sibling API key for YOUR OWN agent identity (same scope/ownership) and return its raw value ONCE, so use it to hand a CLI or child process a working credential; the sibling is a distinct key that shows up in a subsequent `list` made WITH it, the owner can revoke it, and the raw value is never retrievable again. mint always acts on the calling agent, never another agent's id. revoke: self-destruct the agent's OWN key, which stops working immediately and is irreversible (requires confirm:true)."),
     confirm: z.boolean().optional().describe("Required (true) for revoke."),
 };
 const feedbackShape = {
@@ -455,8 +532,15 @@ const agentShape = {
 };
 const communityShape = {
     action: z
-        .enum(["publish", "list_pending", "get_submission", "approve", "reject"])
-        .describe("publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). The capture (html + manifest + the seed rows of seedOnInstall collections) lands PENDING review, installable by its returned direct link but not listed until approved. list_pending / get_submission / approve / reject are RELAY-OPERATOR-only review actions: list_pending (the review queue), get_submission (a submission's full html+manifest+seedRows, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed)."),
+        .enum([
+        "publish",
+        "list_pending",
+        "get_submission",
+        "approve",
+        "reject",
+        "set_trust_level",
+    ])
+        .describe("publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). PRIVACY: publishing makes the template content AND the captured seed rows (the LIVE rows of every seedOnInstall collection, captured at publish time) PUBLIC to every platform user once approved. Do NOT publish an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private): seed data must be example-only. Pass attest_example_only:true to attest you have checked this. The capture (html + manifest + seed rows) lands PENDING review, installable by its returned direct link but not listed until approved; an ESTABLISHED publisher is fast-tracked (the response's expedited/auto_approved tell you which). list_pending / get_submission / approve / reject / set_trust_level are RELAY-OPERATOR-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established')."),
     app_id: z
         .string()
         .optional()
@@ -469,6 +553,10 @@ const communityShape = {
         .string()
         .optional()
         .describe("publish only. Listing blurb (up to 200 chars). Defaults to the manifest description."),
+    long_description: z
+        .string()
+        .optional()
+        .describe("publish only. Optional long-form description (up to 4000 chars) shown on the template detail page below the short blurb, for readers and search ranking. Plain text: blank lines become paragraphs, and it is escaped (never rendered as raw HTML), so write prose, not markup."),
     category: z
         .string()
         .optional()
@@ -477,6 +565,63 @@ const communityShape = {
         .array(z.string())
         .optional()
         .describe("publish only. Up to 6 curation tags."),
+    slug: z
+        .string()
+        .optional()
+        .describe("publish only. Optional per-publisher slug (lowercase, 3 to 48 chars, hyphens). Gives the template a namespaced id <your-handle>/<slug>; a republish reuses the slug and must bump the version."),
+    version: z
+        .string()
+        .optional()
+        .describe("publish only. Semver MAJOR.MINOR.PATCH (default '1.0.0'). A republish under the same slug must be strictly greater than the current version."),
+    changelog_note: z
+        .string()
+        .optional()
+        .describe("publish only. A short note recorded in this version's changelog."),
+    setup_steps: z
+        .array(z.object({
+        kind: z
+            .enum(["config", "seed-data", "connect", "note", "upload"])
+            .describe("config = set a value; upload = an install-time file/image the app stores as an attachment id; connect = wire up an external data source; seed-data = review/replace captured starter data; note = a plain instruction."),
+        label: z.string().describe("Short step label (<= 80 chars)."),
+        key: z
+            .string()
+            .optional()
+            .describe("The settings-collection field this answer is written into (letters, digits, '_', up to 64 chars). Required for an 'upload' step, optional for a 'config' step, not allowed on the others. Must name a declared top-level field of the manifest's x-homespun-manifest.settingsCollection; an 'upload' target must be a string-typed field."),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional longer instruction (<= 300 chars)."),
+        required: z
+            .boolean()
+            .optional()
+            .describe("Whether this step is required (default false)."),
+        secret: z
+            .boolean()
+            .optional()
+            .describe("Mark a step whose value is sensitive (an API key/token). Its default is MASKED on the public detail page; publish only your own example default, never a real secret."),
+        default: z
+            .string()
+            .optional()
+            .describe("Optional example/default value (<= 200 chars)."),
+        choices: z
+            .array(z.string())
+            .optional()
+            .describe("Optional list of allowed values (up to 12)."),
+        valueHint: z
+            .string()
+            .optional()
+            .describe("Optional format hint (<= 120 chars)."),
+    }))
+        .optional()
+        .describe("publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into. Read back via get_submission and rendered on the template detail page."),
+    derived_from_snapshot_id: z
+        .string()
+        .optional()
+        .describe("publish only. Optional remix/fork lineage: the snapshot id this template was derived from."),
+    attest_example_only: z
+        .boolean()
+        .optional()
+        .describe("publish only. Set true to attest that the template content AND the captured seed rows contain NO real personal data. Publishing makes both PUBLIC to every platform user, so seed data (the live rows of your seedOnInstall collections) must be example-only, never real names/emails/addresses/private messages. Recorded and shown to the reviewer; omitting it still publishes but is flagged to the operator as not attested."),
     snapshot_id: z
         .string()
         .optional()
@@ -496,6 +641,79 @@ const communityShape = {
         .string()
         .optional()
         .describe("list_pending only. Opaque cursor from a prior next_cursor."),
+    handle: z
+        .string()
+        .optional()
+        .describe("set_trust_level only. The @-handle of the publisher to promote or demote."),
+    trust_level: z
+        .enum(["new", "established"])
+        .optional()
+        .describe("set_trust_level only. 'established' fast-tracks the publisher's future submissions through review; 'new' reverts to full review."),
+};
+const publisherShape = {
+    action: z
+        .enum(["claim", "get", "update"])
+        .describe("get: return YOUR publisher profile (handle, tenure, counters). claim: set your @-handle ONCE (handle arg; lowercase, 3 to 32 chars, permanent after claiming; needs a verified email). update: change your public display_name/bio/url (any of them; needs a verified email)."),
+    handle: z
+        .string()
+        .optional()
+        .describe("claim only. The lowercase @-handle to claim (^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$). Permanent once claimed."),
+    display_name: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("update only. Public display name (up to 80 chars); null clears it."),
+    bio: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("update only. Short public bio (up to 500 chars); null clears it."),
+    url: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("update only. Public http(s) URL (up to 200 chars); null clears it."),
+};
+const reviewShape = {
+    action: z
+        .enum(["create", "respond", "report", "remove", "unhold"])
+        .describe('create: leave a star rating (1..5) and optional body on a community template YOU have installed (identify it by `template` "<handle>/<slug>" or by `handle`+`slug`); requires a verified email, and one review per install. A body containing a link or contact email is auto-held for a moderator before it shows. respond: reply to a review of one of YOUR OWN templates (review_id + response; null clears it). report: flag a review for the relay\'s moderators (review_id + reason; one report per account). remove / unhold are RELAY-OPERATOR-only moderation actions on a review_id: remove takes a review down (adjusting the aggregate), unhold publishes a previously auto-held review.'),
+    template: z
+        .string()
+        .optional()
+        .describe("create only. The namespaced template id <handle>/<slug> to review."),
+    handle: z
+        .string()
+        .optional()
+        .describe("create only. Publisher handle (with `slug`), an alternative to `template`."),
+    slug: z
+        .string()
+        .optional()
+        .describe("create only. Per-publisher slug (with `handle`)."),
+    stars: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("create only. Star rating, an integer 1 to 5."),
+    body: z
+        .string()
+        .optional()
+        .describe("create only. Optional written review (up to 2000 chars)."),
+    review_id: z
+        .string()
+        .optional()
+        .describe("Required for respond/report/remove/unhold. The review's id."),
+    response: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("respond only. The publisher's public response (up to 2000 chars); null clears it."),
+    reason: z
+        .string()
+        .optional()
+        .describe("report only. Why you are reporting this review (up to 500 chars)."),
 };
 const getSkillShape = {
     version_only: z
@@ -510,7 +728,7 @@ export const TOOLS = [
     // ----- v2 app lifecycle + data (discrete, hot-path) -----------------------
     {
         name: "deploy_app",
-        description: 'Deploy a v2 app: an HTML document + a capability manifest, hosted at its own URL. The manifest has eight extension keys: app metadata; collections (+ per-collection write/read/delete role lists); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules). Pass EITHER no `app_id` (create, mints a slug + URL) OR `app_id` (redeploy an existing app with new content). A redeploy that NARROWS the manifest (drops a collection, tightens a schema, revokes a role) is refused with manifest_incompatible_redeploy unless force:true; a narrowed collection is then detached, never deleted. Ship images/fonts/audio/video/data FILES with the app in the SAME call via `assets[]`: each is validated + stored app-scoped and served at its `path` on the app\'s own origin, so the HTML references it by a stable same-origin path (`<img src="frames/000.jpg">`, `<video src="media/clip.mp4">`), media and font paths support HTTP Range for seeking. A redeploy\'s assets replace the previous version\'s set. BEFORE authoring: call get_skill for the manifest grammar. Returns { app_id, slug, url, version, visibility, created } (create) or { app_id, version, compat, breaks? } (redeploy).',
+        description: "Deploy a v2 app: an HTML document + a capability manifest, hosted at its own URL. The manifest has eight extension keys: app metadata; collections (+ per-collection write/read/delete role lists); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules). Pass EITHER no `app_id` (create, mints a slug + URL) OR `app_id` (redeploy an existing app with new content). Supply the HTML as INLINE `html` OR as `html_path` (an absolute path read on the MCP-SERVER host, which is the relay for a hosted connector or your CLI host for a locally-run one, NOT the remote agent's machine; use it to avoid retransmitting a large HTML file every deploy, but only a locally-run connector can read it, and if both are given inline `html` wins). Pass `dry_run:true` (alias `check`) to VALIDATE ONLY: it runs the full manifest + asset-shape validation, the redeploy compat gate, and the schedule-timezone advisory, then returns { ok, warnings, compat?, breaks? } WITHOUT creating a version or mutating anything. A redeploy that NARROWS the manifest (drops a collection, tightens a schema, revokes a role) is refused with manifest_incompatible_redeploy unless force:true; a narrowed collection is then detached, never deleted. Ship images/fonts/audio/video/data FILES with the app in the SAME call via `assets[]`: each is validated + stored app-scoped and served at its `path` on the app's own origin, so the HTML references it by a stable same-origin path (`<img src=\"frames/000.jpg\">`, `<video src=\"media/clip.mp4\">`), media and font paths support HTTP Range for seeking. A redeploy's assets replace the previous version's set. BEFORE authoring: call get_skill for the manifest grammar. Returns { app_id, slug, url, version, visibility, created } (create) or { app_id, version, compat, breaks? } (redeploy).",
         inputSchema: deployAppShape,
         annotations: {
             title: "Deploy App",
@@ -519,15 +737,44 @@ export const TOOLS = [
             idempotentHint: false,
             openWorldHint: true,
         },
-        handler: async (client, args) => {
+        handler: async (client, args, env) => {
             try {
                 const manifest = parseMaybeStringifiedObject(args["manifest"], "manifest");
                 if ("error" in manifest)
                     return manifest.error;
+                // Resolve the HTML from INLINE `html` or from `html_path` (read on the
+                // MCP-server host). Inline wins when both are given: an explicit `html`
+                // is a deliberate inline deploy, so never read a file the caller also
+                // happened to name. `html_path` is read here (on the MCP server / relay
+                // host), NOT on the calling agent's machine; a hosted connector's host
+                // is Homespun's infra, so a remote agent's path ENOENTs; say so.
+                const inlineHtml = str(args, "html");
+                const htmlPath = str(args, "html_path");
+                let html = inlineHtml;
+                if (html === undefined && htmlPath !== undefined) {
+                    if (env?.hostFsReads === false) {
+                        return invalidArgs("html_path is not available on this connection: the hosted relay does not read files from its own host on your behalf. Pass the HTML inline as `html` instead.");
+                    }
+                    try {
+                        html = readFileSync(htmlPath, "utf8");
+                    }
+                    catch (e) {
+                        return invalidArgs(`failed to read html_path '${htmlPath}' (${e instanceof Error ? e.message : String(e)}). Note: html_path is read on the MCP server / relay host, not on your machine, so it only works when the file is local to the connector (e.g. a locally-run CLI). For a hosted or remote agent, pass the HTML inline as \`html\` instead.`);
+                    }
+                }
+                const dryRun = args["dry_run"] === true || args["check"] === true;
+                const assets = args["assets"];
                 const appId = str(args, "app_id");
                 if (appId === undefined) {
-                    if (str(args, "html") === undefined) {
-                        return invalidArgs("create requires `html`");
+                    if (html === undefined) {
+                        return invalidArgs("create requires `html` or `html_path`");
+                    }
+                    if (dryRun) {
+                        return jsonResult(await client.checkDeploy({
+                            html,
+                            manifest: manifest.value,
+                            assets,
+                        }));
                     }
                     const slug = str(args, "slug");
                     const visibility = args["visibility"];
@@ -535,24 +782,33 @@ export const TOOLS = [
                         return invalidArgs("a `slug` is not allowed with visibility 'link' (link slugs are server-generated); drop visibility 'link', or omit slug");
                     }
                     return jsonResult(await client.deployApp({
-                        html: String(args["html"]),
+                        html,
                         manifest: manifest.value,
                         visibility,
                         slug,
-                        assets: args["assets"],
+                        assets,
                     }));
                 }
-                if (str(args, "html") === undefined) {
-                    return invalidArgs("redeploy requires `html`");
+                if (html === undefined) {
+                    return invalidArgs("redeploy requires `html` or `html_path`");
+                }
+                if (dryRun) {
+                    return jsonResult(await client.checkDeploy({
+                        app_id: appId,
+                        html,
+                        manifest: manifest.value,
+                        force: args["force"],
+                        assets,
+                    }));
                 }
                 if (args["slug"] !== undefined || args["visibility"] !== undefined) {
                     return invalidArgs("slug/visibility cannot change on redeploy — slug is immutable, visibility changes via the `apps` tool (action: update)");
                 }
                 const redeployed = await client.redeployApp(appId, {
-                    html: String(args["html"]),
+                    html,
                     manifest: manifest.value,
                     force: args["force"],
-                    assets: args["assets"],
+                    assets,
                 });
                 return jsonResult(redeployed);
             }
@@ -701,7 +957,7 @@ export const TOOLS = [
     },
     {
         name: "apps",
-        description: "Manage v2 app lifecycle (deploy_app creates/redeploys; this tool covers the rest). ONE tool with an `action` enum: list (YOUR owning human's apps) | show (full detail incl. manifest) | update (visibility only - slug is immutable) | delete (soft-delete, idempotent) | wake (a dormant app; a no-op reporting the actual status otherwise) | domain_set (bind ONE custom domain; returns the DNS records the domain owner must publish) | domain_status (the domain record, live-refreshed against Cloudflare when enabled; inspect last_error when it is not activating) | domain_remove (unbind the domain, idempotent).",
+        description: "Manage v2 app lifecycle (deploy_app creates/redeploys; this tool covers the rest). ONE tool with an `action` enum: list (YOUR owning human's apps) | show (full detail incl. manifest, timezone, has_share_token) | update (visibility and/or timezone - slug is immutable; switching TO 'link' returns a share_url once) | share_link_rotate (rotate a 'link' app's share token, returning a new share_url and revoking the old link; also generates one if the app has none) | delete (soft-delete, idempotent) | wake (a dormant app; a no-op reporting the actual status otherwise) | domain_set (bind ONE custom domain; returns the DNS records the domain owner must publish) | domain_status (the domain record, live-refreshed against Cloudflare when enabled; inspect last_error when it is not activating) | domain_remove (unbind the domain, idempotent).",
         inputSchema: appsShape,
         // Consolidated tool: read actions (list/show) + mutating ones (update/
         // delete/wake). Hint reflects delete, the most-privileged action.
@@ -733,20 +989,36 @@ export const TOOLS = [
                             return invalidArgs("show requires `app_id`");
                         }
                         return jsonResult(await client.getApp(String(args["app_id"])));
-                    case "update":
+                    case "update": {
                         if (str(args, "app_id") === undefined) {
                             return invalidArgs("update requires `app_id`");
                         }
-                        if (str(args, "visibility") === undefined) {
-                            return invalidArgs("update requires `visibility`");
+                        if (str(args, "visibility") === undefined &&
+                            str(args, "timezone") === undefined) {
+                            return invalidArgs("update requires `visibility` and/or `timezone`");
                         }
-                        return jsonResult(await client.updateApp(String(args["app_id"]), args["visibility"]));
+                        return jsonResult(await client.updateApp(String(args["app_id"]), {
+                            ...(args["visibility"] !== undefined
+                                ? {
+                                    visibility: args["visibility"],
+                                }
+                                : {}),
+                            ...(args["timezone"] !== undefined
+                                ? { timezone: String(args["timezone"]) }
+                                : {}),
+                        }));
+                    }
                     case "delete":
                         if (str(args, "app_id") === undefined) {
                             return invalidArgs("delete requires `app_id`");
                         }
                         await client.deleteApp(String(args["app_id"]));
                         return jsonResult({ app_id: args["app_id"], deleted: true });
+                    case "share_link_rotate":
+                        if (str(args, "app_id") === undefined) {
+                            return invalidArgs("share_link_rotate requires `app_id`");
+                        }
+                        return jsonResult(await client.rotateShareLink(String(args["app_id"])));
                     case "wake":
                         if (str(args, "app_id") === undefined) {
                             return invalidArgs("wake requires `app_id`");
@@ -782,7 +1054,7 @@ export const TOOLS = [
     },
     {
         name: "members",
-        description: "Manage a v2 app's membership (auth spec §6) — who besides the app's owner can sign in to a private app / write to member-scoped collections. ONE tool with an `action` enum: add (invite-or-attach a member by email — attaches immediately if the email already has a Human, otherwise the relay emails a magic-link invite) | list (the app's owner + members) | remove (idempotent; also revokes the human's live sessions on this app — the app owner cannot be removed).",
+        description: "Manage a v2 app's membership (auth spec §6) — who besides the app's owner can sign in to a private app / write to member-scoped collections. ONE tool with an `action` enum: add (invite-or-attach a member by email — attaches immediately if the email already has a Human, otherwise the relay emails a magic-link invite) | list (the app's owner + members) | set_role (change an existing member's declared custom role in place, or null to clear it — does NOT revoke their sessions, so use this rather than remove-then-add to re-role someone) | remove (idempotent; also revokes the human's live sessions on this app — the app owner cannot be removed) | roles (the derived roles summary: per declared role and collection, the EFFECTIVE access a holder actually has, reported separately for signed-in members and for grant-link holders since their role floors differ, plus member and active-grant-link counts).",
         inputSchema: membersShape,
         // Consolidated tool: read action (list) + mutating ones (add/remove).
         // Hint reflects remove, the most-privileged action.
@@ -810,10 +1082,29 @@ export const TOOLS = [
                             ...(args["role"] !== undefined
                                 ? { role: args["role"] }
                                 : {}),
+                            ...(args["custom_role"] !== undefined
+                                ? { customRole: String(args["custom_role"]) }
+                                : {}),
                         }));
                     }
                     case "list":
                         return jsonResult(await client.listAppMembers(appId));
+                    case "roles":
+                        return jsonResult(await client.listAppRoles(appId));
+                    case "set_role": {
+                        if (str(args, "human_id") === undefined) {
+                            return invalidArgs("set_role requires `human_id`");
+                        }
+                        // The key must be PRESENT: null means "clear the role", which is a
+                        // real instruction, so an omitted key cannot be read as one.
+                        const role = args["custom_role"];
+                        if (role === undefined) {
+                            return invalidArgs("set_role requires `custom_role` (a declared role name, or null to clear it)");
+                        }
+                        return jsonResult(await client.setAppMemberRole(appId, String(args["human_id"]), {
+                            customRole: role === null ? null : String(role),
+                        }));
+                    }
                     case "remove": {
                         if (str(args, "human_id") === undefined) {
                             return invalidArgs("remove requires `human_id`");
@@ -835,9 +1126,127 @@ export const TOOLS = [
         },
     },
     // ----- consolidated management tools --------------------------------------
+    {
+        name: "grants",
+        description: "Manage a v2 app's grant links (M5). A grant link is a capability URL that confers a DECLARED custom role (x-homespun-manifest.roles) on a stable, per-holder anonymous identity, so the holder's own rows are isolated by author/:own scoping. A grant NEVER escalates to owner/member/agent. ONE tool with an `action` enum: mint (create a link; returns a `grant_url` carrying the token in its #g= fragment, shown ONCE, never recoverable) | list (the app's links, never any token) | revoke (idempotent). mode once = one-time (first-browser-claims), multi = shared (capped by max_uses within expiry). An optional pin (pin_row_key OR pin_where) NARROWS the holder to specific rows, never widens. Note: a write-only grant pinned to a single row key can still read that row's existing data back via create dedup, so a 'write-only to slot X' grant exposes slot X's current contents to the holder.",
+        inputSchema: grantsShape,
+        // Consolidated tool: read action (list) + mutating ones (mint/revoke).
+        // Hint reflects revoke, the most-privileged action.
+        annotations: {
+            title: "Manage App Grant Links",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            if (str(args, "app_id") === undefined) {
+                return invalidArgs(`${action} requires \`app_id\``);
+            }
+            const appId = String(args["app_id"]);
+            try {
+                switch (action) {
+                    case "mint": {
+                        if (str(args, "role") === undefined) {
+                            return invalidArgs("mint requires `role`");
+                        }
+                        const pinRowKey = str(args, "pin_row_key");
+                        const pinWhere = Array.isArray(args["pin_where"])
+                            ? args["pin_where"]
+                            : undefined;
+                        if (pinRowKey !== undefined && pinWhere !== undefined) {
+                            return invalidArgs("mint accepts either `pin_row_key` or `pin_where`, not both");
+                        }
+                        const pin = pinRowKey !== undefined
+                            ? { rowKey: pinRowKey }
+                            : pinWhere !== undefined
+                                ? { where: pinWhere }
+                                : undefined;
+                        return jsonResult(await client.mintAppGrant(appId, {
+                            role: String(args["role"]),
+                            ...(args["mode"] !== undefined
+                                ? { mode: args["mode"] }
+                                : {}),
+                            ...(typeof args["max_uses"] === "number"
+                                ? { maxUses: args["max_uses"] }
+                                : {}),
+                            ...(str(args, "label") !== undefined
+                                ? { label: String(args["label"]) }
+                                : {}),
+                            ...(typeof args["ttl_seconds"] === "number"
+                                ? { ttlSeconds: args["ttl_seconds"] }
+                                : {}),
+                            ...(pin !== undefined ? { pin } : {}),
+                        }));
+                    }
+                    case "list":
+                        return jsonResult(await client.listAppGrants(appId));
+                    case "revoke": {
+                        if (str(args, "grant_id") === undefined) {
+                            return invalidArgs("revoke requires `grant_id`");
+                        }
+                        await client.revokeAppGrant(appId, String(args["grant_id"]));
+                        return jsonResult({
+                            app_id: appId,
+                            grant_id: args["grant_id"],
+                            revoked: true,
+                        });
+                    }
+                    default:
+                        return invalidArgs(`unknown grants action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    // ----- consolidated management tools --------------------------------------
+    {
+        name: "ingest",
+        description: "Manage a v2 app's inbound catch-hooks (inbound-webhooks). A catch-hook lets an EXTERNAL system (Stripe, Zapier, Make, Home Assistant, an email router) POST JSON to a secret URL that writes into a declared collection, so the app receives data even with no agent online. Hooks are DECLARED IN THE MANIFEST (x-homespun-manifest.ingest) and materialized at deploy, so this tool has no create/delete: use it to READ BACK the URL and rotate a leaked one. ONE tool with an `action` enum: list (the app's hooks, each with its full secret URL, current rule collection/mode/wake/handshake, and per-status delivery counts) | rotate (mint a fresh secret for one hook by name and return its NEW url once; the old url stops working immediately, no redeploy needed). After deploying a manifest that declares a hook, run list and tell the owner the exact url to paste into the external system.",
+        inputSchema: ingestShape,
+        // Consolidated tool: read action (list) + a mutating one (rotate). Marked
+        // destructive (not read-only) because rotate invalidates the old URL, which
+        // breaks any external system still using it, following the same "any
+        // consolidated tool that can mutate is destructive" convention as members/
+        // grants/apps.
+        annotations: {
+            title: "Manage App Inbound Hooks",
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            if (str(args, "app_id") === undefined) {
+                return invalidArgs(`${action} requires \`app_id\``);
+            }
+            const appId = String(args["app_id"]);
+            try {
+                switch (action) {
+                    case "list":
+                        return jsonResult(await client.listIngestHooks(appId));
+                    case "rotate": {
+                        if (str(args, "name") === undefined) {
+                            return invalidArgs("rotate requires `name`");
+                        }
+                        return jsonResult(await client.rotateIngestHook(appId, String(args["name"])));
+                    }
+                    default:
+                        return invalidArgs(`unknown ingest action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    // ----- consolidated management tools --------------------------------------
     {
         name: "attachments",
-        description: "Binary attachments (images, PDFs, audio, video) referenced from event payloads / input_data via `format: homespun-attachment-id`. ONE tool with an `action` enum: upload | presign | finalize | download | show | list | delete | mint_token | revoke_token | list_tokens. upload (inline) takes EITHER `content_base64` (base64 bytes, no filesystem; use when you generated the bytes in-session or run as a hosted/remote agent) OR `file_path` (ABSOLUTE path read on the RELAY host, only usable when the file is local to the relay). FOR A LARGE FILE (e.g. a video) use presign + finalize instead of base64: (1) presign with { mime, size, sha256, scope } returns { put_url, attachment_id }; (2) YOU PUT the raw bytes to put_url over plain HTTP out-of-band, so the bytes never route through this tool or the model context, which is why base64 inline is impractical at that size; (3) finalize with the attachment_id. At finalize the relay re-reads the stored bytes, BYTE-SNIFFS the real type, and enforces the same allowlist + size + sha256 + quota + scan checks as any upload, so a presign that lies about its mime is caught and never served inline. The presigned path requires the Azure storage backend; a filesystem self-host returns a clear not-supported error (use inline upload there). download writes to an ABSOLUTE out_path (or returns base64). Scope an upload to agent (default, reusable) or app. mint_token returns a /b/<token> capability URL (ONCE) a browser can GET without your API key.",
+        description: "Binary attachments (images, PDFs, audio, video) referenced from event payloads / input_data via `format: homespun-attachment-id`. ONE tool with an `action` enum: upload | presign | finalize | download | show | list | delete | mint_token | revoke_token | list_tokens. TOKEN COST, READ FIRST: an inline `upload` with `content_base64` carries the bytes in the tool-call arguments, so they enter the MODEL CONTEXT and cost tokens PROPORTIONAL TO FILE SIZE (a few-hundred-KB image is already very costly, worse on every retry). PREFER presign + finalize for ANY real image or media (anything beyond a tiny icon) whenever the client can do an out-of-band HTTP PUT, because the bytes then never touch the model context. upload (inline) takes EITHER `content_base64` (base64 bytes, no filesystem; use for SMALL assets or clients that cannot PUT out-of-band) OR `file_path` (ABSOLUTE path read on the RELAY host, only usable when the file is local to the relay). presign + finalize (the token-free path, for images/video/big audio): (1) presign with { mime, size, sha256, scope } returns { put_url, attachment_id }; (2) YOU PUT the raw bytes to put_url over plain HTTP out-of-band, so the bytes never route through this tool or the model context; (3) finalize with the attachment_id. At finalize the relay re-reads the stored bytes, BYTE-SNIFFS the real type, and enforces the same allowlist + size + sha256 + quota + scan checks as any upload, so a presign that lies about its mime is caught and never served inline. The presigned path requires the Azure storage backend; a filesystem self-host returns a clear not-supported error (use inline upload there). download writes to an ABSOLUTE out_path (or returns base64). Scope an upload to agent (default, reusable) or app. mint_token returns a /b/<token> capability URL (ONCE) a browser can GET without your API key.",
         inputSchema: attachmentsShape,
         // Consolidated tool: read actions (download/show/list/list_tokens) +
         // mutating ones (upload/delete/mint_token/revoke_token). openWorld:true
@@ -850,7 +1259,7 @@ export const TOOLS = [
             idempotentHint: false,
             openWorldHint: true,
         },
-        handler: async (client, args) => {
+        handler: async (client, args, env) => {
             const action = String(args["action"]);
             try {
                 switch (action) {
@@ -878,6 +1287,9 @@ export const TOOLS = [
                             return jsonResult(ref);
                         }
                         let bytes;
+                        if (env?.hostFsReads === false) {
+                            return invalidArgs("file_path is not available on this connection: the hosted relay does not read files from its own host on your behalf. Pass `content_base64` with the file bytes instead.");
+                        }
                         try {
                             bytes = readFileSync(filePath);
                         }
@@ -939,6 +1351,9 @@ export const TOOLS = [
                         const buf = await client.downloadBlob(String(args["attachment_id"]));
                         const outPath = str(args, "out_path");
                         if (outPath !== undefined) {
+                            if (env?.hostFsReads === false) {
+                                return invalidArgs("out_path is not available on this connection: the hosted relay does not write files to its own host on your behalf. Omit out_path to receive the bytes as base64 instead.");
+                            }
                             try {
                                 writeFileSync(outPath, Buffer.from(buf));
                             }
@@ -1038,7 +1453,7 @@ export const TOOLS = [
     },
     {
         name: "key",
-        description: "Inspect or revoke the calling agent's API key. ONE tool with an `action` enum: list (key info — agent_id, key_prefix, timestamps) | revoke (self-destruct the agent's OWN key; it stops working immediately and is irreversible — pass confirm:true). The relay scopes keys to the caller, so both act only on your own key.",
+        description: "Inspect, mint, or revoke the calling agent's API key. ONE tool with an `action` enum: list (key info: agent_id, key_prefix, timestamps) | mint (mint a NEW sibling API key for YOUR OWN agent identity, same scope/ownership, and return its raw value ONCE, the way an MCP-driven agent bootstraps a CLI/child-process credential; the raw key is never retrievable again, the sibling appears in a `list` made WITH it, and the owner can revoke it) | revoke (self-destruct the agent's OWN key; it stops working immediately and is irreversible, so pass confirm:true). The relay derives identity from the caller's token, so every action acts only on the caller's own agent, and mint can never target another agent's id.",
         inputSchema: keyShape,
         // Consolidated tool: read action (list) + a mutating one (revoke
         // self-destructs the agent's own key). Hint reflects the destructive
@@ -1056,6 +1471,12 @@ export const TOOLS = [
                 switch (action) {
                     case "list":
                         return jsonResult(await client.listKeys());
+                    case "mint":
+                        // Mints a sibling key for the CALLER's own identity (the relay
+                        // derives it from the bearer token, and no target field exists, so it
+                        // can never target another agent). The raw key is in this response
+                        // ONCE and never again.
+                        return jsonResult(await client.mintKey());
                     case "revoke": {
                         if (args["confirm"] !== true) {
                             return invalidArgs("revoke is irreversible and stops your key working immediately — pass confirm:true");
@@ -1159,7 +1580,7 @@ export const TOOLS = [
     },
     {
         name: "community",
-        description: "Publish an app you own as a COMMUNITY TEMPLATE, and (relay operators only) review submissions. ONE tool with an `action` enum: publish | list_pending | get_submission | approve | reject. publish captures your live app (html + manifest + the seed rows of its seedOnInstall collections + listing metadata) into a PENDING template - installable by the returned direct link but NOT listed in the public gallery until an operator approves it; you must have a verified email and at most a few pending submissions at once. The review actions are limited to the relay's configured community reviewers: list_pending (the queue), get_submission (a submission's full content by snapshot_id), approve (list it in the gallery; a re-publish supersedes your app's prior approved version), reject (with a required note that lands in the publisher's app feed).",
+        description: "Publish an app you own as a COMMUNITY TEMPLATE, and (relay operators only) review submissions. ONE tool with an `action` enum: publish | list_pending | get_submission | approve | reject. publish captures your live app (html + manifest + the seed rows of its seedOnInstall collections + listing metadata) into a PENDING template - installable by the returned direct link but NOT listed in the public gallery until an operator approves it; you must have a verified email and at most a few pending submissions at once. PRIVACY: an approved template's content AND its captured seed rows become PUBLIC to every platform user, so never publish an app whose seedOnInstall collections hold real personal data - seed data must be example-only. Pass attest_example_only:true to attest you checked this. Optionally give the template a per-publisher `slug` (namespaced id <your-handle>/<slug>) and a semver `version` (default 1.0.0): a republish under the same slug must bump the version. The review actions are limited to the relay's configured community reviewers: list_pending (the queue), get_submission (a submission's full content by snapshot_id), approve (list it in the gallery; a re-publish supersedes your app's prior approved version), reject (with a required note that lands in the publisher's app feed).",
         inputSchema: communityShape,
         // Consolidated tool: read actions (list_pending/get_submission) + mutating
         // ones (publish/approve/reject). Hint reflects the most-privileged action.
@@ -1182,10 +1603,19 @@ export const TOOLS = [
                             appId: String(args["app_id"]),
                             title: str(args, "title"),
                             description: str(args, "description"),
+                            longDescription: str(args, "long_description"),
                             category: str(args, "category"),
                             tags: Array.isArray(args["tags"])
                                 ? args["tags"]
                                 : undefined,
+                            slug: str(args, "slug"),
+                            version: str(args, "version"),
+                            changelogNote: str(args, "changelog_note"),
+                            setupSteps: Array.isArray(args["setup_steps"])
+                                ? args["setup_steps"]
+                                : undefined,
+                            derivedFromSnapshotId: str(args, "derived_from_snapshot_id"),
+                            attestExampleOnly: bool(args, "attest_example_only"),
                         }));
                     }
                     case "list_pending": {
@@ -1216,6 +1646,17 @@ export const TOOLS = [
                         }
                         return jsonResult(await client.reviewCommunitySubmission(String(args["snapshot_id"]), { decision: "reject", note }));
                     }
+                    case "set_trust_level": {
+                        const handle = str(args, "handle");
+                        if (handle === undefined) {
+                            return invalidArgs("set_trust_level requires `handle`");
+                        }
+                        const trustLevel = str(args, "trust_level");
+                        if (trustLevel !== "new" && trustLevel !== "established") {
+                            return invalidArgs("set_trust_level requires `trust_level` of 'new' or 'established'");
+                        }
+                        return jsonResult(await client.setPublisherTrustLevel(handle, trustLevel));
+                    }
                     default:
                         return invalidArgs(`unknown community action '${action}'`);
                 }
@@ -1225,6 +1666,134 @@ export const TOOLS = [
             }
         },
     },
+    {
+        name: "publisher",
+        description: "Manage YOUR community publisher identity: the @-handle and public profile you present in the template gallery. ONE tool with an `action` enum: claim | get | update. get returns your profile (handle, whether it is claimed yet, tenure, and the rating/template counters). claim sets your handle exactly ONCE (it is permanent afterwards) from a lowercase 3-to-32-char string; a handle that is reserved (platform or role words) or already taken is refused. update changes your public display_name, bio, or url at any time. claim and update require a verified email; an existing publisher may already have a provisional `maker-...` handle (auto-assigned) that claim renames the one allowed time.",
+        inputSchema: publisherShape,
+        // Consolidated tool: a read action (get) plus mutating ones (claim/update).
+        // claim is irreversible (the handle is permanent), so the hint reflects the
+        // most-privileged action.
+        annotations: {
+            title: "Publisher Profile",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "get":
+                        return jsonResult(await client.getPublisher());
+                    case "claim": {
+                        const handle = str(args, "handle");
+                        if (handle === undefined) {
+                            return invalidArgs("claim requires `handle`");
+                        }
+                        return jsonResult(await client.claimPublisherHandle(handle));
+                    }
+                    case "update": {
+                        const update = {};
+                        if ("display_name" in args)
+                            update.displayName = args["display_name"];
+                        if ("bio" in args)
+                            update.bio = args["bio"];
+                        if ("url" in args)
+                            update.url = args["url"];
+                        if (Object.keys(update).length === 0) {
+                            return invalidArgs("update requires at least one of `display_name`, `bio`, `url`");
+                        }
+                        return jsonResult(await client.updatePublisher(update));
+                    }
+                    default:
+                        return invalidArgs(`unknown publisher action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
+    {
+        name: "review",
+        description: "Rate and review community templates you have USED, respond to reviews of your own templates, and (relay operators only) moderate. ONE tool with an `action` enum: create | respond | report | remove | unhold. create leaves a 1-to-5 star rating plus an optional written body on a template you have installed - identify the template by `template` (\"<handle>/<slug>\") or by `handle`+`slug`; you need a verified email, and each install yields exactly one review (the aggregate carries across template versions). A body that contains a link or a contact email is AUTO-HELD for a moderator before it appears. respond replies to a review of YOUR OWN template line (review_id + response; null clears it), one editable response per review. report flags a review for the relay's moderators (review_id + reason), deduped per account. remove and unhold are limited to the relay's configured community reviewers: remove takes a review down and adjusts the rating aggregate; unhold publishes a previously auto-held review into the aggregate.",
+        inputSchema: reviewShape,
+        // Consolidated tool: a write action (create), publisher/reporter actions,
+        // and operator moderation (remove/unhold). Hint reflects remove, the most
+        // privileged / destructive action.
+        annotations: {
+            title: "Community Reviews",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        handler: async (client, args) => {
+            const action = String(args["action"]);
+            try {
+                switch (action) {
+                    case "create": {
+                        if (args["stars"] === undefined) {
+                            return invalidArgs("create requires `stars`");
+                        }
+                        const template = str(args, "template");
+                        const handle = str(args, "handle");
+                        const slug = str(args, "slug");
+                        if (template === undefined &&
+                            (handle === undefined || slug === undefined)) {
+                            return invalidArgs('create requires `template` ("<handle>/<slug>") or both `handle` and `slug`');
+                        }
+                        return jsonResult(await client.createReview({
+                            template,
+                            handle,
+                            slug,
+                            stars: args["stars"],
+                            body: str(args, "body"),
+                        }));
+                    }
+                    case "respond": {
+                        const reviewId = str(args, "review_id");
+                        if (reviewId === undefined) {
+                            return invalidArgs("respond requires `review_id`");
+                        }
+                        const response = "response" in args ? args["response"] : null;
+                        return jsonResult(await client.respondToReview(reviewId, response));
+                    }
+                    case "report": {
+                        const reviewId = str(args, "review_id");
+                        if (reviewId === undefined) {
+                            return invalidArgs("report requires `review_id`");
+                        }
+                        const reason = str(args, "reason");
+                        if (reason === undefined) {
+                            return invalidArgs("report requires `reason`");
+                        }
+                        return jsonResult(await client.reportReview(reviewId, reason));
+                    }
+                    case "remove": {
+                        const reviewId = str(args, "review_id");
+                        if (reviewId === undefined) {
+                            return invalidArgs("remove requires `review_id`");
+                        }
+                        return jsonResult(await client.removeReview(reviewId));
+                    }
+                    case "unhold": {
+                        const reviewId = str(args, "review_id");
+                        if (reviewId === undefined) {
+                            return invalidArgs("unhold requires `review_id`");
+                        }
+                        return jsonResult(await client.unholdReview(reviewId));
+                    }
+                    default:
+                        return invalidArgs(`unknown review action '${action}'`);
+                }
+            }
+            catch (e) {
+                return errorResult(e);
+            }
+        },
+    },
     {
         name: "get_skill",
         description: "Fetch the relay's auto-updating SKILL.md (the full Homespun usage guide) — UNAUTHENTICATED, needs no API key. Call this to self-teach the Homespun workflow (events vs records, schema grammars, the poll loop) before driving the other tools. Pass version_only:true to get just the relay's skill version string (to check if a cached copy is stale).",

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.29";
+export declare const VERSION = "1.4.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Single source of the package version, reported in the MCP server's
 // serverInfo. Kept in sync with package.json by the release tooling.
-export const VERSION = "0.0.29";
+export const VERSION = "1.4.2";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homespunapps/mcp",
   "mcpName": "io.github.aerolalit/homespun",
-  "version": "1.0.1",
+  "version": "1.4.2",
   "description": "Model Context Protocol (stdio) server for Homespun: lets any MCP client (Claude Desktop, Cursor, …) hand a human a rich interactive UI by URL and get structured data back.",
   "license": "MIT",
   "type": "module",
@@ -13,9 +13,9 @@
     "relay",
     "human-in-the-loop"
   ],
-  "homepage": "https://homespun.dev",
+  "homepage": "https://docs.homespun.dev",
   "bugs": {
-    "url": "mailto:support@homespun.dev"
+    "url": "https://github.com/homespunapps/homespun/issues"
   },
   "engines": {
     "node": ">=20"
@@ -46,12 +46,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.0",
-    "@homespunapps/core": "^1.0.0",
+    "@homespunapps/core": "^1.4.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
-    "typescript": "^6.0.3",
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homespunapps/homespun.git",
+    "directory": "packages/mcp"
   }
 }

package/server.json

@@ -3,14 +3,14 @@
   "name": "io.github.aerolalit/homespun",
   "title": "Homespun",
   "description": "Hand a human a rich interactive UI by URL and get structured data back, from any MCP client.",
-  "version": "0.0.29",
+  "version": "1.4.2",
   "websiteUrl": "https://homespun.dev",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@homespunapps/mcp",
-      "version": "0.0.29",
+      "version": "1.4.2",
       "transport": {
         "type": "stdio"
       },