@nonbot/mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,43 @@
+Copyright (c) 2026 non.bot. All rights reserved.
+
+PROPRIETARY SOFTWARE — NOT OPEN SOURCE
+
+This software (the "@nonbot/mcp" package and all of its contents, the
+"Software") is the proprietary and confidential property of non.bot. It is
+published to the npm registry for the sole purpose of allowing authorized
+non.bot account holders to install and run it as the Model Context Protocol server that
+connects their AI client to the non.bot service.
+
+PERMITTED USE
+
+Subject to your compliance with the non.bot Terms of Service, you are granted
+a limited, non-exclusive, non-transferable, revocable license to download,
+install, and execute unmodified copies of the Software on machines you control,
+solely to connect to and operate the non.bot service.
+
+PROHIBITED WITHOUT PRIOR WRITTEN PERMISSION FROM non.bot
+
+  - Copying, redistributing, sublicensing, selling, or publishing the Software
+    or any portion of it;
+  - Modifying, adapting, translating, or creating derivative works;
+  - Reverse-engineering, decompiling, or disassembling the Software except to
+    the limited extent such restriction is prohibited by applicable law;
+  - Using the Software, or any technique, method, or design embodied in it, to
+    build, train, or operate a competing product or service.
+
+NO PATENT OR OTHER IP LICENSE
+
+No license to any patent, patent application, trademark, trade secret, or other
+intellectual-property right of non.bot is granted, whether expressly, by
+implication, by estoppel, or otherwise, except for the limited execution right
+stated above. All such rights are expressly reserved.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+non.bot BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT
+OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Contact: legal@non.bot

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# @nonbot/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One MCP server for your non.bot data.** Your terminal agent (Claude Code, Cursor, VS Code, or any MCP client) reads and reasons over your *real* portfolios, decision graph, and Runs, not a copy.
+
+```bash
+npx -y @nonbot/mcp
+```
+
+Built on the official MCP TypeScript SDK and **protocol `2025-11-25`**. Structured tool output, tool annotations, Resources, and Prompts throughout. Needs Node 18 or newer.
+
+> This is the unified successor to the separate `portfolio-mcp` and `context-graph` (WhyGraph) servers. The per-run fleet server is shipped inside `@nonbot/cli` as `nonbot run-mcp` (launched by the daemon, never installed by hand).
+
+---
+
+## Install
+
+### 1. Get a token
+
+Generate a Personal Access Token at **<https://non.bot/settings/connections>** → *API Tokens* → *Generate New Token*. Copy it (shown once). It looks like `pat_…`.
+
+Scoped tokens work too: a token with `portfolio:read` sees only the read tools' data; the table below says what each tool needs. If you have run `nonbot login` (the `@nonbot/cli` daemon) on this machine, you can omit the token entirely: the server falls back to the CLI's auth file.
+
+### 2. Add the server to your client
+
+**Claude Code** — one command:
+
+```bash
+claude mcp add nonbot -e NON_BOT_API_TOKEN=pat_<YOUR_TOKEN> -- npx -y @nonbot/mcp
+```
+
+or in `.mcp.json` (project) / `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project), same shape:
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+**VS Code** — `.vscode/mcp.json` (note the `servers` key; the token is a secret input, so the file is safe to commit):
+
+```json
+{
+  "inputs": [
+    { "id": "nonbot-pat", "type": "promptString", "description": "non.bot Personal Access Token", "password": true }
+  ],
+  "servers": {
+    "nonbot": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "${input:nonbot-pat}" }
+    }
+  }
+}
+```
+
+**Remote (Streamable HTTP)** — the same server runs as a Cloudflare Worker for clients that cannot spawn a local process. Auth is the same `pat_` token, sent as a bearer header:
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "url": "https://nonbot-mcp-remote.conradwade.workers.dev/mcp",
+      "headers": { "Authorization": "Bearer pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add --transport http nonbot https://nonbot-mcp-remote.conradwade.workers.dev/mcp --header "Authorization: Bearer pat_<YOUR_TOKEN>"`. Append `?readonly=1` to the URL for a read-only connection.
+
+> **Claude web and mobile:** claude.ai custom connectors authenticate with OAuth and cannot send a custom header, so the remote endpoint is not yet a one-click connector there. OAuth is the next step for the remote server (see `DISTRIBUTION-PLAN.md`); until it ships, use Claude Code, Cursor, or VS Code.
+
+### 3. Use it
+
+Ask your agent to "list my non.bot portfolios", "show what rules apply before I change auth", or run the `/wsjf_prioritize` prompt.
+
+---
+
+## Tools
+
+<!-- tool-table:start — generated by `npm run gen:tools`; tests/readme-tool-table.test.ts fails if this drifts from the code -->
+### Portfolio (24)
+
+The SAFe portfolio canvas: epics, features, stories, snapshots, personas, and the Run launch surface.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `portfolio_list` | List the portfolios the caller can access (owned, team, and shared). | read | `portfolio:read` |
+| `portfolio_get` | Fetch the full node/edge graph (plus viewport and version) for one portfolio. | read | `portfolio:read` |
+| `portfolio_get_activation` | Fetch the launch payload + story-brief snapshot for one activation (Act-3 ▶ Run). | read | `portfolio:read` |
+| `portfolio_subscribe_to_activations` | Poll the caller’s currently-pending activations (the Act-3 ▶ Run fallback). | read | `portfolio:read` |
+| `portfolio_versions` | List the saved version snapshots (time-travel restore points) for a portfolio — id, label, node count, created time. | read | `portfolio:read` |
+| `portfolio_version_get` | Load one snapshot’s full graph (nodes + edges + viewport) — the restore source. | read | `portfolio:read` |
+| `portfolio_characters` | List the Character personas the caller can see (their own + team), optionally scoped to a portfolio. | read | `portfolio:read` |
+| `portfolio_update` | Whole-graph replace: write the complete nodes + edges for a portfolio. | destructive | `portfolio:write` |
+| `portfolio_create_from_plan` | Create a DRAFT portfolio from an LLM-structured plan (epic + optional features/stories). | write | `portfolio:write` |
+| `portfolio_decompose` | Ask the server AI to decompose an item (epic→features or feature→stories) into SUGGESTED children for review. | write | `portfolio:write` |
+| `portfolio_attach_brief` | Attach metadata to one node: a markdown brief, acceptance criteria, description, and/or hypothesis. | write | `portfolio:write` |
+| `portfolio_link_chat_session` | Backlink a portfolio to the chat that birthed it. | write | `portfolio:write` |
+| `portfolio_publish_draft` | Flip a portfolio from "draft" → "active". | write | `portfolio:write` |
+| `portfolio_mark_run_ready` | Tag a story as ready for CLI pickup (or clear it with run_ready=false). | write | `portfolio:write` |
+| `portfolio_repo_path` | Your per-user local repo path for a portfolio — where ▶ Run activations cd before launching. | write | `portfolio:write` |
+| `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 (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` |
+| `ip_evidence_hashes` | The Export-hash-list file: one `id · sha256 · added(ISO)` line per row (never changed once written) plus a `#` trailer naming removed, missing, unsealed or alt… | read | `portfolio:read` |
+| `ip_packet` | The filing packet of an IP node as the Packet step shows it, rendered by the server from the saved graph: each document's id, name, status (queued / ready / ac… | read | `portfolio:read` |
+| `ip_packet_document` | One packet document's full text (markdown) and its text files (md / csv / txt / svg), rendered by the server from the saved graph. | read | `portfolio:read` |
+| `ip_update` | Apply an op list to one IP node in ONE versioned write: unit.set {unitId, value, expectedRev} · unit.confirm · unit.unconfirm · evidence.update {evId, patch} ·… | write | `portfolio:write` |
+| `ip_evidence_add` | Add one evidence row the SERVER hashes (SHA-256 of the stored copy), timestamps, seals and numbers. | write | `portfolio:write` |
+| `ip_witness_candidates` | Members who may witness evidence on this node (id + name only): editors of the portfolio other than the caller, never someone listed as an inventor in field 5. | write | `portfolio:write` |
+| `ip_build` | Runs `Build draft →` for a PATENT IP node on YOUR OWN model key (the token owner's Anthropic or Gemini key — non.bot never pays for it; no key = HTTP 402 no_ke… | write | `portfolio:write` |
+
+### WhyGraph (7)
+
+The PM decision graph. Read and reasoning only over token auth; writes stay cookie-only on the server.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `whygraph_search` | Search the PM decision graph by keyword, ranked by weight (how reinforced a decision is) then relevance. | read | `portfolio:read` |
+| `whygraph_context` | Given a task you are about to do, return the decisions that apply: the best keyword matches PLUS every LAW (locked, weight ≥ 5) — because LAWs always apply. | read | `portfolio:read` |
+| `whygraph_neighbors` | Graph reasoning the flat decision list cannot give you: starting from one decision, traverse RELATED_TO relationships breadth-first to surface every connected… | read | `portfolio:read` |
+| `whygraph_stats` | A dashboard view of the decision graph: total decisions, a per-category breakdown, the LAWs (locked, weight ≥ 5), and the most-violated decisions. | read | `portfolio:read` |
+| `whygraph_path` | Find the shortest chain of RELATED_TO links connecting one decision to another — how a decision reaches another through the graph. | read | `portfolio:read` |
+| `whygraph_conflicts` | Surface pairs of decisions that govern the SAME field but are NOT linked to each other — potential unreconciled overlap or contradiction to review. | read | `portfolio:read` |
+| `whygraph_recent_violations` | The most recent times decisions were violated — what broke, when, and which decision. | read | `portfolio:read` |
+
+### Run agent protocol (20)
+
+Called by a launched Run agent (telemetry, scope, reflections, close-out), not by a person.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `run_get_state` | Ground-truth run state: active_plan, ghost_plan, stickies, pending_violations, pending_reflections, trust_dial, last_user_intervention_at. | read | `portfolio:read` |
+| `run_load_activation` | Load the full context for a run: the story brief, acceptance criteria, applicable WhyGraph rules, and ensemble defaults. | write | `portfolio:write` |
+| `run_register_agent` | Register an ensemble member for this activation (creates the run on the first agent). | write | `portfolio:write` |
+| `run_declare_scope` | Lead declares the file allowlist + intent. | write | `portfolio:write` |
+| `run_request_scope_change` | Request expansion of the file allowlist. | write | `portfolio:write` |
+| `run_emit_diff` | Report a code diff. Triggers a WhyGraph rule-check + scope guard; returns { violations, reinforcements, blocked_paths }. | write | `portfolio:write` |
+| `run_emit_test_run` | Report a test run; updates the dashboard sparkline. | write | `portfolio:write` |
+| `run_emit_lint` | Report lint hits; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_typecheck` | Report type-check errors; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_build` | Report build status; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_file_touch` | Report a file access (read\|write\|create); glows the living codebase map. | write | `portfolio:write` |
+| `run_emit_usage` | Report ONE turn's raw token counts so the command center's Metered Spend tile and per-run cost cap become truthful (instead of showing $0.00). | write | `portfolio:write` |
+| `run_request_reconsider` | Verifier nudges the Lead to reflect; inserts a pending reflection row. | write | `portfolio:write` |
+| `run_post_reflection` | Lead posts a reflection (response to a reconsider, or self-initiated). decision ∈ continue\|revise_plan\|escalate. | write | `portfolio:write` |
+| `run_resolve_violation` | Resolve a rule violation. action ∈ enforce (rollback) \| accept (weight decay) \| override (log). | write | `portfolio:write` |
+| `run_set_trust_dial` | Adjust the trust dial mid-run (0–10). | write | `portfolio:write` |
+| `run_pause_agent` | Pause one ensemble member by role. | write | `portfolio:write` |
+| `run_resume_agent` | Resume one paused ensemble member by role. | write | `portfolio:write` |
+| `run_emit_pr` | Announce that a PR is open; triggers the Act-5 closing sequence. | write | `portfolio:write` |
+| `run_finish` | Final close-out: triggers reinforcement + candidate-rule extraction, sets the story to shipped. | destructive | `portfolio:write` |
+
+### Run monitoring (9)
+
+The supervisor surface: what the daemon and the fleet are doing, plus the three actuators.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `run_feed` | The unified run feed — daemon heartbeat, fleet (active + last-24h runs with status/health/progress), needs-you items, and reconcile chips. | read | `runs:monitor` or `portfolio:read` |
+| `run_daemon_status` | Is the operator's daemon connected? | read | `runs:monitor` or `portfolio:read` |
+| `run_machines` | The operator's machines with a live daemon (multi-machine runs): machine id, name, terminal kind, last-seen, and (≥0.9.10) per-machine load stats. | read | `runs:monitor` or `portfolio:read` |
+| `run_activations_recent` | The last 10 activations with launch traces (spawn steps, launcher stderr/stdout/exit code), derived status incl. staleness, terminal used, and tmux pane. | read | `runs:monitor` or `portfolio:read` |
+| `run_prompts_list` | Mid-run prompts (a run paused on a menu/question). | read | `runs:monitor` or `portfolio:read` |
+| `run_snapshot_get` | Fetch the result of a run_snapshot_request. status "ready" carries the scrubbed pane tail; "pending" = the daemon hasn't served it yet (re-poll in ~5s, up to ~… | read | `runs:control` |
+| `run_snapshot_request` | Ask the operator's daemon to capture the last lines of a RUNNING run's terminal pane (secrets scrubbed, 16KB tail cap, stored server-side for 5 minutes only). | write | `runs:control` |
+| `run_prompt_answer` | Answer a mid-run prompt on the operator's behalf — the daemon types the answer into the live pane. | destructive | `runs:respond` (explicit; a wildcard token does not satisfy it) |
+| `run_stop_daemon` | The panic button — queue a remote shutdown for the operator's daemon (CLI ≥0.9.12). | destructive | `runs:control` |
+<!-- tool-table:end -->
+
+**Kind** is the tool's MCP annotation: *read* tools never change anything; *destructive* tools are confirm-gated (`portfolio_update` on large removals, `run_prompt_answer`, `run_stop_daemon`). `NON_BOT_MCP_READONLY=1` drops every non-read tool.
+
+**Resources** — `portfolio://<id>` (a portfolio graph) · `whygraph://decisions` (all decisions + edges)
+**Prompts** — `wsjf_prioritize(portfolioId)` · `decision_check(plan)`
+
+Safety rails on writes: `portfolio_update` pre-fetches the live version, backs the prior graph up to `~/.non.bot/backups/<id>-<unix-ts>.json`, validates the new graph (orphan parents, duplicate ids, unresolvable links) and writes with `expectedVersion`, so a concurrent edit on the canvas is a `409`, never a clobber.
+
+---
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `NON_BOT_API_TOKEN` | — | `pat_` token (https://non.bot/settings/connections). Optional when `nonbot login` has run on this machine: the server falls back to the CLI's auth file (`~/.config/nonbot/auth.json`; `NONBOT_CONFIG_DIR` / `NONBOT_PROFILE` respected), so a committed `.mcp.json` never carries a secret. |
+| `NON_BOT_API_BASE` | `https://non.bot` | Host-allowlisted: the token is only ever sent to non.bot / conrad.pm / deploy previews / localhost. |
+| `NON_BOT_MCP_READONLY` | unset | `1` drops every write and action tool, leaving the read tools. |
+
+---
+
+## Architecture (for contributors)
+
+`src/core/` is **Node-free** so the identical tool logic runs in both the local stdio process and the Cloudflare Worker (`../nonbot-mcp-remote`, which imports this package's `dist/`):
+
+- `core/config.ts` — `ApiContext` + the SSRF host-allowlist guard
+- `core/http.ts` — token-bound fetch wrapper
+- `core/validate.ts` — pre-flight graph validation
+- `core/server.ts` — `registerAll(server, ctx)` (the transport-agnostic heart) + `createNonbotMcpServer(ctx)`
+- `core/toolsets/{portfolio,whygraph,run,monitor,ip}.ts`, `core/resources.ts`, `core/prompts.ts`
+- `src/stdio.ts` — the `nonbot-mcp` bin: env/CLI-auth token + filesystem backup hook
+- `scripts/gen-tool-table.mjs` — prints the tool tables above from the live definitions (`--portfolio-mcp` does the same for the legacy server)
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest: tool contracts against a mocked non.bot + README/tool parity
+npm run build       # tsc → dist/ (comments stripped; this is what ships)
+npm run gen:tools   # regenerate the tool tables (paste between the markers in this README)
+npm pack --dry-run  # what the tarball would contain: dist/, README.md, LICENSE
+```
+
+Publishing is tag-driven (`bash deploy-npm.sh nonbot-mcp` from the repo root pushes `nonbot-mcp-v<version>`; GitHub Actions publishes via OIDC trusted publishing). `SERVER_VERSION` in `src/core/server.ts` must match `package.json`.

package/dist/core/config.d.ts

@@ -0,0 +1,9 @@
+export declare function resolveApiBase(raw0?: string): string;
+export interface ApiContext {
+    apiBase: string;
+    getToken: () => string;
+    readonly: boolean;
+    backup?: (id: string, json: unknown) => Promise<void>;
+    readLocalImage?: (path: string) => Promise<string>;
+    fetchImpl?: typeof fetch;
+}

package/dist/core/config.js

@@ -0,0 +1,34 @@
+const DEFAULT_API_BASE = 'https://non.bot';
+export function resolveApiBase(raw0) {
+    let raw = (raw0 || DEFAULT_API_BASE).replace(/\/$/, '');
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw))
+        raw = `https://${raw}`;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`non.bot API base is not a valid URL: ${raw}`);
+    }
+    const host = url.hostname.toLowerCase();
+    const isLocalhost = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (url.protocol === 'http:') {
+        if (!isLocalhost) {
+            throw new Error(`non.bot API base must use https:// — refusing to send the token in cleartext to ${host}. Plain http is only allowed for localhost.`);
+        }
+    }
+    else if (url.protocol !== 'https:') {
+        throw new Error(`non.bot API base must use https:// (got "${url.protocol}//${host}").`);
+    }
+    const allowed = host === 'non.bot' ||
+        host.endsWith('.non.bot') ||
+        host === 'conrad.pm' ||
+        host.endsWith('.conrad.pm') ||
+        host === 'conrad-pm.pages.dev' ||
+        host.endsWith('.conrad-pm.pages.dev') ||
+        isLocalhost;
+    if (!allowed) {
+        throw new Error(`non.bot API base host "${host}" is not allowlisted — the token may only be sent to non.bot, conrad.pm, conrad-pm.pages.dev (deploy previews), or localhost.`);
+    }
+    return raw;
+}

package/dist/core/http.d.ts

@@ -0,0 +1,3 @@
+import type { ApiContext } from './config.js';
+export declare function api(ctx: ApiContext, path: string, init?: RequestInit): Promise<Response>;
+export declare function expectJson<T = unknown>(res: Response, where: string): Promise<T>;

package/dist/core/http.js

@@ -0,0 +1,20 @@
+export async function api(ctx, path, init = {}) {
+    const token = ctx.getToken();
+    if (!token) {
+        throw new Error('No non.bot API token available. For stdio, set NON_BOT_API_TOKEN — generate one at https://non.bot/settings/connections.');
+    }
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${token}`);
+    if (init.body && !headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json');
+    }
+    const doFetch = ctx.fetchImpl ?? fetch;
+    return doFetch(`${ctx.apiBase}${path}`, { ...init, headers });
+}
+export async function expectJson(res, where) {
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`${where}: HTTP ${res.status} — ${text.slice(0, 200)}`);
+    }
+    return (await res.json());
+}

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[];