@nonbot/mcp 0.1.0 → 0.2.0

package/README.md

@@ -100,7 +100,7 @@ Ask your agent to "list my non.bot portfolios", "show what rules apply before I
 ## Tools
 
 <!-- tool-table:start — generated by `npm run gen:tools`; tests/readme-tool-table.test.ts fails if this drifts from the code -->
-### Portfolio (18)
+### Portfolio (24)
 
 The SAFe portfolio canvas: epics, features, stories, snapshots, personas, and the Run launch surface.
 
@@ -124,13 +124,20 @@ The SAFe portfolio canvas: epics, features, stories, snapshots, personas, and th
 | `portfolio_create_activation` | Create an activation (a ▶ Run launch request) for a story. | write | `portfolio:write` + `runs:fire` |
 | `portfolio_update_activation_status` | Transition an activation: pending → running \| failed \| cancelled. | write | `portfolio:write` |
 | `portfolio_snapshot` | Save a labeled version snapshot of a portfolio’s CURRENT graph — a time-travel restore point. | write | `portfolio:write` |
+| `portfolio_create` | Create a new, empty portfolio owned by the caller and return its id + version. | write | `portfolio:write` |
+| `portfolio_add_items` | Add up to 200 items of any level (objective, key-result, epic, feature, story, enabler, milestone) in one versioned write. | write | `portfolio:write` |
+| `portfolio_patch_item` | Change fields of ONE portfolio item without rewriting the graph (PATCH /api/portfolio/graph/node): `set` writes allowlisted PortfolioItemData fields (title, de… | write | `portfolio:write` |
+| `portfolio_layout` | Re-position every item so the Timeline reads cleanly: x from each item's start date (the canvas reads dates off x), y top-down — objectives, key results, then… | write | `portfolio:write` |
+| `portfolio_set_meta` | Graph-level settings that travel with the portfolio (the `__graph_meta__` record): `context_text` (the portfolio's context notes — what a newcomer reads first)… | write | `portfolio:write` |
+| `portfolio_asset_upload` | Store one image (PNG / JPEG / WebP / GIF, ≤ 2.2 MB — downscale first; the app keeps images at 1024 px JPEG) in your private asset store and get back its URL, f… | write | `portfolio:write` |
 
-### IP node (10)
+### IP node (11)
 
 Patent and trademark disclosures on the canvas: read the bag, edit it as an op list, add server-sealed evidence, export the hash list.
 
 | Tool | What it does | Kind | PAT scope |
 |---|---|---|---|
+| `ip_create` | Add an IP node — a patent or trademark disclosure — to a portfolio, wired to its source items (the cards the disclosure is prepared FROM: their title, descript… | write | `portfolio:write` |
 | `ip_list` | Every IP node (patent or trademark disclosure) in a portfolio: id, title, track, kind, started, live source count, live evidence count, filing date. | read | `portfolio:read` |
 | `ip_get` | One IP node's full disclosure bag (units with status, value, provenance; evidence incl. tombstones; events; filing) plus the graph version to pass as expected_… | read | `portfolio:read` |
 | `ip_evidence_list` | Evidence rows from the saved graph, tombstones included, with a seal verdict per row (true = sealed by this server, false = not, null = no signing key) and a w… | read | `portfolio:read` |

package/dist/core/config.d.ts

@@ -4,5 +4,6 @@ export interface ApiContext {
     getToken: () => string;
     readonly: boolean;
     backup?: (id: string, json: unknown) => Promise<void>;
+    readLocalImage?: (path: string) => Promise<string>;
     fetchImpl?: typeof fetch;
 }

package/dist/core/ipShape.d.ts

@@ -0,0 +1,7 @@
+export type IpTrack = 'patent' | 'trademark';
+export declare const IP_KINDS: Record<IpTrack, string[]>;
+export declare const IP_NODE_SIZE: {
+    readonly width: 340;
+    readonly height: 184;
+};
+export declare function emptyIp(track: IpTrack, kind?: string): Record<string, unknown>;

package/dist/core/ipShape.js

@@ -0,0 +1,45 @@
+const UNIT_SHAPES = {
+    patent: [
+        { id: 'u1', editor: 'text' }, { id: 'u2', editor: 'textarea' }, { id: 'u3', editor: 'steps' }, { id: 'u4', editor: 'proposals' },
+        { id: 'u5', editor: 'people' }, { id: 'u6', editor: 'where' }, { id: 'u7', editor: 'events' }, { id: 'u8', editor: 'date' },
+        { id: 'u9', editor: 'list' }, { id: 'u10', editor: 'figures' }, { id: 'u11', editor: 'owner' }, { id: 'u12', editor: 'text' },
+    ],
+    trademark: [
+        { id: 't1', editor: 'tm-mark' }, { id: 't2', editor: 'tm-type' }, { id: 't3', editor: 'tm-owner' }, { id: 't4', editor: 'tm-classes' },
+        { id: 't5', editor: 'tm-basis' }, { id: 't6', editor: 'tm-specimen' }, { id: 't7', editor: 'tm-signatory' }, { id: 't8', editor: 'tm-search' },
+    ],
+};
+export const IP_KINDS = { patent: ['provisional', 'nonprovisional', 'design'], trademark: ['application'] };
+export const IP_NODE_SIZE = { width: 340, height: 184 };
+const TM_EMPTY = {
+    'tm-mark': { k: 'tm', mark: '' },
+    'tm-type': { k: 'tm', type: 'standard', colour: false },
+    'tm-owner': { k: 'tm', rows: [] },
+    'tm-classes': { k: 'tm', answers: { downloadable: null, hosted: null, broker: null }, wording: {} },
+    'tm-basis': { k: 'tm', perClass: {} },
+    'tm-specimen': { k: 'tm', perClass: {} },
+    'tm-signatory': { k: 'tm', name: '', email: '' },
+    'tm-search': { k: 'tm', rows: [] },
+};
+function emptyValue(editor) {
+    switch (editor) {
+        case 'text':
+        case 'textarea': return { k: 'text', t: '' };
+        case 'steps': return { k: 'steps', rows: [] };
+        case 'proposals': return { k: 'proposals', cards: [] };
+        case 'people': return { k: 'people', rows: [] };
+        case 'where': return { k: 'where', side: null, files: [] };
+        case 'events': return { k: 'events', none: false };
+        case 'date': return { k: 'date', date: null, evIds: [] };
+        case 'list': return { k: 'list', rows: [] };
+        case 'figures': return { k: 'figures', rows: [] };
+        case 'owner': return { k: 'owner', entity: '', signed: {} };
+        default: return structuredClone(TM_EMPTY[editor] ?? { k: 'tm' });
+    }
+}
+export function emptyIp(track, kind) {
+    const units = {};
+    for (const s of UNIT_SHAPES[track])
+        units[s.id] = { id: s.id, status: 'empty', rev: 0, value: emptyValue(s.editor), provenance: null, history: [] };
+    return { v: 1, track, kind: kind ?? (track === 'patent' ? 'provisional' : 'application'), title: '', blurb: '', started: false, sourceTicks: {}, units, evidence: [], events: [], filing: null, prefill: null };
+}

package/dist/core/layout.d.ts

@@ -0,0 +1,38 @@
+export declare const PX_PER_WEEK = 120;
+export declare const LEVELS: readonly ["objective", "key-result", "epic", "feature", "story", "enabler", "milestone"];
+export type Level = (typeof LEVELS)[number];
+export interface LayoutNode {
+    id: string;
+    type?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    data?: Record<string, any>;
+}
+export interface LayoutOptions {
+    now?: Date;
+    heights?: Record<string, number>;
+}
+export interface LayoutResult {
+    positions: Map<string, {
+        x: number;
+        y: number;
+    }>;
+    widthOverride: Map<string, number | null>;
+}
+export declare function calendarStart(now: Date): Date;
+export declare const isoDate: (d: Date) => string;
+export declare function columnOf(date: Date, now: Date): number;
+export declare function dateAtColumn(col: number, now: Date): Date;
+export declare function todayColumn(now: Date): number;
+export declare function sprintAtColumn(col: number): {
+    pi: string;
+    sprint: string;
+};
+export declare function scheduleFields(col: number, weeks: number, now: Date): Record<string, unknown>;
+export declare const levelOf: (n: LayoutNode) => Level;
+export declare const isItem: (n: LayoutNode) => boolean;
+export declare const isIpNode: (n: LayoutNode) => boolean;
+export declare function layoutTimeline(nodes: LayoutNode[], opts?: LayoutOptions): LayoutResult;
+export declare function applyLayout<T extends LayoutNode>(nodes: T[], res: LayoutResult): T[];

package/dist/core/layout.js

@@ -0,0 +1,193 @@
+import { IP_NODE_SIZE } from './ipShape.js';
+export const PX_PER_WEEK = 120;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const ITEM_TOP_HANDLE_X = 8;
+const LANE_GAP_X = 24;
+const ROW_GAP = 32;
+const BLOCK_GAP = 120;
+export const LEVELS = ['objective', 'key-result', 'epic', 'feature', 'story', 'enabler', 'milestone'];
+const DEFAULT_DURATION = { epic: 8, feature: 4, story: 1, enabler: 2, milestone: 0, objective: 12, 'key-result': 12 };
+const DEFAULT_WIDTH = { epic: 280, feature: 260, story: 240, enabler: 240, milestone: 120, objective: 280, 'key-result': 260 };
+const MIN_PAINT = { epic: 360, feature: 360, story: 352, enabler: 352 };
+const HEIGHT = { epic: 265, feature: 265, story: 220, enabler: 220, milestone: 54, objective: 200, 'key-result': 220 };
+const HERO_EXTRA = 150;
+export function calendarStart(now) {
+    const s = new Date(now.getFullYear(), now.getMonth() - 3, 1);
+    const d = s.getDay();
+    s.setDate(s.getDate() + (d === 0 ? -6 : 1 - d));
+    return s;
+}
+const pad = (n) => String(n).padStart(2, '0');
+export const isoDate = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+function parseIso(s) {
+    if (typeof s !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(s))
+        return null;
+    const out = new Date(Number(s.slice(0, 4)), Number(s.slice(5, 7)) - 1, Number(s.slice(8, 10)));
+    return Number.isNaN(out.getTime()) ? null : out;
+}
+export function columnOf(date, now) {
+    return Math.round((date.getTime() - calendarStart(now).getTime()) / WEEK_MS);
+}
+export function dateAtColumn(col, now) {
+    const d = calendarStart(now);
+    d.setDate(d.getDate() + Math.round(col * 7));
+    return d;
+}
+export function todayColumn(now) {
+    return Math.max(0, Math.floor((now.getTime() - calendarStart(now).getTime()) / WEEK_MS));
+}
+export function sprintAtColumn(col) {
+    const c = Math.max(0, col);
+    const L = ['S1', 'S2', 'S3', 'S4', 'S5', 'IP'];
+    return { pi: `PI-${Math.floor(c / 12) + 1}`, sprint: L[Math.floor((c % 12) / 2)] ?? 'S1' };
+}
+export function scheduleFields(col, weeks, now) {
+    const s = sprintAtColumn(col);
+    const e = sprintAtColumn(col + Math.round(weeks));
+    return {
+        durationWeeks: weeks,
+        startDate: isoDate(dateAtColumn(col, now)),
+        endDate: isoDate(dateAtColumn(col + weeks, now)),
+        pi: s.pi, sprint: s.sprint, endPi: e.pi, endSprint: e.sprint,
+    };
+}
+export const levelOf = (n) => LEVELS.includes(n.data?.hierarchyLevel) ? n.data.hierarchyLevel : 'story';
+export const isItem = (n) => n.type === 'portfolio-item';
+export const isIpNode = (n) => n.type === 'rad-module' && n.data?.subtype === 'ip';
+export function layoutTimeline(nodes, opts = {}) {
+    const now = opts.now ?? new Date();
+    const heights = opts.heights ?? {};
+    const items = nodes.filter(isItem);
+    const byId = new Map(items.map(n => [n.id, n]));
+    const positions = new Map();
+    const widthOverride = new Map();
+    const geo = new Map();
+    for (const n of items) {
+        const level = levelOf(n);
+        const start = parseIso(n.data?.startDate);
+        const col = start ? columnOf(start, now) : Math.round((n.position?.x ?? 0) / PX_PER_WEEK);
+        const weeks = typeof n.data?.durationWeeks === 'number' ? n.data.durationWeeks : DEFAULT_DURATION[level];
+        const natural = weeks > 0 ? weeks * PX_PER_WEEK : DEFAULT_WIDTH[level];
+        const min = MIN_PAINT[level] ?? 0;
+        widthOverride.set(n.id, natural < min ? min : null);
+        const hero = Array.isArray(n.data?.pastedImages) && n.data.pastedImages.length > 0;
+        geo.set(n.id, { x: col * PX_PER_WEEK, width: Math.max(natural, min), height: heights[n.id] ?? HEIGHT[level] + (hero && (level === 'epic' || level === 'feature') ? HERO_EXTRA : 0) });
+    }
+    const kids = new Map();
+    for (const n of items) {
+        const p = n.data?.parentItemId;
+        if (p && geo.has(p))
+            kids.set(p, [...(kids.get(p) ?? []), n.id]);
+    }
+    const right = new Map();
+    const paintedRight = (id, depth = 0) => {
+        if (right.has(id))
+            return right.get(id);
+        const g = geo.get(id);
+        let r = g.x + g.width;
+        if (depth < 12)
+            for (const k of kids.get(id) ?? [])
+                r = Math.max(r, paintedRight(k, depth + 1) + 20);
+        right.set(id, r);
+        return r;
+    };
+    for (const [id, g] of geo)
+        g.width = paintedRight(id) - g.x;
+    const epicOf = (n) => {
+        let cur = n;
+        for (let i = 0; cur && i < 12; i++) {
+            if (levelOf(cur) === 'epic')
+                return cur.id;
+            cur = cur.data?.parentItemId ? byId.get(cur.data.parentItemId) : undefined;
+        }
+        return null;
+    };
+    const placeBand = (slots, top) => {
+        const lanes = [];
+        const laneOf = new Map();
+        for (const s of slots) {
+            const free = (i) => !lanes[i] || lanes[i].spans.every(([a, b]) => s.x + s.width + LANE_GAP_X <= a || b + LANE_GAP_X <= s.x);
+            const parentLane = s.from !== undefined ? laneOf.get(s.from) : undefined;
+            let l = 0;
+            if (parentLane !== undefined && free(parentLane))
+                l = parentLane;
+            else
+                while (!free(l))
+                    l++;
+            if (!lanes[l])
+                lanes[l] = { spans: [], height: 0 };
+            lanes[l].spans.push([s.x, s.x + s.width]);
+            lanes[l].height = Math.max(lanes[l].height, s.height);
+            laneOf.set(s.id, l);
+        }
+        const laneY = [];
+        let y = top;
+        lanes.forEach((lane, i) => { laneY[i] = y; y += lane.height + 24; });
+        for (const s of slots)
+            positions.set(s.id, { x: s.x, y: laneY[laneOf.get(s.id)] });
+        return lanes.length ? y - 24 + ROW_GAP : top;
+    };
+    const slot = (id, from) => ({ id, ...geo.get(id), ...(from ? { from } : {}) });
+    const byX = (a, b) => geo.get(a.id).x - geo.get(b.id).x || a.id.localeCompare(b.id);
+    let y = 0;
+    for (const o of items.filter(n => levelOf(n) === 'objective').sort(byX))
+        y = placeBand([slot(o.id)], y);
+    y = placeBand(items.filter(n => levelOf(n) === 'key-result').sort(byX).map(n => slot(n.id)), y);
+    const ipNodes = nodes.filter(isIpNode);
+    const ipFirstSource = new Map();
+    const ipUnplaced = [];
+    for (const n of ipNodes) {
+        const src = (n.data?.attachedItemIds ?? []).find((id) => geo.has(id));
+        if (src)
+            ipFirstSource.set(n.id, src);
+        else
+            ipUnplaced.push(n.id);
+    }
+    const epics = items.filter(n => levelOf(n) === 'epic').sort(byX);
+    const rest = items.filter(n => !['objective', 'key-result', 'epic'].includes(levelOf(n)));
+    for (const epic of [...epics.map(e => e.id), null]) {
+        const inBlock = rest.filter(n => epicOf(n) === epic);
+        const blockIds = new Set([...(epic ? [epic] : []), ...inBlock.map(n => n.id)]);
+        const ips = ipNodes.filter(n => blockIds.has(ipFirstSource.get(n.id) ?? ''));
+        if (!epic && !inBlock.length && !ips.length)
+            continue;
+        if (y > 0)
+            y += BLOCK_GAP - ROW_GAP;
+        if (epic)
+            y = placeBand([slot(epic)], y);
+        if (ips.length) {
+            const src = (id) => geo.get(ipFirstSource.get(id));
+            y = placeBand(ips.map(n => ({ id: n.id, x: src(n.id).x + ITEM_TOP_HANDLE_X - IP_NODE_SIZE.width / 2, width: IP_NODE_SIZE.width, height: IP_NODE_SIZE.height })).sort((a, b) => a.x - b.x), y) - ROW_GAP + 16;
+        }
+        const features = inBlock.filter(n => levelOf(n) === 'feature').sort(byX);
+        const leaves = inBlock.filter(n => levelOf(n) === 'story' || levelOf(n) === 'enabler').sort(byX);
+        const underFeature = (f) => leaves.filter(n => n.data?.parentItemId === f);
+        const pool = features.map(f => slot(f.id));
+        for (const f of features)
+            pool.push(...underFeature(f.id).map(n => slot(n.id, f.id)));
+        const featureIds = new Set(features.map(f => f.id));
+        pool.push(...leaves.filter(n => !featureIds.has(n.data?.parentItemId)).map(n => slot(n.id)));
+        pool.push(...inBlock.filter(n => levelOf(n) === 'milestone').sort(byX).map(n => slot(n.id)));
+        y = placeBand(pool, y);
+    }
+    ipUnplaced.forEach((id, k) => positions.set(id, { x: k * (IP_NODE_SIZE.width + LANE_GAP_X), y: y + BLOCK_GAP }));
+    return { positions, widthOverride };
+}
+export function applyLayout(nodes, res) {
+    return nodes.map(n => {
+        const p = res.positions.get(n.id);
+        if (!p)
+            return n;
+        const out = { ...n, position: { x: Math.round(p.x), y: Math.round(p.y) } };
+        if (res.widthOverride.has(n.id)) {
+            const data = { ...(n.data ?? {}) };
+            const w = res.widthOverride.get(n.id);
+            if (w)
+                data.manualWidthOverride = w;
+            else
+                delete data.manualWidthOverride;
+            out.data = data;
+        }
+        return out;
+    });
+}

package/dist/core/server.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ApiContext } from './config.js';
 export declare const SERVER_NAME = "nonbot-mcp";
-export declare const SERVER_VERSION = "0.1.0";
+export declare const SERVER_VERSION = "0.2.0";
 export declare const INSTRUCTIONS: string;
 export declare function registerAll(server: McpServer, ctx: ApiContext): void;
 export declare function createNonbotMcpServer(ctx: ApiContext): McpServer;

package/dist/core/server.js

@@ -1,21 +1,25 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerPortfolioTools } from './toolsets/portfolio.js';
 import { registerIpTools } from './toolsets/ip.js';
+import { registerBuildTools } from './toolsets/build.js';
 import { registerWhygraphTools } from './toolsets/whygraph.js';
 import { registerRunTools } from './toolsets/run.js';
 import { registerMonitorTools } from './toolsets/monitor.js';
 import { registerResources } from './resources.js';
 import { registerPrompts } from './prompts.js';
 export const SERVER_NAME = 'nonbot-mcp';
-export const SERVER_VERSION = '0.1.0';
+export const SERVER_VERSION = '0.2.0';
 export const INSTRUCTIONS = [
     'non.bot MCP — work against the caller’s real product-management data, not a copy.',
     'Two domains: PORTFOLIOS (the SAFe portfolio canvas — epics → features → stories) and',
     'WHYGRAPH (the PM decision graph — the rules and decisions the team has committed to).',
     'Read before you write: call the *_list / *_get / *_search tools first.',
-    'Portfolio edits are whole-graph: portfolio_get to load the current graph + version,',
-    'edit the full node/edge set, then portfolio_update (pass expectedVersion for safe',
-    'concurrent editing). There are no per-node mutators by design.',
+    'BUILDING: portfolio_create makes an empty portfolio; portfolio_add_items adds items of any level',
+    '(parents / OKR links / dependencies by id or by a key from the same call) and lays the Timeline out;',
+    'portfolio_patch_item changes one item; portfolio_layout re-lays everything; portfolio_set_meta sets',
+    'context text and palette; portfolio_asset_upload stores an image; ip_create adds an IP node over its sources.',
+    'Whole-graph rewrites (restructures, deletes): portfolio_get for the graph + version, then portfolio_update',
+    '(pass expectedVersion for safe concurrent editing).',
     'Before a non-trivial decision, call whygraph_context to surface the LAWs and prior',
     'decisions that apply. WhyGraph is read/reasoning-only over this transport.',
     'MONITORING: run_feed / run_daemon_status / run_machines / run_prompts_list answer',
@@ -27,6 +31,7 @@ export const INSTRUCTIONS = [
 ].join(' ');
 export function registerAll(server, ctx) {
     registerPortfolioTools(server, ctx);
+    registerBuildTools(server, ctx);
     registerIpTools(server, ctx);
     registerWhygraphTools(server, ctx);
     registerRunTools(server, ctx);

package/dist/core/toolsets/build.d.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from '../config.js';
+import { type LayoutNode } from '../layout.js';
+type Node = LayoutNode & {
+    id: string;
+    type?: string;
+    data?: Record<string, any>;
+};
+type Edge = {
+    id: string;
+    source: string;
+    target: string;
+    [k: string]: unknown;
+};
+interface Graph {
+    name: string;
+    description: string;
+    nodes: Node[];
+    edges: Edge[];
+    viewport: unknown;
+    version?: number;
+}
+export declare const toHtml: (s: string) => string;
+export declare function newItemId(now?: number): string;
+declare const itemSpec: z.ZodObject<{
+    key: z.ZodOptional<z.ZodString>;
+    level: z.ZodEnum<["objective", "key-result", "epic", "feature", "story", "enabler", "milestone"]>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    bluf: z.ZodOptional<z.ZodString>;
+    acceptance_criteria: z.ZodOptional<z.ZodString>;
+    hypothesis: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<["funnel", "reviewing", "analyzing", "ready", "implementing", "done"]>>;
+    parent: z.ZodOptional<z.ZodString>;
+    okr: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    start_week: z.ZodOptional<z.ZodNumber>;
+    start_date: z.ZodOptional<z.ZodString>;
+    duration_weeks: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    wsjf: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    owner: z.ZodOptional<z.ZodString>;
+    kr_target: z.ZodOptional<z.ZodString>;
+    kr_current: z.ZodOptional<z.ZodString>;
+    okr_status: z.ZodOptional<z.ZodEnum<["on-track", "at-risk", "behind"]>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    level: "epic" | "objective" | "key-result" | "feature" | "story" | "enabler" | "milestone";
+    parent?: string | undefined;
+    description?: string | undefined;
+    acceptance_criteria?: string | undefined;
+    hypothesis?: string | undefined;
+    owner?: string | undefined;
+    key?: string | undefined;
+    bluf?: string | undefined;
+    state?: "done" | "funnel" | "reviewing" | "analyzing" | "ready" | "implementing" | undefined;
+    okr?: string[] | undefined;
+    depends_on?: string[] | undefined;
+    start_week?: number | undefined;
+    start_date?: string | undefined;
+    duration_weeks?: number | undefined;
+    tags?: string[] | undefined;
+    wsjf?: [number, number, number, number] | undefined;
+    kr_target?: string | undefined;
+    kr_current?: string | undefined;
+    okr_status?: "on-track" | "at-risk" | "behind" | undefined;
+    images?: string[] | undefined;
+    fields?: Record<string, unknown> | undefined;
+}, {
+    title: string;
+    level: "epic" | "objective" | "key-result" | "feature" | "story" | "enabler" | "milestone";
+    parent?: string | undefined;
+    description?: string | undefined;
+    acceptance_criteria?: string | undefined;
+    hypothesis?: string | undefined;
+    owner?: string | undefined;
+    key?: string | undefined;
+    bluf?: string | undefined;
+    state?: "done" | "funnel" | "reviewing" | "analyzing" | "ready" | "implementing" | undefined;
+    okr?: string[] | undefined;
+    depends_on?: string[] | undefined;
+    start_week?: number | undefined;
+    start_date?: string | undefined;
+    duration_weeks?: number | undefined;
+    tags?: string[] | undefined;
+    wsjf?: [number, number, number, number] | undefined;
+    kr_target?: string | undefined;
+    kr_current?: string | undefined;
+    okr_status?: "on-track" | "at-risk" | "behind" | undefined;
+    images?: string[] | undefined;
+    fields?: Record<string, unknown> | undefined;
+}>;
+type ItemSpec = z.infer<typeof itemSpec>;
+export declare function buildItems(g: Graph, specs: ItemSpec[], now?: Date): {
+    nodes: Node[];
+    edges: Edge[];
+    ids: Record<string, string>;
+    errors: string[];
+    patched: Map<string, Record<string, any>>;
+};
+export declare function registerBuildTools(server: McpServer, ctx: ApiContext): void;
+export {};

package/dist/core/toolsets/build.js

@@ -0,0 +1,367 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+import { validateGraph } from '../validate.js';
+import { LEVELS, applyLayout, layoutTimeline, scheduleFields, todayColumn, columnOf, isItem, PX_PER_WEEK } from '../layout.js';
+import { emptyIp, IP_KINDS, IP_NODE_SIZE } from '../ipShape.js';
+const STATES = ['funnel', 'reviewing', 'analyzing', 'ready', 'implementing', 'done'];
+const OKR_STATUSES = ['on-track', 'at-risk', 'behind'];
+const RESERVED = new Set(['hierarchyLevel', 'parentItemId', 'linkedEpicIds', 'id', '__proto__', 'constructor', 'prototype']);
+const MAX_ITEMS = 200;
+const MAX_ASSET_BYTES = 2_200_000;
+const text = (obj) => ({ type: 'text', text: JSON.stringify(obj, null, 2) });
+const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export const toHtml = (s) => /^\s*</.test(s) ? s : s.split(/\n{2,}/).map(p => `<p>${escHtml(p.trim()).replace(/\n/g, '<br>')}</p>`).join('');
+export function newItemId(now = Date.now()) { return `pf-${now}-${Math.random().toString(36).slice(2, 11)}`; }
+async function loadGraph(ctx, id) {
+    const data = await expectJson(await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(id)}`), 'load portfolio');
+    const g = (data.graph ?? data);
+    return {
+        name: String(data.name ?? g.name ?? ''),
+        description: String(data.description ?? g.description ?? ''),
+        nodes: Array.isArray(g.nodes) ? g.nodes : [],
+        edges: Array.isArray(g.edges) ? g.edges : [],
+        viewport: g.viewport ?? { x: 0, y: 0, zoom: 1 },
+        version: typeof g.version === 'number' ? g.version : undefined,
+    };
+}
+async function saveGraph(ctx, id, before, after, expectedVersion) {
+    const problems = validateGraph(after.nodes, after.edges);
+    if (problems.length)
+        return { ok: false, message: `Refusing to write — ${problems.length} problem(s):\n` + problems.map(p => `  - ${p}`).join('\n') };
+    if (ctx.backup) {
+        try {
+            await ctx.backup(id, before);
+        }
+        catch { }
+    }
+    const res = await api(ctx, '/api/portfolio/graph', {
+        method: 'PUT',
+        body: JSON.stringify({ id, name: after.name, description: after.description, nodes: after.nodes, edges: after.edges, viewport: after.viewport, expectedVersion: expectedVersion ?? before.version }),
+    });
+    if (res.status === 409) {
+        const c = (await res.json().catch(() => ({})));
+        return { ok: false, message: `Refused (409) — the portfolio changed since it was read (now version ${c.currentVersion ?? '?'}). Nothing was written; call again.` };
+    }
+    const out = await expectJson(res, 'save portfolio');
+    return { ok: true, version: typeof out.version === 'number' ? out.version : undefined };
+}
+const itemSpec = z.object({
+    key: z.string().max(64).optional().describe('A local name for this item, so other items in the SAME call can name it as parent / okr / depends_on before it has an id.'),
+    level: z.enum(LEVELS),
+    title: z.string().min(1).max(200),
+    description: z.string().max(20000).optional().describe('Plain text (blank lines = paragraphs) or HTML.'),
+    bluf: z.string().max(4000).optional().describe('Bottom line up front — the sentence the card shows.'),
+    acceptance_criteria: z.string().max(8000).optional(),
+    hypothesis: z.string().max(4000).optional().describe('Hypothesis statement ("We believe … will … measured by …").'),
+    state: z.enum(STATES).optional().describe('Default funnel.'),
+    parent: z.string().optional().describe('Parent item id, or a key from this call. Epic → feature/enabler/milestone, feature → story/enabler/milestone, objective → key-result.'),
+    okr: z.array(z.string()).max(10).optional().describe('Epics only: key-result ids/keys this epic contributes to (an okr-link edge + the KR roll-up).'),
+    depends_on: z.array(z.string()).max(20).optional().describe('Finish-to-start predecessors (ids or keys).'),
+    start_week: z.number().int().min(-52).max(156).optional().describe('Start, in weeks from the Monday of the current week (negative = past). Ignored when start_date is given.'),
+    start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    duration_weeks: z.number().min(0).max(156).optional().describe('Default: epic 8, feature 4, story 1, enabler 2, milestone 0, objective / key-result 12.'),
+    tags: z.array(z.string().max(40)).max(20).optional(),
+    wsjf: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional().describe('[business value, time criticality, risk reduction, job size].'),
+    owner: z.string().max(80).optional(),
+    kr_target: z.string().max(200).optional(),
+    kr_current: z.string().max(200).optional(),
+    okr_status: z.enum(OKR_STATUSES).optional(),
+    images: z.array(z.string().max(2048)).max(8).optional().describe('Image URLs from portfolio_asset_upload — the first is the card hero.'),
+    fields: z.record(z.unknown()).optional().describe('Any other PortfolioItemData fields, merged last (structural keys are refused).'),
+});
+const DEFAULT_WEEKS = { epic: 8, feature: 4, story: 1, enabler: 2, milestone: 0, objective: 12, 'key-result': 12 };
+const LEGAL_PARENT = {
+    epic: [], objective: [], 'key-result': ['objective'], feature: ['epic'], story: ['feature', 'epic'], enabler: ['epic', 'feature'], milestone: ['epic', 'feature'],
+};
+export function buildItems(g, specs, now = new Date()) {
+    const errors = [];
+    const ids = {};
+    const t0 = now.getTime();
+    const idOf = specs.map((s, i) => { const id = newItemId(t0 + i); ids[s.key ?? `#${i}`] = id; return id; });
+    const levelById = new Map(g.nodes.filter(isItem).map(n => [n.id, String(n.data?.hierarchyLevel)]));
+    specs.forEach((s, i) => levelById.set(idOf[i], s.level));
+    const resolve = (ref) => ids[ref] ?? (levelById.has(ref) ? ref : null);
+    const base = todayColumn(now);
+    const nodes = [];
+    const edges = [];
+    const krLinks = new Map();
+    specs.forEach((s, i) => {
+        const self = idOf[i];
+        const label = s.key ?? s.title;
+        const d = { hierarchyLevel: s.level, title: s.title, description: s.description ? toHtml(s.description) : '', state: s.state ?? 'funnel', createdAt: t0, updatedAt: t0 };
+        if (s.parent) {
+            const p = resolve(s.parent);
+            if (!p)
+                errors.push(`${label}: parent "${s.parent}" is neither an id in the portfolio nor a key in this call`);
+            else if (!(LEGAL_PARENT[s.level] ?? []).includes(levelById.get(p) ?? ''))
+                errors.push(`${label}: a ${s.level} cannot sit under a ${levelById.get(p)} (allowed: ${(LEGAL_PARENT[s.level] ?? []).join(', ') || 'none — top level'})`);
+            else {
+                d.parentItemId = p;
+                edges.push({ id: `edge-${p}-${self}`, source: p, target: self, dependencyType: 'hierarchy' });
+            }
+        }
+        const weeks = s.duration_weeks ?? DEFAULT_WEEKS[s.level] ?? 1;
+        const col = s.start_date ? columnOf(new Date(Number(s.start_date.slice(0, 4)), Number(s.start_date.slice(5, 7)) - 1, Number(s.start_date.slice(8, 10))), now) : base + (s.start_week ?? 0);
+        Object.assign(d, scheduleFields(col, weeks, now));
+        if (s.bluf)
+            d.bluf = toHtml(s.bluf);
+        if (s.acceptance_criteria)
+            d.acceptanceCriteria = toHtml(s.acceptance_criteria);
+        if (s.hypothesis)
+            d.hypothesisStatement = s.hypothesis;
+        if (s.tags)
+            d.tags = s.tags;
+        if (s.owner)
+            d.owner = s.owner;
+        if (s.wsjf)
+            Object.assign(d, { wsjfBusinessValue: s.wsjf[0], wsjfTimeCriticality: s.wsjf[1], wsjfRiskReduction: s.wsjf[2], wsjfJobSize: s.wsjf[3] });
+        if (s.kr_target)
+            d.krTarget = s.kr_target;
+        if (s.kr_current)
+            d.krCurrent = s.kr_current;
+        if (s.okr_status)
+            d.okrStatus = s.okr_status;
+        if (s.images?.length)
+            d.pastedImages = s.images;
+        if (s.level === 'epic')
+            d.innerLoopExpanded = false;
+        for (const [k, v] of Object.entries(s.fields ?? {})) {
+            if (RESERVED.has(k))
+                errors.push(`${label}: fields.${k} is structural — use the tool's own parameter`);
+            else
+                d[k] = v;
+        }
+        for (const kr of s.okr ?? []) {
+            const k = resolve(kr);
+            if (s.level !== 'epic')
+                errors.push(`${label}: okr links are for epics`);
+            else if (!k || levelById.get(k) !== 'key-result')
+                errors.push(`${label}: okr "${kr}" is not a key result`);
+            else {
+                edges.push({ id: `edge-${k}-${self}`, source: k, target: self, dependencyType: 'okr-link' });
+                krLinks.set(k, [...(krLinks.get(k) ?? []), self]);
+            }
+        }
+        for (const dep of s.depends_on ?? []) {
+            const p = resolve(dep);
+            if (!p)
+                errors.push(`${label}: depends_on "${dep}" not found`);
+            else
+                edges.push({ id: `edge-${p}-${self}`, source: p, target: self, dependencyType: 'finish-to-start', label: 'FS' });
+        }
+        nodes.push({ id: self, type: 'portfolio-item', position: { x: col * PX_PER_WEEK, y: 0 }, data: d });
+    });
+    const patched = new Map();
+    for (const [kr, epics] of krLinks) {
+        const fresh = nodes.find(n => n.id === kr);
+        const old = g.nodes.find(n => n.id === kr);
+        const data = { ...((fresh ?? old)?.data ?? {}) };
+        data.linkedEpicIds = [...new Set([...(data.linkedEpicIds ?? []), ...epics])];
+        if (fresh)
+            fresh.data = data;
+        else if (old)
+            patched.set(kr, data);
+    }
+    return { nodes, edges, ids, errors, patched };
+}
+export function registerBuildTools(server, ctx) {
+    if (ctx.readonly)
+        return;
+    server.registerTool('portfolio_create', {
+        title: 'Create an empty portfolio',
+        description: 'Create a new, empty portfolio owned by the caller and return its id + version. Fill it with portfolio_add_items (any level) and ip_create; set its context text and palette with portfolio_set_meta.',
+        inputSchema: {
+            name: z.string().min(1).max(200),
+            description: z.string().max(2000).optional(),
+            status: z.enum(['active', 'draft']).optional().describe('Default active (the CREATE path alone leaves a new row as draft).'),
+        },
+        outputSchema: { id: z.string(), version: z.number().optional(), url: z.string(), status: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const out = await expectJson(await api(ctx, '/api/portfolio/graph', {
+            method: 'PUT', body: JSON.stringify({ name: a.name, description: a.description ?? '', nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } }),
+        }), 'portfolio_create');
+        const id = String(out.id ?? '');
+        if (!id)
+            return fail('portfolio_create: the server did not return an id.');
+        const status = a.status ?? 'active';
+        if (status !== 'draft')
+            await expectJson(await api(ctx, '/api/portfolio/graph', { method: 'PUT', body: JSON.stringify({ id, metaOnly: true, status }) }), 'portfolio_create (status)');
+        const structured = { id, ...(typeof out.version === 'number' ? { version: out.version } : {}), url: `${ctx.apiBase}/portfolio/${id}`, status };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_add_items', {
+        title: 'Add items to a portfolio',
+        description: 'Add up to 200 items of any level (objective, key-result, epic, feature, story, enabler, milestone) in one versioned write. Parents, OKR links and dependencies may name existing ids OR `key`s of other items in the same call, so a whole tree goes in at once. The tool makes the ids, the hierarchy / okr-link / finish-to-start edges, the dates and sprint labels from start_week + duration_weeks, and (unless layout is "none") re-lays the whole portfolio on the Timeline so nothing overlaps. Returns key → id. Rich text fields accept plain text or HTML.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            items: z.array(itemSpec).min(1).max(MAX_ITEMS),
+            layout: z.enum(['timeline', 'none']).optional().describe('Default timeline: re-lay every item after adding. "none": new items get their date x and y 0.'),
+            expected_version: z.number().int().optional().describe('Optional OCC guard; default = the version read at call time.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const keys = a.items.map(s => s.key).filter(Boolean);
+        if (new Set(keys).size !== keys.length)
+            return fail('Two items share a key — keys must be unique within one call.');
+        const built = buildItems(g, a.items);
+        if (built.errors.length)
+            return fail(`Nothing was written — ${built.errors.length} problem(s):\n` + built.errors.map(e => `  - ${e}`).join('\n'));
+        let nodes = [...g.nodes.map(n => built.patched.has(n.id) ? { ...n, data: built.patched.get(n.id) } : n), ...built.nodes];
+        if ((a.layout ?? 'timeline') === 'timeline')
+            nodes = applyLayout(nodes, layoutTimeline(nodes));
+        const after = { ...g, nodes, edges: [...g.edges, ...built.edges] };
+        const r = await saveGraph(ctx, a.portfolio_id, g, after, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, added: built.nodes.length, edges: built.edges.length, ids: built.ids, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_patch_item', {
+        title: 'Patch one item',
+        description: 'Change fields of ONE portfolio item without rewriting the graph (PATCH /api/portfolio/graph/node): `set` writes allowlisted PortfolioItemData fields (title, description, bluf, acceptanceCriteria, hypothesisStatement, state, tags, wsjf*, krTarget, pastedImages, durationWeeks, startDate, …), `unset` deletes them. Rich text is stored as given (pass HTML, or plain text which is wrapped in <p>). A stale version answers 409 — nothing is written.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_id: z.string(),
+            set: z.record(z.unknown()).optional(),
+            unset: z.array(z.string()).max(40).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        if (!a.set && !a.unset)
+            return fail('Provide set and/or unset.');
+        let version = a.expected_version;
+        if (version === undefined)
+            version = (await loadGraph(ctx, a.portfolio_id)).version;
+        const set = {};
+        for (const [k, v] of Object.entries(a.set ?? {}))
+            set[k] = typeof v === 'string' && ['description', 'bluf', 'acceptanceCriteria'].includes(k) ? toHtml(v) : v;
+        const res = await api(ctx, '/api/portfolio/graph/node', { method: 'PATCH', body: JSON.stringify({ graphId: a.portfolio_id, nodeId: a.item_id, expectedVersion: version, ...(a.set ? { set } : {}), ...(a.unset ? { unset: a.unset } : {}) }) });
+        if (res.status === 409)
+            return fail('Refused (409) — the portfolio changed since it was read. Call again.');
+        const out = await expectJson(res, 'portfolio_patch_item');
+        const structured = { ok: true, ...(typeof out.version === 'number' ? { version: out.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_layout', {
+        title: 'Lay out a portfolio on the Timeline',
+        description: 'Re-position every item so the Timeline reads cleanly: x from each item\'s start date (the canvas reads dates off x), y top-down — objectives, key results, then one block per epic (epic, features, stories + enablers, milestones), each row lane-packed so overlapping items stack, IP nodes directly above their first source. Short items get a minimum painted width so titles fit. Content is untouched. `heights` overrides the estimated card height per id (px) when a card measures taller on screen.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            heights: z.record(z.number().min(20).max(2000)).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const res = layoutTimeline(g.nodes, { heights: a.heights });
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: applyLayout(g.nodes, res) }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, positioned: res.positions.size, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_set_meta', {
+        title: 'Set portfolio settings',
+        description: 'Graph-level settings that travel with the portfolio (the `__graph_meta__` record): `context_text` (the portfolio\'s context notes — what a newcomer reads first), `palette` ({ id, name, swatches: [{hex, label?}] ≤ 10, roles?: {epic, feature, story, …: hex | "p:N"} }), `canvas_style`, `sprint_settings`. Only the keys you pass change; everything else in the record is kept.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            context_text: z.string().max(20000).optional(),
+            palette: z.object({ id: z.string().min(1).max(64), name: z.string().min(1).max(64), swatches: z.array(z.object({ hex: z.string().regex(/^#[0-9a-fA-F]{6}$/), label: z.string().max(32).optional() })).max(10), roles: z.record(z.string()).optional() }).optional(),
+            canvas_style: z.record(z.unknown()).optional(),
+            sprint_settings: z.record(z.unknown()).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const cur = g.nodes.find(n => n.id === '__graph_meta__' || n.type === 'graph-meta');
+        const data = { ...(cur?.data ?? {}) };
+        if (a.context_text !== undefined)
+            data.contextText = a.context_text;
+        if (a.palette)
+            data.palette = { ...a.palette, swatches: a.palette.swatches.map(s => ({ ...s, hex: s.hex.toUpperCase() })), roles: a.palette.roles ?? {} };
+        if (a.canvas_style)
+            data.canvasStyle = { ...(data.canvasStyle ?? {}), ...a.canvas_style };
+        if (a.sprint_settings)
+            data.sprintSettings = { ...(data.sprintSettings ?? {}), ...a.sprint_settings };
+        const meta = { id: '__graph_meta__', type: 'graph-meta', position: { x: 0, y: 0 }, data };
+        const nodes = cur ? g.nodes.map(n => n === cur ? meta : n) : [...g.nodes, meta];
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, keys: Object.keys(data), ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_asset_upload', {
+        title: 'Upload an image',
+        description: 'Store one image (PNG / JPEG / WebP / GIF, ≤ 2.2 MB — downscale first; the app keeps images at 1024 px JPEG) in your private asset store and get back its URL, for an item\'s `images` (card hero) or IP evidence (`ip_evidence_add` kind image with {asset: key}). Pass `data_url`, or `file_path` when this server runs locally (stdio).',
+        inputSchema: {
+            data_url: z.string().regex(/^data:image\/(png|jpeg|webp|gif);base64,/).optional(),
+            file_path: z.string().max(1024).optional(),
+        },
+        outputSchema: { url: z.string(), key: z.string().optional(), bytes: z.number() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        let dataUrl = a.data_url;
+        if (!dataUrl && a.file_path) {
+            if (!ctx.readLocalImage)
+                return fail('file_path is only available when the MCP server runs locally — pass data_url instead.');
+            dataUrl = await ctx.readLocalImage(a.file_path);
+        }
+        if (!dataUrl)
+            return fail('Provide data_url or file_path.');
+        const bytes = Math.floor((dataUrl.length - dataUrl.indexOf(',') - 1) * 3 / 4);
+        if (bytes > MAX_ASSET_BYTES)
+            return fail(`The image is ${(bytes / 1e6).toFixed(1)} MB; the limit is 2.2 MB. Downscale it (1024 px JPEG is what the app stores) and retry.`);
+        const out = await expectJson(await api(ctx, '/api/portfolio/storyboard-assets', { method: 'POST', body: JSON.stringify({ dataUrl }) }), 'portfolio_asset_upload');
+        const url = out.url ? String(out.url) : out.key ? `/api/portfolio/asset?key=${encodeURIComponent(String(out.key))}` : '';
+        if (!url)
+            return fail('portfolio_asset_upload: the server returned no url.');
+        const structured = { url, ...(out.key ? { key: String(out.key) } : {}), bytes };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('ip_create', {
+        title: 'Create an IP node',
+        description: 'Add an IP node — a patent or trademark disclosure — to a portfolio, wired to its source items (the cards the disclosure is prepared FROM: their title, description, BLUF, acceptance criteria and hypothesis). Placed above its first source like the canvas does, with an empty disclosure bag; then fill it in the app (Continue → prefills from the sources on your key) or with ip_update. Requires the IP node feature to be on for the caller.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            track: z.enum(['patent', 'trademark']),
+            kind: z.enum(['provisional', 'nonprovisional', 'design', 'application']).optional().describe('patent: provisional (default) / nonprovisional / design; trademark: application.'),
+            title: z.string().max(200).optional().describe('The filing\'s working title shown on the card.'),
+            sources: z.array(z.string()).min(1).max(20).describe('Item ids the disclosure reads from (first = the one it sits above).'),
+            layout: z.enum(['timeline', 'none']).optional().describe('Default timeline: re-lay the portfolio so the node gets its own row above its source. "none": place it 40 px above the source and move nothing else.'),
+            expected_version: z.number().int().optional(),
+        },
+        outputSchema: { nodeId: z.string(), version: z.number().optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const track = a.track;
+        if (a.kind && !IP_KINDS[track].includes(a.kind))
+            return fail(`kind ${a.kind} is not a ${track} kind (${IP_KINDS[track].join(', ')}).`);
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const items = new Map(g.nodes.filter(isItem).map(n => [n.id, n]));
+        const missing = a.sources.filter(s => !items.has(s));
+        if (missing.length)
+            return fail(`Not items in this portfolio: ${missing.join(', ')}`);
+        const src = items.get(a.sources[0]);
+        const nodeId = `radmod-ip-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const bag = { ...emptyIp(track, a.kind), title: a.title ?? '' };
+        const node = {
+            id: nodeId, type: 'rad-module',
+            position: { x: (src.position?.x ?? 0) + 8 - IP_NODE_SIZE.width / 2, y: (src.position?.y ?? 0) - IP_NODE_SIZE.height - 40 },
+            data: { subtype: 'ip', moduleData: bag, width: IP_NODE_SIZE.width, height: IP_NODE_SIZE.height, attachedItemIds: [...new Set(a.sources)] },
+        };
+        let nodes = [...g.nodes, node];
+        if ((a.layout ?? 'timeline') === 'timeline')
+            nodes = applyLayout(nodes, layoutTimeline(nodes));
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { nodeId, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+}

package/dist/core/toolsets/portfolio.js

@@ -222,7 +222,7 @@ export function registerPortfolioTools(server, ctx) {
     }
     server.registerTool('portfolio_update', {
         title: 'Replace a portfolio graph',
-        description: 'Whole-graph replace: write the complete nodes + edges for a portfolio. This is the ONLY graph writer by design — there are no per-node mutators, so the model always composes the full intended state. Pre-flight validation rejects orphan parents, duplicate ids, and unresolvable epic links. The current server state is snapshotted (backed up) before the write. Pass expectedVersion from portfolio_get; if it no longer matches, the write is refused with a 409 instead of clobbering a concurrent edit.',
+        description: 'Whole-graph replace: write the complete nodes + edges for a portfolio. Use it for restructures and deletes; to ADD items use portfolio_add_items, to change one item portfolio_patch_item, to re-position portfolio_layout. Pre-flight validation rejects orphan parents, duplicate ids, and unresolvable epic links. The current server state is snapshotted (backed up) before the write. Pass expectedVersion from portfolio_get; if it no longer matches, the write is refused with a 409 instead of clobbering a concurrent edit.',
         inputSchema: {
             id: z.string().describe('Portfolio id.'),
             nodes: z.array(z.any()).describe('The COMPLETE set of nodes (whole-graph replace).'),
@@ -304,9 +304,9 @@ export function registerPortfolioTools(server, ctx) {
                 nodes,
                 edges,
                 ...(baselineVersion !== undefined ? { expectedVersion: baselineVersion } : {}),
-                ...(args.name !== undefined ? { name: args.name } : {}),
-                ...(args.description !== undefined ? { description: args.description } : {}),
-                ...(args.viewport !== undefined ? { viewport: args.viewport } : {}),
+                name: args.name ?? String(current.name ?? current.graph?.name ?? ''),
+                description: args.description ?? String(current.description ?? current.graph?.description ?? ''),
+                ...(args.viewport !== undefined ? { viewport: args.viewport } : currentGraph.viewport !== undefined ? { viewport: currentGraph.viewport } : {}),
             }),
         });
         if (putRes.status === 409) {

package/dist/stdio.js

@@ -32,13 +32,35 @@ async function fileBackup(id, json) {
     }
     await writeFile(file, JSON.stringify(json, null, 2), 'utf8');
 }
+const IMAGE_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' };
+async function readLocalImage(path) {
+    const ext = path.toLowerCase().split('.').pop() ?? '';
+    const mime = IMAGE_MIME[ext];
+    if (!mime)
+        throw new Error('file_path must be a .png, .jpg, .jpeg, .webp or .gif image');
+    const buf = await readFile(resolve(path));
+    if (buf.length > 2_200_000)
+        throw new Error(`The image is ${(buf.length / 1e6).toFixed(1)} MB; the limit is 2.2 MB — downscale it first`);
+    const magic = buf.subarray(0, 12);
+    const ok = mime === 'image/png' ? magic[0] === 0x89 && magic[1] === 0x50
+        : mime === 'image/jpeg' ? magic[0] === 0xff && magic[1] === 0xd8
+            : mime === 'image/gif' ? magic.toString('latin1', 0, 3) === 'GIF'
+                : magic.toString('latin1', 0, 4) === 'RIFF' && magic.toString('latin1', 8, 12) === 'WEBP';
+    if (!ok)
+        throw new Error('file_path is not the image its extension says it is');
+    return `data:${mime};base64,${buf.toString('base64')}`;
+}
 async function main() {
-    const token = process.env.NON_BOT_API_TOKEN || (await tokenFromCliAuth());
+    const inRun = typeof process.env.NONBOT_RUN_ID === 'string' && process.env.NONBOT_RUN_ID.length > 0;
+    const token = inRun
+        ? (process.env.NONBOT_PAT || '')
+        : (process.env.NON_BOT_API_TOKEN || (await tokenFromCliAuth()));
     const ctx = {
         apiBase: resolveApiBase(process.env.NON_BOT_API_BASE),
         getToken: () => token,
         readonly: process.env.NON_BOT_MCP_READONLY === '1',
         backup: fileBackup,
+        readLocalImage,
     };
     const server = createNonbotMcpServer(ctx);
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nonbot/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "The non.bot MCP server — one server for your portfolios, decision graph, and Runs. Runs over stdio (Claude Code, Cursor, VS Code) with a pat_ token. Built on MCP protocol 2025-11-25.",
   "keywords": [