@gtrabanco/pi-agentic-workflow 0.15.3 → 0.17.0

package/dist/settings/console.js

@@ -7,6 +7,11 @@
 // a scope whose file does not parse cannot be overwritten (that file is evidence
 // the operator must fix, not noise to clobber), and the project scope is refused
 // while the project is untrusted — the same gate the loader applies (AC13).
+//
+// P5 (feature 63): the flow is scope → profile → routes. Every command operates
+// on the active profile's route (for "default" this is top-level; for a named
+// profile it is `profiles.<name>`). The profile defaults to "default", so
+// existing tests that never answer a profile prompt keep working unchanged.
 import { loadConfig, configFilePaths } from "../config/load.js";
 import { effectiveRoute } from "../config/merge.js";
 import { parseConfigFile, parseModelReference } from "../config/schema.js";
@@ -32,6 +37,13 @@ export const prompts = {
     clearOverride: "Clear a command override",
     bulkApply: "Apply one route to several commands",
     bulkClear: "Clear several overrides",
+    switchProfile: "Switch the profile being edited",
+    rotateProfile: "Rotate the active profile",
+    toggleRecommended: "Toggle recommended models",
+    profile: "Which profile?",
+    newProfile: "Name the new profile",
+    profileBuiltIn: (name) => `The "${name}" profile is built into the package and cannot be edited — create a profile to override it.`,
+    profileNamed: (name) => `Editing profile "${name}"`,
     addAnother: "Add another?",
     policy: "Set the unavailable-route policy",
     settle: "Set the post-command model keep/restore policy",
@@ -57,23 +69,27 @@ const INHERIT = "inherit";
 export async function runSettingsConsole(deps) {
     const paths = configFilePaths(deps.agentDir, deps.cwd);
     const merged = loadConfig({ agentDir: deps.agentDir, cwd: deps.cwd, projectTrusted: deps.projectTrusted, readFile: deps.readFile });
-    deps.ui.notify(renderMergedConfig(merged, deps.commands).join("\n"), "info");
-    /** The value in force for a target (the merged route, or the default when the target is "the default route"). */
-    const currentFor = (target) => effectiveRoute(merged.config, target);
+    deps.ui.notify(renderMergedConfig(merged, deps.commands, merged.config.profiles?.nan !== undefined || (deps.models ?? []).some((m) => m.startsWith("nan/"))
+        ? { providerAvailable: (provider) => (deps.models ?? []).some((m) => m.startsWith(`${provider}/`)) }
+        : undefined).join("\n"), "info");
     const opened = await openAScope(deps, paths.global, paths.project);
     if (!opened)
         return { status: "cancelled", edited: false };
     const { scope, path, original } = opened;
     let draft = original;
+    let active = "default";
     for (;;) {
         // Only offered while a turn actually holds the latch: an option that does
         // nothing is how a console becomes noise.
         const choice = await deps.ui.select(prompts.menu, [
+            prompts.switchProfile,
             prompts.setDefaultRoute,
             prompts.setOverride,
             prompts.clearOverride,
             prompts.bulkApply,
             prompts.bulkClear,
+            prompts.rotateProfile,
+            prompts.toggleRecommended,
             prompts.policy,
             prompts.settle,
             ...(deps.routing?.inFlight() ? [prompts.undoInFlight] : []),
@@ -88,57 +104,172 @@ export async function runSettingsConsole(deps) {
         if (choice === undefined || choice === prompts.cancel) {
             return { status: "cancelled", edited: dirty(draft, original) ? await discard(deps.ui) : false };
         }
+        // Profile: switch to another profile (scope → profile → routes)
+        if (choice === prompts.switchProfile) {
+            const picked = await pickProfile(deps, draft, { allowNew: true });
+            if (picked === undefined)
+                continue;
+            // P5: the built-in "nan" profile cannot be edited — create a profile
+            // to override it.
+            if (picked === "nan" && draft.profiles?.nan === undefined) {
+                deps.ui.notify(prompts.profileBuiltIn("nan"), "warning");
+                continue;
+            }
+            if (picked !== "default" && !Object.prototype.hasOwnProperty.call(draft.profiles ?? {}, picked)) {
+                draft = { ...draft, profiles: { ...(draft.profiles ?? {}), [picked]: {} } };
+            }
+            active = picked;
+            deps.ui.notify(prompts.profileNamed(active), "info");
+            continue;
+        }
+        // Rotate: move a profile to the front of profileOrder, clear demotion
+        if (choice === prompts.rotateProfile) {
+            const picked = await pickProfile(deps, draft, { allowNew: false });
+            if (picked === undefined)
+                continue;
+            const base = draft.profileOrder && draft.profileOrder.length > 0 ? draft.profileOrder : ["default"];
+            draft = { ...draft, profileOrder: [picked, ...base.filter((n) => n !== picked)] };
+            deps.routing?.clearProfileDemotion?.();
+            continue;
+        }
+        // Toggle recommended models
+        if (choice === prompts.toggleRecommended) {
+            const current = draft.recommendedModels ?? merged.config.recommendedModels;
+            draft = { ...draft, recommendedModels: !current };
+            continue;
+        }
+        // Set default route on the active profile
         if (choice === prompts.setDefaultRoute) {
-            const edited = await editRoute(deps, DEFAULT_ROUTE, currentFor(DEFAULT_ROUTE));
-            if (edited)
-                draft = { ...draft, default: edited };
+            const target = active === "default" ? DEFAULT_ROUTE : `profile ${active} default`;
+            const routeFile = active === "default"
+                ? (draft.default ?? {})
+                : (draft.profiles?.[active]?.default ?? {});
+            const currentRoute = {
+                model: routeFile.model ?? "inherit",
+                thinking: routeFile.thinking ?? "inherit",
+            };
+            const edited = await editRoute(deps, target, currentRoute);
+            if (edited) {
+                if (active === "default") {
+                    draft = { ...draft, default: edited };
+                }
+                else {
+                    draft = {
+                        ...draft,
+                        profiles: { ...(draft.profiles ?? {}), [active]: { ...(draft.profiles?.[active] ?? {}), default: edited } },
+                    };
+                }
+            }
             continue;
         }
+        // Set override on active profile's commands
         if (choice === prompts.setOverride) {
-            const name = await pickCommand(deps, commandChoices(deps, draft));
+            // Use the full command registry so operators can add new overrides (AC4/OB-3).
+            const cmdNames = [...new Set([...deps.commands, ...Object.keys(draft.commands ?? {})])];
+            const name = await pickCommand(deps, cmdNames);
             if (name === undefined)
                 continue;
-            const route = await editRoute(deps, name, currentFor(name));
-            if (route)
-                draft = { ...draft, commands: { ...draft.commands, [name]: route } };
+            // The initial value comes from the merged config so the picker shows the
+            // value in force, matching the original `currentFor(name)` behavior.
+            const effective = effectiveRoute(merged.config, name);
+            const routeFile = active === "default"
+                ? (draft.commands?.[name] ?? {})
+                : (draft.profiles?.[active]?.commands?.[name] ?? {});
+            const currentRoute = {
+                model: typeof routeFile?.model !== "undefined" ? routeFile.model : effective.model,
+                thinking: typeof routeFile?.thinking !== "undefined" ? routeFile.thinking : effective.thinking,
+            };
+            const route = await editRoute(deps, name, currentRoute);
+            if (route) {
+                if (active === "default") {
+                    draft = { ...draft, commands: { ...draft.commands, [name]: route } };
+                }
+                else {
+                    draft = {
+                        ...draft,
+                        profiles: {
+                            ...(draft.profiles ?? {}),
+                            [active]: { ...(draft.profiles?.[active] ?? {}), commands: { ...(draft.profiles?.[active]?.commands ?? {}), [name]: route } },
+                        },
+                    };
+                }
+            }
             continue;
         }
+        // Clear override on active profile's commands
         if (choice === prompts.clearOverride) {
-            const name = await pickCommand(deps, Object.keys(draft.commands ?? {}));
+            const cmdNames = Object.keys(profileOf(draft, active).commands ?? {});
+            const name = await pickCommand(deps, cmdNames);
             if (name === undefined)
                 continue;
-            const rest = { ...draft.commands };
-            delete rest[name];
-            draft = { ...draft, commands: rest };
+            if (active === "default") {
+                const rest = { ...draft.commands };
+                delete rest[name];
+                draft = { ...draft, commands: rest };
+            }
+            else {
+                const profile = draft.profiles?.[active] ?? {};
+                const rest = { ...(profile.commands ?? {}) };
+                delete rest[name];
+                draft = { ...draft, profiles: { ...(draft.profiles ?? {}), [active]: { ...profile, commands: rest } } };
+            }
             continue;
         }
+        // Bulk apply on active profile's commands
         if (choice === prompts.bulkApply) {
-            // One field pass (model via the chain builder + thinking), applied to every
-            // selected command. A reference missing from the live registry warns per
-            // command but never blocks the write (OB-4 — dispatch's probe stays the
-            // authoritative availability gate).
-            const selected = await pickCommandsMulti(deps, commandChoices(deps, draft));
+            // Use the full command registry so operators can apply to new commands (AC4/OB-3).
+            const cmdNames = [...new Set([...deps.commands, ...Object.keys(draft.commands ?? {})])];
+            const selected = await pickCommandsMulti(deps, cmdNames);
             if (selected === undefined || selected.length === 0)
                 continue;
-            const route = await editRoute(deps, selected[0], currentFor(selected[0]));
+            const routeFile = active === "default"
+                ? (draft.commands?.[selected[0]] ?? {})
+                : (draft.profiles?.[active]?.commands?.[selected[0]] ?? {});
+            const currentRoute = {
+                model: routeFile.model ?? "inherit",
+                thinking: routeFile.thinking ?? "inherit",
+            };
+            const route = await editRoute(deps, selected[0], currentRoute);
             if (route === undefined)
                 continue;
-            const nextCommands = { ...draft.commands };
-            for (const name of selected) {
-                nextCommands[name] = route;
-                warnMissingModel(deps, name, route.model ?? INHERIT);
+            if (active === "default") {
+                const nextCommands = { ...draft.commands };
+                for (const name of selected) {
+                    nextCommands[name] = route;
+                    warnMissingModel(deps, name, route.model ?? INHERIT);
+                }
+                draft = { ...draft, commands: nextCommands };
+            }
+            else {
+                const profile = draft.profiles?.[active] ?? {};
+                const nextCommands = { ...profile.commands };
+                for (const name of selected) {
+                    nextCommands[name] = route;
+                    warnMissingModel(deps, name, route.model ?? INHERIT);
+                }
+                draft = { ...draft, profiles: { ...(draft.profiles ?? {}), [active]: { ...profile, commands: nextCommands } } };
             }
-            draft = { ...draft, commands: nextCommands };
             continue;
         }
+        // Bulk clear on active profile's commands
         if (choice === prompts.bulkClear) {
-            const names = await pickCommandsMulti(deps, Object.keys(draft.commands ?? {}));
+            const cmdNames = Object.keys(profileOf(draft, active).commands ?? {});
+            const names = await pickCommandsMulti(deps, cmdNames);
             if (names === undefined || names.length === 0)
                 continue;
-            const rest = { ...draft.commands };
-            for (const name of names)
-                delete rest[name];
-            draft = { ...draft, commands: rest };
+            if (active === "default") {
+                const rest = { ...draft.commands };
+                for (const name of names)
+                    delete rest[name];
+                draft = { ...draft, commands: rest };
+            }
+            else {
+                const profile = draft.profiles?.[active] ?? {};
+                const rest = { ...(profile.commands ?? {}) };
+                for (const name of names)
+                    delete rest[name];
+                draft = { ...draft, profiles: { ...(draft.profiles ?? {}), [active]: { ...profile, commands: rest } } };
+            }
             continue;
         }
         if (choice === prompts.policy) {
@@ -154,7 +285,7 @@ export async function runSettingsConsole(deps) {
             continue;
         }
         if (choice === prompts.save) {
-            const saved = await saveScope(deps, scope, path, draft);
+            const saved = await saveScope(deps, scope, path, draft, merged);
             if (saved)
                 return { status: "saved", scope, path, file: clean(draft) };
             continue;
@@ -167,6 +298,38 @@ export async function runSettingsConsole(deps) {
  * without being read, and a scope whose file does not parse is refused so the
  * operator's own file survives (AC10, AC13).
  */
+// ---------------------------------------------------------------------------
+// Profile helpers (P5, feature 63)
+// ---------------------------------------------------------------------------
+/** The profile file for a named profile or the default. */
+function profileOf(draft, name) {
+    if (name === "default")
+        return { ...(draft.default ? { default: draft.default } : {}), ...(draft.commands ? { commands: draft.commands } : {}) };
+    return draft.profiles?.[name] ?? {};
+}
+/**
+ * Pick a profile from the list. `allowNew` adds "Name the new profile" to the
+ * options; the input must match a lowercase slug pattern.
+ */
+async function pickProfile(deps, draft, { allowNew }) {
+    const names = ["default", ...Object.keys(draft.profiles ?? {}).filter((n) => n !== "default")];
+    // "nan" is always listed (built-in unless user-defined)
+    if (!names.includes("nan"))
+        names.push("nan");
+    const options = allowNew ? [...names, prompts.newProfile] : names;
+    const picked = await pagedSelect((title, list) => deps.ui.select(title, list), prompts.profile, options);
+    if (picked === undefined)
+        return undefined;
+    if (picked === prompts.newProfile) {
+        const name = await deps.ui.input(prompts.newProfile, "lowercase slug");
+        if (name === undefined || !/^[a-z0-9][a-z0-9._-]*$/u.test(name.trim())) {
+            deps.ui.notify("Rejected: a profile name must be a lowercase slug.", "error");
+            return undefined;
+        }
+        return name.trim();
+    }
+    return picked;
+}
 async function openAScope(deps, globalPath, projectPath) {
     for (;;) {
         const label = await deps.ui.select(prompts.scope, [GLOBAL_LABEL, PROJECT_LABEL]);
@@ -439,11 +602,14 @@ function warnMissingModel(deps, target, model) {
         }
     }
 }
-function commandChoices(deps, draft) {
-    return [...new Set([...deps.commands, ...Object.keys(draft.commands ?? {})])];
-}
-async function saveScope(deps, scope, path, draft) {
+async function saveScope(deps, scope, path, draft, merged) {
     const file = clean(draft);
+    // P5: materialize recommendedModels when the nan provider is available but
+    // the key is absent — the save writes the effective value (AC11).
+    const nanAvailable = (deps.models ?? []).some((m) => m.startsWith("nan/"));
+    if (file.recommendedModels === undefined && nanAvailable) {
+        file.recommendedModels = merged.config.recommendedModels;
+    }
     const text = `${JSON.stringify(file, null, 2)}\n`;
     const problems = problemsFor(file, scope);
     if (problems.length > 0) {
@@ -477,6 +643,8 @@ function describeRouting(file) {
     const routes = [
         file.default ? `default: ${file.default.model ?? "inherit"} / ${file.default.thinking ?? "inherit"}` : "default: inherit / inherit",
         ...Object.entries(file.commands ?? {}).map(([name, route]) => `${name}: ${route.model ?? "inherit"} / ${route.thinking ?? "inherit"}`),
+        ...(file.profileOrder && file.profileOrder.length > 0 ? [`profiles: ${file.profileOrder.join(" → ")}`] : []),
+        ...(file.recommendedModels !== undefined ? [`recommended models: ${file.recommendedModels}`] : []),
         `unavailable: ${file.onUnavailableRoute ?? "stop"}`,
         `settle: ${file.onSettle ?? "keep"}`,
     ];
@@ -504,6 +672,17 @@ function clean(draft) {
         file.onUnavailableRoute = draft.onUnavailableRoute;
     if (draft.onSettle)
         file.onSettle = draft.onSettle;
+    if (draft.recommendedModels !== undefined)
+        file.recommendedModels = draft.recommendedModels;
+    if (draft.profiles && Object.keys(draft.profiles).length > 0) {
+        file.profiles = structuredClone(draft.profiles);
+    }
+    if (draft.profileOrder && draft.profileOrder.length > 0) {
+        file.profileOrder = [...draft.profileOrder];
+    }
+    if (draft.profileFallback && Object.keys(draft.profileFallback).length > 0) {
+        file.profileFallback = { ...draft.profileFallback };
+    }
     return file;
 }
 function parseFile(text, scope) {

package/dist/settings/view.d.ts

@@ -8,4 +8,6 @@ export declare const DEFAULT_ROUTE = "the default route";
  */
 export declare function routePath(target: string): string;
 /** What the operator reads when the console opens. */
-export declare function renderMergedConfig(loaded: LoadedConfig, commands: readonly string[]): string[];
+export declare function renderMergedConfig(loaded: LoadedConfig, commands: readonly string[], opts?: {
+    providerAvailable?: (provider: string) => boolean;
+}): string[];

package/dist/settings/view.js

@@ -1,6 +1,7 @@
 // src/settings/view.ts
 // The settings console's display half (AC10, SPEC S4): what is in effect right
 // now, and which files the values came from.
+import { effectiveProfileOrder } from "../config/profiles.js";
 /** The label for the unqualified route, so `default` is never mistaken for a command name. */
 export const DEFAULT_ROUTE = "the default route";
 /**
@@ -12,9 +13,15 @@ export function routePath(target) {
     return target === DEFAULT_ROUTE ? "$.default" : `$.commands.${target}`;
 }
 /** What the operator reads when the console opens. */
-export function renderMergedConfig(loaded, commands) {
+export function renderMergedConfig(loaded, commands, opts) {
+    const order = effectiveProfileOrder(loaded.config, {
+        providerAvailable: opts?.providerAvailable ?? (() => false),
+    });
     return [
         "agentic-workflow routing — what each command runs on right now",
+        `  profiles: ${order.join(" → ")}`,
+        `  active profile: ${order[0] ?? "default"}`,
+        `  recommended models: ${loaded.config.recommendedModels ? "on" : "off"}${loaded.config.recommendedModels && opts?.providerAvailable?.("nan") ? " (built-in nan profile in the chain)" : ""}`,
         ...configLines(loaded.config, commands),
         ...problems(loaded.problems),
     ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.15.3",
+  "version": "0.17.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 3.0.1
+version: 3.2.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -58,7 +58,7 @@ Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 
 ## Progressive loading — bootstrap or upgrade, never both
 
-The reference allowlist is exactly the four linked paths below. Never invent or
+The reference allowlist is exactly the five linked paths below. Never invent or
 read another `references/` path. Step 0 selects exactly one route:
 
 **Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode
@@ -69,8 +69,12 @@ or portability unless the runtime platform has no named adapter at all.
 - Bare/foreign repository: read
   [bootstrap discovery](references/BOOTSTRAP_DISCOVERY.md), complete its
   interview, then read [bootstrap write](references/BOOTSTRAP_WRITE.md).
+  Both the discovery and write routes load
+  [SERENA language servers](references/SERENA.md) for stack detection.
 - Existing agentic-workflow scaffold: read [upgrade](references/UPGRADE.md)
   only. Its additive-only rule is absolute; do not replay bootstrap.
+  The upgrade route loads [SERENA language servers](references/SERENA.md)
+  for the additive provisioning step.
 - No named adapter exists for the detected runtime platform: add
   [portability](references/PORTABILITY.md) only for that fallback. Claude Code,
   Cursor, Copilot, and OpenCode are named supported adapters; a missing adapter
@@ -99,6 +103,12 @@ 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.
 - **Never redefine the urgency label vocabulary here.** `skills/triage-issue
   /SKILL.md` is the sole owner of the `urgent`/`fix-next` names, colors, and
   apply rules — this skill only seeds those two labels into the repo; it never
@@ -178,6 +188,8 @@ 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).
 - **The closing `→ Next:` block is printed** (plus the offer to install the skills):
 
   ```

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

@@ -67,4 +67,5 @@
      means Starlight). If no, leave the block commented out —
      then reports NOT-CONFIGURED instead of guessing. Never scaffold the
      website itself.
-   - **Naming conventions** and **MCP servers**, if any.
+   - **Naming conventions**, **MCP servers**, and **Serena language servers** (see
+     [SERENA](SERENA.md) for the mapping), if any.

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

@@ -21,11 +21,17 @@
    optional: an absent document means no project invariants are declared, not
    that the scaffold failed. If retained, add its documentation-map row and
    name the project's explicit architectural-decision authority.
-6. **Propagate the unit doc template.** Ensure
+7. **Propagate the unit doc template.** Ensure
    `docs/features/_TEMPLATE/SPEC.md` exists with all 13 mandatory sections.
    This is the template used when creating new unit documents.
-
-7. **Install accepted agent safety hooks.** Keep the canonical policy and
+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.
+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
    page at `.agentic-workflow/path-protection.md`, beside the hooks — the
@@ -38,10 +44,10 @@
    an unknown payload, or an existing customized hook file becomes a residual,
    never a silent overwrite. Direct merges remain blocked; do not create a
    `.automerge` exception.
-8. **Offer the workflow skills.** Propose installing them:
+10. **Offer the workflow skills.** Propose installing them:
    `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
    the source is private). Don't install without a yes.
-9. **State that reviews are self-contained; offer optional extras.** The
+11. **State that reviews are self-contained; offer optional extras.** The
    workflow ships its **own internal review pack** (`review-code`,
    `review-security`, `review-verify`, `review-debt`, `review-design`,
    `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
@@ -51,7 +57,7 @@
    under a short "Optional review extras" note so `review-change` and
    `product-audit` run them **in addition** — never as a dependency. Don't
    install anything without a yes.
-10. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
+12. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
    two capability-gated GitHub labels `triage-issue` owns and applies
    (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
    vocabulary — this step only seeds it, never redefines it):
@@ -64,7 +70,7 @@
    forge is unavailable or the user declines forge setup, skip this step and
    list the two labels as a residual for the user to create manually later
    (never fail the whole scaffold on it).
-12. **Report.** List what was created, which placeholders still need human input,
+13. **Report.** List what was created, which placeholders still need human input,
    the companion skills recorded/installed, the urgency labels seeded (or
    skipped, with reason), and the next step:
    `discover-repository-state` → `/unit-lane` (or `workflow-status`) → catalog

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

@@ -0,0 +1,133 @@
+## Why this step exists
+
+LSP-backed navigation and verification must actually work. A project-local
+`.serena/project.yml` that pins the wrong `language_servers` silently disables
+the server, and every symbol call then times out with
+`Language server status: not initialized` (verified 2026-09-24 in this
+repository).
+
+## The convention this file owns
+
+- `.serena/project.yml` is **committed** to version control (the project's
+  config, not a dev-local override).
+- `.serena/project.local.yml` and `.serena/cache/` stay local (tool-internal
+  state).
+- The target's `.gitignore` must therefore ignore every `.serena` tree **except
+  the root `project.yml`** — the block below enforces that.
+
+## What to write into the target .gitignore
+
+When the target's `.gitignore` does not already contain the block below, append
+it (additive only — see rules below):
+
+```text
+# Ignore every .serena tree (tool-local state); version ONLY the root project
+# config. Serena's own .serena/.gitignore keeps cache and per-dev overrides local.
+**/.serena/
+!.serena/
+.serena/*
+!.serena/project.yml
+```
+
+**Rules:**
+
+- **Additive only** — append the block when it is absent.
+- If the target already ignores `.serena` wholesale (e.g. `.serena/` without
+  an `!` carve-out), **propose the narrowing** and apply it **only with consent**.
+- **Never rewrite unrelated lines.** Only touch the `.serena` block.
+- **Idempotent** — skip when the exact block (all four lines) is already
+  present.
+
+## Language servers for the detected stack
+
+Write language servers in this order: **fixed entries first** (always written,
+regardless of the target), then **detected entries** (from Step 0 signals).
+
+### Fixed entries — always written
+
+| Entry | Why always |
+|---|---|
+| `markdown` | Every scaffolded project has `docs/` and `.md` files (this workflow's own documentation is Markdown) |
+| `json` | Manifests and tool config (`package.json`, `tsconfig.json`, settings) exist in nearly every stack |
+
+### Never auto-detected rule
+
+**`markdown`, `yaml`, and `json` are never auto-detected by Serena — they must
+appear in `language_servers` explicitly, or requests for those file types fall
+back to another server and produce false positives** (e.g. TypeScript diagnostics
+on a `.yml`). Every server listed above (and `yaml` when `.yml`/`.yaml` files
+are present) is explicit-only.
+
+### Detected entries — append when present
+
+| Detected | Entry |
+|---|---|
+| `.yml` / `.yaml` files present (CI workflows, config) | `yaml` |
+| `package.json` / `tsconfig.json` (TypeScript or JavaScript) | `typescript` |
+| `pyproject.toml` / `requirements.txt` | `python` |
+| `go.mod` | `go` |
+| `Cargo.toml` | `rust` |
+| `pom.xml` / `build.gradle` | `java` |
+| `Gemfile` | `ruby` |
+| `composer.json` | `php` |
+| `CMakeLists.txt` / `Makefile` (C/C++) | `cpp` |
+| `.csproj` / `.sln` | `csharp` |
+| shell-dominant repo (`*.sh` prevalent) | `bash` |
+
+The authoritative list of valid values is Serena's own `ls_config.py`
+(`LanguageServerId`). An id Serena does not know about is silently ignored by
+Serena — **the health check below is what proves the list is correct.**
+
+## Ask first
+
+Never write `.serena/` or `.gitignore` without an explicit yes, and report
+exactly what was written. (This matches the skill's existing installation-consent
+rule.)
+
+## Health check — fail closed at the claim
+
+After activation, confirm **each listed server** initialised by asking Serena
+for the project status and verifying `Language server status: initialized` for
+every language in `language_servers`. If a server did not initialise, the
+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.**
+
+### Startup rule (critical)
+
+> **A server that fails to start must not stay listed.** One failing entry
+> disables the whole language-server manager — every symbol call for the
+> project then fails with `Language server manager is not initialized`.
+> After writing the config, the health check must confirm **every** listed
+> server started; any entry that fails is removed from `language_servers`
+> and recorded as a residual with its exact error (e.g. `markdown`: marksman
+> needs the system `libicu` package).
+
+## When a server is missing or fails
+
+`markdown`, `yaml`, and `json` servers exist but are explicit-only and
+experimental: they must be listed by hand or requests fall back and produce
+false positives.
+
+- **Missing (not listed)** → fallback server answers → false positives for that
+  file type (e.g. TypeScript diagnostics on a `.yml`).
+- **Failing (listed but broken)** → whole manager down → every symbol call
+  fails with `Language server manager is not initialized`. Remediation: remove
+  the entry from `language_servers` and record the residual (e.g. `markdown`:
+  marksman needs the system `libicu` package).
+
+Document verification (schema rules like required sections/columns) stays a
+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
+
+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.
+
+## Degraded path
+
+Serena unavailable → warn once, continue, and record the absence in the unit's
+evidence. **Never block a run on it.**