@cratis/pi 3.0.0 → 3.1.1

package/package/corpus/agents/orchestrator.md

@@ -115,7 +115,7 @@ When you receive a goal:
 - [ ] [security-reviewer] Security review of all changed files
 
 ### Phase 5 — Documentation (if applicable)
-- [ ] [write-documentation skill] Document <feature/concept>
+- [ ] [documentation] Document <feature/concept> in its authored source with cratis-documentation-writing (or cratis-engineering-docs-authoring) and cratis-technical-examples for code, when the repository's profiles install them; otherwise follow the repository's own documentation rules
 ```
 
 ---

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

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A stopped connection is never restarted or a request retried implicitly. */
+export class ConnectionFailure extends Error {
+    constructor(message: string, readonly outcomeUnknown = false) {
+        super(outcomeUnknown
+            ? `${message} Source mutation outcome is unknown. Do not retry apply/recovery. Inspect workspace-state in a new explicitly opened session before deciding on recovery.`
+            : message);
+    }
+}

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

@@ -0,0 +1,12 @@
+// 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';
+
+export interface DiscoveredTool {
+    name: string;
+    nativeName: string;
+    description: string;
+    parameters: TSchema;
+    mutation: boolean;
+}

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

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export interface PendingRequest {
+    id: number;
+    mutation: boolean;
+    resolve(value: unknown): void;
+    reject(error: Error): void;
+    cleanup(): void;
+}

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

@@ -0,0 +1,160 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { ConnectionFailure } from './ConnectionFailure.ts';
+import { object } from './configuration.ts';
+import type { PendingRequest } from './PendingRequest.ts';
+
+/** Bounded newline JSON-RPC transport for Screenplay's sequential stdio subset. */
+export class StdioConnection {
+    private _buffer = Buffer.alloc(0);
+    private _sequence = 0;
+    private _pending?: PendingRequest;
+    private _failure?: ConnectionFailure;
+    private _termination?: ReturnType<typeof setTimeout>;
+    private readonly _maximumBytes = 8 * 1024 * 1024;
+
+    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000) {
+        _child.stdout.on('data', this.receive);
+        _child.stdout.on('end', this.ended);
+        _child.stdout.on('error', this.streamFailed);
+        _child.stdin.on('error', this.streamFailed);
+        // Drain without retaining or showing raw server logs/protocol in the host UI.
+        _child.stderr.on('data', this.drain);
+        _child.stderr.on('error', this.streamFailed);
+        _child.on('error', this.spawnFailed);
+        _child.once('close', this.closed);
+    }
+
+    get stopped(): boolean { return this._failure !== undefined; }
+    get outcomeUnknown(): boolean { return this._failure?.outcomeUnknown === true; }
+
+    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.');
+        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);
+            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.'); });
+            } catch {
+                this.stop('Screenplay input pipe failed.');
+            }
+        });
+    }
+
+    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.'); });
+        } catch {
+            this.stop('Screenplay notification failed.');
+            throw this._failure;
+        }
+    }
+
+    dispose(): void { this.stop('Screenplay 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.');
+        return line;
+    }
+
+    private readonly receive = (chunk: Buffer): void => {
+        if (this.stopped) return;
+        // Stream chunks can contain many lines; bound each unfinished line before concatenation.
+        let start = 0;
+        for (let index = 0; index < chunk.length; index++) {
+            if (chunk[index] !== 10) continue;
+            if (!this.append(chunk.subarray(start, index))) return;
+            try {
+                const line = new TextDecoder('utf-8', { fatal: true }).decode(this._buffer);
+                this._buffer = Buffer.alloc(0);
+                this.accept(line);
+            } catch {
+                this.stop('Screenplay returned invalid UTF-8 protocol data.');
+            }
+            if (this.stopped) return;
+            start = index + 1;
+        }
+        this.append(chunk.subarray(start));
+    };
+
+    private append(chunk: Buffer): boolean {
+        if (this._buffer.length + chunk.length > this._maximumBytes) {
+            this.stop('Screenplay response exceeds the 8 MiB transport limit.');
+            return false;
+        }
+        this._buffer = Buffer.concat([this._buffer, chunk]);
+        return true;
+    }
+
+    private accept(line: string): void {
+        try {
+            const message: unknown = JSON.parse(line);
+            if (!object(message) || message.jsonrpc !== '2.0') throw new Error();
+            if ('method' in message) {
+                // This pinned server does not send requests or changing tool lists.
+                throw new Error();
+            }
+            const pending = this._pending;
+            if (!pending || message.id !== pending.id || ('result' in message) === ('error' in message)) throw new Error();
+            if ('error' in message && (!object(message.error) || typeof message.error.code !== 'number' || typeof message.error.message !== 'string')) throw new Error();
+            this._pending = undefined;
+            pending.cleanup();
+            if (object(message.error)) {
+                pending.reject(new ConnectionFailure(`Screenplay 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);
+            } else {
+                pending.resolve(message.result);
+            }
+        } catch {
+            this.stop('Screenplay returned malformed or unexpected JSON-RPC.');
+        }
+    }
+
+    private stop(message: string, outcomeUnknown = this._pending?.mutation === true): void {
+        if (this._failure) return;
+        this._failure = new ConnectionFailure(message, outcomeUnknown);
+        const pending = this._pending;
+        this._pending = undefined;
+        pending?.cleanup();
+        pending?.reject(this._failure);
+        this._buffer = Buffer.alloc(0);
+        this._child.stdout.removeListener('data', this.receive);
+        this._child.stdout.removeListener('end', this.ended);
+        this._child.stdout.resume();
+        this._child.stdin.end();
+        if (this._child.exitCode === null && this._child.signalCode === null) {
+            this._child.kill('SIGTERM');
+            // Deadline escalation, not a completion wait. Cleared on the child's close signal.
+            this._termination = setTimeout(() => this._child.kill('SIGKILL'), 1000);
+            this._termination.unref();
+        }
+    }
+
+    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 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.');
+        clearTimeout(this._termination);
+        this._child.stdout.removeListener('error', this.streamFailed);
+        this._child.stdin.removeListener('error', this.streamFailed);
+        this._child.stderr.removeListener('error', this.streamFailed);
+        this._child.stderr.removeListener('data', this.drain);
+        this._child.removeListener('error', this.spawnFailed);
+    };
+}

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

@@ -0,0 +1,102 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+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> {
+    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}`);
+    return value;
+}
+
+function strings(value: unknown): string[] {
+    if (value === undefined) return [];
+    if (!Array.isArray(value) || !value.every(item => typeof item === 'string')) throw new Error('Expected a Cratis profile/language list.');
+    return value;
+}
+
+/** 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.');
+    const physicalProject = realpathSync(project);
+    const candidate = resolve(physicalProject, root);
+    const local = relative(physicalProject, candidate);
+    if (!local || local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+        throw new Error('Screenplay root must be strictly inside the project.');
+    }
+    let current = physicalProject;
+    for (const part of local.split(sep)) {
+        current = join(current, part);
+        let info;
+        try {
+            info = lstatSync(current);
+        } catch (error) {
+            if (object(error) && error.code === 'ENOENT') throw new Error('Screenplay root is absent. Run cratis ai install or explicitly create the configured model directory; discovery never creates it.');
+            throw error;
+        }
+        if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('Screenplay root must contain only physical directories, not symlinks.');
+    }
+    return current;
+}
+
+/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
+export function selectedServer(project: string, corpus: string) {
+    let configuration: Record<string, unknown>;
+    try {
+        configuration = readJson(join(project, '.cratis', 'ai.json'));
+    } catch (error) {
+        if (object(error) && error.code === 'ENOENT') return undefined;
+        throw error;
+    }
+    const requested = strings(configuration.profiles);
+    if (!requested.length) return undefined;
+    let catalog: Record<string, unknown>;
+    try {
+        catalog = readJson(join(corpus, 'profile-catalog.json'));
+    } catch (error) {
+        if (!object(error) || error.code !== 'ENOENT') throw error;
+        catalog = readJson(join(corpus, '..', 'profile-catalog.json'));
+    }
+    const profiles = [catalog.publicProfiles, catalog.engineeringProfiles].flatMap(group => {
+        if (!Array.isArray(group) || !group.every(object)) throw new Error('Invalid Cratis profile catalog.');
+        return group;
+    });
+    const languages = new Set(strings(configuration.languages));
+    const selected = new Set<string>();
+    const select = (id: string, explicit: boolean): void => {
+        if (selected.has(id)) return;
+        const profile = profiles.find(candidate => candidate.id === id);
+        if (!profile) throw new Error(`Unknown Cratis AI profile '${id}'.`);
+        const supported = strings(profile.languages);
+        if (!explicit && supported.length && !supported.some(language => language === 'language-agnostic' || languages.has(language))) return;
+        selected.add(id);
+        strings(profile.composes).forEach(child => select(child, false));
+    };
+    requested.forEach(id => select(id, true));
+    if (!selected.has('cratis/screenplay')) return undefined;
+    const overrides = configuration.mcpServers;
+    if (overrides !== undefined && !object(overrides)) throw new Error('Invalid mcpServers configuration.');
+    const screenplay = object(overrides) ? overrides.screenplay : undefined;
+    if (screenplay !== undefined && !object(screenplay)) throw new Error('Invalid Screenplay MCP configuration.');
+    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.');
+    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];
+    if (server.transport !== 'stdio' || server.command !== 'cratis' || JSON.stringify(server.args) !== '["screenplay","mcp"]' ||
+        JSON.stringify(server.profiles) !== '["cratis/screenplay"]' || server.env !== undefined) {
+        throw new Error('Only the distributed native Cratis Screenplay MCP command is supported.');
+    }
+    const root = object(screenplay) && screenplay.root !== undefined ? screenplay.root : server.defaultRoot;
+    if (typeof root !== 'string') throw new Error('Screenplay MCP root must be a project-relative string.');
+    const physicalProject = realpathSync(project);
+    return { project: physicalProject, root: physicalRoot(physicalProject, root) };
+}

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

@@ -0,0 +1,149 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+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 } from './process.ts';
+import { discover, failedResult, mapResult } from './protocol.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+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): void {
+    let connection: StdioConnection | undefined;
+    let selectionKey: string | undefined;
+    let attempted = false;
+    let uncertain = false;
+    const registered = new Set<string>();
+    const paused = new Set<string>();
+    const failures = new Map<string, ReturnType<typeof failedResult>>();
+
+    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 => {
+        connection?.dispose();
+        uncertain ||= connection?.outcomeUnknown === true;
+        connection = undefined;
+        deactivate();
+    };
+    const currentSelection = (context: ExtensionContext) => selectedServer(context.cwd, corpus);
+    const ensureCurrent = (context: ExtensionContext): void => {
+        let key: string | undefined;
+        try { key = JSON.stringify(currentSelection(context)); }
+        catch (error) { dispose(); throw error; }
+        if (!key || key !== selectionKey) {
+            dispose();
+            throw new Error('Screenplay profile/root changed. Start a new turn to rediscover tools; never reuse old workspace handles.');
+        }
+        if (!connection || connection.stopped) throw new Error('Screenplay connection is unavailable. No request was retried; explicitly reload after inspecting any uncertain mutation.');
+    };
+    const refresh = async (context: ExtensionContext, newSession = false): Promise<void> => {
+        const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
+        let selection: ReturnType<typeof selectedServer>;
+        try { selection = currentSelection(context); }
+        catch (error) { dispose(); throw error; }
+        const key = JSON.stringify(selection);
+        if (!newSession && attempted && key === selectionKey) return;
+        dispose();
+        attempted = true;
+        selectionKey = key;
+        failures.clear();
+        if (!selection) return;
+        if (uncertain) throw new Error('Screenplay mutation outcome remains unknown. Explicitly reload, inspect workspace-state, and obtain authorization before any recovery.');
+        const modelRoot = selection.root;
+        const activeConnection = connect(selection.project);
+        connection = activeConnection;
+        try {
+            const tools = await discover(activeConnection);
+            if (connection !== activeConnection || activeConnection.stopped) throw new Error('Screenplay session ended during discovery.');
+            const existing = new Set(pi.getAllTools().map(tool => tool.name));
+            if (tools.some(tool => existing.has(tool.nativeName) && !registered.has(tool.nativeName))) throw new Error('Screenplay native tool name conflicts with another extension.');
+            const oldNames = new Set(registered);
+            for (const tool of tools) {
+                registered.add(tool.nativeName);
+                pi.registerTool({
+                    name: tool.nativeName,
+                    label: `Screenplay ${tool.name}`,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                    executionMode: 'sequential',
+                    promptGuidelines: [
+                        'Use the Screenplay model-authoring skill. Read/propose/review before applying; only a direct user request authorizes apply or recovery.',
+                        'Use bounded pages. On an unknown mutation outcome, never retry or recover automatically; inspect workspace-state first.',
+                    ],
+                    async execute(toolCallId, parameters, signal, _onUpdate, toolContext) {
+                        ensureCurrent(toolContext);
+                        if (connection !== activeConnection || !pi.getActiveTools().includes(tool.nativeName)) throw new Error('Screenplay tool is inactive in this session.');
+                        if (!object(parameters)) throw new Error('Screenplay arguments must be an object.');
+                        if (signal?.aborted) throw new Error('Screenplay call cancelled before sending.');
+                        if (tool.mutation) {
+                            if (!toolContext.hasUI) throw new Error('Screenplay source mutation requires explicit user confirmation in Pi interactive/RPC mode.');
+                            const argumentsText = JSON.stringify(parameters);
+                            if (argumentsText.length > 8192) throw new Error('Mutation confirmation arguments are too large; omit includeContent and use the proposal/operation identifiers.');
+                            const approved = await toolContext.ui.confirm(`Screenplay ${tool.name}`, `Modify source under ${modelRoot}?\n${argumentsText}\nOnly approve the exact reviewed proposal or recovery operation.`, { timeout: 60_000, signal });
+                            if (!approved || signal?.aborted) throw new Error('Screenplay source mutation was not approved.');
+                            ensureCurrent(toolContext);
+                        }
+                        let response: unknown;
+                        try {
+                            response = await activeConnection.request('tools/call', { name: tool.name, arguments: parameters }, signal, tool.mutation);
+                            const result = mapResult(response);
+                            if (result.details.isError) {
+                                if (failures.size >= 64) failures.delete(failures.keys().next().value!);
+                                failures.set(toolCallId, failedResult(result));
+                                throw new Error('Screenplay reported a failed tool call.');
+                            }
+                            return result;
+                        } catch (error) {
+                            if (tool.mutation && response !== undefined && !failures.has(toolCallId)) {
+                                uncertain = true;
+                                dispose();
+                                throw new ConnectionFailure('Screenplay mutation returned an invalid result.', true);
+                            }
+                            uncertain ||= activeConnection.outcomeUnknown;
+                            if (activeConnection.stopped) deactivate();
+                            throw error;
+                        }
+                    },
+                });
+            }
+            // Never re-enable a user-disabled tool. SDK allow/exclude restrictions still filter registration.
+            const discovered = new Set(tools.map(tool => tool.nativeName));
+            const next = pi.getActiveTools().filter(name => !registered.has(name) || (discovered.has(name) && (!oldNames.has(name) || previouslyActive.has(name))));
+            for (const name of discovered) if (oldNames.has(name) && previouslyActive.has(name)) next.push(name);
+            pi.setActiveTools([...new Set(next)]);
+            paused.clear();
+        } catch (error) {
+            if (connection === activeConnection) dispose();
+            else activeConnection.dispose();
+            throw error;
+        }
+    };
+
+    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(); });
+    pi.on('tool_result', event => {
+        if (!registered.has(event.toolName)) return;
+        const failure = failures.get(event.toolCallId);
+        failures.delete(event.toolCallId);
+        return failure;
+    });
+}
+
+export default function (pi: ExtensionAPI): void {
+    // A managed project already loads its own bridge. Do not run a second subprocess from @cratis/pi.
+    const managedEntry = join(process.cwd(), '.pi', 'extensions', 'cratis-mcp', 'index.ts');
+    if (bundledCorpus.endsWith(join('package', 'corpus')) && existsSync(join(process.cwd(), '.cratis', 'ai.manifest.json')) && existsSync(managedEntry)) return;
+    const corpus = existsSync(join(bundledCorpus, 'mcp-servers.json')) ? bundledCorpus : join(process.cwd(), '.cratis', 'ai');
+    registerBridge(pi, corpus);
+}

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

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { spawn } from 'node:child_process';
+import { StdioConnection } from './StdioConnection.ts';
+
+/** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
+export function childEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+    const environment: NodeJS.ProcessEnv = {};
+    for (const key of ['PATH', 'HOME', 'USERPROFILE', 'SystemRoot', 'WINDIR', 'TEMP', 'TMP', 'TMPDIR', 'DOTNET_ROOT', 'DOTNET_ROOT_X64', 'DOTNET_ROOT_ARM64']) {
+        if (source[key] !== undefined) environment[key] = source[key];
+    }
+    return environment;
+}
+
+export function startConnection(project: string, launch: typeof spawn = spawn): StdioConnection {
+    return new StdioConnection(launch('cratis', ['screenplay', 'mcp', '--project-root', project], {
+        cwd: project,
+        env: childEnvironment(),
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    }));
+}

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

@@ -0,0 +1,67 @@
+// 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 { DiscoveredTool } from './DiscoveredTool.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+/** Negotiate the server's implemented protocol before exposing any discovered tools. */
+export async function discover(connection: StdioConnection): Promise<DiscoveredTool[]> {
+    const initialized = await connection.request('initialize', {
+        protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'cratis.pi', version: '1.0.0' },
+    });
+    if (!object(initialized) || initialized.protocolVersion !== '2025-06-18' || !object(initialized.serverInfo) ||
+        initialized.serverInfo.name !== 'cratis.screenplay' || !object(initialized.capabilities) || !object(initialized.capabilities.tools) ||
+        initialized.capabilities.tools.listChanged === true) throw new Error('Unsupported Screenplay MCP server capabilities or protocol version.');
+    connection.notify('notifications/initialized');
+    const listed = await connection.request('tools/list', {});
+    if (!object(listed) || !Array.isArray(listed.tools) || !listed.tools.length || listed.tools.length > 128 || listed.nextCursor !== undefined) {
+        throw new Error('Expected a nonempty, unpaginated Screenplay tool catalog (at most 128 tools).');
+    }
+    const names = new Set<string>();
+    return listed.tools.map((tool: unknown) => {
+        if (!object(tool) || typeof tool.name !== 'string' || !/^[a-z][a-z0-9-]{0,47}$/.test(tool.name) ||
+            typeof tool.description !== 'string' || tool.description.length > 8192 || !object(tool.inputSchema) || tool.inputSchema.type !== 'object') {
+            throw new Error('Invalid Screenplay tool name, description, or input schema.');
+        }
+        const nativeName = `screenplay_${tool.name.replaceAll('-', '_')}`;
+        if (names.has(nativeName)) throw new Error('Duplicate Screenplay tool name.');
+        names.add(nativeName);
+        // Hints are not authority. Only the pinned apply/recover operations may mutate source.
+        const mutation = tool.name === 'apply' || tool.name === 'recover-workspace';
+        if (!mutation && (!object(tool.annotations) || tool.annotations.readOnlyHint !== true || tool.annotations.destructiveHint === true)) {
+            throw new Error(`Unrecognized source-mutating Screenplay tool '${tool.name}'; update the reviewed bridge.`);
+        }
+        return { name: tool.name, nativeName, description: tool.description, parameters: tool.inputSchema as TSchema, mutation };
+    });
+}
+
+/** Keep structured data once in details and never present server failures as success. */
+export function mapResult(result: unknown) {
+    if (!object(result) || !Array.isArray(result.content) || (result.isError !== undefined && typeof result.isError !== 'boolean') ||
+        (result.structuredContent !== undefined && !object(result.structuredContent))) throw new Error('Malformed Screenplay tool result.');
+    const texts = result.content.map((part: unknown) => {
+        if (!object(part) || part.type !== 'text' || typeof part.text !== 'string') throw new Error('Unsupported Screenplay result content; expected text.');
+        return part.text;
+    });
+    const fullText = texts.join('\n');
+    const maximumCharacters = 32 * 1024;
+    const truncated = fullText.length > maximumCharacters;
+    const text = truncated
+        ? `${fullText.slice(0, maximumCharacters)}\n[Screenplay display truncated. Request a smaller page or narrower view; full structured data is retained in tool details.]`
+        : fullText;
+    return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+            structuredContent: result.structuredContent,
+            isError: result.isError === true,
+            truncated,
+            ...(truncated && result.structuredContent === undefined ? { fullText } : {}),
+        },
+    };
+}
+
+export function failedResult(result: ReturnType<typeof mapResult>) {
+    return { ...result, isError: true };
+}

package/package/corpus/mcp-servers.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "1.0",
+  "servers": [
+    {
+      "id": "screenplay",
+      "profiles": ["cratis/screenplay"],
+      "transport": "stdio",
+      "command": "cratis",
+      "args": ["screenplay", "mcp"],
+      "defaultRoot": ".cratis/screenplay",
+      "description": "Understand and safely author one Screenplay application through typed AST operations, reviewed proposals, durable identities, and explicit recovery."
+    }
+  ]
+}

package/package/corpus/prompts/write-documentation.prompt.md

@@ -1,21 +1,30 @@
 ---
 agent: agent
-description: "Write documentation following the Diátaxis framework."
+description: "Write reader-centered documentation using the Cratis documentation skills."
 ---
 
 # Write Documentation
 
-Write documentation for a feature, component, or concept. Invoke the **write-documentation** skill and follow `.cratis/ai/rules/documentation.md`.
+Write documentation for a feature, component, or concept. Follow
+`.cratis/ai/rules/documentation.md` and invoke **cratis-documentation-writing**.
+For a Cratis product page, also use **cratis-engineering-docs-authoring**;
+for samples or snippets, use **cratis-technical-examples**.
 
-## Confirm first
+## Determine the reader's job
 
-- **Subject**, **audience**, and the **Diátaxis type** — exactly one:
-  - **Tutorial** — guided lesson for newcomers
-  - **How-to guide** — recipe for a specific task
-  - **Reference** — exhaustive, terse technical description
-  - **Explanation** — concepts, trade-offs, architecture (the *why*)
-- The source files to document.
+From the request and neighboring authored pages, identify the reader, the
+question they have, the outcome they need, and the page's primary purpose:
+tutorial, how-to, explanation, or reference. Ask only when plausible choices
+would materially change the result; don't require an outline approval before
+ordinary drafting. Find the owning source before editing, never a synced copy.
 
-## Workflow
+## Write and verify
 
-Clarify type/audience/scope → propose an outline → write. Active voice, present tense, second person; lead with *why*; complete and correct code examples; Mermaid diagrams for non-trivial concepts; descriptive link text; relative links that resolve. Update `toc.yml` and run the documentation verification before considering it done. The skill carries the per-page detail; don't duplicate it here.
+Lead with the problem and payoff. Use active voice and show how the reader can
+recognize success. A tutorial can briefly explain an observed result without
+turning into a reference dump; link to deeper material. Verify framework APIs
+against first-party source at the applicable version, check the sample at its
+claimed scope, and run the owning repository's content and link gates. Add a
+new page to the owning product's `toc.yml`
+(a page missing from it silently drops out of the sidebar); otherwise update
+navigation only when the page's placement or route changes.

package/package/corpus/rules/ai-distribution.md

@@ -31,6 +31,26 @@ repository through one of three channels, each with its own version semantics:
 - **Native plugin marketplaces** (Claude Code, Codex, Copilot, Cursor) expose the
   skills only, from the unpinned GitHub source.
 
+## Profile-selected MCP servers
+
+`mcp-servers.json` declares MCP launch capabilities for selected profiles. It is
+canonical corpus content, not a replacement client configuration and not an
+instruction for an assistant to install or execute arbitrary software.
+
+The Cratis CLI owns native client registration and executable hosting. Screenplay
+uses `cratis screenplay mcp`, bundled in the CLI; no second global tool install
+or startup download is required. Client installation must preserve unrelated
+servers, settings and comments, detect conflicts, support dry-run/status, and
+remove only unchanged owned entries on uninstall. Unsupported adapters must be
+reported explicitly rather than presented as configured.
+
+Project model roots and opt-outs are consumer-owned configuration. Guidance
+installation never makes `.cratis/screenplay/` managed corpus content. Ordinary
+model writes still require the model-authoring proposal/apply contract and the
+user's in-scope request.
+
+## Preserve consumer ownership
+
 Keep existing repository-local AI files in place while a replacement corpus is
 under canary; do not restart legacy all-to-all propagation and do not delete
 legacy adapters before reviewed retirement evidence exists.
@@ -57,4 +77,3 @@ and roll back the same way — by package version where one exists, otherwise by
 reinstalling from a known-good source commit with `--source`. Never patch managed
 files under `.cratis/ai/`, generated adapters, or marketplace wrappers by hand;
 `cratis ai status` reports such drift and `update` refuses it without `--force`.
-