@cratis/pi 7.93.0 → 7.95.0

package/README.md

@@ -33,6 +33,20 @@ yields to the managed installation to avoid duplicate resources and hooks. The P
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
 
+## MCP servers from the corpus
+
+The packaged `cratis-mcp` extension starts every stdio server declared in
+`mcp-servers.json` whose `profiles` intersect the profiles listed explicitly in
+`.cratis/ai.json` (a profile reached only through another profile's `composes` does
+not start a server; Screenplay keeps its composed selection) (for
+example `codescene` for `cratis/codescene`, `playwright` for `cratis/playwright`).
+Each server gets its own connection, so one failing to start never stops the others,
+and its tools are namespaced by server id (`playwright_browser_navigate`). The
+`command`, `args` and optional literal `env` are used verbatim, without a shell. A
+malformed selected server is skipped with one notice; set
+`mcpServers.<id>.enabled` to `false` in `.cratis/ai.json` to opt a server out.
+`capabilities.json` beside the extension declares this behavior to the Cratis CLI.
+
 ## Screenplay MCP tools
 
 The packaged `cratis-mcp` extension starts the Screenplay MCP server

package/package/corpus/harnesses/copilot/instructions/discoverability.instructions.md

@@ -0,0 +1,34 @@
+---
+applyTo: "**/Documentation/**/*.md,**/Documentation/**/*.mdx,**/src/pages/**/*.astro,**/src/pages/**/*.md,**/src/pages/**/*.mdx,**/src/pages/**/*.html,**/src/content/**/*.md,**/src/content/**/*.mdx"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+  - "**/src/pages/**/*.astro"
+  - "**/src/pages/**/*.md"
+  - "**/src/pages/**/*.mdx"
+  - "**/src/pages/**/*.html"
+  - "**/src/content/**/*.md"
+  - "**/src/content/**/*.mdx"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Writing content that people and assistants can find
+
+Readability comes first. If a change for search engines or AI assistants makes a page harder to read, drop the change. Voice, structure and examples stay with [writing-cratis-docs.md](./writing-cratis-docs.instructions.md), [editing-cratis-docs.md](./editing-cratis-docs.instructions.md) and [documentation-structure-and-formatting.md](./documentation-structure-and-formatting.instructions.md); this rule adds only what they do not cover. Before publishing a page, post or package, use **cratis-discoverability**.
+
+## Every page, post and README
+
+- **Define first, where a definition belongs.** Landing pages, product index pages, glossary entries, READMEs and package descriptions open with one self-contained sentence: "X is a <category> for <audience> that <does>."
+- **Docs tutorials, getting-started pages and explanations follow [writing-cratis-docs.md](./writing-cratis-docs.instructions.md)**: scenario first, pain before relief. Their answer-first, self-contained definition goes in the frontmatter `description`, which serves search and AI. Where it reads naturally, one definition sentence may follow the opening scenario. writing-cratis-docs wins on voice and structure.
+- **Title and description are written by hand.** Title with the distinguishing term first: 50-60 characters for blog and landing pages, 20-60 for docs and reference pages; a README H1 that is the product name is fine. Description is one sentence of 60-160 characters, never over 160, and not a copy of the title or of another page's description.
+- **Name things one way.** The first mention is the full name ("Cratis Chronicle"), later mentions may shorten it. Use the canonical names in the **cratis-discoverability** entity reference, and do not call the platform "Cratis.io".
+- **Links name their destination.** Link text says what is behind it. Outside the docs site, link docs with the absolute canonical host `https://www.cratis.io/...`, never the bare `cratis.io`.
+- **Images carry alt text.** Describe the content. Use an empty `alt=""` only for decoration.
+- **No keyword stuffing, no filler for length, no text hidden from readers.** A page is done when it is complete.
+
+## Sites and packages
+
+- Public pages need a canonical link, one `<h1>`, Open Graph tags, valid JSON-LD that describes visible content, a sitemap entry and a `robots.txt` that allows crawling. Add no new `HowTo` or `FAQPage` markup; keep the visible Q&A.
+- `llms.txt` is an optional index. Never claim it improves ranking. See **cratis-llm-friendly-documentation**.
+- Package metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
+- State only facts the repository supports: versions, licenses, limits. The claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md` still applies.

package/package/corpus/harnesses/pi/extensions/cratis-mcp/CorpusServer.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A validated stdio server from the corpus descriptor; command, args and env are used verbatim. */
+export interface CorpusServer {
+    id: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
+
+/** The servers to start for a project plus the explicit messages for everything skipped. */
+export interface ServerSelection {
+    servers: CorpusServer[];
+    messages: string[];
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/ServerBridge.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { object } from './configuration.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startServer } from './process.ts';
+import { discoverServer, mapServerResult, type ServerCatalog } from './serverProtocol.ts';
+import { selectedCorpusServers } from './servers.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+function withDeadline<T>(work: Promise<T>, milliseconds: number, id: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`MCP server '${id}' did not become ready within ${milliseconds} ms.`)), milliseconds);
+        timer.unref();
+    });
+    work.catch(() => { /* The deadline already reported the outcome; the disposed connection rejects the abandoned request. */ });
+    return Promise.race([work, expired]).finally(() => clearTimeout(timer));
+}
+
+/** Bridge every selected corpus server except Screenplay: one connection each, isolated failures, tools namespaced by server id. */
+export interface ServerBridge {
+    refresh(context: ExtensionContext, newSession: boolean): Promise<void>;
+    dispose(): void;
+}
+
+export function createServerBridge(pi: ExtensionAPI, corpus: string, connect: (project: string, server: CorpusServer) => StdioConnection = startServer, deadlineMilliseconds = 15_000): ServerBridge {
+    const connections = new Map<string, StdioConnection>();
+    const registered = new Set<string>();
+    const paused = new Set<string>();
+    let selectionKey: string | undefined;
+
+    const notify = (context: ExtensionContext, messages: string[]): void => {
+        if (context.hasUI) messages.forEach(message => context.ui.notify(message, 'warning'));
+    };
+    const deactivate = (): void => {
+        const active = pi.getActiveTools();
+        active.filter(name => registered.has(name)).forEach(name => paused.add(name));
+        if (active.some(name => registered.has(name))) pi.setActiveTools(active.filter(name => !registered.has(name)));
+    };
+    const dispose = (): void => {
+        connections.forEach(connection => connection.dispose());
+        connections.clear();
+        deactivate();
+    };
+    interface Started { server: CorpusServer; connection: StdioConnection; catalog?: ServerCatalog; messages: string[] }
+    /** Connect and discover only; registration happens afterwards in selection order so name claims are deterministic. */
+    const start = async (context: ExtensionContext, server: CorpusServer): Promise<Started> => {
+        const connection = connect(context.cwd, server);
+        connections.set(server.id, connection);
+        try {
+            const catalog = await withDeadline(discoverServer(connection, server.id), deadlineMilliseconds, server.id);
+            if (connections.get(server.id) !== connection || connection.stopped) throw new Error(`MCP server '${server.id}' session ended during discovery.`);
+            return { server, connection, catalog, messages: [...catalog.messages] };
+        } catch (error) {
+            connection.dispose();
+            if (connections.get(server.id) === connection) connections.delete(server.id);
+            return { server, connection, messages: [`MCP server '${server.id}' is unavailable: ${error instanceof Error ? error.message : String(error)}`] };
+        }
+    };
+    const register = ({ server, connection, catalog, messages }: Started, claimed: Set<string>): void => {
+        const existing = new Set(pi.getAllTools().map(tool => tool.name));
+        for (const tool of catalog?.tools ?? []) {
+            if (claimed.has(tool.nativeName) || (existing.has(tool.nativeName) && !registered.has(tool.nativeName))) {
+                messages.push(`MCP server '${server.id}' tool '${tool.name}' was skipped: '${tool.nativeName}' conflicts with another tool.`);
+                continue;
+            }
+            claimed.add(tool.nativeName);
+            pi.registerTool({
+                name: tool.nativeName,
+                label: `${server.id} ${tool.name}`,
+                description: tool.description,
+                parameters: tool.parameters,
+                executionMode: 'sequential',
+                async execute(_toolCallId, parameters, signal) {
+                    if (connections.get(server.id) !== connection || connection.stopped || !pi.getActiveTools().includes(tool.nativeName)) {
+                        throw new Error(`MCP server '${server.id}' is unavailable in this session.`);
+                    }
+                    if (!object(parameters)) throw new Error('MCP arguments must be an object.');
+                    const result = mapServerResult(await connection.request('tools/call', { name: tool.name, arguments: parameters }, signal), server.id);
+                    if (result.details.isError) throw new Error(result.content.map(part => part.type === 'text' ? part.text : '').join('\n') || `MCP server '${server.id}' reported a failed tool call.`);
+                    return result;
+                },
+            });
+        }
+    };
+    const refresh = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        let selection: ReturnType<typeof selectedCorpusServers>;
+        try { selection = selectedCorpusServers(context.cwd, corpus); }
+        catch (error) { dispose(); selectionKey = undefined; throw error; }
+        const key = JSON.stringify(selection);
+        if (!newSession && key === selectionKey) return;
+        const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
+        const oldNames = new Set(registered);
+        dispose();
+        selectionKey = key;
+        const messages = [...selection.messages];
+        const claimed = new Set<string>();
+        // Servers start in parallel; a slow or hung one is abandoned at its own deadline and never delays the others.
+        const outcomes = await Promise.all(selection.servers.map(server => start(context, server)));
+        for (const outcome of outcomes) { register(outcome, claimed); messages.push(...outcome.messages); }
+        claimed.forEach(name => registered.add(name));
+        // Never re-enable a user-disabled tool. SDK allow/exclude restrictions still filter registration.
+        const next = pi.getActiveTools().filter(name => !registered.has(name) || (claimed.has(name) && (!oldNames.has(name) || previouslyActive.has(name))));
+        for (const name of claimed) if (oldNames.has(name) && previouslyActive.has(name)) next.push(name);
+        pi.setActiveTools([...new Set(next)]);
+        paused.clear();
+        notify(context, messages);
+    };
+
+    return { refresh, dispose: () => { dispose(); selectionKey = undefined; } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/StdioConnection.ts

@@ -15,7 +15,7 @@ export class StdioConnection {
     private _termination?: ReturnType<typeof setTimeout>;
     private readonly _maximumBytes = 8 * 1024 * 1024;
 
-    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000) {
+    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000, private readonly _label = 'Screenplay', private readonly _tolerant = false) {
         _child.stdout.on('data', this.receive);
         _child.stdout.on('end', this.ended);
         _child.stdout.on('error', this.streamFailed);
@@ -32,22 +32,22 @@ export class StdioConnection {
 
     async request(method: string, params: Record<string, unknown>, signal?: AbortSignal, mutation = false): Promise<unknown> {
         if (this._failure) throw this._failure;
-        if (signal?.aborted) throw new ConnectionFailure('Screenplay request cancelled before sending.');
-        if (this._pending) throw new ConnectionFailure('Screenplay is busy; parallel requests are not queued.');
+        if (signal?.aborted) throw new ConnectionFailure(`${this._label} request cancelled before sending.`);
+        if (this._pending) throw new ConnectionFailure(`${this._label} is busy; parallel requests are not queued.`);
         const id = ++this._sequence;
         const line = this.encode({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve, reject) => {
-            const abort = () => this.stop('Screenplay request cancelled after sending.');
-            const timer = setTimeout(() => this.stop('Screenplay request timed out.'), this._timeout);
+            const abort = () => this.stop(`${this._label} request cancelled after sending.`);
+            const timer = setTimeout(() => this.stop(`${this._label} request timed out.`), this._timeout);
             this._pending = {
                 id, mutation, resolve, reject,
                 cleanup: () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); },
             };
             signal?.addEventListener('abort', abort, { once: true });
             try {
-                this._child.stdin.write(line, error => { if (error) this.stop('Screenplay input pipe failed.'); });
+                this._child.stdin.write(line, error => { if (error) this.stop(`${this._label} input pipe failed.`); });
             } catch {
-                this.stop('Screenplay input pipe failed.');
+                this.stop(`${this._label} input pipe failed.`);
             }
         });
     }
@@ -55,18 +55,18 @@ export class StdioConnection {
     notify(method: string): void {
         if (this._failure) throw this._failure;
         try {
-            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop('Screenplay notification failed.'); });
+            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop(`${this._label} notification failed.`); });
         } catch {
-            this.stop('Screenplay notification failed.');
+            this.stop(`${this._label} notification failed.`);
             throw this._failure;
         }
     }
 
-    dispose(): void { this.stop('Screenplay session closed.'); }
+    dispose(): void { this.stop(`${this._label} session closed.`); }
 
     private encode(value: unknown): string {
         const line = `${JSON.stringify(value)}\n`;
-        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure('Screenplay request exceeds the 8 MiB transport limit.');
+        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure(`${this._label} request exceeds the 8 MiB transport limit.`);
         return line;
     }
 
@@ -82,7 +82,7 @@ export class StdioConnection {
                 this._buffer = Buffer.alloc(0);
                 this.accept(line);
             } catch {
-                this.stop('Screenplay returned invalid UTF-8 protocol data.');
+                this.stop(`${this._label} returned invalid UTF-8 protocol data.`);
             }
             if (this.stopped) return;
             start = index + 1;
@@ -92,7 +92,7 @@ export class StdioConnection {
 
     private append(chunk: Buffer): boolean {
         if (this._buffer.length + chunk.length > this._maximumBytes) {
-            this.stop('Screenplay response exceeds the 8 MiB transport limit.');
+            this.stop(`${this._label} response exceeds the 8 MiB transport limit.`);
             return false;
         }
         this._buffer = Buffer.concat([this._buffer, chunk]);
@@ -103,6 +103,13 @@ export class StdioConnection {
         try {
             const message: unknown = JSON.parse(line);
             if (!object(message) || message.jsonrpc !== '2.0') throw new Error();
+            if ('method' in message && this._tolerant) {
+                // Third-party servers may notify or ask; this client offers no capabilities, so refuse requests and ignore notifications.
+                if ('id' in message && typeof message.method === 'string') {
+                    this._child.stdin.write(this.encode({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } }));
+                }
+                return;
+            }
             if ('method' in message) {
                 // This pinned server does not send requests or changing tool lists.
                 throw new Error();
@@ -113,14 +120,14 @@ export class StdioConnection {
             this._pending = undefined;
             pending.cleanup();
             if (object(message.error)) {
-                pending.reject(new ConnectionFailure(`Screenplay protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
+                pending.reject(new ConnectionFailure(`${this._label} protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
                 // A server failure during mutation is not evidence that nothing was written.
-                if (pending.mutation) this.stop('Screenplay mutation failed with a protocol error.', true);
+                if (pending.mutation) this.stop(`${this._label} mutation failed with a protocol error.`, true);
             } else {
                 pending.resolve(message.result);
             }
         } catch {
-            this.stop('Screenplay returned malformed or unexpected JSON-RPC.');
+            this.stop(`${this._label} returned malformed or unexpected JSON-RPC.`);
         }
     }
 
@@ -145,11 +152,13 @@ export class StdioConnection {
     }
 
     private readonly drain = (): void => { /* Drain server stderr without exposing it as a protocol result. */ };
-    private readonly ended = (): void => this.stop('Screenplay output closed before session shutdown.');
-    private readonly streamFailed = (): void => this.stop('Screenplay stdio failed.');
-    private readonly spawnFailed = (): void => this.stop('Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
+    private readonly ended = (): void => this.stop(`${this._label} output closed before session shutdown.`);
+    private readonly streamFailed = (): void => this.stop(`${this._label} stdio failed.`);
+    private readonly spawnFailed = (): void => this.stop(this._label !== 'Screenplay'
+        ? `Cannot launch the ${this._label} MCP server command. Check that it is installed; this extension never downloads a runtime.`
+        : 'Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
     private readonly closed = (): void => {
-        this.stop('Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
+        this.stop(this._label !== 'Screenplay' ? `${this._label} process exited.` : 'Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
         clearTimeout(this._termination);
         this._child.stdout.removeListener('error', this.streamFailed);
         this._child.stdin.removeListener('error', this.streamFailed);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/capabilities.json

@@ -0,0 +1 @@
+{ "servers": "selected-profiles" }

package/package/corpus/harnesses/pi/extensions/cratis-mcp/configuration.ts

@@ -8,7 +8,7 @@ export function object(value: unknown): value is Record<string, unknown> {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function readJson(path: string): Record<string, unknown> {
+export function readJson(path: string): Record<string, unknown> {
     if (lstatSync(path).size > 1024 * 1024) throw new Error(`Cratis configuration is too large: ${path}`);
     const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
     if (!object(value)) throw new Error(`Expected a JSON object: ${path}`);
@@ -21,6 +21,10 @@ function strings(value: unknown): string[] {
     return value;
 }
 
+export function supportedSchema(version: unknown): boolean {
+    return typeof version === 'string' && /^1\.\d+$/.test(version);
+}
+
 /** Resolve through existing directories only, refusing every source-root symlink. Never creates a directory. */
 export function physicalRoot(project: string, root: string): string {
     if (!root || isAbsolute(root) || root.includes('\0')) throw new Error('Screenplay root must be a nonempty project-relative directory.');
@@ -45,8 +49,16 @@ export function physicalRoot(project: string, root: string): string {
     return current;
 }
 
-/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
-export function selectedServer(project: string, corpus: string) {
+export interface ProfileResolution {
+    configuration: Record<string, unknown>;
+    selected: Set<string>;
+    /** Profiles listed directly in `.cratis/ai.json`, before any `composes` expansion. */
+    explicit: Set<string>;
+    nonApplicationSelection: boolean;
+}
+
+/** Resolve the selected profiles (after `composes` expansion) from the project's `.cratis/ai.json`. */
+export function resolveProfiles(project: string, corpus: string): ProfileResolution | undefined {
     let configuration: Record<string, unknown>;
     try {
         configuration = readJson(join(project, '.cratis', 'ai.json'));
@@ -86,7 +98,14 @@ export function selectedServer(project: string, corpus: string) {
         strings(profile.composes).forEach(child => select(child, false, applicationPath));
     };
     requested.forEach(id => select(id, true));
-    if (!selected.has('cratis/screenplay')) return undefined;
+    return { configuration, selected, explicit: new Set(requested), nonApplicationSelection };
+}
+
+/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
+export function selectedServer(project: string, corpus: string) {
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution?.selected.has('cratis/screenplay')) return undefined;
+    const { configuration, nonApplicationSelection } = resolution;
     const overrides = configuration.mcpServers;
     if (overrides !== undefined && !object(overrides)) throw new Error('Invalid mcpServers configuration.');
     const screenplay = object(overrides) ? overrides.screenplay : undefined;
@@ -94,7 +113,9 @@ export function selectedServer(project: string, corpus: string) {
     if (object(screenplay) && screenplay.enabled === false) return undefined;
     if (object(screenplay) && screenplay.enabled !== undefined && screenplay.enabled !== true) throw new Error('Screenplay MCP enabled must be a boolean.');
     const descriptor = readJson(join(corpus, 'mcp-servers.json'));
-    if (descriptor.schemaVersion !== '1.0' || !Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
+    // Any 1.x descriptor is accepted; another major loads no corpus MCP servers (the generic bridge reports it once).
+    if (!supportedSchema(descriptor.schemaVersion)) return undefined;
+    if (!Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
     const servers = descriptor.servers.filter(server => object(server) && server.id === 'screenplay');
     if (servers.length !== 1 || !object(servers[0])) throw new Error('Expected exactly one Screenplay MCP descriptor.');
     const server = servers[0];

package/package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts

@@ -7,8 +7,10 @@ import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConnectionFailure } from './ConnectionFailure.ts';
 import { object, selectedServer } from './configuration.ts';
-import { startConnection, supportsNoModelStartup } from './process.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startConnection, startServer, supportsNoModelStartup } from './process.ts';
 import { discover, failedResult, mapResult } from './protocol.ts';
+import { createServerBridge } from './ServerBridge.ts';
 import type { DiscoveredTool } from './DiscoveredTool.ts';
 import type { StdioConnection } from './StdioConnection.ts';
 
@@ -16,7 +18,8 @@ const extensionDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCorpus = resolve(extensionDirectory, '..', '..', '..', '..');
 
 /** Native tools go through Pi's tool_call restrictions and normal execution/result pipeline. */
-export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup): void {
+export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup, connectServer: (project: string, server: CorpusServer) => StdioConnection = startServer): void {
+    const servers = createServerBridge(pi, corpus, connectServer);
     let connection: StdioConnection | undefined;
     let selectionKey: string | undefined;
     let attempted = false;
@@ -149,9 +152,15 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         }
     };
 
-    pi.on('session_start', (_event, context) => refresh(context, true));
-    pi.on('before_agent_start', async (_event, context) => { await refresh(context); });
-    pi.on('session_shutdown', () => { dispose(); failures.clear(); });
+    // Screenplay and the other corpus servers fail independently; the first failure is surfaced after both ran.
+    const refreshAll = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        const outcomes = await Promise.allSettled([refresh(context, newSession), servers.refresh(context, newSession)]);
+        const failed = outcomes.find(outcome => outcome.status === 'rejected');
+        if (failed) throw failed.reason;
+    };
+    pi.on('session_start', (_event, context) => refreshAll(context, true));
+    pi.on('before_agent_start', async (_event, context) => { await refreshAll(context, false); });
+    pi.on('session_shutdown', () => { dispose(); servers.dispose(); failures.clear(); });
     pi.on('tool_result', event => {
         if (!registered.has(event.toolName)) return;
         const failure = failures.get(event.toolCallId);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { execFile, spawn } from 'node:child_process';
+import type { CorpusServer } from './CorpusServer.ts';
 import { StdioConnection } from './StdioConnection.ts';
 
 /** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
@@ -43,3 +44,14 @@ export function startConnection(project: string, launch: typeof spawn = spawn):
         windowsHide: true,
     }));
 }
+
+/** Launch a corpus server verbatim (no shell, no interpolation): the default environment plus its declared literal env only. */
+export function startServer(project: string, server: CorpusServer, launch: typeof spawn = spawn): StdioConnection {
+    return new StdioConnection(launch(server.command, server.args, {
+        cwd: project,
+        env: { ...childEnvironment(), ...server.env },
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    }), 30_000, server.id, true);
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/serverProtocol.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { TSchema } from 'typebox';
+import { object } from './configuration.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+/** A tool of a corpus server other than Screenplay, exposed under a name namespaced by the server id. */
+export interface ServerTool {
+    name: string;
+    nativeName: string;
+    description: string;
+    parameters: TSchema;
+}
+
+export interface ServerCatalog {
+    tools: ServerTool[];
+    messages: string[];
+}
+
+const maximumTools = 128;
+const maximumPages = 8;
+const maximumNativeNameLength = 64;
+const maximumDescriptionLength = 4 * 1024;
+const maximumSchemaLength = 64 * 1024;
+const maximumImageLength = 2 * 1024 * 1024;
+const imageTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+/** Initialize and list tools; tools that cannot be exposed safely are skipped with a message rather than failing the server. */
+export async function discoverServer(connection: StdioConnection, id: string): Promise<ServerCatalog> {
+    const initialized = await connection.request('initialize', {
+        protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'cratis.pi', version: '1.0.0' },
+    });
+    if (!object(initialized) || !object(initialized.capabilities) || !object(initialized.capabilities.tools)) {
+        throw new Error(`MCP server '${id}' did not advertise tool support.`);
+    }
+    connection.notify('notifications/initialized');
+    const listed: unknown[] = [];
+    let cursor: unknown;
+    for (let page = 0; page < maximumPages; page++) {
+        const response = await connection.request('tools/list', cursor === undefined ? {} : { cursor });
+        if (!object(response) || !Array.isArray(response.tools)) throw new Error(`MCP server '${id}' returned an invalid tool list.`);
+        listed.push(...response.tools);
+        if (listed.length > maximumTools) throw new Error(`MCP server '${id}' exposes more than ${maximumTools} tools.`);
+        cursor = response.nextCursor;
+        if (cursor === undefined) break;
+        if (typeof cursor !== 'string') throw new Error(`MCP server '${id}' returned an invalid pagination cursor.`);
+    }
+    const catalog: ServerCatalog = { tools: [], messages: [] };
+    const names = new Set<string>();
+    for (const tool of listed) {
+        const name = object(tool) ? tool.name : undefined;
+        if (!object(tool) || typeof name !== 'string' || !name || !object(tool.inputSchema) || tool.inputSchema.type !== 'object' ||
+            (tool.description !== undefined && typeof tool.description !== 'string')) {
+            catalog.messages.push(`MCP server '${id}' has a tool with an invalid name or input schema; it was skipped.`);
+            continue;
+        }
+        if (JSON.stringify(tool.inputSchema).length > maximumSchemaLength || ((tool.description as string | undefined)?.length ?? 0) > maximumDescriptionLength) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its description or input schema is too large.`);
+            continue;
+        }
+        const nativeName = `${id}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`;
+        if (nativeName.length > maximumNativeNameLength || names.has(nativeName)) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its namespaced name is too long or not unique.`);
+            continue;
+        }
+        names.add(nativeName);
+        catalog.tools.push({ name, nativeName, description: (tool.description as string | undefined) ?? '', parameters: tool.inputSchema as TSchema });
+    }
+    if (!catalog.tools.length) throw new Error(`MCP server '${id}' exposes no usable tools.`);
+    return catalog;
+}
+
+/** Map an MCP result to Pi content. Server-reported errors throw so Pi marks the call failed. */
+export function mapServerResult(result: unknown, id: string) {
+    if (!object(result) || !Array.isArray(result.content) || (result.isError !== undefined && typeof result.isError !== 'boolean')) {
+        throw new Error(`Malformed MCP result from '${id}'.`);
+    }
+    const content = result.content.map((part: unknown) => {
+        if (object(part) && part.type === 'text' && typeof part.text === 'string') return { type: 'text' as const, text: part.text };
+        if (object(part) && part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') {
+            if (!imageTypes.has(part.mimeType) || part.data.length > maximumImageLength) return { type: 'text' as const, text: `[image omitted: unsupported type or larger than ${maximumImageLength / 1024 / 1024} MiB]` };
+            return { type: 'image' as const, data: part.data, mimeType: part.mimeType };
+        }
+        return { type: 'text' as const, text: `[unsupported ${object(part) ? String(part.type) : 'unknown'} content omitted]` };
+    });
+    const maximumCharacters = 32 * 1024;
+    const bounded = content.map(part => part.type === 'text' && part.text.length > maximumCharacters
+        ? { ...part, text: `${part.text.slice(0, maximumCharacters)}\n[display truncated]` }
+        : part);
+    return { content: bounded, details: { isError: result.isError === true, structuredContent: result.structuredContent } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/servers.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { join } from 'node:path';
+import { object, readJson, resolveProfiles, supportedSchema } from './configuration.ts';
+import type { CorpusServer, ServerSelection } from './CorpusServer.ts';
+
+const validId = /^[A-Za-z0-9_-]+$/;
+
+function isSelected(entry: Record<string, unknown>, selected: Set<string>): boolean {
+    return Array.isArray(entry.profiles) && entry.profiles.some(profile => typeof profile === 'string' && selected.has(profile));
+}
+
+function problem(entry: Record<string, unknown>): string | undefined {
+    if (typeof entry.id !== 'string' || !validId.test(entry.id)) return 'the id must match ^[A-Za-z0-9_-]+$';
+    if (entry.transport !== 'stdio') return 'only the stdio transport is supported';
+    if (typeof entry.command !== 'string' || !entry.command) return 'the command is missing or empty';
+    if (!Array.isArray(entry.args) || !entry.args.every(argument => typeof argument === 'string')) return 'args must be an array of strings';
+    if (entry.env !== undefined && (!object(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
+        return 'env must be an object of literal string values';
+    }
+    return undefined;
+}
+
+/** `mcpServers.<id>.enabled`: false opts out, a non-boolean is an error for that server only. */
+function optOut(overrides: Record<string, unknown>, id: string): 'enabled' | 'disabled' | string {
+    const override = overrides[id];
+    if (override === undefined) return 'enabled';
+    if (!object(override)) return 'the mcpServers configuration must be an object';
+    if (override.enabled === undefined || override.enabled === true) return 'enabled';
+    return override.enabled === false ? 'disabled' : 'mcpServers enabled must be a boolean';
+}
+
+/** Select every stdio server whose profiles intersect the explicitly listed profiles (never composed ones), except Screenplay which keeps its own path. */
+export function selectedCorpusServers(project: string, corpus: string): ServerSelection {
+    const selection: ServerSelection = { servers: [], messages: [] };
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution) return selection;
+    const descriptor = readJson(join(corpus, 'mcp-servers.json'));
+    if (!supportedSchema(descriptor.schemaVersion)) {
+        selection.messages.push(`Cratis MCP descriptor schemaVersion '${String(descriptor.schemaVersion)}' is not supported; no corpus MCP servers were loaded.`);
+        return selection;
+    }
+    if (!Array.isArray(descriptor.servers)) {
+        selection.messages.push('Cratis MCP descriptor has no servers list; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const overrides = resolution.configuration.mcpServers;
+    if (overrides !== undefined && !object(overrides)) {
+        selection.messages.push('Invalid mcpServers configuration; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const entries = descriptor.servers.filter(object);
+    const counts = new Map<unknown, number>();
+    entries.forEach(entry => counts.set(entry.id, (counts.get(entry.id) ?? 0) + 1));
+    const reported = new Set<unknown>();
+    for (const entry of entries) {
+        if (entry.id === 'screenplay') continue;
+        // An entry without profiles can never be selected, so it is ignored like any other unselected entry.
+        if (!isSelected(entry, resolution.explicit)) continue;
+        const label = `MCP server '${String(entry.id)}'`;
+        if (counts.get(entry.id)! > 1) {
+            if (!reported.has(entry.id)) selection.messages.push(`${label} was skipped: the descriptor declares the id more than once.`);
+            reported.add(entry.id);
+            continue;
+        }
+        const invalid = problem(entry);
+        if (invalid) { selection.messages.push(`${label} was skipped: ${invalid}.`); continue; }
+        const id = entry.id as string;
+        const state = object(overrides) ? optOut(overrides, id) : 'enabled';
+        if (state === 'disabled') continue;
+        if (state !== 'enabled') { selection.messages.push(`${label} was skipped: ${state}.`); continue; }
+        selection.servers.push({ id, command: entry.command as string, args: entry.args as string[], env: { ...(entry.env as Record<string, string> | undefined) } });
+    }
+    return selection;
+}

package/package/corpus/hooks/scripts/cratis-patterns.json

@@ -87,6 +87,30 @@
             "paths": ["**/*.ts", "**/*.tsx"],
             "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/wwwroot/**", "**/obj/**", "**/bin/**"],
             "message": "Cratis Components 4 has no PrimeReact underneath — a `primereact/dialog` import is a leftover from Components 3. Use `CommandDialog` from `@cratis/components/CommandDialog` or `Dialog` from `@cratis/components/Dialogs`."
+        },
+        {
+            "id": "cratis-apex-docs-link",
+            "rule": "discoverability.md — canonical links",
+            "pattern": "https?://cratis\\.io([/)\"' <]|$)",
+            "paths": ["**/*.md", "**/*.mdx", "**/*.html", "**/*.astro"],
+            "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/obj/**", "**/bin/**", "**/.ai-work/**"],
+            "message": "Discoverability (advisory): the docs host is `https://www.cratis.io`. Link the canonical host, not the bare `cratis.io`."
+        },
+        {
+            "id": "cratis-empty-image-alt",
+            "rule": "discoverability.md — images carry alt text",
+            "pattern": "!\\[\\]\\(",
+            "paths": ["**/*.md", "**/*.mdx"],
+            "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/obj/**", "**/bin/**", "**/.ai-work/**"],
+            "message": "Discoverability (advisory): an image with empty alt text. Describe the content, or keep it empty only when the image is purely decorative."
+        },
+        {
+            "id": "cratis-package-url-github-only",
+            "rule": "discoverability.md — package metadata",
+            "pattern": "<PackageProjectUrl>[[:space:]]*https?://github\\.com",
+            "paths": ["**/*.csproj", "**/*.props"],
+            "exclude_paths": ["**/node_modules/**", "**/obj/**", "**/bin/**"],
+            "message": "Discoverability (advisory): `PackageProjectUrl` should point at the product's docs page `https://www.cratis.io/<product>/`, not only at GitHub."
         }
     ]
 }

package/package/corpus/prompts/pre-publish-check.prompt.md

@@ -0,0 +1,26 @@
+---
+agent: agent
+description: "Run the discoverability check on content about to be published."
+---
+
+# Pre-publish check
+
+Run the discoverability check on what is about to be published: a docs page, blog
+post, landing page, README or package metadata. Follow
+`.cratis/ai/rules/discoverability.md` and invoke **cratis-discoverability**.
+
+## Identify the content
+
+Find the files in the change, the content type of each, and the owning source (never
+a synced copy). Ask only when the content type is unclear.
+
+## Check and fix
+
+Apply the skill's checks for each content type to the draft: opening definition,
+title and description, canonical names, canonical `https://www.cratis.io/...` links,
+alt text and, for sites and packages, the structured data and metadata. Make the
+fixes in the owning files. Where a fix would hurt readability, keep the text and
+report it. For a built site, run the skill's checker on the build output.
+
+Report what changed, what was left alone and why, and any check that could not run.
+Publishing, merging and releasing stay with a person.

package/package/corpus/rules/discoverability.md

@@ -0,0 +1,33 @@
+---
+applyTo: "**/Documentation/**/*.md,**/Documentation/**/*.mdx,**/src/pages/**/*.astro,**/src/pages/**/*.md,**/src/pages/**/*.mdx,**/src/pages/**/*.html,**/src/content/**/*.md,**/src/content/**/*.mdx"
+paths:
+  - "**/Documentation/**/*.md"
+  - "**/Documentation/**/*.mdx"
+  - "**/src/pages/**/*.astro"
+  - "**/src/pages/**/*.md"
+  - "**/src/pages/**/*.mdx"
+  - "**/src/pages/**/*.html"
+  - "**/src/content/**/*.md"
+  - "**/src/content/**/*.mdx"
+---
+
+# Writing content that people and assistants can find
+
+Readability comes first. If a change for search engines or AI assistants makes a page harder to read, drop the change. Voice, structure and examples stay with [writing-cratis-docs.md](./writing-cratis-docs.md), [editing-cratis-docs.md](./editing-cratis-docs.md) and [documentation-structure-and-formatting.md](./documentation-structure-and-formatting.md); this rule adds only what they do not cover. Before publishing a page, post or package, use **cratis-discoverability**.
+
+## Every page, post and README
+
+- **Define first, where a definition belongs.** Landing pages, product index pages, glossary entries, READMEs and package descriptions open with one self-contained sentence: "X is a <category> for <audience> that <does>."
+- **Docs tutorials, getting-started pages and explanations follow [writing-cratis-docs.md](./writing-cratis-docs.md)**: scenario first, pain before relief. Their answer-first, self-contained definition goes in the frontmatter `description`, which serves search and AI. Where it reads naturally, one definition sentence may follow the opening scenario. writing-cratis-docs wins on voice and structure.
+- **Title and description are written by hand.** Title with the distinguishing term first: 50-60 characters for blog and landing pages, 20-60 for docs and reference pages; a README H1 that is the product name is fine. Description is one sentence of 60-160 characters, never over 160, and not a copy of the title or of another page's description.
+- **Name things one way.** The first mention is the full name ("Cratis Chronicle"), later mentions may shorten it. Use the canonical names in the **cratis-discoverability** entity reference, and do not call the platform "Cratis.io".
+- **Links name their destination.** Link text says what is behind it. Outside the docs site, link docs with the absolute canonical host `https://www.cratis.io/...`, never the bare `cratis.io`.
+- **Images carry alt text.** Describe the content. Use an empty `alt=""` only for decoration.
+- **No keyword stuffing, no filler for length, no text hidden from readers.** A page is done when it is complete.
+
+## Sites and packages
+
+- Public pages need a canonical link, one `<h1>`, Open Graph tags, valid JSON-LD that describes visible content, a sitemap entry and a `robots.txt` that allows crawling. Add no new `HowTo` or `FAQPage` markup; keep the visible Q&A.
+- `llms.txt` is an optional index. Never claim it improves ranking. See **cratis-llm-friendly-documentation**.
+- Package metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
+- State only facts the repository supports: versions, licenses, limits. The claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md` still applies.

package/package/corpus/rules/general.md

@@ -131,6 +131,7 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | C# / TypeScript style and code-quality principles | `csharp.md`, `typescript.md`, `code-quality.md`, `code-quality.csharp.md`, `code-quality.typescript.md` |
 | Kotlin / Java / Elixir style; Orleans grains; reactors; GitHub Actions workflows | `kotlin.md`, `java.md`, `elixir.md`, `orleans.md`, `reactors.md`, `github-actions.md` |
 | Documentation pages (`Documentation/`): structure, voice, examples, editing | `documentation.md`, `documentation-structure-and-formatting.md`, `writing-cratis-docs.md`, `editing-cratis-docs.md`, `writing-correct-examples.md` |
+| Findability of published pages, READMEs and package metadata | `discoverability.md` |
 | Go style, source and module files | `go.md`; framework contributors also read `go-engineering.md`; product APIs use `cratis-chronicle-client-go`, `cratis-arc-go` and `cratis-fundamentals-concept-go` |
 | Service lifetimes — why anything taking a scoped dependency is scoped or transient, never a singleton | `csharp.md` |
 | React + Arc + Cratis Components + MVVM + dialogs | `react.md`, `components.md`, `dialogs.md` |

package/package/corpus/skills/cratis-discoverability/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/package/corpus/skills/cratis-discoverability/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cratis-discoverability
+description: Run the pre-publish check that makes Cratis content easy to find in search and AI answers without making it harder to read - a docs page, blog post, landing page, README or package metadata (title, description, opening definition, canonical links, entity names, alt text, structured data). Use when about to publish or review content for discoverability, SEO, AEO or GEO, or when writing package descriptions and README openers. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
+license: MIT
+---
+
+# Discoverability before you publish
+
+Discoverability is a property of good content: a clear definition, an honest title, one name per
+thing and working links. The always-on rule is [discoverability.md](../../rules/discoverability.md);
+this skill is the procedure to run on the finished draft. If a fix makes the page worse to read,
+drop the fix and say so.
+
+## Procedure
+
+1. Name the content type: docs page, blog post, landing page, README or package metadata.
+2. Name the reader's one job and, for docs, the page type (tutorial, how-to, reference, explanation).
+3. Apply the checks for that type below. Fix the draft; do not annotate it.
+4. For a built site, run the checker and fix errors; warnings are judgment calls to report.
+5. Report what was changed, what was left alone and why.
+
+Read `references/page-checklist.md` for the full per-type checklist and the field lengths.
+
+## Checks by content type
+
+- **Docs page.** The `description` is written by hand as one self-contained
+  definition or outcome sentence. Tutorials, getting-started pages and explanations follow
+  `writing-cratis-docs` (scenario first); the definition lives in the `description`, and one
+  definition sentence may follow the opening scenario where it reads naturally. `writing-cratis-docs`
+  wins on voice and structure. Product index pages open with the definition sentence.
+  Reference pages stay terse: title is the exact name plus its product, no question headings, no
+  intro. Titles are unique across the site and name the product ("Chronicle projections").
+- **Blog post.** The title states the topic in the words a reader would search. The intro gives the
+  conclusion in two sentences. Show the named author and date, add `lastUpdated` only for real
+  changes, link the owning docs pages with `https://www.cratis.io/...`, keep `description` apart
+  from the card `excerpt`.
+- **Landing page.** One primary term in the title, the `<h1>` or the first paragraph, and a
+  one-sentence definition above the fold. Brand lines stay; pair them with a category term in the
+  title and description. Respect the claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md`.
+- **README.** The H1 may be the product name ("Cratis <Product>"). The first sentence defines the product in 15-35 plain
+  nouns, with no logo-only or metaphor opener. Links are absolute; link the docs page.
+- **Package metadata.** One sentence naming what the package is and which Cratis product it belongs
+  to, identical to the README opener. `PackageProjectUrl` and `homepage` point at the docs page, not
+  only at GitHub. Read `references/package-metadata.md` for the field map.
+
+## Names
+
+Use the canonical names, one per concept, and the first-mention rule. Read
+`references/entities.md` when naming a product, writing a definition sentence or filling `sameAs`.
+Do not invent a name, URL, maturity word or claim that the references do not state.
+
+## Structured data
+
+Describe only what is visible on the page, one `@graph` per page, stable `@id`s. Add no `HowTo` and
+no new `FAQPage`. Read `references/structured-data.md` for the patterns and what each page type
+gets. Do not name people in structured data.
+
+## Checking a built site
+
+For a built static site (Astro `dist/` or a plain-HTML repository root), run with Node.js:
+`node <skill-directory>/scripts/verify-discoverability.mjs --root <dir> --site <https://host>`.
+It reports `<html lang>`, title, description, canonical host, `<h1>` count, JSON-LD parse errors,
+`robots.txt`, the sitemap and `llms.txt` structure. Errors exit 1; warnings do not. Pass
+`--warn-only` to downgrade errors and `--require-llms` where the site ships `llms.txt`.
+Read `scripts/verify-discoverability.mjs` only when changing the checker.
+
+## Pitfalls
+
+- Question headings everywhere: use them only where they read naturally (concept pages, FAQs,
+  comparisons, blog), never on reference pages or tutorial steps.
+- Padding to a word count: there is no minimum length; a complete page is done.
+- Apex `https://cratis.io/` links: the docs host is `https://www.cratis.io`.
+- A description that repeats the title or a sibling page's description.

package/package/corpus/skills/cratis-discoverability/references/entities.md

@@ -0,0 +1,68 @@
+# Entity names and definitions
+
+## Contents
+
+- Naming rules
+- Shared identifiers
+- Definition sentences
+- Disambiguation
+
+Only facts the Cratis repositories state are listed. If a product, URL or identifier is not here,
+find it in the product's own README or docs before writing it; do not guess.
+
+## Naming rules
+
+- First mention on a page: "Cratis Chronicle". Later mentions may be "Chronicle". In package
+  descriptions, README H1s and GitHub About text, always the prefixed form.
+- The product is Cratis Direct. "Direct" and "Stagehand" are internal or older names.
+- Cratis Build, Cratis Studio and Cratis Assurance are the three offers on cratis.no. In technical
+  copy and metadata, name the product (Chronicle, Arc), not the offer.
+- The product is not "Cratis.io". `cratis.io` is the docs host, canonical `https://www.cratis.io`.
+- "Cratis" alone is both the company and the platform. Say "the Cratis platform" where the company
+  could be meant.
+- Cratis Studio maturity: follow `BRAND.md` (Preview) until the owner decides otherwise.
+
+## Shared identifiers
+
+| Item | Value |
+| --- | --- |
+| Organization `@id` | `https://cratis.no/#organization` |
+| Company site | `https://cratis.no` |
+| Docs (canonical host) | `https://www.cratis.io` |
+| Blog | `https://blog.cratis.io` |
+| GitHub organization | `https://github.com/Cratis` |
+| NuGet profile | `https://www.nuget.org/profiles/Cratis` |
+| npm organization | `https://www.npmjs.com/org/cratis` |
+| YouTube | `https://www.youtube.com/@CratisStack` |
+
+Product docs follow `https://www.cratis.io/<product>/`.
+
+## Definition sentences
+
+Use these as the opening sentence of a definitional page, README or package description. Adjust only
+to fit the page; keep the facts.
+
+| Name | Sentence | Docs page (under `https://www.cratis.io`) |
+| --- | --- | --- |
+| Cratis (platform) | Cratis is an open-source (MIT) event sourcing and CQRS platform for .NET, built around the Chronicle event-sourcing database. | `https://www.cratis.io/` |
+| Cratis Chronicle | Cratis Chronicle is an open-source (MIT) event-sourcing database and runtime with a .NET kernel and clients for several languages. | `/chronicle/` |
+| Cratis Arc | Cratis Arc is an open-source (MIT) CQRS application framework for ASP.NET Core with generated TypeScript proxies. | `/arc/` |
+| Cratis Fundamentals | Cratis Fundamentals is the set of shared building blocks beneath the Cratis stack for .NET and TypeScript. | `/fundamentals/` |
+| Cratis Studio | Cratis Studio is a collaborative environment for designing, visualizing and editing Screenplay event models. | `/studio/` |
+| Cratis Direct | Cratis Direct is the managed control plane for the Cratis software factory: it turns GitHub signals into prioritized, governed AI work and reviewed pull requests. | none confirmed |
+| Cratis Cast | Cratis Cast is a profile-site engine and directory for the people who build with Cratis, with verified, event-sourced profile pages. | `https://cast.cratis.io` |
+| Cratis Screenplay | Cratis Screenplay is a business-oriented declarative language for specifying the desired functionality of an information system. | `/screenplay/` |
+| Cratis Stage | Cratis Stage compiles Screenplay source, verifies modeled specifications, and renders or partially performs Cratis applications. | none confirmed |
+| Cratis Prologue | Cratis Prologue captures selected signals from an existing system and interprets them into a provisional event model for review. | `/prologue/` |
+| Cratis CLI | The Cratis CLI is a terminal tool for inspecting and diagnosing Cratis Chronicle. | `/cli/` |
+| Chronicle Workbench | Chronicle Workbench is the web dashboard bundled with Cratis Chronicle for browsing events and operating a deployment. | `/chronicle/workbench/` |
+| Chronicle MCP | The Chronicle MCP server connects an AI agent to a running Cratis Chronicle database over the Model Context Protocol. | `/chronicle-mcp/` |
+
+Chronicle storage is pluggable (MongoDB by default, PostgreSQL, SQL Server, SQLite, in-memory).
+Arc works without event sourcing; the Chronicle integration is optional.
+
+## Disambiguation
+
+- `@cratis/arc` is the browser client of Arc .NET; `@cratis/arc.core` is the Node server package.
+- "Cast" alone is not the streaming protocol: write "Cratis Cast".
+- A docs slug not in the table is unconfirmed. Check the docs site before linking it.

package/package/corpus/skills/cratis-discoverability/references/package-metadata.md

@@ -0,0 +1,38 @@
+# Package metadata
+
+## Contents
+
+- Field map
+- Writing the description
+- Pitfalls
+
+## Field map
+
+| Field | NuGet (`.csproj`, `Directory.Build.props`) | npm (`package.json`) |
+| --- | --- | --- |
+| Description | `<Description>`, 80-250 characters; the first 100 are what shows | `description`, 80-160 characters |
+| Tags | `<PackageTags>`, 5-10, `cratis` plus category terms | `keywords`, the same list |
+| Project URL | `<PackageProjectUrl>` = `https://www.cratis.io/<product>/` | `homepage`, the same |
+| Repository | `RepositoryUrl` | `repository` |
+| Authors | `Cratis` | `author` `Cratis` |
+| License | `PackageLicenseExpression` `MIT` | `license` `MIT` |
+| Readme | A packed README with the same opener | `README.md` |
+
+Use a `https://www.cratis.io/<product>/` page that exists; check the docs site rather than guessing
+a slug. If none exists, leave the existing URL and report it.
+
+## Writing the description
+
+One sentence: what it is, for whom, and which Cratis product it belongs to - "<what it is> for
+<audience>, part of Cratis <Parent>". Name the parent so the package disambiguates ("the client for
+Cratis Chronicle, the open-source event-sourcing database"). The text equals the README opener and
+the GitHub About text. Tags are specific ("event-sourcing", "cqrs", "dotnet"); never "utilities".
+
+## Pitfalls
+
+- An empty `Description`.
+- Mixed `Authors` values across packages of one product.
+- `PackageProjectUrl` pointing only at GitHub.
+- Two packages with near-identical descriptions. Where `@cratis/arc` (the browser client of Arc
+  .NET) and `@cratis/arc.core` (the Node server package) could be confused, each description says
+  which one it is.

package/package/corpus/skills/cratis-discoverability/references/page-checklist.md

@@ -0,0 +1,88 @@
+# Page checklist
+
+## Contents
+
+- Field targets
+- Every page
+- Docs pages
+- Blog posts
+- Landing pages
+- READMEs
+- Before publishing a site change
+
+## Field targets
+
+Lengths are targets, counted in characters including any site suffix.
+
+| Field | Target |
+| --- | --- |
+| Title | Distinguishing term first. Blog and landing pages 50-60; docs and reference pages 20-60; a README H1 that is the product name is fine |
+| Description | One sentence, 60-160, never over 160; the point comes first |
+| Lead answer passage | 40-60 words, names its subject, one key property, one limit |
+| Heading | Under about 70 characters |
+| `og:image` | 1200x630, under 200 KB, with `og:image:alt` |
+
+## Every page
+
+- [ ] One reader job. For docs, one page type: tutorial, how-to, reference or explanation.
+- [ ] Title unique, distinguishing term near the front.
+- [ ] Description written by hand; not the title, not another page's description.
+- [ ] The `description` answers what the page is or achieves in one self-contained sentence; the first paragraph does too on landing, index, glossary and README pages.
+- [ ] Canonical names; first mention uses the full "Cratis X" form.
+- [ ] Facts, numbers and comparisons carry a source or a date; nothing beyond the claim gate.
+- [ ] Links have descriptive text. Root-relative inside the docs site, absolute
+      `https://www.cratis.io/...` elsewhere.
+- [ ] Images have alt text (empty only when decorative) and sensible size.
+- [ ] Linked from at least two other pages and from the right hub; no orphan.
+- [ ] Read aloud once: if it sounds written for a crawler, rewrite it.
+
+## Docs pages
+
+- Voice and structure follow `writing-cratis-docs`, which wins on any conflict: tutorials,
+  getting-started pages and explanations open with a concrete scenario (pain, then relief). Put the
+  answer-first definition in the frontmatter `description`; one definition sentence may follow the
+  scenario where it reads naturally.
+- Product index page: opens with the one-sentence definition, then the without-versus-with framing.
+- Concept page: scenario first; then why it exists, when to use it, when not to, how it works.
+  H2s such as "What is X" and "When to use X" only where they fit. No H1 in the body.
+- Tutorial: title names the outcome and starts with a verb; the scenario, then what the reader will
+  have running; prerequisites and versions up front; one visible result per step; "Last updated" and the
+  version it applies to.
+- How-to: the task as the title; goal, prerequisites, numbered steps, a done check, the two likely
+  failures; versions stated.
+- Reference: the title is the exact name with its product; first sentence says what it is for;
+  tables and signatures; stable anchors; no intro, no pitch. Merge or enrich near-empty stub pages.
+
+## Blog posts
+
+- [ ] Title states the topic; series name goes in a `series` field or at the end.
+- [ ] Two-sentence conclusion up front; "when this is the wrong fit" where it applies.
+- [ ] Named author where agreed (`cratis-team` only for company announcements), date, `lastUpdated`
+      only on real changes.
+- [ ] At least one internal link to the owning docs page; tags reused from the existing list, no
+      singleton tags; a cover image with alt text for posts likely to be shared.
+
+## Landing pages
+
+- [ ] One primary term in title, `<h1>` or first paragraph; one-sentence definition above the fold.
+- [ ] Description differs per page and is not a 300-character paragraph.
+- [ ] No testimonials, numbers, customers, prices or maturity claims the claim gate does not allow.
+- [ ] Norwegian pages are written natively, keep established English technical terms, link to the
+      English page with `hreflang`, and are not machine-translated and published unreviewed.
+
+## READMEs
+
+- [ ] H1 may be the product name ("Cratis <Product>"); first sentence is the definition (15-35 words, no metaphor).
+- [ ] Then install, a minimal working example, a link to `https://www.cratis.io/<product>/`,
+      license and how it relates to the rest of Cratis.
+- [ ] GitHub About text equals the README opener (80-160 characters); website is the docs page;
+      topics include `cratis` plus category terms.
+
+## Before publishing a site change
+
+- [ ] Title, description, canonical, Open Graph and JSON-LD present and unique on changed pages.
+- [ ] Sitemap lists new pages; `robots.txt` unchanged unless intended.
+- [ ] JSON-LD validates; no `HowTo`; no new `FAQPage`.
+- [ ] The content is in the raw HTML the server returns, not only rendered by JavaScript.
+- [ ] Internal links resolve; no apex `cratis.io` links.
+- [ ] A real HTTP 404 for unknown URLs; redirect stubs keep a canonical and stay out of the sitemap.

package/package/corpus/skills/cratis-discoverability/references/structured-data.md

@@ -0,0 +1,62 @@
+# Structured data patterns
+
+## Contents
+
+- Rules
+- Types per page type
+- Pattern
+
+## Rules
+
+- One `@graph` per page with stable `@id` values. The organization `@id` is
+  `https://cratis.no/#organization`.
+- Markup describes what is visible on the page, and every date is a real one.
+- Add no `HowTo`. Add no new `FAQPage`; keep the visible question and answer text. Use `QAPage` only
+  for real user questions and answers.
+- Do not name people (`Person`, `author` name) in structured data unless the owner has approved it.
+  Reference the organization by `@id`.
+- Do not add `offers`, an address or contact data without approval (see `SITE.md`).
+- Validate with the schema.org validator or Google's Rich Results Test. Invalid markup is worse than
+  none. Static sites hand-write `<script type="application/ld+json">`; Astro sites generate it in
+  the head component, so change it there rather than per page.
+
+## Types per page type
+
+| Page type | Types |
+| --- | --- |
+| Company home | `Organization` (name, url, logo, `sameAs`), `WebSite` |
+| Product marketing page | `SoftwareApplication` (name, applicationCategory, license, url, `sameAs`) |
+| Docs concept, tutorial, how-to, reference | `TechArticle` with `headline`, `dateModified`, plus `BreadcrumbList` |
+| Docs hub and landing page | `CollectionPage` or `WebPage`, not `TechArticle` |
+| Blog post | `BlogPosting` (`datePublished`, `dateModified`, `publisher`, `image`) |
+| Repository or sample code | `SoftwareSourceCode` |
+| Legal pages | `WebPage` |
+| 404 and app hosts | none |
+
+## Pattern
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "TechArticle",
+      "@id": "https://www.cratis.io/chronicle/projections/#article",
+      "headline": "Chronicle projections",
+      "description": "A projection declares how Chronicle builds a read model from events.",
+      "dateModified": "YYYY-MM-DD",
+      "publisher": { "@id": "https://cratis.no/#organization" },
+      "mainEntityOfPage": "https://www.cratis.io/chronicle/projections/"
+    },
+    {
+      "@type": "BreadcrumbList",
+      "itemListElement": [
+        { "@type": "ListItem", "position": 1, "name": "Chronicle", "item": "https://www.cratis.io/chronicle/" },
+        { "@type": "ListItem", "position": 2, "name": "Projections" }
+      ]
+    }
+  ]
+}
+```
+
+The values are illustrative: take the title, description and dates from the page itself.

package/package/corpus/skills/cratis-discoverability/scripts/verify-discoverability.mjs

@@ -0,0 +1,107 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+//
+// Checks a built static site (Astro dist/ or a plain-HTML repo root) before it is published:
+// every indexable page has <html lang>, one <title>, a meta description, a canonical on the
+// expected host and parseable JSON-LD; the site has robots.txt, a sitemap and (optionally) a
+// well-formed llms.txt. Node standard library only.
+//
+// Usage: node verify-discoverability.mjs --root dist --site https://blog.cratis.io [--require-llms] [--warn-only]
+// Exit codes: 0 clean or warnings only, 1 errors, 2 could not run.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const args = process.argv.slice(2);
+const option = (name, fallback) => { const i = args.indexOf(name); return i < 0 ? fallback : args[i + 1]; };
+const root = option('--root', 'dist');
+const site = option('--site');
+const requireLlms = args.includes('--require-llms');
+const warnOnly = args.includes('--warn-only');
+const ignore = (option('--ignore', 'node_modules,.git,.cratis,.github,404.html,_astro,storybook') ?? '').split(',');
+
+if (!site || !existsSync(root)) {
+    console.error(`could not run: need --site and an existing --root (got ${root})`);
+    process.exit(2);
+}
+const host = new URL(site).host;
+let errors = 0;
+let warnings = 0;
+const report = (level, file, message) => {
+    if (level === 'error' && !warnOnly) errors++; else warnings++;
+    console.log(`::${level === 'error' && !warnOnly ? 'error' : 'warning'} file=${file}::${message}`);
+};
+
+function* htmlFiles(dir) {
+    for (const name of readdirSync(dir)) {
+        if (ignore.includes(name)) continue;
+        const path = join(dir, name);
+        if (statSync(path).isDirectory()) yield* htmlFiles(path);
+        else if (name.endsWith('.html')) yield path;
+    }
+}
+
+const attr = (tag, name) => tag.match(new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`, 'i'))?.[1];
+const tags = (html, pattern) => [...html.matchAll(pattern)].map(match => match[0]);
+const titles = new Map();
+
+for (const path of htmlFiles(root)) {
+    const file = relative(process.cwd(), path);
+    const html = readFileSync(path, 'utf8');
+    const metas = tags(html, /<meta\b[^>]*>/gi);
+    const robots = metas.find(tag => /name\s*=\s*["']robots["']/i.test(tag));
+    if (robots && /noindex/i.test(attr(robots, 'content') ?? '')) continue;      // deliberately not indexed
+    if (/http-equiv\s*=\s*["']refresh["']/i.test(html)) continue;                 // redirect stub
+
+    if (!/<html\b[^>]*\blang\s*=/i.test(html)) report('error', file, 'missing <html lang>');
+    const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.trim();
+    if (!title) report('error', file, 'missing or empty <title>');
+    else {
+        if (title.length > 65) report('warning', file, `title is ${title.length} characters; keep the distinguishing words in the first 60`);
+        titles.set(title, [...(titles.get(title) ?? []), file]);
+    }
+    const description = metas.find(tag => /name\s*=\s*["']description["']/i.test(tag));
+    const descriptionText = description ? attr(description, 'content') ?? '' : '';
+    if (!descriptionText) report('error', file, 'missing meta description');
+    else if (descriptionText.length < 60 || descriptionText.length > 160) report('warning', file, `meta description is ${descriptionText.length} characters (aim for 60-160)`);
+    const canonical = tags(html, /<link\b[^>]*>/gi).find(tag => /rel\s*=\s*["']canonical["']/i.test(tag));
+    const href = canonical ? attr(canonical, 'href') : undefined;
+    if (!href) report('error', file, 'missing <link rel="canonical">');
+    else {
+        try {
+            const url = new URL(href);
+            if (url.host !== host) report('error', file, `canonical points at ${url.host}, expected ${host}`);
+        } catch {
+            report('error', file, `canonical is not an absolute URL: ${href}`);
+        }
+    }
+    if ((html.match(/<h1\b/gi) ?? []).length !== 1) report('warning', file, 'expected exactly one <h1>');
+    for (const block of html.matchAll(/<script\b[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+        try {
+            const data = JSON.parse(block[1]);
+            const nodes = Array.isArray(data) ? data : data['@graph'] ?? [data];
+            if (!Array.isArray(data) && !String(data['@context'] ?? '').includes('schema.org')) report('error', file, 'JSON-LD without a schema.org @context');
+            for (const node of nodes) if (!node['@type']) report('warning', file, 'JSON-LD node without @type');
+        } catch (error) {
+            report('error', file, `JSON-LD does not parse: ${error.message}`);
+        }
+    }
+}
+
+for (const [title, files] of titles) if (files.length > 1) report('warning', files[0], `title "${title}" is shared by ${files.length} pages`);
+
+const robotsPath = join(root, 'robots.txt');
+if (!existsSync(robotsPath)) report('error', root, 'no robots.txt');
+else if (!/^\s*sitemap\s*:/im.test(readFileSync(robotsPath, 'utf8'))) report('warning', robotsPath, 'robots.txt does not declare a Sitemap');
+if (!readdirSync(root).some(name => /^sitemap.*\.xml$/.test(name))) report('error', root, 'no sitemap*.xml at the site root');
+
+const llmsPath = join(root, 'llms.txt');
+if (existsSync(llmsPath)) {
+    // Same structure rules as vendor/claude-seo/scripts/agentic_check.py evaluate_llms_txt (Lighthouse llms-txt audit).
+    const llms = readFileSync(llmsPath, 'utf8').replace(/^\uFEFF/, '');
+    if (!/^\s*#\s+.+/m.test(llms)) report('error', llmsPath, 'llms.txt has no H1');
+    if (!/\[.+\]\(.+\)/.test(llms)) report('error', llmsPath, 'llms.txt has no Markdown links');
+    if (!/^\s*>\s+\S/m.test(llms)) report('warning', llmsPath, "llms.txt has no '>' summary");
+} else if (requireLlms) report('error', root, 'no llms.txt');
+
+console.log(`verify-discoverability: ${errors} error(s), ${warnings} warning(s)`);
+process.exit(errors ? 1 : 0);

package/package/corpus/skills/cratis-discoverability/verification.json

@@ -0,0 +1,13 @@
+{
+  "skill": "cratis-discoverability",
+  "input": "Run the pre-publish discoverability check on a new blog post, a package README and the package metadata for a Cratis library.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "If a fix makes the page worse to read," },
+    { "kind": "skill-contains", "value": "Add no `HowTo` and" },
+    { "kind": "skill-contains", "value": "Do not name people in structured data." },
+    { "kind": "skill-contains", "value": "Apex `https://cratis.io/` links: the docs host is `https://www.cratis.io`." },
+    { "kind": "skill-contains", "value": "no logo-only or metaphor opener" },
+    { "kind": "skill-contains", "value": "Padding to a word count: there is no minimum length" }
+  ]
+}

package/package/profile-catalog.json

@@ -657,6 +657,7 @@
       "availableTargets": [
         "cratis-content-length",
         "cratis-developer-marketing",
+        "cratis-discoverability",
         "cratis-release-notes",
         "cratis-social-feed-post",
         "cratis-technical-examples",
@@ -670,6 +671,7 @@
     {
       "id": "cratis/documentation",
       "availableTargets": [
+        "cratis-discoverability",
         "cratis-documentation-writing",
         "cratis-engineering-docs-authoring",
         "cratis-llm-friendly-documentation",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.93.0",
+  "version": "7.95.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [