@tymio/mcp-server 1.0.1 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking
+
+- **Pinned workspace for stdio** — `tymio-mcp` (OAuth proxy and API-key bridge) **requires** `TYMIO_WORKSPACE_SLUG` or `DRD_WORKSPACE_SLUG` (the hub workspace slug this process is bound to). Every tool call must include **`workspaceSlug`** matching that pin (case-insensitive). Prevents agents from targeting another workspace for the same user.
+- **Tests / local tooling only** — set `TYMIO_MCP_SKIP_WORKSPACE_PINNING=1` to skip the startup requirement (do not use in production agent configs).
+
+### Added / changed
+
+- **API-key stdio** — Resolves the pinned slug to a tenant via `GET /api/me/tenants` and sends **`X-Tenant-Id`** on all hub REST calls; tool payloads still carry `workspaceSlug` for consistency but must match the pin.
+- **OAuth stdio (hub proxy)** — Asserts tool arguments match the pinned slug before `callTool` to the hosted MCP.
+- **Hub (server) MCP** — Stricter `workspaceSlug` validation (length, `^[a-z0-9-]+$`) and **case-insensitive** match to the session workspace; API-key sessions can use tenant-list routes needed for resolution (`authViaApiKey` + `requireSession` behavior).
+
+### Requires
+
+- **Deploy hub** with the matching server changes **before or with** rolling out this CLI to users who rely on API-key stdio or the updated MCP slug rules.
+
+## 1.1.0
+
+- **Bundled agent personas** (`personas/*.md`): `workspace`, `pm`, `po`, `dev` — aligned with Tymio hub roles; shipped in the npm tarball.
+- **`tymio-mcp persona list`** and **`tymio-mcp persona <id>`** — print persona Markdown to stdout (or list ids).
+- **`TYMIO_MCP_PERSONA`** — optional env on the stdio process; appends the selected persona to MCP server **`instructions`** after the main agent guide (`hub` aliases `workspace`). Invalid values log a stderr warning and fall back to the base guide only.
+- **Startup stderr hint** — when a valid persona is set, reminds that instructions include it and how to print the prompt (`tymio-mcp persona <id>`).
+- **Agent guidance** — `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` updated with persona usage; `README.md` and help text document commands and env.
+
+## 1.0.1
+
+Prior release (OAuth proxy, API-key REST subset, `tymio-mcp instructions`, login/logout).

package/README.md

@@ -37,6 +37,30 @@ Installable **`tymio-mcp`** command: connect editors and agents to **Tymio** in
 
 **Agents / IDE:** MCP clients that support [server instructions](https://modelcontextprotocol.io) receive the same long-form guide as `tymio-mcp instructions` during the initialize handshake. You can still run `tymio-mcp instructions` in a terminal to print it, or read this README.
 
+### Bundled agent personas (PM / PO / DEV)
+
+The package ships Markdown prompts in **`personas/`** (aligned with Cursor Skills in the monorepo).
+
+| Mechanism | What it does |
+|-----------|----------------|
+| **`tymio-mcp persona list`** | Lists persona ids and usage |
+| **`tymio-mcp persona pm`** (or `po`, `dev`, `workspace`) | Prints that prompt to **stdout** (pipe into docs or paste into a chat) |
+| **`TYMIO_MCP_PERSONA=pm`** on the `tymio-mcp` process | **Appends** the same Markdown to MCP server **`instructions`** after the main CLI guide — steers the model for clients that honor instructions (no Skills required). Use `hub` as an alias for `workspace`. |
+
+Example Cursor stdio config with a Product Owner bias:
+
+```json
+{
+  "mcpServers": {
+    "tymio-po": {
+      "command": "tymio-mcp",
+      "args": [],
+      "env": { "TYMIO_MCP_PERSONA": "po" }
+    }
+  }
+}
+```
+
 ### OAuth callback port
 
 The CLI listens on **`http://127.0.0.1:19876/callback`** during `login` (override with `TYMIO_OAUTH_PORT`). That URI must be reachable from your browser and should stay stable so it matches the dynamically registered OAuth client.
@@ -84,6 +108,9 @@ Example:
 | `tymio-mcp` | Run stdio MCP (OAuth proxy unless API key env is set) |
 | `tymio-mcp login [url]` | OAuth sign-in; optional MCP URL overrides `TYMIO_MCP_URL` |
 | `tymio-mcp logout` | Delete stored OAuth client + tokens |
+| `tymio-mcp instructions` / `guide` | Print full agent Markdown (same as MCP `instructions` base) |
+| `tymio-mcp persona list` | Bundled persona ids (`pm`, `po`, `dev`, `workspace`) |
+| `tymio-mcp persona <id>` | Print one persona Markdown to stdout |
 | `tymio-mcp help` | Usage |
 
 ---

package/TYMIO_MCP_CLI_AGENT_GUIDANCE.md

@@ -9,6 +9,7 @@
 3. **`DRD_API_KEY` / `API_KEY` on the stdio process** means the **server deployment automation secret** (the same value as the hub’s configured `API_KEY` for `Authorization: Bearer …` on REST). It is **not** something each user generates in the Tymio UI. Only operators with access to deployment secrets use it (CI, scripts, optional stdio “REST bridge” mode).
 4. **Default vs API-key stdio:** If `DRD_API_KEY` or `API_KEY` is set to a non-empty value in the **environment of the `tymio-mcp` process**, the CLI uses a **fixed REST tool subset**, not OAuth to the hosted hub. For the **full** tool surface, use **remote** `…/mcp` or stdio **without** those env vars (after `tymio-mcp login`).
 5. **Full text of this guide:** shell command `tymio-mcp instructions` (or `tymio-mcp guide`). MCP clients that support server `instructions` receive this content at initialize when using the published CLI.
+6. **Bundled agent personas (PM / PO / DEV / workspace):** optional Markdown prompts ship with the package under `personas/`. **Print a prompt:** `tymio-mcp persona pm` (or `po`, `dev`, `workspace`). **Embed in MCP `instructions`:** set `TYMIO_MCP_PERSONA=pm` (same ids; `hub` aliases `workspace`) on the `tymio-mcp` process — the stdio server appends that persona after this guide so clients that honor `instructions` steer the model without Cursor Skills. **List ids:** `tymio-mcp persona list`.
 
 ---
 

package/dist/api.d.ts

@@ -1,6 +1,8 @@
 /**
  * Minimal Tymio hub API client for the stdio MCP server. Uses DRD_API_BASE_URL and DRD_API_KEY from env.
  */
+export declare function setApiKeyBridgeTenantId(tenantId: string): void;
+export declare function clearApiKeyBridgeTenant(): void;
 /** JSON-friendly body; plain objects are stringified. */
 export type DrdFetchInit = Omit<RequestInit, "body"> & {
     body?: string | Record<string, unknown>;

package/dist/api.js

@@ -4,8 +4,19 @@
 /** Hub origin (no `/mcp` path). Stdio bridge calls REST under `/api/...`. */
 const baseUrl = process.env.DRD_API_BASE_URL ?? "https://tymio.app";
 const apiKey = process.env.DRD_API_KEY ?? process.env.API_KEY ?? "";
+/** Set by API-key stdio after resolving slug → tenant id (never send cross-tenant requests). */
+let bridgeTenantHeaders = {};
+export function setApiKeyBridgeTenantId(tenantId) {
+    bridgeTenantHeaders = { "X-Tenant-Id": tenantId };
+}
+export function clearApiKeyBridgeTenant() {
+    bridgeTenantHeaders = {};
+}
 function headers() {
-    const h = { "Content-Type": "application/json" };
+    const h = {
+        "Content-Type": "application/json",
+        ...bridgeTenantHeaders
+    };
     if (apiKey)
         h["Authorization"] = `Bearer ${apiKey}`;
     return h;

package/dist/apiKeyStdio.js

@@ -1,75 +1,101 @@
 /**
  * REST/API-key stdio bridge (subset of hub tools). Set DRD_API_BASE_URL + DRD_API_KEY (or API_KEY).
+ * Requires TYMIO_WORKSPACE_SLUG or DRD_WORKSPACE_SLUG (unless TYMIO_MCP_SKIP_WORKSPACE_PINNING=1 for tests).
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { drdFetch, drdFetchText, getBaseUrl, hasApiKey } from "./api.js";
-import { AGENT_INSTRUCTIONS } from "./cliMessages.js";
+import { resolveTenantIdForWorkspaceSlug } from "./apiKeyTenantResolve.js";
+import { drdFetch, drdFetchText, getBaseUrl, hasApiKey, setApiKeyBridgeTenantId } from "./api.js";
+import { getMcpServerInstructions } from "./persona.js";
 import { toolTextWithFeedback } from "./mcpFeedbackFooter.js";
 import { writeStdioStartupHint } from "./stdioHints.js";
+import { assertToolArgsMatchPinnedWorkspace, omitWorkspaceSlug, readPinnedWorkspaceSlugForStdio, WORKSPACE_SLUG_ZOD } from "./workspaceSlug.js";
 export async function runApiKeyStdio() {
     writeStdioStartupHint("api-key");
-    const server = new McpServer({ name: "tymio-hub", version: "1.0.0" }, { instructions: AGENT_INSTRUCTIONS });
+    const pinnedSlug = readPinnedWorkspaceSlugForStdio();
+    if (pinnedSlug) {
+        try {
+            const tenantId = await resolveTenantIdForWorkspaceSlug(pinnedSlug);
+            setApiKeyBridgeTenantId(tenantId);
+        }
+        catch (e) {
+            process.stderr.write(`[tymio-mcp] API-key bridge: cannot resolve workspace: ${e}\n`);
+            process.exit(1);
+        }
+    }
+    const server = new McpServer({ name: "tymio-hub", version: "1.0.0" }, { instructions: getMcpServerInstructions() });
     async function textContent(text) {
         return toolTextWithFeedback(getBaseUrl(), text);
     }
-    // --- Health & meta (no auth required for health)
+    function assertPin(args, tool) {
+        if (pinnedSlug)
+            assertToolArgsMatchPinnedWorkspace(args, pinnedSlug, tool);
+    }
+    const ws = { workspaceSlug: WORKSPACE_SLUG_ZOD };
     server.registerTool("drd_health", {
         title: "Tymio API health check",
-        description: "Check if the Tymio hub API is reachable.",
-        inputSchema: z.object({})
-    }, async () => {
+        description: "Check if the Tymio hub API is reachable. Requires workspaceSlug (must match server pin).",
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_health");
         const data = await drdFetch("/api/health");
         return textContent(JSON.stringify(data));
     });
     server.registerTool("drd_meta", {
         title: "Get Tymio meta",
         description: "Get meta data: domains, products, accounts, partners, personas, revenue streams, users.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_meta");
         const data = await drdFetch("/api/meta");
         return textContent(JSON.stringify(data, null, 2));
     });
-    // --- Initiatives
-    const listInitiativesSchema = z.object({
+    const listInitiativesSchema = z
+        .object({
         domainId: z.string().optional(),
         ownerId: z.string().optional(),
         horizon: z.enum(["NOW", "NEXT", "LATER"]).optional(),
         priority: z.enum(["P0", "P1", "P2", "P3"]).optional(),
         isGap: z.boolean().optional()
-    });
+    })
+        .extend(ws);
     server.registerTool("drd_list_initiatives", {
         title: "List initiatives",
         description: "List initiatives with optional filters: domainId, ownerId, horizon, priority, isGap.",
         inputSchema: listInitiativesSchema
     }, async (args) => {
+        assertPin(args, "drd_list_initiatives");
+        const { workspaceSlug: _w, ...filters } = args;
         const params = new URLSearchParams();
-        if (args.domainId)
-            params.set("domainId", args.domainId);
-        if (args.ownerId)
-            params.set("ownerId", args.ownerId);
-        if (args.horizon)
-            params.set("horizon", args.horizon);
-        if (args.priority)
-            params.set("priority", args.priority);
-        if (args.isGap !== undefined)
-            params.set("isGap", String(args.isGap));
+        if (filters.domainId)
+            params.set("domainId", filters.domainId);
+        if (filters.ownerId)
+            params.set("ownerId", filters.ownerId);
+        if (filters.horizon)
+            params.set("horizon", filters.horizon);
+        if (filters.priority)
+            params.set("priority", filters.priority);
+        if (filters.isGap !== undefined)
+            params.set("isGap", String(filters.isGap));
         const data = await drdFetch(`/api/initiatives?${params.toString()}`);
         return textContent(JSON.stringify(data.initiatives, null, 2));
     });
     server.registerTool("drd_get_initiative", {
         title: "Get initiative by ID",
         description: "Get a single initiative by its ID.",
-        inputSchema: z.object({ id: z.string().describe("Initiative ID") })
-    }, async ({ id }) => {
+        inputSchema: z.object({ id: z.string().describe("Initiative ID") }).extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_get_initiative");
+        const { id } = omitWorkspaceSlug(args);
         const data = await drdFetch(`/api/initiatives/${id}`);
         return textContent(JSON.stringify(data.initiative, null, 2));
     });
     server.registerTool("drd_create_initiative", {
         title: "Create initiative",
         description: "Create a new initiative. Requires admin/editor role.",
-        inputSchema: z.object({
+        inputSchema: z
+            .object({
             title: z.string(),
             domainId: z.string(),
             description: z.string().optional(),
@@ -80,7 +106,10 @@ export async function runApiKeyStdio() {
             commercialType: z.string().optional(),
             isGap: z.boolean().optional()
         })
-    }, async (body) => {
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_create_initiative");
+        const body = omitWorkspaceSlug(args);
         const data = await drdFetch("/api/initiatives", {
             method: "POST",
             body: JSON.stringify(body)
@@ -90,7 +119,8 @@ export async function runApiKeyStdio() {
     server.registerTool("drd_update_initiative", {
         title: "Update initiative",
         description: "Update an existing initiative by ID.",
-        inputSchema: z.object({
+        inputSchema: z
+            .object({
             id: z.string(),
             title: z.string().optional(),
             domainId: z.string().optional(),
@@ -102,7 +132,10 @@ export async function runApiKeyStdio() {
             commercialType: z.string().optional(),
             isGap: z.boolean().optional()
         })
-    }, async ({ id, ...body }) => {
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_update_initiative");
+        const { id, ...body } = omitWorkspaceSlug(args);
         const data = await drdFetch(`/api/initiatives/${id}`, {
             method: "PUT",
             body: JSON.stringify(body)
@@ -112,29 +145,35 @@ export async function runApiKeyStdio() {
     server.registerTool("drd_delete_initiative", {
         title: "Delete initiative",
         description: "Delete an initiative by ID.",
-        inputSchema: z.object({ id: z.string() })
-    }, async ({ id }) => {
+        inputSchema: z.object({ id: z.string() }).extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_delete_initiative");
+        const { id } = omitWorkspaceSlug(args);
         await drdFetch(`/api/initiatives/${id}`, { method: "DELETE" });
         return textContent(JSON.stringify({ ok: true }));
     });
-    // --- Domains, products, personas
     server.registerTool("drd_list_domains", {
         title: "List domains",
         description: "List all domains.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_domains");
         const data = await drdFetch("/api/domains");
         return textContent(JSON.stringify(data.domains, null, 2));
     });
     server.registerTool("drd_create_domain", {
         title: "Create domain",
         description: "Create a new domain (pillar). Requires workspace OWNER or ADMIN.",
-        inputSchema: z.object({
+        inputSchema: z
+            .object({
             name: z.string().min(1),
             color: z.string().min(1),
             sortOrder: z.number().int().optional()
         })
-    }, async (body) => {
+            .extend(ws)
+    }, async (args) => {
+        assertPin(args, "drd_create_domain");
+        const body = omitWorkspaceSlug(args);
         const data = await drdFetch("/api/domains", {
             method: "POST",
             body: JSON.stringify({
@@ -148,107 +187,120 @@ export async function runApiKeyStdio() {
     server.registerTool("drd_list_products", {
         title: "List products",
         description: "List all products (with hierarchy).",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_products");
         const data = await drdFetch("/api/products");
         return textContent(JSON.stringify(data.products, null, 2));
     });
     server.registerTool("drd_list_personas", {
         title: "List personas",
         description: "List all personas.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_personas");
         const data = await drdFetch("/api/personas");
         return textContent(JSON.stringify(data.personas, null, 2));
     });
     server.registerTool("drd_list_accounts", {
         title: "List accounts",
         description: "List all accounts.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_accounts");
         const data = await drdFetch("/api/accounts");
         return textContent(JSON.stringify(data.accounts, null, 2));
     });
     server.registerTool("drd_list_partners", {
         title: "List partners",
         description: "List all partners.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_partners");
         const data = await drdFetch("/api/partners");
         return textContent(JSON.stringify(data.partners, null, 2));
     });
-    // --- KPIs, milestones, stakeholders
     server.registerTool("drd_list_kpis", {
         title: "List KPIs",
         description: "List all initiative KPIs with their initiative context (title, domain, owner).",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_kpis");
         const data = await drdFetch("/api/kpis");
         return textContent(JSON.stringify(data.kpis, null, 2));
     });
     server.registerTool("drd_list_milestones", {
         title: "List milestones",
         description: "List all initiative milestones with their initiative context.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_milestones");
         const data = await drdFetch("/api/milestones");
         return textContent(JSON.stringify(data.milestones, null, 2));
     });
     server.registerTool("drd_list_demands", {
         title: "List demands",
         description: "List all demands (from accounts, partners, internal, compliance).",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_demands");
         const data = await drdFetch("/api/demands");
         return textContent(JSON.stringify(data.demands, null, 2));
     });
     server.registerTool("drd_list_revenue_streams", {
         title: "List revenue streams",
         description: "List all revenue streams.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "drd_list_revenue_streams");
         const data = await drdFetch("/api/revenue-streams");
         return textContent(JSON.stringify(data.revenueStreams, null, 2));
     });
     server.registerTool("tymio_get_coding_agent_guide", {
         title: "Get Tymio coding agent playbook (Markdown)",
         description: "Full docs/CODING_AGENT_TYMIO.md: MCP usage, as-is to Tymio, feature lifecycle. Call at session start when automating this hub.",
-        inputSchema: z.object({})
-    }, async () => {
+        inputSchema: z.object(ws)
+    }, async (args) => {
+        assertPin(args, "tymio_get_coding_agent_guide");
         const md = await drdFetchText("/api/agent/coding-guide");
         return textContent(md);
     });
     server.registerTool("tymio_get_agent_brief", {
         title: "Get compiled agent capability brief",
         description: "Returns the hub capability ontology as Markdown or JSON. mode=compact|full, format=md|json.",
-        inputSchema: z.object({
+        inputSchema: z
+            .object({
             mode: z.enum(["compact", "full"]).default("compact"),
             format: z.enum(["md", "json"]).default("md")
         })
+            .extend(ws)
     }, async (args) => {
-        const params = new URLSearchParams({ mode: args.mode, format: args.format });
+        assertPin(args, "tymio_get_agent_brief");
+        const { mode, format } = omitWorkspaceSlug(args);
+        const params = new URLSearchParams({ mode, format });
         const q = params.toString();
-        if (args.format === "md") {
-            const text = await drdFetchText(`/api/ontology/brief?${q}`);
-            return textContent(text);
-        }
         const raw = await drdFetchText(`/api/ontology/brief?${q}`);
-        try {
-            const parsed = JSON.parse(raw);
-            return textContent(JSON.stringify(parsed, null, 2));
-        }
-        catch {
-            return textContent(raw);
+        if (format === "json") {
+            try {
+                const parsed = JSON.parse(raw);
+                return textContent(JSON.stringify(parsed, null, 2));
+            }
+            catch {
+                return textContent(raw);
+            }
         }
+        return textContent(raw);
     });
     server.registerTool("tymio_list_capabilities", {
         title: "List hub capabilities (ontology)",
         description: "Optional status: ACTIVE, DRAFT, DEPRECATED.",
-        inputSchema: z.object({ status: z.enum(["ACTIVE", "DRAFT", "DEPRECATED"]).optional() })
+        inputSchema: z.object({ status: z.enum(["ACTIVE", "DRAFT", "DEPRECATED"]).optional() }).extend(ws)
     }, async (args) => {
+        assertPin(args, "tymio_list_capabilities");
+        const { status } = omitWorkspaceSlug(args);
         const params = new URLSearchParams();
-        if (args.status)
-            params.set("status", args.status);
+        if (status)
+            params.set("status", status);
         const q = params.toString();
         const data = await drdFetch(`/api/ontology/capabilities${q ? `?${q}` : ""}`);
         return textContent(JSON.stringify(data, null, 2));
@@ -256,14 +308,18 @@ export async function runApiKeyStdio() {
     server.registerTool("tymio_get_capability", {
         title: "Get one capability by id or slug",
         description: "Provide id or slug.",
-        inputSchema: z.object({ id: z.string().optional(), slug: z.string().optional() })
+        inputSchema: z
+            .object({ id: z.string().optional(), slug: z.string().optional() })
+            .extend(ws)
     }, async (args) => {
-        if (args.id) {
-            const data = await drdFetch(`/api/ontology/capabilities/${args.id}`);
+        assertPin(args, "tymio_get_capability");
+        const { id, slug } = omitWorkspaceSlug(args);
+        if (id) {
+            const data = await drdFetch(`/api/ontology/capabilities/${id}`);
             return textContent(JSON.stringify(data, null, 2));
         }
-        if (args.slug) {
-            const data = await drdFetch(`/api/ontology/capabilities/by-slug/${encodeURIComponent(args.slug)}`);
+        if (slug) {
+            const data = await drdFetch(`/api/ontology/capabilities/by-slug/${encodeURIComponent(slug)}`);
             return textContent(JSON.stringify(data, null, 2));
         }
         throw new Error("Provide id or slug");

package/dist/apiKeyTenantResolve.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolve workspace slug to tenant id for API-key bridge; verifies ACTIVE membership for the API key user.
+ */
+export declare function resolveTenantIdForWorkspaceSlug(expectedSlug: string): Promise<string>;

package/dist/apiKeyTenantResolve.js

@@ -0,0 +1,17 @@
+import { drdFetch } from "./api.js";
+import { isValidWorkspaceSlugFormat } from "./workspaceSlug.js";
+/**
+ * Resolve workspace slug to tenant id for API-key bridge; verifies ACTIVE membership for the API key user.
+ */
+export async function resolveTenantIdForWorkspaceSlug(expectedSlug) {
+    if (!isValidWorkspaceSlugFormat(expectedSlug)) {
+        throw new Error(`Invalid workspace slug: ${JSON.stringify(expectedSlug)}`);
+    }
+    const want = expectedSlug.toLowerCase();
+    const data = await drdFetch("/api/me/tenants");
+    const row = data.tenants.find((m) => m.tenant.slug.toLowerCase() === want && m.tenant.status === "ACTIVE");
+    if (!row) {
+        throw new Error(`API key user has no ACTIVE membership for workspace slug "${expectedSlug}". Check TYMIO_WORKSPACE_SLUG and hub memberships.`);
+    }
+    return row.tenant.id;
+}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { runApiKeyStdio } from "./apiKeyStdio.js";
 import { runHubOAuthStdio } from "./hubProxyStdio.js";
 import { runLoginCommand } from "./loginCommand.js";
 import { removeAllOAuthFiles } from "./fileOAuthProvider.js";
+import { runPersonaCli } from "./persona.js";
 function useApiKeyBridge() {
     return Boolean(process.env.DRD_API_KEY?.trim() || process.env.API_KEY?.trim());
 }
@@ -27,6 +28,10 @@ export async function runCli(argv) {
         process.stderr.write(`${HELP_SUMMARY}\n`);
         return;
     }
+    if (args[0] === "persona") {
+        process.exitCode = runPersonaCli(args.slice(1));
+        return;
+    }
     if (useApiKeyBridge()) {
         await runApiKeyStdio();
         return;

package/dist/cliMessages.d.ts

@@ -1,5 +1,5 @@
 /** Short usage (stderr) — keep in sync with guidance file for agents. */
-export declare const HELP_SUMMARY = "Tymio MCP CLI (@tymio/mcp-server)\n\nCommands:\n  tymio-mcp                    Start stdio MCP (default: OAuth \u2192 hosted Tymio MCP)\n  tymio-mcp login [url]        Sign in with Google (browser). Saves tokens locally.\n  tymio-mcp logout             Delete saved OAuth client + tokens\n  tymio-mcp instructions       Full setup text for humans & coding agents (print this)\n  tymio-mcp help               This summary\n\nEnvironment:\n  TYMIO_MCP_URL          Hosted MCP URL (default https://tymio.app/mcp)\n  TYMIO_OAUTH_PORT       Loopback port for login callback (default 19876)\n  TYMIO_MCP_QUIET        If set, suppress stderr hints when starting stdio\n  DRD_API_KEY / API_KEY  If set \u2192 API-key REST tool bridge (subset), not OAuth proxy\n  DRD_API_BASE_URL       Hub origin for API-key bridge (default https://tymio.app)\n\nCritical for agents: There is NO MCP API key in Tymio user Settings \u2014 use OAuth (remote /mcp URL or tymio-mcp login).\nTip: Run  tymio-mcp instructions  for the full Markdown guide, Cursor JSON, and troubleshooting.\n";
+export declare const HELP_SUMMARY = "Tymio MCP CLI (@tymio/mcp-server)\n\nCommands:\n  tymio-mcp                    Start stdio MCP (default: OAuth \u2192 hosted Tymio MCP)\n  tymio-mcp login [url]        Sign in with Google (browser). Saves tokens locally.\n  tymio-mcp logout             Delete saved OAuth client + tokens\n  tymio-mcp instructions       Full setup text for humans & coding agents (print this)\n  tymio-mcp persona list       Bundled PM/PO/DEV/workspace prompts (see also TYMIO_MCP_PERSONA)\n  tymio-mcp persona <id>       Print one persona Markdown to stdout (pm | po | dev | workspace)\n  tymio-mcp help               This summary\n\nEnvironment:\n  TYMIO_MCP_URL          Hosted MCP URL (default https://tymio.app/mcp)\n  TYMIO_OAUTH_PORT       Loopback port for login callback (default 19876)\n  TYMIO_MCP_QUIET        If set, suppress stderr hints when starting stdio\n  TYMIO_WORKSPACE_SLUG   Required for stdio (or DRD_WORKSPACE_SLUG): hub workspace slug this process is pinned to; every tool call must use the same slug (tests: TYMIO_MCP_SKIP_WORKSPACE_PINNING=1)\n  TYMIO_MCP_PERSONA      Optional: pm | po | dev | workspace (hub aliases workspace) \u2014 appended to MCP server instructions\n  DRD_API_KEY / API_KEY  If set \u2192 API-key REST tool bridge (subset), not OAuth proxy\n  DRD_API_BASE_URL       Hub origin for API-key bridge (default https://tymio.app)\n\nCritical for agents: There is NO MCP API key in Tymio user Settings \u2014 use OAuth (remote /mcp URL or tymio-mcp login).\nTip: Run  tymio-mcp instructions  for the full Markdown guide, Cursor JSON, and troubleshooting.\n";
 /**
  * Long-form instructions for coding agents and operators (Markdown).
  * Loaded from `TYMIO_MCP_CLI_AGENT_GUIDANCE.md` beside the installed package / dist output.

package/dist/cliMessages.js

@@ -34,12 +34,16 @@ Commands:
   tymio-mcp login [url]        Sign in with Google (browser). Saves tokens locally.
   tymio-mcp logout             Delete saved OAuth client + tokens
   tymio-mcp instructions       Full setup text for humans & coding agents (print this)
+  tymio-mcp persona list       Bundled PM/PO/DEV/workspace prompts (see also TYMIO_MCP_PERSONA)
+  tymio-mcp persona <id>       Print one persona Markdown to stdout (pm | po | dev | workspace)
   tymio-mcp help               This summary
 
 Environment:
   TYMIO_MCP_URL          Hosted MCP URL (default https://tymio.app/mcp)
   TYMIO_OAUTH_PORT       Loopback port for login callback (default 19876)
   TYMIO_MCP_QUIET        If set, suppress stderr hints when starting stdio
+  TYMIO_WORKSPACE_SLUG   Required for stdio (or DRD_WORKSPACE_SLUG): hub workspace slug this process is pinned to; every tool call must use the same slug (tests: TYMIO_MCP_SKIP_WORKSPACE_PINNING=1)
+  TYMIO_MCP_PERSONA      Optional: pm | po | dev | workspace (hub aliases workspace) — appended to MCP server instructions
   DRD_API_KEY / API_KEY  If set → API-key REST tool bridge (subset), not OAuth proxy
   DRD_API_BASE_URL       Hub origin for API-key bridge (default https://tymio.app)
 

package/dist/hubProxyStdio.js

@@ -7,8 +7,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { defaultMcpUrl, defaultOAuthRedirectUrl } from "./configPaths.js";
 import { FileOAuthProvider } from "./fileOAuthProvider.js";
-import { AGENT_INSTRUCTIONS } from "./cliMessages.js";
+import { getMcpServerInstructions } from "./persona.js";
 import { writeStdioStartupHint } from "./stdioHints.js";
+import { assertToolArgsMatchPinnedWorkspace, readPinnedWorkspaceSlugForStdio } from "./workspaceSlug.js";
 function pkgVersion() {
     try {
         const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
@@ -24,6 +25,7 @@ const passthroughArgs = z.object({}).passthrough();
  */
 export async function runHubOAuthStdio(mcpUrl = defaultMcpUrl()) {
     writeStdioStartupHint("oauth");
+    const pinnedWorkspaceSlug = readPinnedWorkspaceSlugForStdio();
     const redirectUrl = defaultOAuthRedirectUrl();
     const provider = new FileOAuthProvider(redirectUrl);
     const transport = new StreamableHTTPClientTransport(mcpUrl, { authProvider: provider });
@@ -39,7 +41,7 @@ export async function runHubOAuthStdio(mcpUrl = defaultMcpUrl()) {
         throw e;
     }
     const { tools } = await client.listTools();
-    const server = new McpServer({ name: "tymio-hub", version: pkgVersion() }, { instructions: AGENT_INSTRUCTIONS });
+    const server = new McpServer({ name: "tymio-hub", version: pkgVersion() }, { instructions: getMcpServerInstructions() });
     for (const tool of tools) {
         const name = tool.name;
         server.registerTool(name, {
@@ -47,6 +49,9 @@ export async function runHubOAuthStdio(mcpUrl = defaultMcpUrl()) {
             description: tool.description ?? "",
             inputSchema: passthroughArgs
         }, async (args) => {
+            if (pinnedWorkspaceSlug) {
+                assertToolArgsMatchPinnedWorkspace(args ?? {}, pinnedWorkspaceSlug, name);
+            }
             const result = await client.callTool({
                 name,
                 arguments: args ?? {}

package/dist/persona.d.ts

@@ -0,0 +1,16 @@
+declare const PERSONA_IDS: readonly ["pm", "po", "dev", "workspace"];
+export type PersonaId = (typeof PERSONA_IDS)[number];
+/** `hub` is an alias for `workspace` (base hub agent behavior). */
+export declare function normalizePersonaId(raw: string | undefined): PersonaId | null;
+export declare function listPersonaIds(): readonly PersonaId[];
+export declare function loadPersonaMarkdown(id: PersonaId): string;
+export declare function personaListHelpText(): string;
+/**
+ * Full MCP server `instructions`: base CLI guide plus optional persona from `TYMIO_MCP_PERSONA`.
+ */
+export declare function getMcpServerInstructions(): string;
+/** Non-empty when a valid persona is active (for stderr startup hint). */
+export declare function activePersonaForHint(): PersonaId | null;
+/** CLI subcommand: `tymio-mcp persona …` — exit code. */
+export declare function runPersonaCli(argv: string[]): number;
+export {};

package/dist/persona.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { AGENT_INSTRUCTIONS } from "./cliMessages.js";
+const PERSONA_IDS = ["pm", "po", "dev", "workspace"];
+function personasDir() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "personas");
+}
+/** `hub` is an alias for `workspace` (base hub agent behavior). */
+export function normalizePersonaId(raw) {
+    if (!raw?.trim())
+        return null;
+    const s = raw.trim().toLowerCase();
+    if (s === "hub")
+        return "workspace";
+    if (PERSONA_IDS.includes(s))
+        return s;
+    return null;
+}
+export function listPersonaIds() {
+    return PERSONA_IDS;
+}
+export function loadPersonaMarkdown(id) {
+    const file = path.join(personasDir(), `${id}.md`);
+    if (!existsSync(file)) {
+        throw new Error(`Bundled persona file missing: ${file}`);
+    }
+    return readFileSync(file, "utf8");
+}
+export function personaListHelpText() {
+    return `Tymio MCP — bundled agent personas (Markdown prompts)
+
+Usage:
+  tymio-mcp persona list              Show this list
+  tymio-mcp persona <id>            Print persona prompt to stdout (pipe into your agent / docs)
+
+Ids: ${PERSONA_IDS.join(", ")}
+
+Embed in MCP sessions (stdio / some clients read server instructions):
+  export TYMIO_MCP_PERSONA=pm        # or po, dev, workspace
+  tymio-mcp                          # persona text is appended to MCP server instructions
+
+Cursor: you can instead enable Skills (.cursor/skills/tymio-*-agent); CLI personas help IDEs without Skills or CI.
+
+`;
+}
+/**
+ * Full MCP server `instructions`: base CLI guide plus optional persona from `TYMIO_MCP_PERSONA`.
+ */
+export function getMcpServerInstructions() {
+    const raw = process.env.TYMIO_MCP_PERSONA;
+    if (!raw?.trim())
+        return AGENT_INSTRUCTIONS;
+    const id = normalizePersonaId(raw);
+    if (!id) {
+        process.stderr.write(`[tymio-mcp] Unknown TYMIO_MCP_PERSONA="${raw.trim()}". Valid: ${PERSONA_IDS.join(", ")} (hub aliases workspace). See: tymio-mcp persona list\n`);
+        return AGENT_INSTRUCTIONS;
+    }
+    let block;
+    try {
+        block = loadPersonaMarkdown(id);
+    }
+    catch (e) {
+        process.stderr.write(`[tymio-mcp] Could not load persona "${id}": ${e}\n`);
+        return AGENT_INSTRUCTIONS;
+    }
+    return `${AGENT_INSTRUCTIONS}\n\n---\n\n## Bundled agent persona (\`TYMIO_MCP_PERSONA=${id}\`)\n\n${block}\n`;
+}
+/** Non-empty when a valid persona is active (for stderr startup hint). */
+export function activePersonaForHint() {
+    return normalizePersonaId(process.env.TYMIO_MCP_PERSONA);
+}
+/** CLI subcommand: `tymio-mcp persona …` — exit code. */
+export function runPersonaCli(argv) {
+    const sub = argv[0];
+    if (!sub || sub === "list" || sub === "--help" || sub === "-h") {
+        process.stderr.write(personaListHelpText());
+        return 0;
+    }
+    const id = normalizePersonaId(sub);
+    if (!id) {
+        process.stderr.write(`Unknown persona "${sub}". Run: tymio-mcp persona list\n`);
+        return 1;
+    }
+    try {
+        process.stdout.write(loadPersonaMarkdown(id));
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(String(e) + "\n");
+        return 1;
+    }
+}

package/dist/stdioHints.js

@@ -1,3 +1,4 @@
+import { activePersonaForHint } from "./persona.js";
 /**
  * One-line stderr hint when starting stdio (does not touch stdout — MCP JSON-RPC stays clean).
  * Suppress with TYMIO_MCP_QUIET=1 or non-TTY stderr.
@@ -8,9 +9,13 @@ export function writeStdioStartupHint(mode) {
     if (!process.stderr.isTTY)
         return;
     if (mode === "oauth") {
-        process.stderr.write("[tymio-mcp] OAuth proxy to Tymio MCP. No MCP key in Tymio Settings — use login/OAuth. First run: `tymio-mcp login`. Guide: `tymio-mcp instructions` | `tymio-mcp help`\n");
+        process.stderr.write("[tymio-mcp] OAuth proxy to Tymio MCP. No MCP key in Tymio Settings — use login/OAuth. First run: `tymio-mcp login`. Set TYMIO_WORKSPACE_SLUG (or DRD_WORKSPACE_SLUG) to pin this server to one workspace. Guide: `tymio-mcp instructions` | `tymio-mcp help`\n");
     }
     else {
-        process.stderr.write("[tymio-mcp] API-key REST bridge. Set DRD_API_BASE_URL + DRD_API_KEY. Agent guide: `tymio-mcp instructions`\n");
+        process.stderr.write("[tymio-mcp] API-key REST bridge. Set DRD_API_BASE_URL + DRD_API_KEY + TYMIO_WORKSPACE_SLUG (tenant resolved to X-Tenant-Id). Agent guide: `tymio-mcp instructions`\n");
+    }
+    const persona = activePersonaForHint();
+    if (persona) {
+        process.stderr.write(`[tymio-mcp] TYMIO_MCP_PERSONA=${persona} — persona text is appended to MCP server instructions. Print prompt: tymio-mcp persona ${persona}\n`);
     }
 }

package/dist/workspaceSlug.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/** Matches hub workspace slug rules (see server tenant slug validation). */
+export declare const WORKSPACE_SLUG_ZOD: z.ZodString;
+export declare function isValidWorkspaceSlugFormat(slug: string): boolean;
+/**
+ * Pinned slug for this stdio process: every proxied MCP tool call must use this workspace.
+ * Set `TYMIO_MCP_SKIP_WORKSPACE_PINNING=1` only in tests.
+ */
+export declare function readPinnedWorkspaceSlugForStdio(): string | null;
+/** Enforce agent-supplied slug matches pinned CLI config (defense in depth vs hub session). */
+export declare function assertToolArgsMatchPinnedWorkspace(args: unknown, pinnedSlug: string, toolName: string): void;
+/** After assert, remove workspaceSlug before REST bodies. */
+export declare function omitWorkspaceSlug<T extends Record<string, unknown>>(args: T): Omit<T, "workspaceSlug">;

package/dist/workspaceSlug.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/** Matches hub workspace slug rules (see server tenant slug validation). */
+export const WORKSPACE_SLUG_ZOD = z
+    .string()
+    .min(2)
+    .max(50)
+    .regex(/^[a-z0-9-]+$/, "Workspace slug: 2–50 chars, lowercase a-z, digits, hyphens only.");
+export function isValidWorkspaceSlugFormat(slug) {
+    return WORKSPACE_SLUG_ZOD.safeParse(slug).success;
+}
+/**
+ * Pinned slug for this stdio process: every proxied MCP tool call must use this workspace.
+ * Set `TYMIO_MCP_SKIP_WORKSPACE_PINNING=1` only in tests.
+ */
+export function readPinnedWorkspaceSlugForStdio() {
+    if (process.env.TYMIO_MCP_SKIP_WORKSPACE_PINNING === "1") {
+        return null;
+    }
+    const raw = process.env.TYMIO_WORKSPACE_SLUG?.trim() || process.env.DRD_WORKSPACE_SLUG?.trim();
+    if (!raw) {
+        process.stderr.write("[tymio-mcp] Missing TYMIO_WORKSPACE_SLUG or DRD_WORKSPACE_SLUG. Set this to your hub workspace slug (e.g. acme-corp). Required so this MCP server only operates on one workspace; tool args must match.\n");
+        process.exit(1);
+    }
+    const parsed = WORKSPACE_SLUG_ZOD.safeParse(raw);
+    if (!parsed.success) {
+        process.stderr.write(`[tymio-mcp] Invalid workspace slug: ${JSON.stringify(raw)}. Use 2–50 characters: lowercase letters, digits, hyphens only.\n`);
+        process.exit(1);
+    }
+    return parsed.data;
+}
+/** Enforce agent-supplied slug matches pinned CLI config (defense in depth vs hub session). */
+export function assertToolArgsMatchPinnedWorkspace(args, pinnedSlug, toolName) {
+    if (!args || typeof args !== "object") {
+        throw new Error(`[tymio-mcp] ${toolName}: missing or invalid arguments object.`);
+    }
+    const o = args;
+    const slug = o.workspaceSlug;
+    if (typeof slug !== "string") {
+        throw new Error(`[tymio-mcp] ${toolName}: workspaceSlug is required on every tool call (string, must match ${pinnedSlug}).`);
+    }
+    const t = slug.trim().toLowerCase();
+    if (!isValidWorkspaceSlugFormat(t)) {
+        throw new Error(`[tymio-mcp] ${toolName}: invalid workspaceSlug format. Use 2–50 chars: lowercase a-z, digits, hyphens.`);
+    }
+    if (t !== pinnedSlug.toLowerCase()) {
+        throw new Error(`[tymio-mcp] ${toolName}: workspaceSlug "${slug}" does not match this MCP server pin "${pinnedSlug}". Refusing cross-workspace access.`);
+    }
+}
+/** After assert, remove workspaceSlug before REST bodies. */
+export function omitWorkspaceSlug(args) {
+    const { workspaceSlug: _, ...rest } = args;
+    return rest;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tymio/mcp-server",
-  "version": "1.0.1",
-  "description": "Tymio MCP CLI: OAuth stdio proxy to hosted MCP, or API-key REST tool bridge",
+  "version": "2.0.0",
+  "description": "Tymio MCP CLI: OAuth stdio proxy to hosted MCP, API-key REST bridge, bundled PM/PO/DEV/workspace agent personas",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -9,6 +9,8 @@
   },
   "files": [
     "dist",
+    "personas",
+    "CHANGELOG.md",
     "README.md",
     "TYMIO_MCP_CLI_AGENT_GUIDANCE.md"
   ],

package/personas/dev.md

@@ -0,0 +1,33 @@
+# Tymio — Developer agent
+
+You act as a **developer** whose scope is defined in **Tymio**. **Read** the hub for what to build; **implement** in the user’s repo. You do **not** own roadmap/backlog unless explicitly asked to update hub rows.
+
+## Ontology
+
+Default **leaf** is **Requirement** → parent **Feature** → **Initiative**. Use **`tymio_get_agent_brief`** / **`tymio_get_coding_agent_guide`** for product/API truth; use backlog tools for scope. **Dependencies** between bets are initiative-level. Monorepo reference: `.cursor/skills/tymio-workspace/references/tymio-hub-ontology.md`.
+
+## Before you code
+
+1. **`tymio_get_agent_brief`**; heavy implementation: **`tymio_get_coding_agent_guide`**.
+2. Map work to initiative/feature/requirement IDs via **`drd_list_*`** / **`drd_get_initiative`**.
+3. If hub reads fail, report it; fix MCP/OAuth.
+
+## Data
+
+| Need | Tools |
+|------|--------|
+| Acceptance | **`drd_list_requirements`** (update only if user asked) |
+| Packaging | **`drd_list_features`**, **`drd_list_initiatives`** |
+| Blockers | **`drd_list_dependencies`**, decisions, risks |
+| Surfaces | **`tymio_list_capabilities`**, **`tymio_get_capability`** |
+| Taxonomy | **`drd_meta`** |
+
+## Avoid
+
+- Reprioritizing initiatives (PM).
+- Bulk-creating features/requirements without PO-style instruction.
+- Treating the coding guide as permission to change deployment secrets or admin settings.
+
+## Output
+
+Open with requirement/feature IDs/titles; PR summaries link hub records to files; ask when requirements are ambiguous before large refactors.

package/personas/pm.md

@@ -0,0 +1,31 @@
+# Tymio — Product Manager agent
+
+You act as a **Product Manager** on the **Tymio hub**. Focus **portfolio and roadmap coherence** (themes, bets, tradeoffs, stakeholders, signals) — not fine-grained backlog grooming (defer to the PO persona).
+
+## Ontology
+
+Internalize the **backlog graph** before reasoning: Initiatives under Domains; Features under Initiatives; Requirements under Features; **Dependency** links initiatives, not features. Separate that from the **capability** brief (`tymio_*`). Monorepo reference: `.cursor/skills/tymio-workspace/references/tymio-hub-ontology.md`.
+
+## Before you reason
+
+1. **`tymio_get_agent_brief`** and **`drd_meta`** — do not invent domain/product/tool names.
+2. If MCP fails, fix OAuth / `tymio-mcp login`; never tell users to copy an MCP key from Tymio Settings.
+3. Assume **`VIEWER`/`EDITOR`** unless known otherwise.
+
+## Workflows
+
+1. **`drd_meta`**, **`drd_list_domains`**, **`drd_list_products`**, optional **`drd_get_product_tree`**.
+2. **`drd_list_initiatives`** (filters as supported).
+3. **`drd_get_initiative`** → **`drd_list_decisions`**, **`drd_list_risks`**, **`drd_list_stakeholders`**, timeline tools.
+4. Signals: **`drd_list_demands`**, **`drd_list_accounts`**, **`drd_list_partners`**, KPIs/milestones/personas as needed.
+5. Mutations only if permitted: **`drd_create_initiative`** / **`drd_update_initiative`** — no bulk delete without explicit confirmation.
+
+## Avoid
+
+- Defaulting to rewriting requirements/features (PO/Dev).
+- Deep coding-guide dives unless the user asks (use Dev persona).
+- Guessing IDs — resolve via meta/list tools.
+
+## Output
+
+Hub facts first, then recommendations; separate “in hub” vs “proposed”; stakeholder summaries tie to domains/products, KPIs/milestones, decisions/risks.

package/personas/po.md

@@ -0,0 +1,35 @@
+# Tymio — Product Owner agent
+
+You act as a **Product Owner** on the **Tymio hub**. Focus **backlog refinement and delivery readiness**: features, requirements, acceptance, ownership, dependencies, timeline — not portfolio strategy (PM persona).
+
+## Ontology
+
+Follow **Domain/Product → Initiative → Feature → Requirement** before creating rows. Never create a **Feature** without a real `initiativeId` or a **Requirement** without a real `featureId`. **Dependency** in the hub is **initiative-level**. Monorepo reference: `.cursor/skills/tymio-workspace/references/tymio-hub-ontology.md`.
+
+## Before you write
+
+1. **`tymio_get_agent_brief`** then **`drd_meta`**.
+2. Fix auth if tools fail; no MCP key in user Settings.
+3. Creating/updating work typically needs **EDITOR+**.
+
+## Workflows
+
+1. **`drd_list_initiatives`** → **`drd_get_initiative`**.
+2. **`drd_list_features`** → create/update features.
+3. **`drd_list_requirements`** → create/update/upsert requirements with testable acceptance.
+4. **`drd_list_assignments`**, **`drd_list_dependencies`**, decisions/risks for blockers.
+5. Timeline tools for communication, not as a substitute for requirements.
+
+## Handoffs
+
+From PM: prioritized initiatives; to Dev: requirements/features should stand alone for implementation questions.
+
+## Avoid
+
+- Deletes without explicit user confirmation.
+- Silent initiative priority/horizon changes when the user only asked for requirement edits.
+- Invented dependency edges.
+
+## Output
+
+Current state (IDs + titles) → proposed edits → open questions; small verifiable requirements; status changes with from → to and why.

package/personas/workspace.md

@@ -0,0 +1,41 @@
+# Tymio workspace (agents)
+
+Bundled with `@tymio/mcp-server` for MCP `instructions` when `TYMIO_MCP_PERSONA=workspace` (default hub behavior is unchanged; this block is optional context).
+
+When working **in the Tymio monorepo**, the API is often `http://localhost:8080` and MCP at `http://localhost:8080/mcp`.
+
+## Before any mutation
+
+1. Confirm MCP is connected; if tools are missing or auth fails, do not claim hub data changed.
+2. Almost all `/api/*` needs a session or `Authorization: Bearer` deployment key where enabled.
+3. Prefer **`tymio_get_agent_brief`** (or `GET /api/ontology/brief`) before assuming which routes or tools exist.
+
+## Connect
+
+- **Remote MCP:** `POST https://tymio.app/mcp` (or your host) with OAuth — no per-user MCP API key in Tymio Settings.
+- **Stdio:** `tymio-mcp login` then run `tymio-mcp` without `DRD_API_KEY`/`API_KEY` for the full proxied tool list. With those env vars set, only a REST subset is available.
+
+## Vocabulary
+
+| In conversation | In Tymio |
+|-----------------|----------|
+| App / application (surface) | Usually **Product** (line / asset) |
+| Tenant / customer org | **Workspace** |
+| “Capability” in ontology | Product **affordance** (routes, tools, models) — **not** a backlog row |
+
+**Flow:** demand/idea → **Initiative** → **Features** → **Requirements** (with domain/product from meta).
+
+## Hub ontology (two layers)
+
+1. **Backlog graph:** Domain → Initiative → Feature → Requirement; demands link to initiatives/features; **dependencies** are initiative→initiative in the default model.
+2. **Capability brief:** `tymio_get_agent_brief`, `tymio_list_capabilities` — what the product exposes.
+
+Use **`drd_meta`** then list/get tools for live tenant data. Full Mermaid + tables live in the monorepo: `.cursor/skills/tymio-workspace/references/tymio-hub-ontology.md`.
+
+## Roles
+
+`VIEWER`, `EDITOR`, `ADMIN`, `SUPER_ADMIN` — assume least privilege.
+
+## Personas
+
+PM / PO / DEV prompts: `tymio-mcp persona pm|po|dev` or set `TYMIO_MCP_PERSONA`. Role matrix: `docs/TYMIO_AGENT_ROLES_PM_PO_DEV.md` in the monorepo.