@gtrabanco/pi-agentic-workflow 0.26.0 → 0.30.0

package/README.md

@@ -146,6 +146,47 @@ set of routes, and you can define as many as you like under `profiles`:
   The built-in `nan` profile is shown but not editable — create a profile to
   override it.
 
+## Serena (ships by default)
+
+Installing this package also gives you **Serena's language-server tools** —
+`serena_find_symbol`, `serena_find_referencing_symbols`,
+`serena_get_symbols_overview`, `serena_find_declaration`, diagnostics and the
+rest. Two declarations make that work, and they ship together: the exact-pinned
+`@bacnh85/pi-serena` dependency, and a second `pi.extensions` entry pointing at
+that dependency's own extension. Pi installs a package's dependencies but
+activates only the package's own `pi.extensions` entries, so the pin alone would
+install a toolset nothing ever loaded.
+
+**You must run `/init-workspace` once per project.** This package never writes or
+repairs `.serena/project.yml` — `init-workspace` is its only writer, so there is
+one implementation of that contract and no drift. A project whose config is
+missing, lists no `language_servers`, or was provisioned by an older bundled
+`init-workspace` gets **one** notification per session state pointing at
+`/init-workspace`; the latch lives in this package's state file, so a restart does
+not re-nag.
+
+Serena itself is a local tool: install the machine half with `uv tool install -p
+3.13 serena-agent` (or `/init-workspace`, which offers it). Nothing is uploaded
+and no key is configured.
+
+**Switching it off.** pi owns package resources, so the off switch is pi's, not a
+key of ours: `pi config` opens the resource picker (tab switches scope) and lets
+you disable the package's resources, and the same filter is expressible in
+settings under `packages`:
+
+```json
+{
+  "packages": [
+    { "source": "npm:@gtrabanco/pi-agentic-workflow", "extensions": ["./dist/extension/index.js"] }
+  ]
+}
+```
+
+That keeps the workflow's own extension and commands and drops the Serena
+extension entry, so the `serena_*` tools are never registered. There is no
+settings key inside this package for it: the entry is declared in the manifest,
+and a config key cannot gate a manifest-declared extension.
+
 ## Path protection (optional)
 
 The Tier 2 preventive guard blocks a `write` / `edit` tool call to an existing

package/dist/extension/factory.d.ts

@@ -43,6 +43,12 @@ export interface ExtensionDeps<M extends ModelRef = ModelRef> {
     loadConfig?: (ctx: InvocationContext<M>) => LoadedConfig;
     /** P4: profile demotion state store (optional — defaults to file-backed). */
     profileState?: import("../routing/state.js").ProfileStateStore;
+    /**
+     * Feature 67 D5/AC9: the Serena readiness nudge. Consulted at the first
+     * workflow-command dispatch, so a session that never starts through
+     * `session_start` still hears it once.
+     */
+    serenaReadiness?: import("../routing/serena-readiness.js").SerenaReadinessGate;
 }
 export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     router: Router<M>;

package/dist/extension/factory.js

@@ -31,11 +31,19 @@ export function createExtension(deps) {
     // P4: build the profile state store when not provided.
     const profileState = deps.profileState ?? createProfileStateStore({ path: stateFilePath(agentDir) });
     const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands, profileState });
+    // Said once per state, not once per command: the gate latches in memory for
+    // this session and in the package's state file for later ones.
+    const reportSerenaReadiness = (ctx) => {
+        const message = deps.serenaReadiness?.check(ctx.cwd);
+        if (message)
+            ctx.notify(message, "warning");
+    };
     for (const command of catalogue.commands) {
         registrar.registerCommand(command.name, {
             ...(command.description ? { description: command.description } : {}),
             handler: async (args, ctx) => {
                 reportCatalogueIssues(ctx);
+                reportSerenaReadiness(ctx);
                 await router.dispatch(command, args, ctx);
             },
         });
@@ -44,6 +52,7 @@ export function createExtension(deps) {
     // and the same two config files, never a separate route surface (OB-5, AC6).
     const settingsHandler = async (_args, ctx) => {
         reportCatalogueIssues(ctx);
+        reportSerenaReadiness(ctx);
         // Bound for the console: two verbs and the session they act on, so it cannot
         // reach for `settle` or `dispatch` by accident.
         const routing = {

package/dist/extension/index.js

@@ -7,7 +7,8 @@ import { evaluateToolCall, isProtectedPath, normalizeTarget } from "../config/pa
 import { createExtension } from "./factory.js";
 import { readGitStatusBounded } from "./receipt-guard.js";
 import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
-import { createHintStore, stateFilePath } from "../routing/state.js";
+import { createHintStore, createSerenaReadinessStore, stateFilePath } from "../routing/state.js";
+import { createSerenaReadinessGate, readInitWorkspaceRevision } from "../routing/serena-readiness.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
@@ -174,6 +175,14 @@ function resolveExistingPrefix(target) {
 export default function extension(pi) {
     const agentDir = getAgentDir();
     const hint = createHintStore({ path: stateFilePath(agentDir) });
+    // One gate for both entry points (AC9): session start says it first, and a
+    // session that begins by running a command says it there instead. The
+    // revision is the bundled init-workspace's own, so an upgrade that ships a
+    // newer provisioning contract can tell the operator the project predates it.
+    const serenaReadiness = createSerenaReadinessGate({
+        store: createSerenaReadinessStore({ path: stateFilePath(agentDir) }),
+        revision: readInitWorkspaceRevision(skillsDir),
+    });
     // Said once per session: an override that was ignored (or a malformed file)
     // is reported the first time the guard runs, never on every tool call.
     let reportedDegradations = false;
@@ -190,6 +199,7 @@ export default function extension(pi) {
         skillsDir,
         agentDir,
         hint,
+        serenaReadiness,
         loadConfig: (ctx) => loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }),
         // The console edits the same files the dispatcher reads (SPEC S4, AC10).
         settings: ({ ctx, catalogue: routed, routing }) => runSettingsConsole({
@@ -204,6 +214,14 @@ export default function extension(pi) {
             writeFile: writeConfigFile,
         }),
     });
+    // The readiness nudge's first chance (AC9): a session that opens here hears
+    // it, and the gate latches so the command path never repeats it. Soft by
+    // construction — the gate swallows a broken read and a failed latch.
+    pi.on("session_start", (_event, ctx) => {
+        const message = serenaReadiness.check(ctx.cwd);
+        if (message)
+            ctx.ui.notify(message, "warning");
+    });
     pi.on("model_select", (event) => router.noteModelSelect(event.model));
     pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));
     // The inline-receipt path is impossible: a `gh pr comment` carrying a

package/dist/routing/serena-readiness.d.ts

@@ -0,0 +1,77 @@
+import type { SerenaReadinessRecord, SerenaReadinessStore } from "./state.js";
+/**
+ * Serena readiness nudge (feature 67 P5, decision D5 / AC9).
+ *
+ * A pi user who installs this package gets Serena's tools, but the project
+ * config is `init-workspace`'s to write (AC6: one writer, no drift). So this is
+ * the only thing the package may do about a project that was never provisioned:
+ * **say so, once**, and point at the command that fixes it.
+ *
+ * The contract, in four lines:
+ *  - it reads `.serena/project.yml` and reports `missing`, `stale`, `outdated`
+ *    (the bundled init-workspace moved on) or `ready`;
+ *  - it announces **exactly one** message per recorded state, then latches —
+ *    the latch lives in the package's own global state file, so a restart does
+ *    not re-nag (the first-run hint's contract);
+ *  - it writes nothing to the project and nothing to any configuration;
+ *  - every failure is soft: a broken read is `missing`, a failed latch is a
+ *    nuisance, and neither ever throws into a command.
+ */
+/** The one command that owns Serena provisioning. */
+export declare const INIT_WORKSPACE_COMMAND = "/init-workspace";
+/** What a `.serena/project.yml` says about itself — only what this check reads. */
+export interface SerenaConfig {
+    present: boolean;
+    /** The `language_servers` entries, in file order. Empty when absent or empty. */
+    languageServers: string[];
+}
+export type SerenaReadiness = {
+    kind: "missing";
+} | {
+    kind: "stale";
+    detail: string;
+} | {
+    kind: "outdated";
+    recorded: string;
+    revision: string;
+} | {
+    kind: "ready";
+};
+/**
+ * Read the two facts this check needs out of the project config. A tolerant
+ * line scanner, not a YAML parser: the file is written by `init-workspace`, and
+ * the only key read here is the `language_servers` list. Anything it cannot
+ * understand reads as "no servers", which is the fail-closed direction — the
+ * nudge fires rather than a broken config passing silently.
+ */
+export declare function inspectSerenaConfig(text: string | null | undefined): SerenaConfig;
+/**
+ * Decide what this project needs. `recorded` is the latch's last announcement —
+ * a changed shipped revision is itself a trigger, so an upgraded package can
+ * tell the operator that the config predates it.
+ */
+export declare function evaluateSerenaReadiness({ config, recorded, revision, }: {
+    config: SerenaConfig;
+    recorded?: SerenaReadinessRecord;
+    revision: string;
+}): SerenaReadiness;
+/** The one notification this module may produce, or null when there is nothing to say. */
+export declare function serenaReadinessMessage(readiness: SerenaReadiness): string | null;
+export interface SerenaReadinessGate {
+    /** The message to announce for this project, or null when nothing is due. */
+    check(projectKey: string): string | null;
+}
+/**
+ * The gate the two entry points share (session start and the first command
+ * dispatch). One latch per extension instance, so a single session announces at
+ * most once; the persisted record keeps later sessions quiet.
+ */
+export declare function createSerenaReadinessGate({ store, revision, readProject, now, }: {
+    store: SerenaReadinessStore;
+    revision: string;
+    /** Injectable so the suite reads fixtures instead of a real project. */
+    readProject?: (projectKey: string) => string | null;
+    now?: () => string;
+}): SerenaReadinessGate;
+/** The bundled `init-workspace` revision, read from the shipped skill's frontmatter. */
+export declare function readInitWorkspaceRevision(skillsDir: string): string;

package/dist/routing/serena-readiness.js

@@ -0,0 +1,142 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Serena readiness nudge (feature 67 P5, decision D5 / AC9).
+ *
+ * A pi user who installs this package gets Serena's tools, but the project
+ * config is `init-workspace`'s to write (AC6: one writer, no drift). So this is
+ * the only thing the package may do about a project that was never provisioned:
+ * **say so, once**, and point at the command that fixes it.
+ *
+ * The contract, in four lines:
+ *  - it reads `.serena/project.yml` and reports `missing`, `stale`, `outdated`
+ *    (the bundled init-workspace moved on) or `ready`;
+ *  - it announces **exactly one** message per recorded state, then latches —
+ *    the latch lives in the package's own global state file, so a restart does
+ *    not re-nag (the first-run hint's contract);
+ *  - it writes nothing to the project and nothing to any configuration;
+ *  - every failure is soft: a broken read is `missing`, a failed latch is a
+ *    nuisance, and neither ever throws into a command.
+ */
+/** The one command that owns Serena provisioning. */
+export const INIT_WORKSPACE_COMMAND = "/init-workspace";
+/**
+ * Read the two facts this check needs out of the project config. A tolerant
+ * line scanner, not a YAML parser: the file is written by `init-workspace`, and
+ * the only key read here is the `language_servers` list. Anything it cannot
+ * understand reads as "no servers", which is the fail-closed direction — the
+ * nudge fires rather than a broken config passing silently.
+ */
+export function inspectSerenaConfig(text) {
+    if (typeof text !== "string")
+        return { present: false, languageServers: [] };
+    const lines = text.split(/\r?\n/u);
+    const start = lines.findIndex((line) => /^language_servers:/u.test(line));
+    if (start === -1)
+        return { present: true, languageServers: [] };
+    // Inline form: `language_servers: [markdown, json]`
+    const inline = /^language_servers:\s*\[(.*)\]\s*$/u.exec(lines[start]);
+    if (inline) {
+        return {
+            present: true,
+            languageServers: inline[1]
+                .split(",")
+                .map((entry) => entry.trim().replace(/^["']|["']$/gu, ""))
+                .filter(Boolean),
+        };
+    }
+    const languageServers = [];
+    for (const line of lines.slice(start + 1)) {
+        const item = /^\s+-\s*(.+?)\s*$/u.exec(line);
+        if (!item) {
+            // The list ended (a new top-level key) or the line is blank/comment.
+            if (line.trim() !== "" && !/^\s*#/u.test(line))
+                break;
+            continue;
+        }
+        languageServers.push(item[1].replace(/^["']|["']$/gu, ""));
+    }
+    return { present: true, languageServers };
+}
+/**
+ * Decide what this project needs. `recorded` is the latch's last announcement —
+ * a changed shipped revision is itself a trigger, so an upgraded package can
+ * tell the operator that the config predates it.
+ */
+export function evaluateSerenaReadiness({ config, recorded, revision, }) {
+    if (!config.present)
+        return { kind: "missing" };
+    if (config.languageServers.length === 0) {
+        return {
+            kind: "stale",
+            detail: "the project config lists no language_servers, so no server will start for it",
+        };
+    }
+    if (recorded?.state === "ready" && recorded.revision !== revision) {
+        return { kind: "outdated", recorded: recorded.revision, revision };
+    }
+    return { kind: "ready" };
+}
+/** The one notification this module may produce, or null when there is nothing to say. */
+export function serenaReadinessMessage(readiness) {
+    switch (readiness.kind) {
+        case "missing":
+            return (`pi-agentic-workflow: serena — this project has no .serena/project.yml, so no language server ` +
+                `will start for it. Run ${INIT_WORKSPACE_COMMAND} to provision it (this is said once).`);
+        case "stale":
+            return (`pi-agentic-workflow: serena — ${readiness.detail}. Run ${INIT_WORKSPACE_COMMAND} to rewrite it ` +
+                `(this is said once).`);
+        case "outdated":
+            return (`pi-agentic-workflow: serena — this project's config was provisioned by init-workspace ` +
+                `${readiness.recorded}, and this package ships ${readiness.revision}. Run ${INIT_WORKSPACE_COMMAND} ` +
+                `to bring it up to date (this is said once).`);
+        case "ready":
+            return null;
+    }
+}
+/**
+ * The gate the two entry points share (session start and the first command
+ * dispatch). One latch per extension instance, so a single session announces at
+ * most once; the persisted record keeps later sessions quiet.
+ */
+export function createSerenaReadinessGate({ store, revision, readProject = (projectKey) => {
+    try {
+        return readFileSync(join(projectKey, ".serena", "project.yml"), "utf8");
+    }
+    catch {
+        return null;
+    }
+}, now = () => new Date().toISOString(), }) {
+    let announced = false;
+    return {
+        check(projectKey) {
+            if (announced)
+                return null;
+            announced = true;
+            const config = inspectSerenaConfig(readProject(projectKey));
+            const recorded = store.record(projectKey);
+            const readiness = evaluateSerenaReadiness({ config, recorded, revision });
+            // The latch compares STATE KINDS, not just the presence of a record: a
+            // project that was ready and lost its config is a new thing to say, while
+            // a project still missing one is not.
+            const due = readiness.kind !== "ready" && recorded?.state !== readiness.kind;
+            // Latch second, and always: a ready project still stores its revision, so
+            // a later upgrade has a baseline to compare against.
+            store.latch(projectKey, { state: readiness.kind, revision, at: now() });
+            if (!due)
+                return null;
+            return serenaReadinessMessage(readiness);
+        },
+    };
+}
+/** The bundled `init-workspace` revision, read from the shipped skill's frontmatter. */
+export function readInitWorkspaceRevision(skillsDir) {
+    try {
+        const text = readFileSync(join(skillsDir, "init-workspace", "SKILL.md"), "utf8");
+        const match = /^version:\s*(\S+)\s*$/mu.exec(text.split("\n---", 1)[0] ?? "");
+        return match ? match[1] : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/routing/state.d.ts

@@ -37,3 +37,35 @@ export interface ProfileStateStoreOptions {
     writeFile?: (path: string, text: string) => void;
 }
 export declare function createProfileStateStore({ path, readFile, writeFile, }: ProfileStateStoreOptions): ProfileStateStore;
+/**
+ * What the operator was last told about one project's Serena config, keyed by
+ * the project root. The record is the nudge's whole memory: the state kind it
+ * announced and the init-workspace revision that was current when it did.
+ */
+export interface SerenaReadinessRecord {
+    /** The readiness kind announced (`missing`, `stale`, `outdated`, `ready`). */
+    state: string;
+    /** The bundled `init-workspace` revision in force at that moment. */
+    revision: string;
+    /** ISO-8601 timestamp of the announcement. */
+    at: string;
+}
+export interface SerenaReadinessStore {
+    /** The record for `projectKey`, or undefined when this project was never seen. */
+    record(projectKey: string): SerenaReadinessRecord | undefined;
+    /** Persist the record for `projectKey`. Returns false when the write failed. */
+    latch(projectKey: string, record: SerenaReadinessRecord): boolean;
+}
+export interface SerenaReadinessStoreOptions {
+    path: string;
+    readFile?: (path: string) => string | null;
+    writeFile?: (path: string, text: string) => void;
+}
+/**
+ * The nudge's latch, in the package's own global state file beside the
+ * first-run hint and the profile demotion — never inside the project, and never
+ * inside any configuration. Read-merge-write throughout, so no other key in
+ * that file is disturbed; every failure is soft (a latch that cannot be
+ * persisted re-shows the nudge next session, which is a nuisance, not a fault).
+ */
+export declare function createSerenaReadinessStore({ path, readFile, writeFile, }: SerenaReadinessStoreOptions): SerenaReadinessStore;

package/dist/routing/state.js

@@ -129,3 +129,54 @@ export function createProfileStateStore({ path, readFile = readOrNull, writeFile
         },
     };
 }
+/**
+ * The nudge's latch, in the package's own global state file beside the
+ * first-run hint and the profile demotion — never inside the project, and never
+ * inside any configuration. Read-merge-write throughout, so no other key in
+ * that file is disturbed; every failure is soft (a latch that cannot be
+ * persisted re-shows the nudge next session, which is a nuisance, not a fault).
+ */
+export function createSerenaReadinessStore({ path, readFile = readOrNull, writeFile = writeThrough, }) {
+    const readState = () => {
+        const text = readFile(path);
+        if (text === null || text.trim() === "")
+            return {};
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed === "object" && parsed !== null)
+                return parsed;
+        }
+        catch {
+            // Corrupt state: treat as empty, so the nudge is shown rather than lost.
+        }
+        return {};
+    };
+    return {
+        record(projectKey) {
+            const raw = readState().serenaReadiness;
+            if (typeof raw !== "object" || raw === null)
+                return undefined;
+            const entry = raw[projectKey];
+            if (typeof entry !== "object" || entry === null)
+                return undefined;
+            const { state, revision, at } = entry;
+            if (typeof state !== "string" || typeof revision !== "string" || typeof at !== "string")
+                return undefined;
+            return { state, revision, at };
+        },
+        latch(projectKey, record) {
+            const state = readState();
+            const existing = state.serenaReadiness;
+            const perProject = typeof existing === "object" && existing !== null ? existing : {};
+            perProject[projectKey] = record;
+            state.serenaReadiness = perProject;
+            try {
+                writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.26.0",
+  "version": "0.30.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",
@@ -21,7 +21,8 @@
   "type": "module",
   "pi": {
     "extensions": [
-      "./dist/extension/index.js"
+      "./dist/extension/index.js",
+      "./node_modules/@bacnh85/pi-serena/extensions/index.ts"
     ],
     "skills": [
       "./skills"
@@ -57,8 +58,9 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
+    "@bacnh85/pi-serena": "0.10.0",
     "@gtrabanco/agentic-workflow": "0.2.0",
-    "@gtrabanco/agentic-workflow-schema": "4.6.0"
+    "@gtrabanco/agentic-workflow-schema": "4.7.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 4.0.3
+version: 4.1.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -26,7 +26,8 @@ raw placeholders.
   three-tier dispatch and stops with the dispatcher's `open-questions@1` block
   — against a scratch unit folder when no unit exists yet (§Consent).
 ✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
-✓ Nothing was installed or overwritten without an explicit yes
+✓ Nothing was installed, registered (MCP) or overwritten — including the global
+  Serena config — without an explicit yes
 ✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
 ✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
 ```
@@ -122,12 +123,16 @@ loads exactly upgrade and skips bootstrap plus portability.
   on its own. **The urgency label seeding is additive-only the same way:**
   create a missing `urgent`/`fix-next` label, never touch one that already
   exists (name, color, or description a project already customized).
-- **Serena convention.** `.serena/project.yml` is committed; `project.local.yml`
-  and `cache` stay local. Never write `.serena/` config without consent. LSP
-  never verifies documents — false positives happen when a file type's server
-  is not listed (markdown/yaml/json are never auto-detected), and a listed
-  server that fails to start must be removed (one failure disables every
-  server in the project). Document verification is a script's job.
+- **Serena convention — tool and config, one consent question.** `.serena/project.yml`
+  is committed; `project.local.yml` and `cache` stay local. Never write
+  `.serena/` config, install the tool, register an MCP server or touch the
+  global `serena_config.yml` (`trusted_project_path_patterns`) without an
+  explicit yes — [SERENA](references/SERENA.md) owns the single question and
+  the fixed provisioning report. LSP never verifies documents — false positives
+  happen when a file type's server is not listed (markdown/yaml/json are never
+  auto-detected), a listed server that fails to start must be removed (one
+  failure disables every server in the project), and LSP evidence stays
+  TypeScript/JavaScript-only. Document verification is a script's job.
 - **Retrieval index scaffold and git hooks are consent-gated (AC22).** The
   index surface — the committed `.agentic-workflow/index.json` config plus the
   three freshness hooks (`post-merge`, `post-checkout`, `post-rewrite`, all
@@ -217,8 +222,11 @@ OpenCode adapter does not load this fallback.
   listed as a residual when its hook API/dependency was unavailable.
   The adaptive lane conventions (unit document, triage, catalog steps, guards,
   evidence, commit formats) are written into AGENTS.md.
-- The Serena project config is provisioned (or reported as a residual with the
-  reason, and the health check ran).
+- Serena is provisioned and reported: the one consent question was asked, the
+  project config written (or skipped with its reason), the tool installed and its
+  MCP server registered for the detected platform — or each refused/absent item
+  recorded as a residual with its reason — and the fixed provisioning report
+  states the health check per listed server. The run completes either way.
 - **The closing `→ Next:` block is printed** (plus the offer to install the skills):
 
   ```

package/skills/init-workspace/references/BOOTSTRAP_DISCOVERY.md

@@ -69,3 +69,9 @@
      website itself.
    - **Naming conventions**, **MCP servers**, and **Serena language servers** (see
      [SERENA](SERENA.md) for the mapping), if any.
+   - **Serena footprint** — the platform whose MCP config is the one to register
+     (Claude Code, Cursor, VS Code/Copilot, Codex, JetBrains), the installers
+     actually present (`uv --version`, `pipx --version`), and whether the global
+     `serena_config.yml` already covers this project root under
+     `trusted_project_path_patterns`. The write step offers **one** consent
+     question from these three facts; it never asks a second time.

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -24,13 +24,16 @@
 7. **Propagate the unit doc template.** Ensure
    `docs/features/_TEMPLATE/SPEC.md` exists with all 14 sections sections.
    This is the template used when creating new unit documents.
-8. **Provision the Serena project config.** Load
-   [SERENA](SERENA.md), ask consent, then: (a) append the `.gitignore`
-   block additively (skip when already present); (b) write `.serena/project.yml`
-   with the `language_servers` list for every detected language (never overwrite
-   an existing file — report it); (c) run the health check from SERENA.md and
-   record the result. If Serena is not installed, offer install or record as a
-   residual.
+8. **Provision Serena — one consented question, then write.** Load
+   [SERENA](SERENA.md) and ask its single consent question; one yes covers the
+   tool install, the detected platform's MCP registration and the global trust
+   append, and a refusal installs, registers and writes **nothing**. On yes:
+   (a) append the `.gitignore` block additively (skip when already present);
+   (b) write `.serena/project.yml` with the `language_servers` list for every
+   detected language (never overwrite an existing file — report it); (c) run the
+   health check and render the fixed provisioning report. When no installer is
+   available, offer only what the machine can perform and record the residual
+   with its reason — the run completes either way.
 9. **Install accepted agent safety hooks.** Keep the canonical policy and
    fullauto wrapper at `.agentic-workflow/hooks/`. Seed the shipped
    path-protection policy at `.agentic-workflow/path-policy.json` and its doc

package/skills/init-workspace/references/SERENA.md

@@ -93,6 +93,12 @@ check names the offending entry. Removing a failing entry (per the startup
 rule below) is the correct remediation — never leave a dead entry in the file.
 **Never claim LSP evidence for a run whose server never started.**
 
+The report's `health:` line carries one entry per listed server. When the check
+cannot run at all — no tool, no installer, or a refused consent, including a
+refused **trust** append (§Trust) — it says so once, on that line, with the
+reason, instead of reporting a pass: an absent check is a residual, never a
+silent pass.
+
 ### Startup rule (critical)
 
 > **A server that fails to start must not stay listed.** One failing entry
@@ -121,13 +127,93 @@ deterministic script's job regardless — LSP serves navigation and diagnostics,
 not our document grammar. `node`+`npm` are required for json/yaml; `libicu` is
 required for marksman.
 
-## Tool install is a different step
+## Provisioning the tool — one consented question
+
+This file owns the **project config** *and* the tool that reads it. The install
+half (`#219`) lands here as one step, never a second interview.
+
+**Order inside the step (fixed):**
+
+1. **Detect what can be performed** — `uv --version` first, then `pipx
+   --version`. Never offer a route the machine cannot run.
+2. **Ask ONCE**, with the whole set in the question: the tool install, the MCP
+   registration for **the detected platform only**, and the global trust append
+   when the project root is not covered. One yes covers the set the question
+   names; a narrower yes narrows the set.
+3. **On yes** — install, register, append trust, then report exactly what
+   happened (§Report).
+4. **On no** — install nothing, register nothing, write nothing. Record the
+   absence as a residual with its reason and finish; the run still completes.
+
+**Install routes, in the order tried:**
+
+| Route | Command | When |
+|---|---|---|
+| preferred | `uv tool install -p 3.13 serena-agent`, then `serena init` | `uv` is on PATH |
+| fallback | `pipx install serena-agent`, then `serena init` | `uv` absent, `pipx` present — **MCP path only** |
+
+`serena init` creates the global `serena_config.yml` when absent and never
+rewrites an existing one. `serena -V` prints `Serena <version>`: that is the
+health reader, and the only proof the tool runs.
+
+### MCP registration — the detected platform, its own shape
+
+Register **one** server named `serena`, in the config file of the platform
+Step 0 detected. Never write a cross-platform blob, and never write a second
+platform's file "to be safe". A per-workspace file (`.vscode/mcp.json`,
+`.cursor/mcp.json`) needs the same consent as the rest; a global one
+(`~/.codex/config.toml`, the JetBrains `mcp.json`) is append-only — the one
+entry, never another line.
+
+| Detected | Where | Entry |
+|---|---|---|
+| Claude Code | `claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"` (user scope: `--scope user`, `--project-from-cwd`) | command `serena` |
+| Copilot / VS Code | `.vscode/mcp.json` → `servers.serena` | `{"type":"stdio","command":"serena","args":["start-mcp-server","--context=vscode","--project","${workspaceFolder}"]}` |
+| Cursor | `.cursor/mcp.json` → `mcpServers.serena` | `{"command":"serena","args":["start-mcp-server","--context=ide"]}` |
+| JetBrains Copilot | the global `mcp.json` Copilot opens | `{"type":"stdio","command":"serena","args":["start-mcp-server","--context=jb-copilot-plugin"]}` |
+| Codex | `~/.codex/config.toml` → `[mcp_servers.serena]` | `command = "serena"`, `args = ["start-mcp-server","--project-from-cwd","--context=codex"]` |
+
+### Trust — the fresh clone (global config, consent-gated)
+
+`trusted_project_path_patterns` lives in the user's **global** `serena_config.yml`,
+not the project's `.serena/project.yml`, and a fresh config defaults it to `[]`.
+A project root no pattern covers starts no language server, so the health check
+fails with nothing in the project to blame.
+
+- **Detect** — read the global config, test this project root against the
+  patterns.
+- **Offer the append inside the same consented question.** This file is shared by
+  every project on the machine, so it is never written implicitly.
+- **On yes** — append **one pattern naming this project root**. Never rewrite,
+  reorder or reformat any other line; an append is the only permitted edit.
+- **On no** — record the untrusted state as the health-check residual. It is a
+  residual, not an error, and it never blocks the run.
+
+### Report — exactly what happened
+
+Close the step with this fixed block. "Installed" is never assumed and never
+reported from the intent to install:
 
-This file owns the **project config**, not the tool. If Serena is not installed,
-offer the install (ask-first; `uv`/`uvx` preferred, `pipx` fallback) or record
-it as a residual. The install half is tracked by #219.
+```text
+SERENA PROVISIONING
+tool:      <installed | already present | refused | no installer | failed: <reason>>
+version:   <serena -V output, or n/a>
+mcp:       <registered <platform> -> <path> | already present | refused | failed: <reason>>
+trust:     <appended <pattern> | already covered | refused - untrusted | n/a>
+config:    <written .serena/project.yml | already present | skipped: <reason>>
+health:    <one line per listed server, see below>
+residual:  <none | the reason this run is degraded>
+```
 
 ## Degraded path
 
-Serena unavailable → warn once, continue, and record the absence in the unit's
-evidence. **Never block a run on it.**
+Serena unavailable — no tool, no installer (`uv`, `pipx`), or a refused consent —
+→ warn once, continue, and record the absence with its reason in the unit's
+evidence. **Never block a run on it**, and never let a degraded run read as a
+healthy one: the report says which line is missing and why.
+
+LSP evidence itself stays confined to **TypeScript/JavaScript**: a diagnostic
+from any other listed server is navigation aid, never verification evidence, and
+no claim may cite it. Document verification (schema rules, required sections,
+column counts) stays a **deterministic script's** job regardless — LSP serves
+navigation, not our document grammar.

package/skills/init-workspace/references/UPGRADE.md

@@ -92,13 +92,15 @@ lacks**. Nine ordered steps:
    rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
    project recolored or redescribed is left exactly as-is).
 
-8. **Provision the Serena project config, additively only (Refs #219).** Load
-   [SERENA](SERENA.md). Append the `.gitignore` block only if the target
-   does not already contain it. Write `.serena/project.yml` only if it is
-   absent — never touch an existing one. Report what was skipped and why.
-   Run the health check and record the result. If Serena is not installed,
-   offer install or record as a residual. This step is additive-only; it
-   never rewrites or deletes, consistent with upgrade mode's rule.
+8. **Provision Serena, additively only (Refs #219).** Load
+   [SERENA](SERENA.md) and ask its single consent question — the tool install,
+   the detected platform's MCP registration and the global trust append all ride
+   on that one yes, and a refusal writes nothing. Then append the `.gitignore`
+   block only if the target lacks it, and write `.serena/project.yml` only if it
+   is absent — never touch an existing one. Report what was skipped and why, run
+   the health check, and render the fixed provisioning report. This step is
+   additive-only; it never rewrites or deletes, consistent with upgrade mode's
+   rule.
 9. **Report + hand off.** Summarize blocks added, filled, and skipped
    (residuals), the legacy `CLAUDE.md` outcome (folded items and removed, or kept
    with the reason), the urgency labels seeded (or already present), then print the