@cratis/pi 7.1.4 → 7.2.0

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

@@ -1,250 +1,19 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
-const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
-
-type AiConfiguration = { profiles?: string[] };
-
-export interface ManagedRule {
-    /** Path relative to the rules root, e.g. `code-quality-csharp.md` or `project/running-the-local-stack.md`. */
-    name: string;
-    /** Full file content, frontmatter included, exactly as the other harnesses receive it. */
-    content: string;
-    /** `application`, `framework`, or undefined when the rule is not profile-specific. */
-    profile?: string;
-    /** Globs from `applyTo` and `paths`. Empty means the rule applies to every file. */
-    globs: string[];
-}
-
-const universalGlobs = new Set(['**', '**/*', '*']);
-
-function unquote(value: string): string {
-    return value.trim().replace(/^["']|["']$/g, '');
-}
-
-/**
- * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
- * `  - item` lines. Anything richer is not used by the rules and is deliberately not supported.
- */
-function frontmatter(content: string): Map<string, string[]> {
-    const fields = new Map<string, string[]>();
-    if (!content.startsWith('---\n')) return fields;
-    const end = content.indexOf('\n---\n', 4);
-    if (end < 0) return fields;
-    let current: string | undefined;
-    for (const line of content.slice(4, end).split('\n')) {
-        const item = /^\s+-\s+(.*)$/.exec(line);
-        if (item && current) {
-            fields.get(current)!.push(unquote(item[1]));
-            continue;
-        }
-        const scalar = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
-        if (!scalar) continue;
-        current = scalar[1];
-        const value = unquote(scalar[2]);
-        fields.set(current, value ? value.split(',').map(unquote).filter(Boolean) : []);
-    }
-    return fields;
-}
-
-function escapeRegExp(text: string): string {
-    return text.replace(/[.+^$()|[\]\\]/g, '\\$&');
-}
-
-/** Converts the glob dialect used by `applyTo` (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
-export function globToRegExp(glob: string): RegExp {
-    let pattern = '';
-    for (let index = 0; index < glob.length; index++) {
-        const character = glob[index];
-        if (character === '*') {
-            if (glob[index + 1] === '*') {
-                if (glob[index + 2] === '/') {
-                    pattern += '(?:.*/)?';
-                    index += 2;
-                } else {
-                    pattern += '.*';
-                    index += 1;
-                }
-            } else {
-                pattern += '[^/]*';
-            }
-        } else if (character === '?') {
-            pattern += '[^/]';
-        } else if (character === '{') {
-            const close = glob.indexOf('}', index);
-            if (close > index) {
-                pattern += `(?:${glob.slice(index + 1, close).split(',').map(part => escapeRegExp(part.trim())).join('|')})`;
-                index = close;
-            } else {
-                pattern += '\\{';
-            }
-        } else {
-            pattern += escapeRegExp(character);
-        }
-    }
-    return new RegExp(`^${pattern}$`);
-}
-
-function rulesRoot(cwd: string): string {
-    const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
-    return existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
-}
-
-function configuration(cwd: string): AiConfiguration | undefined {
-    const path = join(cwd, '.cratis', 'ai.json');
-    if (!existsSync(path)) return undefined;
-    try {
-        return JSON.parse(readFileSync(path, 'utf8')) as AiConfiguration;
-    } catch {
-        return undefined;
-    }
-}
-
-/**
- * A profile-specific rule is kept only when the repository selects that profile. Repositories without
- * a `.cratis/ai.json` keep every rule, matching the `@cratis/pi` package.
- */
-function matchesProfile(rule: ManagedRule, selected: AiConfiguration | undefined): boolean {
-    if (!rule.profile || !selected) return true;
-    const profiles = selected.profiles ?? [];
-    if (rule.profile === 'application') return profiles.some(profile => profile.startsWith('cratis/application'));
-    if (rule.profile === 'framework') return profiles.some(profile => profile.startsWith('cratis/engineering'));
-    return true;
-}
-
-/** Loads every managed rule with its frontmatter interpreted, filtered to the repository's profiles. */
-export function managedRules(cwd: string): ManagedRule[] {
-    const root = rulesRoot(cwd);
-    const selected = configuration(cwd);
-    return readdirSync(root, { recursive: true, encoding: 'utf8' })
-        .filter((entry): entry is string => entry.endsWith('.md'))
-        .sort()
-        .map(entry => {
-            const content = readFileSync(join(root, entry), 'utf8');
-            const fields = frontmatter(content);
-            return {
-                name: entry.split(sep).join('/'),
-                content,
-                profile: fields.get('profile')?.[0],
-                globs: [...(fields.get('applyTo') ?? []), ...(fields.get('paths') ?? [])],
-            } satisfies ManagedRule;
-        })
-        .filter(rule => matchesProfile(rule, selected));
-}
-
-/** Rules that apply to every file. These belong in the system prompt. */
-export function universalRules(cwd: string): ManagedRule[] {
-    return managedRules(cwd).filter(rule => rule.globs.length === 0 || rule.globs.some(glob => universalGlobs.has(glob)));
-}
-
-/** Rules whose `applyTo`/`paths` match a repository-relative path. These are delivered when that file is touched. */
-export function rulesForPath(cwd: string, relativePath: string): ManagedRule[] {
-    const normalized = relativePath.split(sep).join('/');
-    return managedRules(cwd).filter(rule =>
-        rule.globs.length > 0 &&
-        !rule.globs.some(glob => universalGlobs.has(glob)) &&
-        rule.globs.some(glob => globToRegExp(glob).test(normalized)));
-}
-
-/** Upper bound on files considered from one bash command, so a wide command cannot deliver the corpus. */
-const maxPathsPerCommand = 10;
+import { universalRules } from '../shared/rules.ts';
 
 /**
- * Extracts file paths a bash command refers to. `rtk.md` tells agents to run `rtk read`, `rtk grep`
- * and `rtk find` from the terminal for bulk reads, so file access frequently arrives as a bash
- * command rather than the read tool; without this, a session that follows that rule would never
- * receive a path-scoped rule. A token counts only when it resolves to a file that exists inside the
- * working directory, which keeps a filename mentioned inside a commit message from matching.
- */
-function pathsFromCommand(command: string, cwd: string): string[] {
-    const found: string[] = [];
-    for (const raw of command.split(/[\s;|&()<>]+/)) {
-        if (found.length >= maxPathsPerCommand) break;
-        const token = raw.replace(/^['"]+|['"]+$/g, '').replace(/[,:]+$/, '');
-        if (!token || token.startsWith('-') || !/[./]/.test(token)) continue;
-        try {
-            if (statSync(resolve(cwd, token)).isFile()) found.push(token);
-        } catch {
-            /* not a path we can see; ignore */
-        }
-    }
-    return found;
-}
-
-function touchedPaths(toolName: string, input: unknown, cwd: string): string[] {
-    if (toolName === 'bash' || toolName === 'powershell') {
-        const command = (input as { command?: unknown } | undefined)?.command;
-        return typeof command === 'string' ? pathsFromCommand(command, cwd) : [];
-    }
-    if (toolName !== 'read' && toolName !== 'write' && toolName !== 'edit') return [];
-    const candidate = (input as { path?: unknown; file_path?: unknown } | undefined);
-    const value = candidate?.path ?? candidate?.file_path;
-    return typeof value === 'string' && value.length > 0 ? [value] : [];
-}
-
-/**
- * Gives Pi the same rule semantics as the other harnesses: universal rules in the system prompt, and
- * path-scoped rules attached the first time a matching file is touched in the session. Without this,
- * every rule was concatenated into every turn regardless of `applyTo`, `paths`, or `profile`.
- *
- * Delivery happens on `tool_result`, so a rule arrives after the call that first touched its file.
- * `ToolCallEventResult` carries only `block`/`reason`/`terminate`, so there is no supported way to add
- * context before a tool runs. In practice a file is read before it is edited, and reads through both
- * the read tool and bash are covered, so the rule is present before the edit; a file created blind by
- * `write` is the residual case, and it receives the rule with that result.
+ * Puts the universal rules in the system prompt, giving Pi the same rule semantics as the other harnesses.
+ * Rules scoped by `applyTo`, `paths` or `profile` are not concatenated into every turn; the
+ * `cratis-path-guidance` extension attaches path-scoped rules the first time a matching file is touched.
  *
- * A delivered rule lives in the conversation rather than the system prompt, so anything that rewrites
- * or replaces the conversation can remove it. The delivery record is therefore reset whenever that
- * happens, and the rule is delivered again the next time one of its files is touched.
+ * The universal rules are a large, fixed cost on every turn (about 26k tokens), which is why a session that
+ * only wants path guidance and the hooks should load `cratis-path-guidance` and `cratis-hooks` instead.
  */
 export default function (pi: ExtensionAPI): void {
-    const delivered = new Set<string>();
-
-    // Compaction summarizes the conversation, which can drop an injected rule while leaving the
-    // delivery record claiming it is present; a switch replaces the conversation outright. Without
-    // this reset a long session would silently lose its scoped rules and never see them again.
-    const reset = () => {
-        delivered.clear();
-    };
-    pi.on('session_start', reset);
-    pi.on('session_compact', reset);
-    pi.on('session_before_switch', reset);
-
     pi.on('before_agent_start', (event, context) => ({
         systemPrompt: `${event.systemPrompt}\n\n${universalRules(context.cwd).map(rule => rule.content).join('\n\n')}`,
     }));
-
-    pi.on('tool_result', (event, context) => {
-        if (event.isError) return;
-        const paths = touchedPaths(event.toolName, (event as { input?: unknown }).input, context.cwd);
-        if (paths.length === 0) return;
-        const pending: ManagedRule[] = [];
-        const matched: string[] = [];
-        for (const path of paths) {
-            const relativePath = relative(context.cwd, resolve(context.cwd, path));
-            if (!relativePath || relativePath.startsWith('..')) continue;
-            for (const rule of rulesForPath(context.cwd, relativePath)) {
-                if (delivered.has(rule.name) || pending.some(candidate => candidate.name === rule.name)) continue;
-                pending.push(rule);
-                if (!matched.includes(relativePath)) matched.push(relativePath);
-            }
-        }
-        if (pending.length === 0) return;
-        pending.forEach(rule => delivered.add(rule.name));
-        const existing = Array.isArray(event.content) ? event.content : [];
-        return {
-            content: [
-                ...existing,
-                {
-                    type: 'text',
-                    text: `\n\n[cratis-rules] Rules that apply to ${matched.map(path => path.split(sep).join('/')).join(', ')}:\n\n${pending.map(rule => rule.content).join('\n\n')}`,
-                },
-            ],
-        };
-    });
 }

package/package/corpus/harnesses/pi/extensions/shared/AiConfiguration.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The parts of a repository's `.cratis/ai.json` that rule and skill selection read. */
+export interface AiConfiguration {
+    profiles?: string[];
+    languages?: string[];
+}

package/package/corpus/harnesses/pi/extensions/shared/ManagedRule.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export interface ManagedRule {
+    /** Path relative to the rules root, e.g. `code-quality-csharp.md` or `project/running-the-local-stack.md`. */
+    name: string;
+    /** Full file content, frontmatter included, exactly as the other harnesses receive it. */
+    content: string;
+    /** `application`, `framework`, or undefined when the rule is not profile-specific. */
+    profile?: string;
+    /** Globs from `applyTo` and `paths`. Empty means the rule applies to every file. */
+    globs: string[];
+}

package/package/corpus/harnesses/pi/extensions/shared/corpusRoot.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 { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The corpus this extension tree ships in: `.cratis/ai` for a managed installation and the repository,
+ * `package/corpus` inside the published `@cratis/pi` package. Both place `harnesses/pi/extensions/shared`
+ * four levels below it.
+ */
+export const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');

package/package/corpus/harnesses/pi/extensions/shared/frontmatter.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export function unquote(value: string): string {
+    return value.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
+ * `  - item` lines. Anything richer is not used by the rules and skills and is deliberately not supported.
+ */
+export function frontmatter(content: string): Map<string, string[]> {
+    const fields = new Map<string, string[]>();
+    if (!content.startsWith('---\n')) return fields;
+    const end = content.indexOf('\n---\n', 4);
+    if (end < 0) return fields;
+    let current: string | undefined;
+    for (const line of content.slice(4, end).split('\n')) {
+        const item = /^\s+-\s+(.*)$/.exec(line);
+        if (item && current) {
+            fields.get(current)!.push(unquote(item[1]));
+            continue;
+        }
+        const scalar = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+        if (!scalar) continue;
+        current = scalar[1];
+        const value = unquote(scalar[2]);
+        fields.set(current, value ? value.split(',').map(unquote).filter(Boolean) : []);
+    }
+    return fields;
+}

package/package/corpus/harnesses/pi/extensions/shared/globs.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Globs that match every file. A rule or skill that declares one is not scoped to a path. */
+export const universalGlobs = new Set(['**', '**/*', '*']);
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+
+/** Converts the glob dialect used by `applyTo` and `paths` (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+    let pattern = '';
+    for (let index = 0; index < glob.length; index++) {
+        const character = glob[index];
+        if (character === '*') {
+            if (glob[index + 1] === '*') {
+                if (glob[index + 2] === '/') {
+                    pattern += '(?:.*/)?';
+                    index += 2;
+                } else {
+                    pattern += '.*';
+                    index += 1;
+                }
+            } else {
+                pattern += '[^/]*';
+            }
+        } else if (character === '?') {
+            pattern += '[^/]';
+        } else if (character === '{') {
+            const close = glob.indexOf('}', index);
+            if (close > index) {
+                pattern += `(?:${glob.slice(index + 1, close).split(',').map(part => escapeRegExp(part.trim())).join('|')})`;
+                index = close;
+            } else {
+                pattern += '\\{';
+            }
+        } else {
+            pattern += escapeRegExp(character);
+        }
+    }
+    return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Why a glob cannot scope a skill trigger, or undefined when it can. A trigger must be a non-empty,
+ * repository-relative, balanced glob that does not match every file, otherwise it would either never fire
+ * or fire on every write.
+ */
+export function globProblem(glob: string): string | undefined {
+    if (glob.trim().length === 0) return 'is empty';
+    if (glob !== glob.trim()) return 'has leading or trailing whitespace';
+    if (glob.startsWith('/') || glob.includes('\\')) return 'must be a repository-relative glob using forward slashes';
+    if (universalGlobs.has(glob)) return 'matches every file';
+    if (glob.split('{').length !== glob.split('}').length) return 'has unbalanced braces';
+    try {
+        globToRegExp(glob);
+    } catch {
+        return 'does not compile to a matcher';
+    }
+    return undefined;
+}

package/package/corpus/harnesses/pi/extensions/shared/rules.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import type { AiConfiguration } from './AiConfiguration.ts';
+import { corpusRoot } from './corpusRoot.ts';
+import { frontmatter } from './frontmatter.ts';
+import { globToRegExp, universalGlobs } from './globs.ts';
+import type { ManagedRule } from './ManagedRule.ts';
+
+function rulesRoot(cwd: string): string {
+    const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
+    return existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
+}
+
+function configuration(cwd: string): AiConfiguration | undefined {
+    const path = join(cwd, '.cratis', 'ai.json');
+    if (!existsSync(path)) return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8')) as AiConfiguration;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * A profile-specific rule is kept only when the repository selects that profile. Repositories without
+ * a `.cratis/ai.json` keep every rule, matching the `@cratis/pi` package.
+ */
+function matchesProfile(rule: ManagedRule, selected: AiConfiguration | undefined): boolean {
+    if (!rule.profile || !selected) return true;
+    const profiles = selected.profiles ?? [];
+    if (rule.profile === 'application') return profiles.some(profile => profile.startsWith('cratis/application'));
+    if (rule.profile === 'framework') return profiles.some(profile => profile.startsWith('cratis/engineering'));
+    return true;
+}
+
+/**
+ * The packaged `@cratis/pi` corpus holds every rule, so the languages and documentation a repository selected
+ * decide which apply: a rule scoped to `.cs` files needs `csharp`, to `.ts` files needs `typescript`, and to
+ * Markdown needs the `cratis/documentation` profile. A repository that selects no languages keeps them all.
+ */
+function matchesSelection(name: string, applyTo: string[], selected: AiConfiguration | undefined): boolean {
+    const languages = selected?.languages ?? [];
+    if (!selected || languages.length === 0) return true;
+    const scope = applyTo.join(',');
+    const needsCSharp = scope.includes('.cs');
+    const needsTypeScript = scope.includes('.ts') || name === 'rtk.md' || name.endsWith('/rtk.md');
+    const needsDocumentation = scope.includes('md');
+    if (!needsCSharp && !needsTypeScript && !needsDocumentation) return true;
+    return (needsCSharp && languages.includes('csharp')) ||
+        (needsTypeScript && languages.includes('typescript')) ||
+        (needsDocumentation && (selected.profiles ?? []).includes('cratis/documentation'));
+}
+
+/**
+ * Loads every managed rule with its frontmatter interpreted, filtered to the repository's profiles. From the
+ * packaged corpus, which is not resolved for the repository, the selected languages and documentation apply as
+ * well. A managed `.cratis/ai/rules` is already resolved by the CLI, so that second filter is skipped there.
+ */
+export function managedRules(cwd: string): ManagedRule[] {
+    const root = rulesRoot(cwd);
+    const selected = configuration(cwd);
+    const resolved = existsSync(join(cwd, '.cratis', 'ai', 'rules'));
+    return readdirSync(root, { recursive: true, encoding: 'utf8' })
+        .filter((entry): entry is string => entry.endsWith('.md'))
+        .sort()
+        .map(entry => {
+            const content = readFileSync(join(root, entry), 'utf8');
+            const fields = frontmatter(content);
+            return {
+                rule: {
+                    name: entry.split(sep).join('/'),
+                    content,
+                    profile: fields.get('profile')?.[0],
+                    globs: [...(fields.get('applyTo') ?? []), ...(fields.get('paths') ?? [])],
+                } satisfies ManagedRule,
+                applyTo: fields.get('applyTo') ?? [],
+            };
+        })
+        .filter(({ rule, applyTo }) => matchesProfile(rule, selected) && (resolved || matchesSelection(rule.name, applyTo, selected)))
+        .map(({ rule }) => rule);
+}
+
+/** Rules that apply to every file. These belong in the system prompt. */
+export function universalRules(cwd: string): ManagedRule[] {
+    return managedRules(cwd).filter(rule => rule.globs.length === 0 || rule.globs.some(glob => universalGlobs.has(glob)));
+}
+
+/** Rules whose `applyTo`/`paths` match a repository-relative path. These are delivered when that file is touched. */
+export function rulesForPath(cwd: string, relativePath: string): ManagedRule[] {
+    const normalized = relativePath.split(sep).join('/');
+    return managedRules(cwd).filter(rule =>
+        rule.globs.length > 0 &&
+        !rule.globs.some(glob => universalGlobs.has(glob)) &&
+        rule.globs.some(glob => globToRegExp(glob).test(normalized)));
+}

package/package/corpus/harnesses/pi/extensions/shared/skillFrontmatter.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The `SKILL.md` frontmatter key that lists the globs a skill is hinted for. It is deliberately Cratis-specific:
+ * Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a "conditional skill" that stays out
+ * of the skill list until a matching file is touched), and `.claude/skills` exposes this corpus to it.
+ */
+export const skillTriggerKey = 'cratis-hint-paths';

package/package/corpus/harnesses/pi/extensions/shared/skillSelection.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 { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AiConfiguration } from './AiConfiguration.ts';
+import { corpusRoot } from './corpusRoot.ts';
+
+interface Profile {
+    id: string;
+    composes?: string[];
+    availableTargets?: string[];
+    languages?: string[];
+}
+
+interface Catalog {
+    publicProfiles: Profile[];
+    engineeringProfiles: Profile[];
+}
+
+/** The catalog beside the repository corpus (`.cratis/ai`), or beside `package/corpus` in the published package. */
+function catalog(): Profile[] | undefined {
+    const path = [join(corpusRoot, 'profile-catalog.json'), join(corpusRoot, '..', 'profile-catalog.json')].find(existsSync);
+    if (path === undefined) return undefined;
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Catalog;
+    return [...parsed.publicProfiles, ...parsed.engineeringProfiles];
+}
+
+function supportsLanguage(profile: Profile, languages: Set<string>): boolean {
+    if (!profile.languages?.length) return true;
+    return profile.languages.some(language => language === 'language-agnostic' || languages.has(language));
+}
+
+/**
+ * The skills the packaged `@cratis/pi` makes available for a repository, resolved from `.cratis/ai.json` and the
+ * profile catalog exactly as `selectedSkillPaths` in `@cratis/pi` does (a repository without `ai.json` gets every
+ * catalog skill, because that is what the package loads for it). Undefined when the selection cannot be resolved,
+ * so a caller hints nothing rather than guessing.
+ *
+ * This mirrors `Source/Pi.Plugin/src/index.ts`, which cannot import from the corpus in both the repository and
+ * the published layout; a specification keeps the two in step.
+ */
+export function selectedSkillNames(cwd: string): string[] | undefined {
+    try {
+        const profiles = catalog();
+        if (profiles === undefined) return undefined;
+        const configurationPath = join(cwd, '.cratis', 'ai.json');
+        if (!existsSync(configurationPath)) {
+            return [...new Set(profiles.flatMap(profile => profile.availableTargets ?? []))].sort();
+        }
+        const configuration = JSON.parse(readFileSync(configurationPath, 'utf8')) as AiConfiguration;
+        const languages = new Set(configuration.languages ?? []);
+        const selected = new Set<string>();
+        const select = (id: string, explicitSelection: boolean): void => {
+            const profile = profiles.find(candidate => candidate.id === id);
+            if (!profile) throw new Error(`Unknown Cratis AI profile '${id}'.`);
+            if (!explicitSelection && !supportsLanguage(profile, languages)) return;
+            if (selected.has(id)) return;
+            selected.add(id);
+            profile.composes?.forEach(child => select(child, false));
+        };
+        configuration.profiles?.forEach(profile => select(profile, true));
+        return [...new Set(profiles.filter(profile => selected.has(profile.id)).flatMap(profile => profile.availableTargets ?? []))].sort();
+    } catch {
+        return undefined;
+    }
+}

package/package/corpus/skills/cratis-application-react-specifications/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-application-react-specifications
 description: Write specifications for the React and TypeScript surface of a Cratis application slice — view models, helpers, command orchestration, and narrow component behavior — using Vitest with Mocha-style describe/it, Sinon, and the Chai should interface. Use when adding or changing frontend behavior in an application that consumes Cratis. Do not use for backend scenarios or for specifications inside a Cratis framework package.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
 ---
 
 # Cratis application React specifications

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-application-slice-specifications
 description: Specify the backend behavior of an event-sourced Cratis application slice with the in-process scenario family — CommandScenario, EventScenario, ReadModelScenario and ReactorScenario — including what to cover for each slice type and where the specification files live. Use when adding or changing backend behavior in an application built on Cratis. Do not use for framework library specifications and do not use for frontend behavior.
 license: MIT
+cratis-hint-paths:
+  - "**/when_*/**/*.cs"
+  - "**/for_*/**/*.cs"
 ---
 
 # Cratis application slice specifications

package/package/corpus/skills/cratis-documentation-writing/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-documentation-writing
 description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
 license: MIT
+cratis-hint-paths:
+  - "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Documentation writing
@@ -61,7 +63,13 @@ and neighboring pages; ask only when the alternatives change the outcome.
    targeted recipes, and exact reference. Give different languages or hosts
    their own procedures when a shared path cannot be run as written. A
    'coming from X' bridge should map familiar concepts to the new workflow,
-   not replace it.
+   not replace it. When a page shows several backends, state how they differ
+   once, in a "how the backends differ" table near the start: identity
+   source, id and response wire types, default authorization, live versus
+   snapshot queries, and unsupported features with their tracking issue.
+   Inside a step, write only what the current tab's reader needs. Across a
+   series, keep backend limitations in one table on the series index and link
+   it; don't repeat an issue-tracked limitation on every page.
 4. Draft in workflow order. For a tutorial, use one working domain throughout,
    show what to run and what appears, and recap before adding another concept.
    For a how-to, keep only what the specific task needs. Link out for details.
@@ -144,6 +152,12 @@ Never transcribe an API from memory, hand-translate an unsupported client, or
 claim a pasted block is runnable when it requires unstated setup. Show the
 command and observable output for a substantial walkthrough.
 
+Adding a backend or client to a product also changes pages the product's own
+checks don't scan, such as cross-product and site-level pages. Search them for
+single-language claims ("in C#", C#-only APIs presented as universal) and for
+series indexes whose description, reading order or production claims no longer
+hold.
+
 Edit the *authored* file, never a synced copy. The Cratis site derives each
 product page's edit link from that source path, so don't hand-author
 `editUrl` in product frontmatter. Recheck examples against the supported
@@ -157,8 +171,9 @@ wording, structure and examples as readers hit them.
 
 Read [Cratis site specifics](references/cratis-site.md) before writing a
 Cratis product page. It covers the teaching components (`YouWillLearn`,
-`Recap`, client tabs), maturity labeling, cross-product compatibility, the
-Prompter feedback signal, and who decides page structure.
+`Recap`, client tabs, including on site-owned pages), the variant-docs audit,
+maturity and preview labeling, cross-product compatibility, the Prompter
+feedback signal, and who decides page structure.
 
 ## Contextual awareness