spur-board 0.1.0 → 0.3.0

package/dist/mcp.mjs

@@ -1,6 +1,6 @@
-import { O as ERRORS, l as renderMcpError, o as OPERATIONS } from "./src-CqH_W7D8.mjs";
-import { r as CliError, t as requestOperation } from "./client-C1hJzdYE.mjs";
-import { t as loadClientConfig } from "./config-DQmktVi-.mjs";
+import { j as ERRORS, s as OPERATIONS, u as renderMcpError } from "./src-BDNEze3S.mjs";
+import { r as CliError, t as requestOperation } from "./client-C81xon5D.mjs";
+import { t as loadClientConfig } from "./config-D8AEf8vU.mjs";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { z } from "zod";

package/dist/migrations/0010_manual_links.sql

@@ -0,0 +1,40 @@
+-- Manual ticket links and observed PR openness. Preserve existing link IDs and provenance.
+CREATE TABLE link_new (
+  id INTEGER PRIMARY KEY,
+  task_id INTEGER NOT NULL REFERENCES task (id),
+  entity TEXT NOT NULL,
+  repo TEXT,
+  number INTEGER,
+  pr_state TEXT,
+  session_id TEXT,
+  role TEXT,
+  source TEXT NOT NULL,
+  banned INTEGER NOT NULL DEFAULT 0 CHECK (banned IN (0, 1)),
+  created_at TEXT NOT NULL,
+  ticket_key TEXT,
+  pr_open INTEGER CHECK (pr_open IN (0, 1)),
+  CHECK (entity <> 'pr' OR
+    (repo IS NOT NULL AND number IS NOT NULL AND pr_state IS NOT NULL AND pr_open IS NOT NULL)),
+  CHECK (entity <> 'session' OR session_id IS NOT NULL),
+  CHECK (entity <> 'ticket' OR ticket_key IS NOT NULL)
+) STRICT;
+
+INSERT INTO link_new (id, task_id, entity, repo, number, pr_state, session_id, role,
+  source, banned, created_at, ticket_key, pr_open)
+SELECT link.id, link.task_id, link.entity, link.repo, link.number, link.pr_state,
+  link.session_id, link.role, link.source, link.banned, link.created_at, NULL,
+  CASE WHEN link.entity = 'pr' THEN
+    CASE WHEN EXISTS (
+      SELECT 1 FROM pr_snapshot AS pr
+      WHERE pr.repo = link.repo AND pr.number = link.number AND pr.state IN ('closed', 'merged')
+    ) THEN 0 ELSE 1 END
+  ELSE NULL END
+FROM link;
+
+DROP TABLE link;
+ALTER TABLE link_new RENAME TO link;
+CREATE UNIQUE INDEX link_pr_pair ON link (task_id, repo, number) WHERE entity = 'pr';
+CREATE UNIQUE INDEX link_session_pair ON link (task_id, session_id) WHERE entity = 'session';
+CREATE UNIQUE INDEX link_ticket_pair ON link (task_id, ticket_key) WHERE entity = 'ticket';
+CREATE UNIQUE INDEX link_one_active_pr ON link (task_id)
+  WHERE entity = 'pr' AND pr_state = 'active' AND banned = 0 AND pr_open = 1;

package/dist/{src-CqH_W7D8.mjs → src-BDNEze3S.mjs}

@@ -98,6 +98,16 @@ const ACTORS = [
 	"agent",
 	"system"
 ];
+/** Bot OAuth scopes required by the generated Slack manifest and checked by doctor. */
+const SLACK_BOT_SCOPES = [
+	"chat:write",
+	"chat:write.customize",
+	"groups:history",
+	"groups:read",
+	"app_mentions:read",
+	"commands",
+	"reactions:write"
+];
 //#endregion
 //#region ../contracts/src/config.ts
 const WEEKDAYS = [
@@ -235,10 +245,14 @@ const configSchema = z.strictObject({
 		rejectDuplicates(items, "id", "project id", ctx);
 	}),
 	operator: z.strictObject({ slack: nonEmpty }),
-	slack: z.strictObject({ channels: z.strictObject({
-		orchestrators: nonEmpty.optional(),
-		feed: nonEmpty.optional()
-	}).prefault({}) }).prefault({}),
+	slack: z.strictObject({
+		command: z.string().regex(/^\/[a-z0-9_-]+$/, "Expected a slash command such as /board").default("/board"),
+		appId: z.string().regex(/^A[A-Z0-9]+$/, "Expected a Slack app ID").optional(),
+		channels: z.strictObject({
+			orchestrators: nonEmpty.optional(),
+			feed: nonEmpty.optional()
+		}).prefault({})
+	}).prefault({}),
 	thresholds: z.strictObject({
 		staleMultiplier: z.number().min(1).default(3),
 		blockOpenMs: durationMs(864e5, "How long a block may stay open before an item is raised")
@@ -418,8 +432,15 @@ const ERRORS = {
 		status: 409,
 		exit: EXIT_CODES.refused,
 		message: "The task is archived, so it cannot change.",
-		hint: "Add the task to the board again with `board task add <KEY>` if work goes on.",
-		recovery: noRetry("Add the task to the board again if work continues.")
+		hint: "Ask an operator to add the task to the board again if work continues.",
+		recovery: noRetry("Ask an operator to add the task to the board again if work continues.")
+	}),
+	link_conflict: spec("link_conflict", {
+		status: 409,
+		exit: EXIT_CODES.refused,
+		message: "Another linked pull request prevents this manual link.",
+		hint: "Read the task links and use a different task or resolve the existing pull request link.",
+		recovery: noRetry("Read the task links and resolve the blocking pull request.")
 	}),
 	retry_not_applicable: spec("retry_not_applicable", {
 		status: 409,
@@ -601,8 +622,9 @@ const taskKeySchema = refSchema("task", "Task key: a Jira key (PROJ-123) or a Gi
 function errorCodeOf(error) {
 	return error.issues.some((issue) => issue.code === "custom" && issue.params?.["code"] === "wrong_id_kind") ? "wrong_id_kind" : "usage";
 }
+const ACTOR_PART = /^[A-Za-z0-9._-]+$/;
 /** A spur project or session name inside an actor ID. It never contains `/`. */
-const actorPartSchema = z.string().regex(/^[A-Za-z0-9._-]+$/, "Expected letters, digits, \".\", \"_\" or \"-\"");
+const actorPartSchema = z.string().regex(ACTOR_PART, "Expected letters, digits, \".\", \"_\" or \"-\"");
 /**
 * Who did something, as one string: `operator`, `system`, or `agent:<project>/<session>` for
 * an agent, naming its spur project and session. Every store column that records a doer uses
@@ -621,6 +643,17 @@ const actorIdSchema = z.union([
 		actorPartSchema
 	])
 ]).describe("Actor: operator, system, or agent:<project>/<session>.");
+/** Joins the journal's `actor` and `actorRef` into an `ActorId`. Throws on an invalid pair. */
+function encodeActorId(value) {
+	const { actor, actorRef } = value;
+	if (actor !== "agent") {
+		if (actorRef !== void 0) throw new Error("actorRef is set only when actor is agent");
+		return actor;
+	}
+	if (actorRef === void 0) throw new Error("actorRef is required when actor is agent");
+	for (const part of [actorRef.project, actorRef.session]) if (!ACTOR_PART.test(part)) throw new Error(`Invalid actor part ${JSON.stringify(part)}: use letters, digits, . _ -`);
+	return `agent:${actorRef.project}/${actorRef.session}`;
+}
 /** Splits an `ActorId` into `actor` and `actorRef`; `null` when the text is not an actor ID. */
 function parseActorId(text) {
 	const result = actorIdSchema.safeParse(text);
@@ -866,28 +899,49 @@ const eventPayloadSchemas = {
 		kind: z.enum(["unknown_state", "unknown_status"]),
 		value: S
 	}),
-	link_added: z.discriminatedUnion("entity", [z.looseObject({
-		entity: z.literal("session"),
-		session: S,
-		role: z.enum(SESSION_LINK_ROLES),
-		source: z.enum(LINK_SOURCES),
-		facts: sessionFactsSchema.optional()
-	}), z.looseObject({
-		entity: z.literal("pr"),
-		repo: S,
-		pr: N,
-		state: z.enum(PR_LINK_STATES),
-		source: z.enum(LINK_SOURCES),
-		facts: prFactsSchema.optional()
-	})]),
-	link_removed: z.discriminatedUnion("entity", [z.looseObject({
-		entity: z.literal("session"),
-		session: S
-	}), z.looseObject({
-		entity: z.literal("pr"),
-		repo: S,
-		pr: N
-	})]),
+	link_added: z.discriminatedUnion("entity", [
+		z.looseObject({
+			entity: z.literal("session"),
+			session: S,
+			role: z.enum(SESSION_LINK_ROLES),
+			source: z.enum(LINK_SOURCES),
+			facts: sessionFactsSchema.optional(),
+			reason: S.optional()
+		}),
+		z.looseObject({
+			entity: z.literal("pr"),
+			repo: S,
+			pr: N,
+			state: z.enum(PR_LINK_STATES),
+			source: z.enum(LINK_SOURCES),
+			facts: prFactsSchema.optional(),
+			reason: S.optional()
+		}),
+		z.looseObject({
+			entity: z.literal("ticket"),
+			ticket: S,
+			source: z.enum(LINK_SOURCES),
+			reason: S.optional()
+		})
+	]),
+	link_removed: z.discriminatedUnion("entity", [
+		z.looseObject({
+			entity: z.literal("session"),
+			session: S,
+			reason: S.optional()
+		}),
+		z.looseObject({
+			entity: z.literal("pr"),
+			repo: S,
+			pr: N,
+			reason: S.optional()
+		}),
+		z.looseObject({
+			entity: z.literal("ticket"),
+			ticket: S,
+			reason: S.optional()
+		})
+	]),
 	task_added: z.looseObject({ column: z.enum(COLUMN_IDS) }),
 	task_archived: z.looseObject({ reason: z.enum(ARCHIVE_REASONS) }),
 	block_opened: z.looseObject({
@@ -933,7 +987,10 @@ const eventPayloadSchemas = {
 		gateway: S,
 		reason: S
 	}),
-	from_you_raised: z.looseObject({ item: S }),
+	from_you_raised: z.looseObject({
+		item: S,
+		rule: S.optional()
+	}),
 	from_you_cleared: z.looseObject({ item: S }),
 	flag_raised: z.looseObject({
 		flag: S,
@@ -1311,19 +1368,24 @@ const statusSessionFactsSchema = z.strictObject({
 		url: z.url({ protocol: /^https?$/ }).describe("Published link URL.")
 	})).describe("Links published by this session.")
 }).describe("Session facts with links as display entries.");
+const linkViewSchema = z.strictObject({
+	kind: z.enum([
+		"pr",
+		"session",
+		"ticket"
+	]).describe("Linked entity kind."),
+	ref: z.string().min(1).describe("Pull request, session, or ticket identifier."),
+	role: z.enum([
+		"worker",
+		"other",
+		"orchestrator"
+	]).nullable().describe("Session role; null for a pull request or ticket.")
+}).describe("An effective link to a task.");
 const statusTaskSchema = taskViewSchema.extend({
 	ticket: ticketFactsSchema.nullable().describe("Latest ticket facts, or null before observation."),
 	prs: z.array(prFactsSchema).describe("Latest facts for linked pull requests."),
 	sessions: z.array(statusSessionFactsSchema).describe("Latest facts for linked sessions."),
-	links: z.array(z.strictObject({
-		kind: z.enum(["pr", "session"]).describe("Linked entity kind."),
-		ref: z.string().min(1).describe("Pull request or session identifier."),
-		role: z.enum([
-			"worker",
-			"other",
-			"orchestrator"
-		]).nullable().describe("Session role; null for a pull request.")
-	})).describe("Links fixed when each entity first joined the task.")
+	links: z.array(linkViewSchema).describe("Effective pull request, session, and ticket links.")
 }).describe("A board task with its latest observed facts and links.");
 const statusItemSchema = itemViewSchema.extend({
 	key: z.string().min(1).describe("Stable key of this actionable item."),
@@ -1378,7 +1440,44 @@ const schemaGetOutputSchema = z.strictObject({
 //#region ../contracts/src/ops/catalog.ts
 const project = z.string().min(1).optional().describe("Project to limit the answer to; absent means every project the caller may see.");
 const text = (what) => z.string().min(1).describe(what);
-const target = text("What to link: a spur session name, or a pull request as owner/repo#n.");
+const target = text("Pull request, session, or ticket linked to the task.");
+const linkInput = z.discriminatedUnion("mode", [
+	z.strictObject({
+		mode: z.literal("pr").describe("Link a pull request."),
+		task: taskKeySchema,
+		pr: z.url({ protocol: /^https?$/ }).describe("Pull request URL."),
+		reason: text("Why this link is being changed.")
+	}),
+	z.strictObject({
+		mode: z.literal("session").describe("Link a spur session."),
+		task: taskKeySchema,
+		session: text("Spur session ID."),
+		reason: text("Why this link is being changed.")
+	}),
+	z.strictObject({
+		mode: z.literal("ticket").describe("Link an additional tracker ticket."),
+		task: taskKeySchema,
+		ticket: taskKeySchema,
+		reason: text("Why this link is being changed.")
+	})
+]);
+const linkModes = [
+	{
+		mode: "pr",
+		flag: "--pr",
+		value: "pr"
+	},
+	{
+		mode: "session",
+		flag: "--session",
+		value: "session"
+	},
+	{
+		mode: "ticket",
+		flag: "--ticket",
+		value: "ticket"
+	}
+];
 const at = "2026-01-05T09:30:00.000Z";
 const task = {
 	key: "PROJ-123",
@@ -1497,7 +1596,7 @@ const OPERATIONS = [
 	defineOperation({
 		id: "task.get",
 		kind: "query",
-		description: "Show a task with its blocks and comments.",
+		description: "Show a task with its links, blocks and comments.",
 		mcp: {
 			whenToUse: "Inspect one task now.",
 			whenNotToUse: "Use task_history for past events."
@@ -1505,6 +1604,7 @@ const OPERATIONS = [
 		input: z.strictObject({ task: taskKeySchema }),
 		output: z.strictObject({
 			task: taskViewSchema,
+			links: z.array(linkViewSchema).describe("Effective pull request, session, and ticket links."),
 			blocks: z.array(blockViewSchema).describe("Blocks on the task, open and unblocked."),
 			comments: z.array(commentSchema).describe("Comments on the task, oldest first.")
 		}),
@@ -1523,6 +1623,7 @@ const OPERATIONS = [
 			input: { task: "PROJ-123" },
 			output: {
 				task,
+				links: [],
 				blocks: [question],
 				comments: [comment]
 			}
@@ -1809,51 +1910,49 @@ const OPERATIONS = [
 	defineOperation({
 		id: "link.add",
 		kind: "mutation",
-		description: "Link a spur session or a pull request to a task.",
+		description: "Manually link a pull request, session, or additional ticket to a task.",
 		mcp: {
-			whenToUse: "Attach a session or pull request.",
+			whenToUse: "Attach a pull request, session, or additional ticket.",
 			whenNotToUse: "Use link_remove to detach one."
 		},
-		input: z.strictObject({
-			task: taskKeySchema,
-			target
-		}),
+		input: linkInput,
 		output: linkOutput,
 		grants: operatorOnly,
 		errors: [
 			"wrong_id_kind",
 			"not_found",
-			"task_archived"
+			"task_archived",
+			"link_conflict"
 		],
 		cli: {
 			command: "link",
-			args: ["task", "target"]
+			args: ["task"],
+			modes: linkModes
 		},
 		slack: null,
 		examples: [{
 			summary: "Link a pull request",
 			input: {
+				mode: "pr",
 				task: "PROJ-123",
-				target: "acme/web#7"
+				pr: "https://github.com/example/web/pull/7",
+				reason: "Attach work started before the ticket was named."
 			},
 			output: {
 				task: "PROJ-123",
-				target: "acme/web#7"
+				target: "example/web#7"
 			}
 		}]
 	}),
 	defineOperation({
 		id: "link.remove",
 		kind: "mutation",
-		description: "Remove a link between a task and a spur session or a pull request.",
+		description: "Manually remove a pull request, session, or ticket link from a task.",
 		mcp: {
-			whenToUse: "Detach a linked session or pull request.",
+			whenToUse: "Detach a linked pull request, session, or ticket.",
 			whenNotToUse: "Use link_add to attach one."
 		},
-		input: z.strictObject({
-			task: taskKeySchema,
-			target
-		}),
+		input: linkInput,
 		output: linkOutput,
 		grants: operatorOnly,
 		errors: [
@@ -1863,14 +1962,17 @@ const OPERATIONS = [
 		],
 		cli: {
 			command: "unlink",
-			args: ["task", "target"]
+			args: ["task"],
+			modes: linkModes
 		},
 		slack: null,
 		examples: [{
 			summary: "Unlink a session",
 			input: {
+				mode: "session",
 				task: "PROJ-123",
-				target: "web-7"
+				session: "web-7",
+				reason: "Wrong task."
 			},
 			output: {
 				task: "PROJ-123",
@@ -2245,39 +2347,83 @@ const OPERATIONS = [
 			]
 		},
 		slack: null,
-		examples: [{
-			summary: "Unblock after fixing the build",
-			input: {
-				mode: "done",
-				block: "B13",
-				ref: "example/web#9"
+		examples: [
+			{
+				summary: "Unblock after fixing the build",
+				input: {
+					mode: "done",
+					block: "B13",
+					ref: "example/web#9"
+				},
+				output: { block: {
+					...codeBlock,
+					state: "unblocked",
+					outcome: "done",
+					outcomeReason: "example/web#9",
+					unblockedBy: "agent:web/web-8",
+					unblockedAt: at
+				} }
 			},
-			output: { block: {
-				...codeBlock,
-				state: "unblocked",
-				outcome: "done",
-				outcomeReason: "example/web#9",
-				unblockedBy: "agent:web/web-8",
-				unblockedAt: at
-			} }
-		}, {
-			summary: "Withdraw a question",
-			input: {
-				mode: "withdraw",
-				block: "B12",
-				answer: "Answered outside the board."
+			{
+				summary: "Explain why a code block no longer applies",
+				input: {
+					mode: "reason",
+					block: "B13",
+					reason: "The build issue was resolved."
+				},
+				output: { block: {
+					...codeBlock,
+					state: "unblocked",
+					outcome: "reason",
+					outcomeReason: "The build issue was resolved.",
+					unblockedBy: "agent:web/web-8",
+					unblockedAt: at
+				} }
 			},
-			output: { block: {
-				...question,
-				state: "unblocked",
-				outcome: "withdrawn",
-				unblockedBy: "agent:web/web-7",
-				unblockedAt: at
-			} }
-		}]
+			{
+				summary: "Withdraw a question",
+				input: {
+					mode: "withdraw",
+					block: "B12",
+					answer: "Answered outside the board."
+				},
+				output: { block: {
+					...question,
+					state: "unblocked",
+					outcome: "withdrawn",
+					unblockedBy: "agent:web/web-7",
+					unblockedAt: at
+				} }
+			}
+		]
 	})
 ];
 //#endregion
+//#region ../contracts/src/ops/roles.ts
+const ROLE_GRANTS = {
+	operator: /* @__PURE__ */ new Set([
+		"operator",
+		"block-addressee",
+		"block-author"
+	]),
+	worker: /* @__PURE__ */ new Set([
+		"project-agent",
+		"task-worker",
+		"block-addressee",
+		"block-author"
+	]),
+	orchestrator: /* @__PURE__ */ new Set([
+		"project-agent",
+		"column-orchestrator",
+		"block-addressee",
+		"block-author"
+	])
+};
+/** Whether a role has at least one catalog grant for an operation or a particular input mode. */
+function roleCanUseOperation(operation, role, mode) {
+	return operation.grants === "any" || operation.grants.some((rule) => ROLE_GRANTS[role].has(rule.grant) && (mode === void 0 || rule.mode === void 0 || rule.mode === mode));
+}
+//#endregion
 //#region ../contracts/src/ops/snapshot.ts
 /**
 * The catalog as plain JSON: grants, exit codes, errors, and every operation with its JSON
@@ -2472,4 +2618,4 @@ var AdapterError = class extends Error {
 	}
 };
 //#endregion
-export { errorEnvelopeSchema as A, actorIdSchema as C, taskKeySchema as D, parseRef as E, configSchema as M, ERRORS as O, ticketFactsSchema as S, parseActorId as T, SESSION_HEALTH_STATES as _, buildCatalogSnapshot as a, prRefSchema as b, renderJsonError as c, conversationRefSchema as d, inboundEventSchema as f, eventPayloadSchemas as g, userIdSchema as h, sourceCursorSchema as i, successEnvelopeSchema as j, errorContextSchema as k, renderMcpError as l, messageRefSchema as m, batchSchema as n, OPERATIONS as o, interactionRefSchema as p, entityRefSchema as r, renderHttpProblem as s, AdapterError as t, SPACE_IDS as u, SESSION_STATUSES as v, errorCodeOf as w, sessionFactsSchema as x, prFactsSchema as y };
+export { taskKeySchema as A, sessionFactsSchema as C, errorCodeOf as D, encodeActorId as E, configSchema as F, SLACK_BOT_SCOPES as I, errorContextSchema as M, errorEnvelopeSchema as N, parseActorId as O, successEnvelopeSchema as P, prRefSchema as S, actorIdSchema as T, EVENT_KINDS as _, buildCatalogSnapshot as a, SESSION_STATUSES as b, renderHttpProblem as c, SPACE_IDS as d, conversationRefSchema as f, userIdSchema as g, messageRefSchema as h, sourceCursorSchema as i, ERRORS as j, parseRef as k, renderJsonError as l, interactionRefSchema as m, batchSchema as n, roleCanUseOperation as o, inboundEventSchema as p, entityRefSchema as r, OPERATIONS as s, AdapterError as t, renderMcpError as u, eventPayloadSchemas as v, ticketFactsSchema as w, prFactsSchema as x, SESSION_HEALTH_STATES as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spur-board",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "engines": {
     "node": "^24.12.0 || ^26.0.0"

package/skills/setup/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: spur-board-setup
+description: Install, configure, check, and update spur-board with an operator. Use when asked to set up or upgrade the Board. Don't use for daily operations; use spur-board.
+---
+
+# Set up spur-board
+
+Ask one question at a time, only when current state cannot answer it. Check before every write. Ask before changing package, config, secret, service, token, skill-folder, or project-checkout state, or enabling lingering. Never show secret values or put them in chat, logs, or shell history. A same-version rerun changes nothing and repeats no answered question. Never uninstall the service or revoke a token without an explicit operator request.
+
+## 1. Inspect
+
+- Check Linux, systemd user services, npm, `flock`, and Node 24.12+ (24.x) or 26.x. Read the PATH and Node executable from a live Spur session and check its version; the interactive shell may use another Node. Stop with a specific fix for any missing prerequisite.
+- Check Spur through its HTTP API, or run its CLI from the home folder. Running it inside a folder with `spur.yaml` can attach that folder to the daemon.
+- Locate `config.yaml` and `secrets.env` under `$XDG_CONFIG_HOME/spur-board/` (default `$HOME/.config/spur-board/`), or under `$BOARD_HOME` when set. Inspect configured fields, required secret _names_ and file modes, package and skill versions, service status, operator access, and product-skill visibility. Never print private file contents.
+- If config exists, run `board doctor --offline`; it checks config only. If the service is reachable, record failed and warning check names from `board doctor --json`.
+
+## 2. Install the package
+
+- Check whether the required package version and `board` binary are visible on the live session PATH. If current, skip installation.
+- Otherwise choose a user npm prefix whose `bin` is on that PATH, commonly `$HOME/.local`; use the live session's Node and npm for `npm i -g --prefix <prefix> spur-board`. Verify `board --version` with the live session PATH.
+
+## 3. Complete missing configuration
+
+- Discover repositories, Spur projects, and GitHub logins where possible. For each unset value, ask one question and write only that answer: Jira filter and statuses if used, repositories, project names and roles, operator GitHub login per project, and the operator's Slack user ID. Preserve settled and unrelated fields; validate against the shipped config schema.
+- If Slack roles are unset, follow [Slack setup](references/slack.md). List channels visible to the bot and ask which serve orchestrators and feed; store their IDs. The bot sees only private channels it joined.
+- Check required secret names and permissions. Follow [secret files](references/secrets.md) for private entry and any existing `slack.env` migration. Write `config.yaml` and a regular mode `0600` `secrets.env` only when needed.
+- After config edits, run `board doctor --offline` and apply its config fixes. An offline pass does not prove service or integration readiness.
+
+## 4. Start service and grant access
+
+- Check `board service status`; if absent, run `board service install`. Ask before enabling user lingering, which keeps the service running after logout.
+- If operator access is unset, ask whether the operator will use a Spur project marked `operator` or a session outside Spur rooted in a chosen folder. The project path needs no token. For the folder path, check for an existing valid token; only if absent run `board token create --name <name> --into <folder>`, then ask the operator to approve the request in Slack. Check existing agent registration before registering `board mcp`.
+- Check installed skill stamps and content. If absent or older, ask before writing skill folders, run `board skills install`, then verify both Claude Code and Codex copies.
+- For a Spur project used by Codex, check `.agents/skills/spur-board/SKILL.md` in a fresh session. If missing, ask before touching the project's main checkout. In that checkout, link the path to the installed product skill, for example `ln -s "$HOME/.codex/skills/spur-board" .agents/skills/spur-board`. Add `/.agents/skills/spur-board` to the Git exclude file resolved by `git rev-parse --git-path info/exclude`. Add `.agents/skills/spur-board` to that project's `symlinks` in `spur.yaml` and reload Spur config. Start a new session and verify the injected SKILL.md resolves.
+
+## 5. Finish
+
+- Run `board doctor --json`. For each failed check, inspect state, apply its `fix` with any needed consent, and repeat until green. Report warnings, especially live sessions started before the last skill install; they must restart to load it.
+- Wait for the feed's `spur-board is live` line after the first complete poll. If absent, inspect doctor checks and service logs and continue the fix loop. Confirm receipt without exposing a channel ID.
+
+## Update
+
+For a newer package, follow [the update run](references/update.md). Keep completed config and operator access intact.

package/skills/setup/references/secrets.md

@@ -0,0 +1,9 @@
+# Secret files
+
+Use this when secret names are missing or a legacy `slack.env` is present. Work in the resolved Board config directory; never display values or paste them into chat, logs, or shell history.
+
+1. Inspect whether `secrets.env` and `slack.env` are regular files, their modes, and their key names only. The config directory must be private and `secrets.env` must have mode `0600`.
+2. Ask the operator to enter any missing values through a private local mechanism. Required names are `GITHUB_TOKEN`; `JIRA_EMAIL` and `JIRA_API_TOKEN` when Jira is used; and `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` when Slack is configured. Do not create placeholder values.
+3. If `slack.env` exists, ask before migration. For duplicate names, ask which value to keep without revealing either. Preserve every unrelated existing `secrets.env` key.
+4. Build a new regular `secrets.env` with mode `0600` without logging its content. Verify its key names and mode before removing `slack.env`. Leave the source untouched on any error or if consent is withheld.
+5. Check only presence and permissions afterward. Online doctor performs the integration checks; an offline doctor pass does not validate the secret values.

package/skills/setup/references/slack.md

@@ -0,0 +1,9 @@
+# Slack setup
+
+Use this when the orchestrators or feed channel is not configured, or the app-level token is missing.
+
+1. Check the bot's current channel membership. List the private channels it can see and ask the operator, one choice at a time, which should serve orchestrators and feed. An empty list does not prove no channels exist: the bot sees only private channels to which it was invited. Store channel IDs in config, never guessed names.
+2. If no channel fits, ask for an operator-chosen prefix and suggest available names using it. The operator creates or invites the app to channels; ask before any app or channel change.
+3. Check whether an app and slash command already exist. If either is missing, use `board slack manifest --app-name <name> --command <slash-command>` to prepare a manifest with operator-chosen names. The operator creates the Slack app; do not claim the manifest creates it.
+4. The manifest cannot create the app-level token with `connections:write`. Guide the operator through creating that token in Slack, then use the private entry procedure in [secret files](secrets.md). Never ask for a token value in chat.
+5. Check channel membership and command configuration with online doctor. If a check fails, apply its reported fix after inspecting state.

package/skills/setup/references/update.md

@@ -0,0 +1,11 @@
+# Update run
+
+Use this when the installed package is older than the intended release. Keep completed configuration and operator access intact.
+
+1. Check the package version, live Spur session Node and PATH, installed skill stamps and content, service version, and current doctor results. Ask no question already answered in config.
+2. Install the newer package with the Node and user prefix visible to live Spur sessions. Verify `board --version` there. Do not reinstall a matching package.
+3. If skills are older, ask before writing agent skill folders, run `board skills install`, and verify both installed copies. Record the install time so older live sessions can be identified.
+   For a local same-version trial, compare packed and installed bytes too; a matching stamp can hide old content.
+4. Compare the unit's absolute Node and daemon paths with the newly selected Node and installed package. If either path changed, run the new package's `board service install`; it rewrites the unit, reloads systemd, and restarts an active service. If paths are unchanged but the daemon version changed, run `board service restart`. Do not restart twice or restart an unchanged service.
+5. Run `board doctor --json` until no blocking check remains. Report live sessions that still use the older skill and ask the operator to restart those sessions. Do not assume an existing agent or MCP process reloaded updated files.
+6. Never rewrite settled config, reissue an operator token, uninstall the service, or revoke a token as part of an update.