@glie/mcp-polaris 0.6.0 → 0.8.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

@@ -53,9 +53,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 +82,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(`
@@ -128,6 +130,18 @@ var TOOLS = [
     ]),
     call: async (args) => (await apiCall("POST", "/api/projects", args)).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 +156,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 +173,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 +202,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("image/png | image/jpeg | image/webp"),
+      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.`,
@@ -220,20 +295,79 @@ var TOOLS = [
   },
   {
     name: "polaris.task.create",
-    description: "Create a task within a milestone. For a marketing CREATIVE (a task in an mkt campaign): channel + format + scheduled_date (the publish day / calendar slot) + platform (if this creative is individually paid).",
+    description: "Create a task within a milestone. For a marketing CREATIVE (a task in an mkt campaign): channel + format + scheduled_date (the publish day / calendar slot) + platform (if this creative is individually paid). A CAROUSEL (format=carrossel) also requires `slides` (2..10) \u2014 without it the call is refused, because a carousel with no declared size ships one image.",
     inputSchema: objSchema({
       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, reel, story, artigo, \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."),
+      medium: strSchema("mkt: what the piece IS \u2014 image | video | text. The engine follows it (Codex, Remotion, " + "the writer). A carousel is `image` with slides > 1: only an image has more than one."),
+      surface: strSchema("mkt: where it publishes \u2014 feed | stories | reels | shorts | article | newsletter. It is " + "what separates a reel from a story: same medium, same 9:16, different place (and a " + "story is gone in 24h)."),
+      aspect: strSchema("mkt: the piece's SHAPE \u2014 1:1 | 4:5 | 9:16 | 16:9 | 2:3. The format says what the piece " + "IS (post, carrossel, reel), this says how it is framed, and they are independent: a " + "carousel can be vertical, a reel can be square. Omit to take the channel's usual one."),
+      output_type: strSchema("pr|post|video|email|generic \u2014 the delivery medium. Omit it: the format decides (reel/v\xEDdeo/short \u2192 video). Only pass it to override."),
       scheduled_date: strSchema("mkt: publish day (ISO date) \u2014 the calendar slot"),
       platform: strSchema("mkt: ad platform if this creative is individually paid"),
       asset_url: strSchema("mkt: URL of the produced creative asset (image/video) for the reviewer")
     }, ["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("image/png | image/jpeg | image/webp"),
+      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.",
@@ -241,7 +375,8 @@ var TOOLS = [
       id: intSchema(),
       name: strSchema(),
       description_md: strSchema("full markdown brief; replaces the current description"),
-      asset_url: strSchema("mkt: URL of the produced creative asset (image/video) for the reviewer")
+      asset_url: strSchema("mkt: URL of the produced creative asset (image/video) for the reviewer"),
+      output_type: strSchema("pr|post|video|email|generic \u2014 fix the delivery medium of a task filed with the wrong one (it routes the worker to the video or the image pipeline).")
     }, ["id"]),
     call: async (args) => {
       const body = {};
@@ -251,21 +386,41 @@ var TOOLS = [
         body.description_md = args.description_md;
       if (typeof args.asset_url === "string")
         body.asset_url = args.asset_url;
+      if (typeof args.output_type === "string")
+        body.output_type = args.output_type;
       return (await apiCall("PATCH", `/api/tasks/${args.id}`, body)).body;
     }
   },
   {
     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).",
+    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).",
     inputSchema: objSchema({ id: intSchema(), status: strSchema() }, ["id", "status"]),
     call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/state`, { status: args.status })).body
   },
   {
     name: "polaris.task.approve",
-    description: "The human review gate: approve a task in `approval` \u2192 it advances toward release. Human-only. To ship several approval tasks of one milestone together, group them into a stack and use polaris.stack.release instead.",
+    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, 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
+  },
+  {
+    name: "polaris.task.unschedule",
+    description: "Unschedule a mkt creative: agendado \u2192 approval. Refused once the post is live. The creative returns to approval for edits or re-scheduling.",
+    inputSchema: objSchema({ id: intSchema() }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/tasks/${args.id}/unschedule`)).body
+  },
+  {
+    name: "polaris.task.mark_published",
+    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
+  },
   {
     name: "polaris.task.dep_add",
     description: "Add a dependency edge (cycle-checked).",
@@ -340,13 +495,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
   },
@@ -501,6 +656,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.",
@@ -529,11 +708,10 @@ var TOOLS = [
   },
   {
     name: "polaris.project.update",
-    description: "Update a project (human-only): repo_url, description_md, name, status (active|paused|archived), owner_human_id.",
+    description: "Update a project (human-only): repo_url, name, status (active|paused|archived), owner_human_id. Brand/context live in the CLAUDE.md \u2014 use polaris.project.claude_md_set.",
     inputSchema: objSchema({
       key: strSchema("project key"),
       name: strSchema(),
-      description_md: strSchema(),
       repo_url: strSchema("github.com repo URL"),
       status: strSchema("active|paused|archived"),
       owner_human_id: intSchema()
@@ -549,6 +727,55 @@ 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.",
+    inputSchema: objSchema({ key: strSchema("project key") }, ["key"]),
+    call: async (args) => (await apiCall("GET", `/api/projects/${args.key}/presences`)).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: adding the same place twice fills in what was left empty. 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"),
+      url: strSchema("public profile or listing URL"),
+      handle: strSchema("@handle or account name"),
+      state: strSchema("missing | exists | connected (channel only)"),
+      login_email: strSchema(),
+      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(),
+      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).",
@@ -564,12 +791,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;
@@ -609,9 +846,27 @@ var TOOLS = [
     ]),
     call: async (args) => (await apiCall("POST", `/api/agents/${args.id}/claude-login/code`, { code: args.code })).body
   },
+  {
+    name: "polaris.agent.claude_logout",
+    description: "Log an agent out of Claude (human-only): deletes its stored credentials and clears the login. Use when claude_login_status is 'expired' to force a clean re-login.",
+    inputSchema: objSchema({ id: intSchema("agent id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/agents/${args.id}/claude-login/logout`)).body
+  },
+  {
+    name: "polaris.agent.codex_login",
+    description: "Kick off a generator agent's Codex device-login (human-only). Poll agent.get for codex_login_url, then approve it in the browser \u2014 no code to paste back.",
+    inputSchema: objSchema({ id: intSchema("agent id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/agents/${args.id}/codex-login`)).body
+  },
+  {
+    name: "polaris.agent.codex_logout",
+    description: "Log an agent out of Codex (human-only): deletes its stored auth and clears the login. Use when codex_login_status is 'expired' to force a clean re-login.",
+    inputSchema: objSchema({ id: intSchema("agent id") }, ["id"]),
+    call: async (args) => (await apiCall("POST", `/api/agents/${args.id}/codex-login/logout`)).body
+  },
   {
     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(),
@@ -624,28 +879,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
   },

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@glie/mcp-polaris",
-  "version": "0.6.0",
-  "description": "Model Context Protocol (stdio) server exposing Polaris — glie's ops platform — as native tools in Claude Code and any MCP client.",
+  "version": "0.8.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"
   },
@@ -21,7 +25,14 @@
     "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"