@glie/mcp-polaris 0.7.0 → 0.9.0

package/README.md

@@ -47,15 +47,49 @@ it. The same token authenticates this server and the `polaris` CLI as you.
 
 ## Tools
 
-`polaris.me`, `polaris.project.*`, `polaris.milestone.*` (incl. `update` to
-refine a spec), `polaris.task.*` (incl. `update`, `transition`, `approve`),
-`polaris.stack.*` (`list` / `get` / `release` for the approval Release Candidate
-flow), `polaris.agent.*`, `polaris.claude_md.get`, `polaris.framework.list`, plus
-read-only context from the feed: `polaris.activity.list` (what happened) and
+**Roadmap.** `polaris.me`, `polaris.project.*`, `polaris.milestone.*` (incl.
+`update` to refine a spec, `attachment_*` to list/attach/remove the visual
+references anchored in its body), `polaris.task.*` (incl. `update`,
+`transition`, `approve`, `schedule`, `attachment_*` — same as the milestone's,
+plus how a milestone reference gets forwarded here via
+`source_attachment_id`), `polaris.stack.*` (`list` / `get` / `release` for the
+approval Release Candidate flow), `polaris.agent.*`, `polaris.team.*`,
+`polaris.claude_md.get`, `polaris.framework.list`.
+
+**Helpdesk.** `polaris.ticket.*` (the customer conversation: `reply`, `pass`,
+`frame_issue`, `link_issue`) and `polaris.issue.*` (the problem: `open`,
+`transition`, `add_task`). N tickets can dedup onto one issue, and one issue
+fans out into N tasks.
+
+**Context, read-only.** `polaris.activity.list` (what happened) and
 `polaris.chat.get` / `polaris.chat.messages` (comments agents left on a scope).
 
 Run `tools/list` against the server for the full, current set.
 
+## Marketing creatives
+
+A task inside an mkt campaign is a creative, and `polaris.task.create` takes the
+four axes that describe one:
+
+| Field     | What it says                | Values                                          |
+| --------- | --------------------------- | ----------------------------------------------- |
+| `medium`  | what the piece is           | `image` / `video` / `text`                       |
+| `surface` | where it publishes          | `feed` / `stories` / `reels` / `shorts` / `article` / `newsletter` |
+| `slides`  | how many images it carries  | 2 to 10, images only. A carousel is an image with plural |
+| `aspect`  | how it is framed            | `1:1` / `4:5` / `9:16` / `16:9` / `2:3`         |
+
+Plus `channel` (Instagram, TikTok, LinkedIn, ...) and `scheduled_date`, the day
+it publishes.
+
+The pairs are checked at creation, not patched over at generation time: a
+carousel with no `slides` is refused (it would ship a single image under a name
+that promises several), `slides` on a non-image piece is refused, and an
+`aspect` that the surface does not accept is refused. Omit `aspect` to take the
+channel's usual one.
+
+`format` is still written and read, as the label the board and the agents use,
+but it is derived from the axes rather than defining them.
+
 ## License
 
 Apache-2.0

package/dist/index.js

@@ -3,6 +3,21 @@
 
 // ../../src/mcp/index.ts
 import { createInterface } from "readline";
+
+// ../../src/lib/media-types.ts
+var MEDIA_TYPES = [
+  { mime: "image/png", kind: "image", ext: ".png", aliases: [] },
+  { mime: "image/jpeg", kind: "image", ext: ".jpg", aliases: [".jpeg"] },
+  { mime: "image/webp", kind: "image", ext: ".webp", aliases: [] },
+  { mime: "video/mp4", kind: "video", ext: ".mp4", aliases: [] },
+  { mime: "video/quicktime", kind: "video", ext: ".mov", aliases: [] },
+  { mime: "video/webm", kind: "video", ext: ".webm", aliases: [] }
+];
+function allMimes() {
+  return MEDIA_TYPES.map((t) => t.mime);
+}
+
+// ../../src/mcp/index.ts
 var BASE = process.env.POLARIS_URL ?? "http://127.0.0.1:7843";
 var TOKEN = process.env.POLARIS_TOKEN ?? "";
 var PROJECT = process.env.POLARIS_PROJECT ?? "";
@@ -53,9 +68,11 @@ var INSTRUCTIONS = [
   "\u2022 polaris.claude_md.get(project_key) \u2014 read the project's conventions BEFORE you touch its tasks.",
   "",
   "STATE MACHINES \u2014 transitions are enforced; only legal moves succeed:",
-  "\u2022 Task:      draft \u2192 backlog \u2192 dev \u2192 test \u2192 approval \u2192 release \u2192 done    (any \u2192 canceled)",
+  "\u2022 Task:      draft \u2192 backlog \u2192 dev \u2192 test \u2192 approval \u2192 release \u2192 done    (any \u2192 canceled;",
+  "             canceled \u2192 draft and done \u2192 approval undo the last step)",
   "    dev = an agent implements it & opens a PR \xB7 test = QA \xB7 approval = a human reviews \xB7 release = merged to dev/shipped.",
-  "\u2022 Milestone: draft \u2192 discovery \u2192 loop \u2192 release \u2192 done                    (any \u2192 canceled)",
+  "\u2022 Milestone: draft \u2192 discovery \u2192 loop \u2192 release \u2192 done                    (any \u2192 canceled;",
+  "             canceled \u2192 discovery brings back a milestone closed by mistake)",
   "    discovery = answer the framework Q&A to split it into tasks \xB7 loop = build/test/approve \xB7 release = ship.",
   "\u2022 Stack (Release Candidate): 2+ approval tasks of ONE milestone on an rc branch, tested & shipped together \u2014",
   "    liquid (assembling) \u2192 blocked (a member conflicts) | frozen (human-resolved) \u2192 released   (any \u2192 canceled).",
@@ -80,8 +97,8 @@ var INSTRUCTIONS = [
   '\u2022 "Break a milestone into tasks"  \u2192 polaris.milestone.qa_list / qa_answer (while in discovery)',
   `\u2022 "Triage support / what's waiting?" \u2192 polaris.ticket.list (status, project_key) \u2014 P1 first`,
   '\u2022 "Reply to a customer / hand off"  \u2192 polaris.ticket.reply then polaris.ticket.pass(to)',
-  '\u2022 "Turn a report into work"         \u2192 polaris.ticket.frame_issue \u2192 polaris.issue.add_task \xD7N',
-  '\u2022 "Same bug reported again"         \u2192 polaris.ticket.link_issue (dedup onto the open issue)',
+  '\u2022 "Turn a report into work"         \u2192 polaris.ticket.frame_issue \u2192 polaris.issue.add_task \xD7N (framing is HUMAN-only; the helpdesker proposes it)',
+  '\u2022 "Same bug reported again"         \u2192 polaris.ticket.link_issue (dedup onto the open issue; HUMAN-only) \u2192 say we already have it \u2192 close the duplicate ticket',
   "",
   "Identifiers: projects by `key` (string, e.g. saasA); milestones/tasks/agents/stacks by numeric `id`. Writes need a token; reads work anonymously."
 ].join(`
@@ -121,13 +138,32 @@ var TOOLS = [
   },
   {
     name: "polaris.project.create",
-    description: "Create a project (human-only).",
-    inputSchema: objSchema({ key: strSchema(), name: strSchema(), description_md: strSchema() }, [
-      "key",
-      "name"
-    ]),
+    description: "Create a project (human-only). With GitHub connected a repository is required \u2014 pick one from polaris.github.repositories. One repository holds one project.",
+    inputSchema: objSchema({
+      key: strSchema(),
+      name: strSchema(),
+      repo_url: strSchema("https://github.com/owner/repo \u2014 required when GitHub is connected")
+    }, ["key", "name"]),
     call: async (args) => (await apiCall("POST", "/api/projects", args)).body
   },
+  {
+    name: "polaris.github.repositories",
+    description: "Repositories a project may live in (human-only): whether GitHub is connected, and every repository the GitHub App reaches \u2014 available, or why not (already another project's, or archived).",
+    inputSchema: objSchema({}),
+    call: async () => (await apiCall("GET", "/api/github/repositories")).body
+  },
+  {
+    name: "polaris.project.arm",
+    description: "Arm a project for auto-approval (human-only): while armed, dev work that reaches `approval` CLEAN is approved on your behalf \u2014 no per-task click \u2014 and follows the normal path to release. Escalated tasks, mkt creatives, and support work still wait for a person; a merge that fails leaves the task in `approval`. Idempotent.",
+    inputSchema: objSchema({ key: strSchema("project key (e.g. saasA)") }, ["key"]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/arm`)).body
+  },
+  {
+    name: "polaris.project.disarm",
+    description: "Disarm a project (human-only). Immediate effect: the next task to reach `approval` waits for a person again. Work already parked in `approval` is untouched. Idempotent.",
+    inputSchema: objSchema({ key: strSchema("project key (e.g. saasA)") }, ["key"]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/disarm`)).body
+  },
   {
     name: "polaris.milestone.list",
     description: "List milestones in a project.",
@@ -142,11 +178,16 @@ var TOOLS = [
   },
   {
     name: "polaris.milestone.update",
-    description: "Correct or refine a milestone's spec \u2014 PATCH its description_md (and optionally name), same idea as polaris.task.update. Use it to sharpen the brief for better scoping. Needs a token.",
+    description: "Correct or refine a milestone's spec \u2014 PATCH its description_md (and optionally name), same idea as polaris.task.update. On a mkt campaign the market can also be corrected, while it is still in draft or discovery: after that the creatives are already bound to accounts. The campaign's rhythm, budget and channels live in the description \u2014 write them there and the briefer reads them. Needs a token.",
     inputSchema: objSchema({
       id: intSchema(),
       name: strSchema(),
-      description_md: strSchema("full markdown brief; replaces the current description")
+      description_md: strSchema("full markdown brief; replaces the current description"),
+      market: {
+        type: "array",
+        items: { type: "string", enum: ["BR", "US", "EU"] },
+        description: "mkt: target markets; replaces the current list"
+      }
     }, ["id"]),
     call: async (args) => {
       const body = {};
@@ -154,6 +195,8 @@ var TOOLS = [
         body.name = args.name;
       if (typeof args.description_md === "string")
         body.description_md = args.description_md;
+      if ("market" in args)
+        body.market = args.market;
       return (await apiCall("PATCH", `/api/milestones/${args.id}`, body)).body;
     }
   },
@@ -181,6 +224,60 @@ var TOOLS = [
       answer_md: args.answer_md
     })).body
   },
+  {
+    name: "polaris.milestone.attachment_list",
+    description: "List this milestone's IMAGE attachments \u2014 anchored in its description_md by a `ref:N` marker, or attached but not yet placed in the text. A link is not here: it's plain `[text](url)` markdown written straight into description_md, no row, no marker \u2014 read it off the text like any other prose. Each image carries a `marker` ready to paste into description_md, an `attachment_id` (the underlying file \u2014 pass it to attachment_create elsewhere to attach the SAME image with no re-upload), and an `alt` (a plain description of what it shows, often blank) \u2014 intent (what to do with it) always lives in the description_md text around the marker, never in `alt`.",
+    inputSchema: objSchema({ id: intSchema("milestone id") }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/milestones/${args.id}/attachments`)).body
+  },
+  {
+    name: "polaris.milestone.attachment_presign",
+    description: "Step 1 of attaching an image to a milestone: reserve an upload key. Returns file_key + upload_url \u2014 PUT the raw image bytes to upload_url YOURSELF (curl/fetch from your shell; this call does not carry bytes), then call polaris.milestone.attachment_create with the same file_key. A link isn't an attachment at all \u2014 just write `[text](url)` straight into the milestone's description_md.",
+    inputSchema: objSchema({
+      id: intSchema("milestone id"),
+      mime: strSchema(allMimes().join(" | ")),
+      size_bytes: intSchema()
+    }, ["id", "mime", "size_bytes"]),
+    call: async (args) => (await apiCall("POST", `/api/milestones/${args.id}/attachments/presign`, {
+      mime: args.mime,
+      size_bytes: args.size_bytes
+    })).body
+  },
+  {
+    name: "polaris.milestone.attachment_create",
+    description: "Attach an IMAGE to a milestone. Two shapes: a fresh upload (file_key from attachment_presign + mime + size_bytes + filename, alt optional); or attaching an EXISTING file already uploaded elsewhere (attachment_id \u2014 from another attachment's `attachment_id` field \u2014 alt optional) which is how a milestone reference gets forwarded onto a task without re-uploading its bytes. The same file can be attached to any number of milestones/tasks this way (N:N) \u2014 each attachment gets its own `alt` here, independent of what it says anywhere else it's attached. A link is NOT this call \u2014 write `[text](url)` straight into the milestone's description_md, no attachment row at all. `alt` only describes what the image shows \u2014 it is never an instruction; what to DO with it lives in the body prose around the marker this call returns, which you paste into description_md yourself (an attachment nobody placed in the text is as good as absent). Read that prose to decide: the default, when it just describes what the reference IS, is to pass it along as-is; only when it explicitly asks for something derived (a description, a summary) should you use it as input instead and write that into the task's own text.",
+    inputSchema: objSchema({
+      id: intSchema("milestone id"),
+      alt: strSchema("what the image shows, plainly \u2014 never an instruction"),
+      filename: strSchema("required for a fresh upload \u2014 the file's own name"),
+      file_key: strSchema("from attachment_presign"),
+      mime: strSchema(),
+      size_bytes: intSchema(),
+      attachment_id: intSchema("attach an EXISTING file (its attachment_id) instead of file_key/mime/size_bytes/filename \u2014 no re-upload")
+    }, ["id"]),
+    call: async (args) => {
+      const { id, ...body } = args;
+      return (await apiCall("POST", `/api/milestones/${id}/attachments`, body)).body;
+    }
+  },
+  {
+    name: "polaris.milestone.attachment_update",
+    description: "Edit the alt text on a milestone attachment \u2014 the only field worth changing after upload; the image itself and its filename stay what was actually uploaded. Only THIS attachment (this milestone) changes \u2014 the same file attached elsewhere keeps its own alt.",
+    inputSchema: objSchema({ id: intSchema("milestone id"), seq: intSchema(), alt: strSchema() }, [
+      "id",
+      "seq",
+      "alt"
+    ]),
+    call: async (args) => (await apiCall("PATCH", `/api/milestones/${args.id}/attachments/${args.seq}`, {
+      alt: args.alt
+    })).body
+  },
+  {
+    name: "polaris.milestone.attachment_delete",
+    description: "Remove an attachment from a milestone by its seq. Only removes it from THIS milestone \u2014 the underlying file, and any other milestone/task it's attached to, are untouched.",
+    inputSchema: objSchema({ id: intSchema("milestone id"), seq: intSchema() }, ["id", "seq"]),
+    call: async (args) => (await apiCall("DELETE", `/api/milestones/${args.id}/attachments/${args.seq}`)).body
+  },
   {
     name: "polaris.task.list",
     description: `Find tasks \u2014 the agent's entry point. Pass assignee_agent_id="self" (or assignee_human_id="self" for a human) to get what is YOURS; add status=dev (etc.) to see only active work. Other filters: milestone_id, product_key, team.`,
@@ -225,7 +322,7 @@ var TOOLS = [
       milestone_id: intSchema(),
       name: strSchema(),
       description_md: strSchema(),
-      status: strSchema("draft|backlog|dev|test|approval|release (default draft)"),
+      status: strSchema("draft \u2014 the only status a task can be created in; it reaches the rest by being moved, one legal step at a time (polaris.task.transition)"),
       channel: strSchema("mkt: Instagram, TikTok, LinkedIn, \u2026"),
       format: strSchema("mkt: post, carrossel, reel, story, artigo, \u2026"),
       slides: intSchema("mkt: REQUIRED when format is a carousel \u2014 how many images the piece has (2..10). " + "It is a contract: the generator delivers exactly this many. Omit for every other format."),
@@ -239,6 +336,60 @@ var TOOLS = [
     }, ["milestone_id", "name"]),
     call: async (args) => (await apiCall("POST", "/api/tasks", args)).body
   },
+  {
+    name: "polaris.task.attachment_list",
+    description: "List this task's IMAGE attachments, including ones a milestone reference forwarded here (attached by attachment_id, no re-upload) plus anything attached directly to this task. A link is not here: it's plain `[text](url)` markdown written straight into the task's description_md, no row, no marker. Each image carries a `marker` ready to paste into description_md, an `attachment_id` (the underlying file \u2014 pass it to attachment_create elsewhere to attach the SAME image with no re-upload), and an `alt` (a plain description of what it shows, often blank) \u2014 intent (what to do with it) always lives in the description_md text around the marker, never in `alt`.",
+    inputSchema: objSchema({ id: intSchema("task id") }, ["id"]),
+    call: async (args) => (await apiCall("GET", `/api/tasks/${args.id}/attachments`)).body
+  },
+  {
+    name: "polaris.task.attachment_presign",
+    description: "Step 1 of attaching an image to a task: reserve an upload key. Returns file_key + upload_url \u2014 PUT the raw image bytes to upload_url YOURSELF (curl/fetch from your shell; this call does not carry bytes), then call polaris.task.attachment_create with the same file_key. A link isn't an attachment at all \u2014 just write `[text](url)` straight into the task's description_md.",
+    inputSchema: objSchema({
+      id: intSchema("task id"),
+      mime: strSchema(allMimes().join(" | ")),
+      size_bytes: intSchema()
+    }, ["id", "mime", "size_bytes"]),
+    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/attachments/presign`, {
+      mime: args.mime,
+      size_bytes: args.size_bytes
+    })).body
+  },
+  {
+    name: "polaris.task.attachment_create",
+    description: "Attach an IMAGE to a task. Two shapes: a fresh upload (file_key from attachment_presign + mime + size_bytes + filename, alt optional); or attaching an EXISTING file already uploaded elsewhere (attachment_id \u2014 from another attachment's `attachment_id` field \u2014 alt optional, no re-upload). This is how the BRIEF forwards a milestone's image onto a task it's planning. The same file can be attached to any number of milestones/tasks (N:N) \u2014 each attachment gets its own `alt` here, independent of what it says anywhere else it's attached. A link is NOT this call: write `[text](url)` straight into the task's description_md \u2014 for a milestone link, just copy the markdown across, there's nothing to attach. `alt` only describes what the image shows \u2014 never an instruction. Read the milestone's OWN body prose around its marker for intent (alt never carries it), and once attached here, paste the `marker` this call returns into the task's description_md yourself, with that instruction right after it \u2014 an attachment nobody placed in the text is as good as absent. Default: forward as-is; only when that prose explicitly asks for something derived (a description, a summary) should you use it as input instead and write that into this task's own description_md.",
+    inputSchema: objSchema({
+      id: intSchema("task id"),
+      alt: strSchema("what the image shows, plainly \u2014 never an instruction"),
+      filename: strSchema("required for a fresh upload \u2014 the file's own name"),
+      file_key: strSchema("from attachment_presign"),
+      mime: strSchema(),
+      size_bytes: intSchema(),
+      attachment_id: intSchema("attach an EXISTING file (its attachment_id) instead of file_key/mime/size_bytes/filename \u2014 no re-upload")
+    }, ["id"]),
+    call: async (args) => {
+      const { id, ...body } = args;
+      return (await apiCall("POST", `/api/tasks/${id}/attachments`, body)).body;
+    }
+  },
+  {
+    name: "polaris.task.attachment_update",
+    description: "Edit the alt text on a task attachment \u2014 the only field worth changing after upload; the image itself and its filename stay what was actually uploaded. Only THIS attachment (this task) changes \u2014 the same file attached elsewhere keeps its own alt.",
+    inputSchema: objSchema({ id: intSchema("task id"), seq: intSchema(), alt: strSchema() }, [
+      "id",
+      "seq",
+      "alt"
+    ]),
+    call: async (args) => (await apiCall("PATCH", `/api/tasks/${args.id}/attachments/${args.seq}`, {
+      alt: args.alt
+    })).body
+  },
+  {
+    name: "polaris.task.attachment_delete",
+    description: "Remove an attachment from a task by its seq. Only removes it from THIS task \u2014 the underlying file, and any other milestone/task it's attached to, are untouched.",
+    inputSchema: objSchema({ id: intSchema("task id"), seq: intSchema() }, ["id", "seq"]),
+    call: async (args) => (await apiCall("DELETE", `/api/tasks/${args.id}/attachments/${args.seq}`)).body
+  },
   {
     name: "polaris.task.update",
     description: "Correct or refine a task's spec \u2014 PATCH its description_md (and optionally name). For a marketing creative, set asset_url to the produced asset (image/video) so the reviewer can download and review it. It is NOT a log of what was done (leave that as a comment). Needs a token.",
@@ -264,19 +415,26 @@ var TOOLS = [
   },
   {
     name: "polaris.task.transition",
-    description: "Move a task to its next status when you finish a stage (e.g. dev\u2192test once your PR is up). Enforced flow: draft\u2192backlog\u2192dev\u2192test\u2192approval\u2192release\u2192done (any\u2192canceled). Illegal jumps are rejected. The approval\u2192release gate is polaris.task.approve (human-only).",
-    inputSchema: objSchema({ id: intSchema(), status: strSchema() }, ["id", "status"]),
-    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/state`, { status: args.status })).body
+    description: 'Move a task to its next status when you finish a stage (e.g. dev\u2192test once your PR is up). Enforced flow: draft\u2192backlog\u2192dev\u2192test\u2192approval\u2192release\u2192done (any\u2192canceled). Illegal jumps are rejected. Neither terminal state is a dead end: canceled\u2192draft and done\u2192approval undo the last step, so a mistaken close is recoverable without touching the database. The approval\u2192release gate is polaris.task.approve (human-only).\n\nThree of these moves hand the work to someone else, and `note` is REQUIRED on them \u2014 it is the message that travels with it, and it lands in the task chat as a handover: `dev\u2192test` (what you did and what to look at first), `test\u2192dev` (why it comes back \u2014 it is what the next attempt is made from), and `test\u2192approval`, which also requires `verdict` ("approved" or "rejected": a person is about to decide, and they need to know whether this passed or ran out of rounds). Every other move takes no note.',
+    inputSchema: objSchema({ id: intSchema(), status: strSchema(), note: strSchema(), verdict: strSchema() }, ["id", "status"]),
+    call: async (args) => {
+      const body = { status: args.status };
+      if (typeof args.note === "string")
+        body.note = args.note;
+      if (typeof args.verdict === "string")
+        body.verdict = args.verdict;
+      return (await apiCall("POST", `/api/tasks/${args.id}/state`, body)).body;
+    }
   },
   {
     name: "polaris.task.approve",
-    description: "The human review gate: approve a dev task in `approval` \u2192 it advances toward release. Human-only. NOT valid for mkt creatives (output_type=post/video/etc.) \u2014 use polaris.task.schedule or polaris.task.mark_published instead. To ship several approval tasks together, group them into a stack and use polaris.stack.release.",
+    description: "The human review gate: a task in `approval` advances to `release` \u2014 cleared to go out, not gone out. Human-only, and valid for everything: a mkt creative approves the same way, and is then either scheduled (auto-publish at its time) or marked published once it has gone out. To ship several approval tasks together, group them into a stack and use polaris.stack.release.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/approve`)).body
   },
   {
     name: "polaris.task.schedule",
-    description: "Schedule a mkt creative for publication: approval \u2192 agendado. The creative must be bound to an active social account (resolved from its market + channel) and have a publish_at in the future. Its copy is frozen while scheduled \u2014 editing it requires unscheduling first.",
+    description: "Schedule a mkt creative for publication: approval \u2192 agendado, and the publisher takes it to `done` when its time arrives. The creative must be bound to an active social account (resolved from its market + channel) and have a publish_at in the future. Its copy is frozen while scheduled \u2014 editing it requires unscheduling first.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/schedule`)).body
   },
@@ -288,7 +446,7 @@ var TOOLS = [
   },
   {
     name: "polaris.task.mark_published",
-    description: "Manually mark a mkt creative as published: approval \u2192 release (bypasses scheduling). Recorded as a manual human action. Use when the post was published outside the scheduler.",
+    description: "The creative has gone out: `release` \u2192 `done`, optionally with the permalink of the post. This is the LAST transition, not a shortcut \u2014 approve it into `release` first (cleared to go out), then mark it published once it actually has. Recorded as a manual human action; use it when the post went out outside the scheduler.",
     inputSchema: objSchema({ id: intSchema() }, ["id"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/mark-published`)).body
   },
@@ -366,13 +524,13 @@ var TOOLS = [
   },
   {
     name: "polaris.ticket.frame_issue",
-    description: "Frame a NEW issue (the problem) from this ticket's conversation \u2014 the helpdesk twin of a milestone. A note is added to the thread. Then decompose it via polaris.issue.add_task.",
+    description: "Frame a NEW issue (the problem) from this ticket's conversation \u2014 the helpdesk twin of a milestone. A note is added to the thread. Then decompose it via polaris.issue.add_task. HUMAN ONLY: an agent token gets 403 (agent_cannot_admin) \u2014 the helpdesker proposes the issue during triage and a human validates it with a button.",
     inputSchema: objSchema({ id: intSchema(), title: strSchema() }, ["id", "title"]),
     call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/issues`, { title: args.title })).body
   },
   {
     name: "polaris.ticket.link_issue",
-    description: "Link this ticket to an EXISTING issue (dedup \u2014 it's a duplicate report of a problem already being worked).",
+    description: "Link this ticket to an EXISTING issue (dedup \u2014 it's a duplicate report of a problem already being worked). Then tell the customer we already have the problem, point them to follow it in the product, and close this ticket after sending. HUMAN ONLY: an agent token gets 403 (agent_cannot_admin) \u2014 the helpdesker proposes the link, a human accepts it.",
     inputSchema: objSchema({ id: intSchema(), issue_id: intSchema() }, ["id", "issue_id"]),
     call: async (args) => (await apiCall("POST", `/api/tickets/${args.id}/issues/link`, { issue_id: args.issue_id })).body
   },
@@ -527,6 +685,30 @@ var TOOLS = [
       return r.body;
     }
   },
+  {
+    name: "polaris.revision.list",
+    description: "History of an object's markdown field, newest first \u2014 what the text was BEFORE and AFTER each change, who changed it and how (human, descriptioner, revert). Use it to answer \"what did the descriptioner actually change in this milestone?\", which the activity feed cannot tell you. Scopes: milestone|task|issue|agent use `id`; agent_function uses `key` (e.g. 'planner').",
+    inputSchema: objSchema({
+      scope: strSchema("milestone|task|issue|agent|agent_function"),
+      id: intSchema("object id \u2014 every scope except agent_function"),
+      key: strSchema("text key \u2014 agent_function only, e.g. 'planner'")
+    }, ["scope"]),
+    call: async (args) => {
+      const qs = new URLSearchParams;
+      qs.set("scope", String(args.scope));
+      if (args.id !== undefined && args.id !== null)
+        qs.set("id", String(args.id));
+      if (args.key !== undefined && args.key !== null)
+        qs.set("key", String(args.key));
+      return (await apiCall("GET", `/api/revisions?${qs}`)).body;
+    }
+  },
+  {
+    name: "polaris.revision.revert",
+    description: "Restore a markdown field to its value BEFORE the given revision. Not a rollback \u2014 it writes normally, so it records its own revision with source='revert' and can itself be reverted. Needs a token.",
+    inputSchema: objSchema({ id: intSchema("revision id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/revisions/${args.id}/revert`)).body
+  },
   {
     name: "polaris.chat.get",
     description: "Resolve the chat thread for a scope (e.g. task 42) and return its id. Idempotent (get-or-create). You rarely need this directly \u2014 polaris.chat.messages takes the scope and resolves the id for you.",
@@ -574,6 +756,88 @@ var TOOLS = [
     inputSchema: objSchema({ key: strSchema("project key"), content: strSchema("full CLAUDE.md markdown") }, ["key", "content"]),
     call: async (args) => (await apiCall("PUT", `/api/projects/${args.key}/claude-md`, { content: args.content })).body
   },
+  {
+    name: "polaris.presence.list",
+    description: "Where a product exists in the world: the channels it publishes on and the directories it is listed in, each with its state (missing \u2192 exists \u2192 connected). Read this before writing a campaign \u2014 a channel that is not connected cannot be published to. Each row carries what the catalogue knows in `place`: read `place.actor` before planning work there \u2014 `agent` means there is a publishing tool, `human` means a person does it and records where, and `place.final_state` says how far this particular place can ever get.",
+    inputSchema: objSchema({ key: strSchema("project key") }, ["key"]),
+    call: async (args) => (await apiCall("GET", `/api/projects/${args.key}/presences`)).body
+  },
+  {
+    name: "polaris.place.list",
+    description: "The catalogue of places a product can exist in \u2014 every social network, paid surface, syndication platform, app store and software directory the studio knows about. The world's list, not ours: read it to decide WHERE a product should be. Each entry says what the place is, who acts there (`actor`: agent = there is a publishing tool; human = a person does it and records where), how far it can get (`final_state`), WHY it is worth being there (`note`), and the URL that was verified (`source`). Whether we are actually there is a PRESENCE \u2014 polaris.presence.list.",
+    inputSchema: objSchema({}),
+    call: async () => (await apiCall("GET", "/api/places")).body
+  },
+  {
+    name: "polaris.org_credential.list",
+    description: "The accounts that serve MANY products at once \u2014 Google Play Console, App Store Connect, a vendor login that covers several listings. Read it to know whether an entry can be opened at all, and by whom: the row names the owner, and the password never leaves the server. A presence points at one of these when the credential is the org's rather than the product's.",
+    inputSchema: objSchema({}),
+    call: async () => (await apiCall("GET", "/api/org-credentials")).body
+  },
+  {
+    name: "polaris.org_credential.add",
+    description: "Register an org-wide credential (human-only). Idempotent on slug + login: the same Play Console twice is the same Play Console, and a DIFFERENT login on the same site is a different credential. A place reached by OAuth is refused \u2014 that credential already lives in social accounts. Never send a password you were not given.",
+    inputSchema: objSchema({
+      slug: strSchema("play-store \xB7 app-store \xB7 capterra \u2026"),
+      label: strSchema("human name; defaults to the catalogue's"),
+      url: strSchema("where you log in"),
+      login_email: strSchema(),
+      notes: strSchema("who holds the second factor, and anything the next person needs")
+    }, ["slug"]),
+    call: async (args) => (await apiCall("POST", "/api/org-credentials", args)).body
+  },
+  {
+    name: "polaris.org_credential.verify",
+    description: "Stamp an org credential as CHECKED \u2014 it still opens the door (human-only). A credential does not announce that it expired: that is discovered on the day it is needed, which is always the worst day.",
+    inputSchema: objSchema({ id: intSchema("credential id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/org-credentials/${args.id}/verify`, {})).body
+  },
+  {
+    name: "polaris.presence.add",
+    description: "Add a place to a project (human-only). kind: channel (we publish there) | listing (we keep an entry there). Idempotent on slug + MARKET: adding Instagram BR twice is the same Instagram BR, and Instagram US is a different presence. Never send a password you were not given.",
+    inputSchema: objSchema({
+      key: strSchema("project key"),
+      kind: strSchema("channel | listing"),
+      slug: strSchema("instagram \xB7 linkedin \xB7 reddit \xB7 g2 \xB7 capterra \u2026"),
+      label: strSchema("human name, e.g. Instagram"),
+      market: strSchema("the market this one serves (BR \xB7 US \xB7 \u2026) \u2014 it is half the identity, so a product with an account per market gets one presence per market. Omit where the place has no market (a blog, a store entry)."),
+      url: strSchema("public profile or listing URL"),
+      handle: strSchema("@handle or account name"),
+      state: strSchema("missing | exists | connected \u2014 connected means there IS a link"),
+      login_email: strSchema(),
+      org_credential_id: intSchema("the org-wide account that opens this entry, when there is one"),
+      notes: strSchema()
+    }, ["key", "kind", "slug", "label"]),
+    call: async (args) => {
+      const { key, ...body } = args;
+      return (await apiCall("POST", `/api/projects/${key}/presences`, body)).body;
+    }
+  },
+  {
+    name: "polaris.presence.update",
+    description: "Edit one presence \u2014 its URL, handle, owner, notes or state (human-only).",
+    inputSchema: objSchema({
+      key: strSchema("project key"),
+      id: intSchema("presence id"),
+      label: strSchema(),
+      url: strSchema(),
+      handle: strSchema(),
+      state: strSchema("missing | exists | connected"),
+      login_email: strSchema(),
+      org_credential_id: intSchema("the org-wide account that opens this entry; null unlinks"),
+      notes: strSchema()
+    }, ["key", "id"]),
+    call: async (args) => {
+      const { key, id, ...body } = args;
+      return (await apiCall("PATCH", `/api/projects/${key}/presences/${id}`, body)).body;
+    }
+  },
+  {
+    name: "polaris.presence.verify",
+    description: "Stamp a presence as CHECKED AGAINST THE TRUTH of the product (human-only). Use it after actually looking: on a directory listing the risk is not staleness, it is the feature checklist claiming something the product does not do.",
+    inputSchema: objSchema({ key: strSchema("project key"), id: intSchema() }, ["key", "id"]),
+    call: async (args) => (await apiCall("POST", `/api/projects/${args.key}/presences/${args.id}/verify`, {})).body
+  },
   {
     name: "polaris.agent.create",
     description: "Create an agent/employee (human-only). function: developer|tester|planner|helpdesker; product = project key; team = dev|mkt; domain optional (roadmap|helpdesk|both).",
@@ -589,12 +853,22 @@ var TOOLS = [
   },
   {
     name: "polaris.agent.update",
-    description: "Update an agent (human-only): name (rename), domain (roadmap|helpdesk|both), or mantra_md. The stable agent_id_slug never changes.",
+    description: "Update an agent (human-only): name (rename), domain (roadmap|helpdesk|both), mantra_md, or resource_limits. The stable agent_id_slug never changes. resource_limits (CPU/RAM/disk, enforced via the agent's systemd unit) is null-or-object: null clears every field back to the default; an object states ALL fields (memory_max_mb, cpu_quota_pct, disk_quota_mb \u2014 each an integer, or null for that field's default). Takes effect on the agent's next re-provision, not instantly.",
     inputSchema: objSchema({
       id: intSchema(),
       name: strSchema(),
       domain: strSchema("roadmap|helpdesk|both"),
-      mantra_md: strSchema()
+      mantra_md: strSchema(),
+      resource_limits: {
+        type: ["object", "null"],
+        description: "CPU/RAM/disk caps. null = defaults for all fields. Object must state every field (int or null): memory_max_mb, cpu_quota_pct, disk_quota_mb.",
+        properties: {
+          memory_max_mb: { type: ["integer", "null"] },
+          cpu_quota_pct: { type: ["integer", "null"] },
+          disk_quota_mb: { type: ["integer", "null"] }
+        },
+        additionalProperties: false
+      }
     }, ["id"]),
     call: async (args) => {
       const { id, ...patch } = args;
@@ -654,7 +928,7 @@ var TOOLS = [
   },
   {
     name: "polaris.milestone.create",
-    description: "Create a milestone. team=dev|mkt; end_date = deadline (ISO date, required). For a marketing CAMPAIGN (team=mkt) these extra fields carry the plan: market (BR/US/EU), cadence (per-channel rules Discovery expands into dated creatives), max_creatives (cap on that expansion), and paid + platforms + budget for a paid campaign.",
+    description: "Create a milestone. team=dev|mkt; end_date = deadline (ISO date, required). For a marketing CAMPAIGN (team=mkt), `market` says which markets it serves \u2014 that is what routes each creative to an account. Everything else about the campaign (rhythm, channels, budget, angle) goes in `description_md`: the briefer reads it and cuts the creatives, each with its own day.",
     inputSchema: objSchema({
       project_key: strSchema(),
       name: strSchema(),
@@ -667,28 +941,7 @@ var TOOLS = [
         type: "array",
         items: { type: "string" },
         description: "mkt: target markets \u2014 any of BR, US, EU"
-      },
-      cadence: {
-        type: "array",
-        description: "mkt: per-channel cadence rules Discovery expands into dated creatives",
-        items: {
-          type: "object",
-          properties: {
-            channel: { type: "string", description: "Instagram, TikTok, LinkedIn, \u2026" },
-            format: { type: "string", description: "post, reel, story, artigo, \u2026" },
-            n: { type: "integer", description: "count per period" },
-            per: { type: "string", description: "day | week" }
-          }
-        }
-      },
-      max_creatives: intSchema("mkt: cap on how many creatives Discovery/cadence may generate"),
-      paid: { type: "boolean", description: "mkt: is the whole campaign paid?" },
-      platforms: {
-        type: "array",
-        items: { type: "string" },
-        description: "mkt paid: any of Meta, Google, Reddit, LinkedIn, TikTok, YouTube"
-      },
-      budget: { type: "number", description: "mkt: campaign ad-spend budget (\u20AC)" }
+      }
     }, ["project_key", "name", "team", "end_date"]),
     call: async (args) => (await apiCall("POST", "/api/milestones", args)).body
   },
@@ -716,11 +969,23 @@ var TOOLS = [
     inputSchema: objSchema({ id: intSchema("stack id"), task_id: intSchema() }, ["id", "task_id"]),
     call: async (args) => (await apiCall("DELETE", `/api/stacks/${args.id}/tasks`, { task_id: args.task_id })).body
   },
+  {
+    name: "polaris.task.escalate",
+    description: "You are making a piece and something needs a HUMAN DECISION before it can be made \u2014 a premise in the brief that turned out false, two ways forward and no ground to choose between them, a collision with something already live. Stops the piece and puts it in front of a person, in `approval`, with your question attached.\n\nNot for a piece you could not finish: that is what ending the run does. This is for one you are not going to decide alone.\n\nThe `note` is the whole point \u2014 what you found, what the options are, and what you are not choosing on your own. Without it this is an abandoned piece with a flag on it.",
+    inputSchema: objSchema({
+      id: intSchema(),
+      note: strSchema("the question \u2014 what was found, the options, and what you will not decide")
+    }, ["id", "note"]),
+    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/escalate`, { note: args.note })).body
+  },
   {
     name: "polaris.task.return_to_backlog",
-    description: "Send an approval task back for rework (human-only) \u2014 to its sticky developer (dev) or backlog. Clears escalation.",
-    inputSchema: objSchema({ id: intSchema() }, ["id"]),
-    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/return-to-backlog`)).body
+    description: "Send an approval task back for rework (human-only) \u2014 to its sticky developer (dev) or backlog. Clears escalation.\n\n**Write the `note`.** On a rework the agent does NOT re-read the brief: the request it gets says *you already have the brief*, and the note is the only thing that reaches it. Sending a piece back without one asks for the same piece again \u2014 and an agent that finds the field empty concludes the worker restarted and changes nothing, which is what it should do.",
+    inputSchema: objSchema({
+      id: intSchema(),
+      note: strSchema("why it is coming back \u2014 this is the brief for the next attempt")
+    }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/return-to-backlog`, args.note ? { note: args.note } : undefined)).body
   },
   {
     name: "polaris.chat.post",

package/package.json

@@ -1,18 +1,14 @@
 {
   "name": "@glie/mcp-polaris",
-  "version": "0.7.0",
-  "description": "Model Context Protocol (stdio) server exposing Polaris \u2014 glie's ops platform \u2014 as native tools in Claude Code and any MCP client.",
+  "version": "0.9.0",
+  "description": "Model Context Protocol (stdio) server exposing Polaris, glie's ops platform, as native tools in Claude Code and any MCP client.",
   "license": "Apache-2.0",
   "author": "glie <carlos@glie.ai>",
   "type": "module",
   "bin": {
     "mcp-polaris": "dist/index.js"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "engines": {
     "node": ">=18"
   },
@@ -25,14 +21,7 @@
     "directory": "packages/mcp-polaris"
   },
   "homepage": "https://polaris.glie.ai",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "claude-code",
-    "polaris",
-    "glie"
-  ],
+  "keywords": ["mcp", "model-context-protocol", "claude", "claude-code", "polaris", "glie"],
   "scripts": {
     "build": "bun run build.ts",
     "prepublishOnly": "bun run build.ts"