pi-mono-all 1.0.0

package/node_modules/pi-mono-figma/src/figma-tokens.ts

@@ -0,0 +1,57 @@
+export interface FigmaTokenMap {
+	styles: Record<string, { key?: string; name: string; type?: string; description?: string }>;
+	variables: Record<string, { key?: string; name: string; collectionName?: string; resolvedType?: string }>;
+	collections: Record<string, { name: string; modes?: Array<{ modeId: string; name: string }> }>;
+	warnings: string[];
+}
+
+export function buildFigmaTokenMap(stylesResponse: unknown, variablesResponse: unknown): FigmaTokenMap {
+	const warnings: string[] = [];
+	const styles: FigmaTokenMap["styles"] = {};
+	for (const style of getNestedArray(stylesResponse, ["meta", "styles"])) {
+		const record = asRecord(style);
+		const id = stringValue(record.node_id) ?? stringValue(record.nodeId) ?? stringValue(record.key);
+		if (!id) continue;
+		styles[id] = { key: stringValue(record.key), name: String(record.name ?? id), type: stringValue(record.style_type) ?? stringValue(record.styleType), description: stringValue(record.description) };
+	}
+
+	const variables: FigmaTokenMap["variables"] = {};
+	const collections: FigmaTokenMap["collections"] = {};
+	const meta = asRecord(asRecord(variablesResponse).meta ?? variablesResponse);
+	const rawCollections = asRecord(meta.variableCollections ?? meta.variable_collections);
+	for (const [collectionId, raw] of Object.entries(rawCollections)) {
+		const record = asRecord(raw);
+		collections[collectionId] = {
+			name: String(record.name ?? collectionId),
+			modes: Array.isArray(record.modes) ? record.modes.map((mode) => ({ modeId: String(asRecord(mode).modeId ?? asRecord(mode).mode_id ?? ""), name: String(asRecord(mode).name ?? "Mode") })) : undefined,
+		};
+	}
+	const rawVariables = asRecord(meta.variables);
+	for (const [variableId, raw] of Object.entries(rawVariables)) {
+		const record = asRecord(raw);
+		const collectionId = stringValue(record.variableCollectionId) ?? stringValue(record.variable_collection_id);
+		variables[variableId] = {
+			key: stringValue(record.key),
+			name: String(record.name ?? variableId),
+			collectionName: collectionId ? collections[collectionId]?.name : undefined,
+			resolvedType: stringValue(record.resolvedType) ?? stringValue(record.resolved_type),
+		};
+	}
+	if (!Object.keys(styles).length) warnings.push("No named styles were available to resolve style IDs.");
+	if (!Object.keys(variables).length) warnings.push("No local variables were available to resolve variable IDs.");
+	return { styles, variables, collections, warnings };
+}
+
+function getNestedArray(value: unknown, path: readonly string[]): unknown[] {
+	let current = value;
+	for (const segment of path) current = asRecord(current)[segment];
+	return Array.isArray(current) ? current : [];
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}

package/node_modules/pi-mono-figma/src/figma-tools.ts

@@ -0,0 +1,352 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { registerAuthConfigurator, runWithAuthRetry, type AuthConfiguratorOptions } from "pi-common/auth-config";
+import { jsonToolResult, textToolResult } from "pi-common/tool-result";
+import { FigmaClient, parseFigmaUrl } from "./figma-client.js";
+import {
+	FigmaGetDesignContextParams,
+	FigmaComponentImplementationHintsParams,
+	FigmaExtractAssetsParams,
+	FigmaFindCodeConnectMappingParams,
+	FigmaGetFileParams,
+	FigmaGetNodesParams,
+	FigmaFindNodesParams,
+	FigmaImplementationContextParams,
+	FigmaProcessedNodeParams,
+	FigmaProcessedNodeWithRenderParams,
+	FigmaParseUrlParams,
+	FigmaRenderNodesParams,
+	FigmaSearchComponentsParams,
+	FigmaSingleFileParams,
+} from "./figma-schemas.js";
+
+const DEFAULT_PROCESSED_MAX_CHARS = 20_000;
+const DEFAULT_RAW_MAX_CHARS = 40_000;
+
+interface ProcessedNodeParams {
+	fileKey: string;
+	nodeId: string;
+	depth?: number;
+	includeHidden?: boolean;
+	includeVectors?: boolean;
+	includeComponentInternals?: boolean;
+	renderImage?: boolean;
+	outputDir?: string;
+	format?: "png" | "jpg" | "svg" | "pdf";
+	scale?: number;
+	maxResponseChars?: number;
+}
+
+interface ImplementationContextParams extends ProcessedNodeParams {
+	framework?: "react" | "html" | "vue" | "angular" | "react-native";
+	styling?: "css" | "css-modules" | "styled-components" | "tailwind" | "inline";
+	resolveTokens?: boolean;
+	includeCodeSnippets?: boolean;
+}
+
+const FIGMA_AUTH: AuthConfiguratorOptions = {
+	service: "figma",
+	displayName: "Figma",
+	envName: "FIGMA_TOKEN",
+	authPath: ["figma", "token"],
+	commandName: "figma-auth",
+	toolName: "figma_configure_auth",
+	tokenUrl: "https://www.figma.com/settings/tokens",
+	scopeInstructions: ["Enable File content/read access for the files, projects, or team you want pi to inspect.", "No write/admin scopes are required."],
+};
+
+function withFigmaAuth<T>(ctx: ExtensionContext, operation: () => Promise<T>): Promise<T> {
+	return runWithAuthRetry(ctx, FIGMA_AUTH, operation);
+}
+
+export function registerFigmaTools(pi: ExtensionAPI): void {
+	const client = new FigmaClient();
+	registerAuthConfigurator(pi, FIGMA_AUTH);
+
+	pi.registerTool({
+		name: "figma_parse_url",
+		label: "Figma Parse URL",
+		description: "Parse a Figma URL into fileKey and nodeId values for the other figma_* tools.",
+		promptSnippet: "Parse Figma URLs into file key and node ID.",
+		parameters: FigmaParseUrlParams,
+		async execute(_toolCallId, params) {
+			return jsonToolResult(parseFigmaUrl(params.url));
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_design_context",
+		label: "Figma Design Context",
+		description: "Fetch compact LLM-ready Figma context. With nodeId returns target node summary, ancestors/page, and sibling names; without nodeId returns canvases and top-level frames only.",
+		promptSnippet: "Explore compact Figma file structure and a target node summary without full raw JSON.",
+		promptGuidelines: [
+			"Use figma_configure_auth only when Figma auth is missing, invalid, expired, or the user asks to update the token; never ask the user to paste tokens in chat.",
+			"Use figma_parse_url, figma_render_nodes, and figma_explain_node or figma_get_node_summary as the default workflow.",
+			"Use figma_get_implementation_context when translating a design into code.",
+			"Do not call figma_get_nodes by default; use it only when raw Figma JSON is explicitly needed or when debugging the extension.",
+			"Use figma_render_nodes when screenshots or visual assets are needed.",
+		],
+		parameters: FigmaGetDesignContextParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getDesignContext(params.fileKey, params.nodeId));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_find_nodes_by_name",
+		label: "Figma Find Nodes By Name",
+		description: "Search Figma layer/node names within a file or scoped subtree. Returns compact path-aware matches with result caps; prefer this before raw JSON exploration.",
+		promptSnippet: "Find Figma nodes/layers by name before choosing a target frame.",
+		parameters: FigmaFindNodesParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.findNodesByName(params.fileKey, params));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_find_nodes_by_text",
+		label: "Figma Find Nodes By Text",
+		description: "Search visible Figma text nodes within a file or scoped subtree and return compact path-aware matches with nearest parent context.",
+		promptSnippet: "Find Figma nodes by visible text before choosing a target frame.",
+		parameters: FigmaFindNodesParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.findNodesByText(params.fileKey, params));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_node_summary",
+		label: "Figma Node Summary",
+		description: "Fetch a compact structured summary of a Figma node: dimensions, layout, spacing, styles, visible text, component properties, and shallow child hierarchy. Default depth is 2; hidden nodes, vectors, and component internals are omitted by default.",
+		promptSnippet: "Get LLM-ready structured summaries of Figma frames/components.",
+		parameters: FigmaProcessedNodeParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getNodeSummary(params.fileKey, params.nodeId, processedOptions(params)));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_extract_text",
+		label: "Figma Extract Text",
+		description: "Extract visible text nodes from a Figma node without raw JSON. Hidden text is excluded by default and results are capped for LLM readability.",
+		promptSnippet: "Extract visible text from Figma designs.",
+		parameters: FigmaProcessedNodeParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.extractText(params.fileKey, params.nodeId, processedOptions(params)));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_explain_node",
+		label: "Figma Explain Node",
+		description: "Explain a Figma node in human-readable Markdown using compact summary, visible text, shallow hierarchy, and optional rendered image asset. Primary tool for questions like 'Explain this component'.",
+		promptSnippet: "Explain a Figma component/frame in Markdown without raw JSON.",
+		parameters: FigmaProcessedNodeWithRenderParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const assets = params.renderImage ? await withFigmaAuth(ctx, () => renderAssets(client, ctx, params)) : undefined;
+			const result = await withFigmaAuth(ctx, () => client.explainNode(params.fileKey, params.nodeId, { ...processedOptions(params), assets }));
+			return limitedTextToolResult(result, params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS);
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_implementation_context",
+		label: "Figma Implementation Context",
+		description: "Return concise design-to-code context for a Figma node: purpose, sections, fields/buttons, measurements, typography, colors, spacing, CSS layout/responsive hints, accessibility hints, design tokens, assets, and optional framework starter snippets.",
+		promptSnippet: "Get coding-ready Figma implementation context.",
+		parameters: FigmaImplementationContextParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const assets = params.renderImage ? await withFigmaAuth(ctx, () => renderAssets(client, ctx, params)) : undefined;
+			const result = await withFigmaAuth(ctx, () =>
+				client.getImplementationContext(params.fileKey, params.nodeId, { ...processedOptions(params), assets, ...implementationOptions(params) }),
+			);
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_file",
+		label: "Figma File",
+		description: "Fetch a raw Figma file JSON document. Use only when raw Figma JSON is explicitly needed or when debugging the extension; prefer figma_get_node_summary, figma_explain_node, or figma_get_design_context.",
+		parameters: FigmaGetFileParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getFile(params.fileKey, params.depth));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_RAW_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_nodes",
+		label: "Figma Nodes",
+		description: "Fetch raw Figma JSON for one or more nodes/frames/components by node ID. Use only when raw Figma JSON is explicitly needed or when debugging the extension; do not use by default.",
+		parameters: FigmaGetNodesParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getNodes(params.fileKey, params.nodeIds));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_RAW_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_node_metadata",
+		label: "Figma Node Metadata",
+		description: "Fetch compact spatial/layout metadata for one or more Figma nodes.",
+		parameters: FigmaGetNodesParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getNodeMetadata(params.fileKey, params.nodeIds));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_styles",
+		label: "Figma Styles",
+		description: "Fetch named styles from a Figma file, including colors, text, effects, and grids.",
+		parameters: FigmaSingleFileParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getStyles(params.fileKey));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_variables",
+		label: "Figma Variables",
+		description: "Fetch local Figma variables and collections for design tokens.",
+		parameters: FigmaSingleFileParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getVariables(params.fileKey));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_components",
+		label: "Figma Components",
+		description: "Fetch Figma component metadata for a file.",
+		parameters: FigmaSingleFileParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getComponents(params.fileKey));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_component_sets",
+		label: "Figma Component Sets",
+		description: "Fetch Figma component set metadata for a file.",
+		parameters: FigmaSingleFileParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getComponentSets(params.fileKey));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_search_components",
+		label: "Figma Search Components",
+		description: "Search Figma components in a file by name or description.",
+		parameters: FigmaSearchComponentsParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.searchComponents(params.fileKey, params.query));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_render_nodes",
+		label: "Figma Render Nodes",
+		description: "Render one or more Figma nodes to image URLs and optionally download them as local assets.",
+		parameters: FigmaRenderNodesParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () =>
+				client.renderNodes(params.fileKey, params.nodeIds, {
+					cwd: ctx.cwd,
+					outputDir: params.outputDir,
+					format: params.format,
+					scale: params.scale,
+					download: params.download,
+				}),
+			);
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_extract_assets",
+		label: "Figma Extract Assets",
+		description: "Extract a compact asset manifest for a Figma subtree, including SVG/icon exports, node renders, image fills, node paths, hashes, sizes, and local file paths when downloaded.",
+		promptSnippet: "Extract icons, renders, and image fills from a Figma frame as an asset manifest.",
+		parameters: FigmaExtractAssetsParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.extractAssets(params.fileKey, params.nodeId, { ...params, cwd: ctx.cwd }));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_find_code_connect_mapping",
+		label: "Figma Find Code Connect Mapping",
+		description: "Scan the local repo for Code Connect files, figma.connect calls, Figma URLs, node IDs, and component keys matching a target. No live Figma request is required.",
+		promptSnippet: "Find local Code Connect or Figma-node-to-component mappings in the current repo.",
+		parameters: FigmaFindCodeConnectMappingParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await client.findCodeConnectMapping({ ...params, cwd: ctx.cwd });
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+
+	pi.registerTool({
+		name: "figma_get_component_implementation_hints",
+		label: "Figma Component Implementation Hints",
+		description: "Combine Figma summary, implementation context, variants/properties, accessibility, token dependencies, assets, optional local Code Connect matches, and starter snippets into compact component implementation guidance.",
+		promptSnippet: "Get high-level implementation hints for turning a Figma component into code.",
+		parameters: FigmaComponentImplementationHintsParams,
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const result = await withFigmaAuth(ctx, () => client.getComponentImplementationHints(params.fileKey, params.nodeId, { ...processedOptions(params), ...params, cwd: ctx.cwd }));
+			return jsonToolResult(result, { maxChars: params.maxResponseChars ?? DEFAULT_PROCESSED_MAX_CHARS });
+		},
+	});
+}
+
+function processedOptions(params: ProcessedNodeParams) {
+	return {
+		depth: params.depth,
+		includeHidden: params.includeHidden,
+		includeVectors: params.includeVectors,
+		includeComponentInternals: params.includeComponentInternals,
+	};
+}
+
+function implementationOptions(params: ImplementationContextParams) {
+	return {
+		framework: params.framework,
+		styling: params.styling,
+		resolveTokens: params.resolveTokens,
+		includeCodeSnippets: params.includeCodeSnippets,
+	};
+}
+
+async function renderAssets(client: FigmaClient, ctx: ExtensionContext, params: ProcessedNodeParams): Promise<Array<{ nodeId: string; url?: string | null; path?: string }>> {
+	const rendered = await client.renderNodes(params.fileKey, [params.nodeId], {
+		cwd: ctx.cwd,
+		outputDir: params.outputDir,
+		format: params.format,
+		scale: params.scale,
+		download: true,
+	});
+	return Object.entries(rendered.images).map(([nodeId, url]) => ({
+		nodeId,
+		url,
+		path: rendered.savedFiles.find((file) => file.nodeId === nodeId)?.path,
+	}));
+}
+
+function limitedTextToolResult(text: string, maxChars: number) {
+	const truncated = text.length > maxChars;
+	const output = truncated ? `${text.slice(0, maxChars)}\n\n[truncated ${text.length - maxChars} characters; call figma_get_node_summary on a narrower child node]` : text;
+	return textToolResult(output, { truncated, characters: text.length });
+}

package/node_modules/pi-mono-linear/CHANGELOG.md

@@ -0,0 +1,44 @@
+# pi-mono-linear
+
+## 0.2.1
+
+### Patch Changes
+
+- Add the all-in-one pi package and bundle the shared pi-common workspace package into distributed packages.
+
+## 0.2.0
+
+### Minor Changes
+
+- Added `linear_upload_file` to upload local images, videos, and generic files to Linear and return sanitized asset metadata.
+- Added `linear_upload_file_to_issue_comment` to upload a local file and create a Markdown issue comment with the resulting Linear asset URL.
+
+## 0.1.2
+
+### Patch Changes
+
+### Fixed: package extension entrypoint
+
+- Added the package root `index.ts` extension entrypoint so pi can load the Linear tools from the published package manifest.
+
+## 0.1.1
+
+### Patch Changes
+
+### Enhanced: auth setup
+
+- Added `/linear-auth` command and `linear_configure_auth` tool for masked local API-key capture.
+- Linear tools now prompt for a fresh key and retry once when auth is missing, invalid, or expired.
+- Key setup writes to `~/.pi/agent/auth.json` without returning the key to the model.
+
+## 0.1.0
+
+### Minor Changes
+
+### New Extension: linear
+
+- Added native Linear GraphQL tools for workspace metadata, teams, issues, projects, workflow states, labels, users, comments, cycles, and documents.
+- Added mutation tools for creating issues, updating issues, and creating comments.
+- Added bundled `linear` skill that explains when and how to use the native `linear_*` tools.
+- Added authentication support via `LINEAR_API_KEY` and `~/.pi/agent/auth.json` at `.linear.key`.
+- Added README documentation for API key creation, required Linear read/write permissions, and setup/troubleshooting.

package/node_modules/pi-mono-linear/README.md

@@ -0,0 +1,159 @@
+# pi-mono-linear
+
+A pi extension and skill package that exposes native Linear GraphQL tools for issue, project, team, user, comment, file upload, cycle, label, workflow-state, and document workflows.
+
+## Tools
+
+### Workspace and users
+
+- `linear_whoami`
+- `linear_workspace_metadata`
+- `linear_list_teams`
+- `linear_get_team`
+- `linear_list_users`
+- `linear_get_user`
+
+### Issues
+
+- `linear_list_issues`
+- `linear_get_issue`
+- `linear_search_issues`
+- `linear_list_my_issues`
+- `linear_create_issue`
+- `linear_update_issue`
+
+### Metadata and related records
+
+- `linear_list_projects`
+- `linear_get_project`
+- `linear_list_issue_statuses`
+- `linear_get_issue_status`
+- `linear_list_labels`
+- `linear_list_cycles`
+- `linear_list_documents`
+- `linear_get_document`
+
+### Comments
+
+- `linear_list_comments`
+- `linear_create_comment`
+- `linear_configure_auth`
+
+### Files
+
+- `linear_upload_file`
+- `linear_upload_file_to_issue_comment`
+
+The package also bundles the `linear` skill under `skills/linear/SKILL.md`.
+
+## Authentication
+
+The extension looks for a Linear API key in this order:
+
+1. in-memory key override created by `/linear-auth --force` or `linear_configure_auth`
+2. `LINEAR_API_KEY` environment variable
+3. `~/.pi/agent/auth.json` at `.linear.key`
+
+If no key is found, or if Linear rejects the key as invalid/expired, the native tools can prompt you with a masked local dialog and store the replacement key without returning it to the model.
+
+Do **not** paste API keys into an LLM chat.
+
+### Recommended: native auth command
+
+Run this in pi:
+
+```text
+/linear-auth --force
+```
+
+The command shows the Linear API-key URL and required permissions, prompts for the key with masked input, and writes it to `~/.pi/agent/auth.json` at `.linear.key`.
+
+The same flow is available to the agent through the `linear_configure_auth` tool. That tool returns only metadata such as `stored: true`; it never returns the key.
+
+If a normal `linear_*` request fails because the key is missing, invalid, or expired, the extension retries once after prompting you for a fresh key.
+
+### Option A: environment variable
+
+For the current shell session:
+
+```bash
+export LINEAR_API_KEY="lin_api_xxx"
+```
+
+To persist it, add that export to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or your preferred secrets manager.
+
+### Option B: pi auth file
+
+Create or update `~/.pi/agent/auth.json`:
+
+```json
+{
+  "linear": {
+    "key": "lin_api_xxx"
+  }
+}
+```
+
+Recommended file permissions:
+
+```bash
+mkdir -p ~/.pi/agent
+chmod 700 ~/.pi/agent
+chmod 600 ~/.pi/agent/auth.json
+```
+
+If the file already contains other credentials, merge the `linear.key` entry instead of overwriting the file.
+
+## Creating a Linear API key
+
+1. Open Linear.
+2. Go to **Settings → Account → Security & Access**.
+3. Under **Personal API keys**, click **Create key**.
+4. Name it something recognizable, for example `pi-agent`.
+5. Choose the minimum access level needed for your workflow.
+6. If your workspace supports team restrictions, restrict the key to only the teams pi needs.
+7. Copy the key once and store it via `LINEAR_API_KEY` or `~/.pi/agent/auth.json`.
+
+## Required scopes / permissions
+
+Use the least privilege that supports the tools you need:
+
+- **Read** is enough for read-only tools such as `linear_workspace_metadata`, `linear_search_issues`, `linear_get_issue`, list tools, and document/comment reads.
+- **Write** is required for mutation tools: `linear_create_issue`, `linear_update_issue`, `linear_create_comment`, `linear_upload_file`, and `linear_upload_file_to_issue_comment`.
+- **Admin** is not required for this extension's tools.
+
+If you restrict the key to specific teams, the key must include the teams/projects/issues you want to query or mutate.
+
+Linear API keys are sent in the `Authorization` header as the raw key value; do not prefix them with `Bearer`.
+
+## Usage tips
+
+- Use `linear_workspace_metadata` first when team/project/state/label/user IDs are unknown.
+- Use `linear_search_issues` for keyword lookup.
+- Use `linear_get_issue` before updating an issue or creating a comment.
+- Use `linear_list_issues` for filtered issue lists by team, assignee, status, and limit.
+- Use `linear_upload_file` to upload a local image, video, or generic file and return a Linear asset URL.
+- Use `linear_upload_file_to_issue_comment` after `linear_get_issue` to upload a local file and post a Markdown comment. Images are rendered with image Markdown; other files use links.
+- File upload tool results return sanitized metadata and the stable Linear asset URL. They do not return local file bytes, signed upload URLs, or upload headers.
+
+## Troubleshooting
+
+### Missing auth key
+
+Set `LINEAR_API_KEY` or add `.linear.key` to `~/.pi/agent/auth.json`.
+
+### Permission errors
+
+Confirm the key has the right access level:
+
+- Read-only workflows need **Read**.
+- Create/update/comment workflows need **Write**.
+- Team-restricted keys must include the relevant team.
+
+### Custom Linear endpoint
+
+By default, the extension uses `https://api.linear.app/graphql`. Override it with:
+
+```bash
+export LINEAR_GRAPHQL_URL="https://api.linear.app/graphql"
+```

package/node_modules/pi-mono-linear/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerLinearTools } from "./src/linear-tools.js";
+
+export default function linearExtension(pi: ExtensionAPI): void {
+	registerLinearTools(pi);
+}

package/node_modules/pi-mono-linear/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "pi-mono-linear",
+  "version": "0.2.1",
+  "description": "Pi extension and skill for Linear GraphQL tools",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-skill",
+    "linear"
+  ],
+  "dependencies": {
+    "pi-common": "workspace:*"
+  },
+  "bundledDependencies": [
+    "pi-common"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}