@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/sessions/grok-build-cli.js

@@ -0,0 +1,196 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { lstat, open, realpath, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, parse, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { resolveGrokHomeResult } from '../providers/grok-build-paths.js';
+import { SessionContractError } from './contracts.js';
+import { validateGrokBuildMarkdown } from './adapters/grok-build.js';
+const execFile = promisify(execFileCallback);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_OUTPUT = 2_000_000;
+const TIMEOUT_MS = 15_000;
+export async function grokBuildList(options, limit = 20) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'Grok Build list limit must be 1..500');
+    }
+    const stdout = await runGrok(options, ['sessions', 'list', '--limit', String(limit)]);
+    return parseSessionIds(stdout, 'list');
+}
+export async function grokBuildSearch(options, query, limit = 20) {
+    if (!query.trim() || query.length > 500 || /[\x00-\x1f\x7f]/.test(query)) {
+        throw new SessionContractError('INVALID_SEARCH_QUERY', 'Grok Build search query must be nonempty plain text under 500 characters');
+    }
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'Grok Build search limit must be 1..500');
+    }
+    const stdout = await runGrok(options, ['sessions', 'search', query, '--limit', String(limit)]);
+    return parseSessionIds(stdout, 'search');
+}
+export async function grokBuildExport(options, sessionId, outputDirectory) {
+    const id = assertGrokSessionId(sessionId);
+    const directory = await safeDirectory(outputDirectory);
+    const stdout = await runGrok(options, ['export', id]);
+    if (Buffer.byteLength(stdout) > MAX_OUTPUT) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build export is not a bounded documented Markdown transcript');
+    }
+    validateGrokBuildMarkdown(stdout);
+    const destination = join(directory, `${id}.md`);
+    try {
+        await writeFile(destination, stdout.endsWith('\n') ? stdout : `${stdout}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new SessionContractError('IMPORT_CONFLICT', 'Grok Build export already exists; select a new output directory');
+        }
+        throw error;
+    }
+    return destination;
+}
+export function assertGrokSessionId(value) {
+    if (!UUID.test(value)) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'Grok Build session ID must be a UUID');
+    }
+    return value.toLowerCase();
+}
+export function parseGrokHeadlessSessionId(output, format) {
+    if (Buffer.byteLength(output) > MAX_OUTPUT) {
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build headless output exceeds 2 MB');
+    }
+    const lines = format === 'json' ? [output] : output.trim().split(/\r?\n/);
+    const ids = new Set();
+    for (const line of lines) {
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build headless output is not valid JSON');
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build headless event must be an object');
+        }
+        const id = value.sessionId;
+        if (id !== undefined) {
+            if (typeof id !== 'string' || !UUID.test(id)) {
+                throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build headless event has an invalid sessionId');
+            }
+            ids.add(id.toLowerCase());
+        }
+    }
+    if (ids.size !== 1) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build headless output must expose exactly one consistent sessionId');
+    }
+    return [...ids][0];
+}
+export async function grokHeadlessSessionIdFromFile(input, format) {
+    const path = resolve(input);
+    const parent = await safeDirectory(dirname(path));
+    if (dirname(path) !== parent) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'Grok Build headless output escapes its authorized directory');
+    }
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+        const item = await handle.stat();
+        if (!item.isFile() || item.size > MAX_OUTPUT) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build headless output must be a bounded regular file');
+        }
+        return parseGrokHeadlessSessionId(await handle.readFile('utf8'), format);
+    }
+    catch (error) {
+        if (error.code === 'ELOOP') {
+            throw new SessionContractError('SOURCE_SYMLINK', 'Grok Build headless output cannot be a symlink');
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function runGrok(options, args) {
+    const cwd = await safeDirectory(options.cwd);
+    const env = options.env ?? process.env;
+    const home = resolveGrokHomeResult(env);
+    if (!home.ok)
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', home.message);
+    await rejectSymlinkComponents(home.path);
+    const binary = options.binary ?? 'grok';
+    if (binary !== 'grok' && !isAbsolute(binary)) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build binary override must be absolute');
+    }
+    const runner = options.runner ?? execFile;
+    try {
+        const result = await runner(binary, ['--no-auto-update', ...args], {
+            cwd, env: { ...env, GROK_HOME: home.path, NO_COLOR: '1' },
+            timeout: TIMEOUT_MS, maxBuffer: MAX_OUTPUT,
+        });
+        if (Buffer.byteLength(result.stdout) > MAX_OUTPUT) {
+            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build CLI output exceeds 2 MB');
+        }
+        return result.stdout;
+    }
+    catch (error) {
+        if (error instanceof SessionContractError)
+            throw error;
+        if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Build CLI output exceeds 2 MB');
+        }
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Build CLI failed or timed out; check the local `grok` installation, authentication, and selected workspace.');
+    }
+}
+function parseSessionIds(stdout, mode) {
+    const ids = [];
+    let recognized = false;
+    for (const line of stdout.split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        if (line === 'No sessions found.' || line.startsWith('SESSION ID ') || line.startsWith('Label: ')
+            || line === '(no label)' || /^Total: \d+$/.test(line)) {
+            recognized = true;
+            continue;
+        }
+        const id = /^([0-9a-f-]{36})(?:\s|$)/i.exec(line)?.[1];
+        if (id && UUID.test(id)) {
+            ids.push(id.toLowerCase());
+            recognized = true;
+            continue;
+        }
+        if (mode === 'search' && /^  \S/.test(line) && recognized)
+            continue;
+        throw new SessionContractError('SCHEMA_DRIFT', `unrecognized Grok Build ${mode} output; check CLI version`);
+    }
+    if (!recognized) {
+        throw new SessionContractError('SCHEMA_DRIFT', `empty Grok Build ${mode} output; check CLI version`);
+    }
+    return [...new Set(ids)];
+}
+async function safeDirectory(input) {
+    if (!isAbsolute(input) || parse(resolve(input)).root === resolve(input)) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build directory must be an absolute non-root path');
+    }
+    await rejectSymlinkComponents(input);
+    const canonical = await realpath(input);
+    if (!(await lstat(canonical)).isDirectory()) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Build directory must exist and be a directory');
+    }
+    return canonical;
+}
+async function rejectSymlinkComponents(input) {
+    let current = resolve(input);
+    while (current !== parse(current).root) {
+        try {
+            if ((await lstat(current)).isSymbolicLink()) {
+                throw new SessionContractError('SOURCE_SYMLINK', 'Grok Build path contains a symlink');
+            }
+        }
+        catch (error) {
+            if (error instanceof SessionContractError)
+                throw error;
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        current = dirname(current);
+    }
+}
+//# sourceMappingURL=grok-build-cli.js.map

package/dist/src/sessions/index.js

@@ -34,9 +34,12 @@ export * from './adapters/opencode.js';
 export * from './adapters/openclaw.js';
 export * from './adapters/openhuman.js';
 export * from './adapters/grokbot.js';
+export * from './adapters/grok-build.js';
+export * from './grok-build-cli.js';
 export * from './adapters/pi.js';
 export * from './adapters/deepseek-harness.js';
 export * from './adapters/warp.js';
 export * from './adapters/windsurf.js';
+export * from './adapters/muse.js';
 export * from './adapters/omp.js';
 //# sourceMappingURL=index.js.map

package/dist/src/sessions/workspace-discovery.js

@@ -16,8 +16,8 @@ import { redactSourceLocator } from './discovery.js';
 import { fingerprintSourceFile } from './readers.js';
 export const DISCOVERY_MANIFEST_VERSION = '1.0.0';
 const MANUAL_EXPORT_PROVIDERS = new Set([
-    'copilot', 'hermes', 'opencode', 'openclaw', 'openhuman', 'grokbot',
-    'warp', 'devin-desktop', 'generic',
+    'copilot', 'hermes', 'opencode', 'openclaw', 'openhuman', 'grokbot', 'grok-build',
+    'warp', 'devin-desktop', 'muse', 'generic',
 ]);
 export async function discoverWorkspaceHistories(options) {
     const workspacePath = await canonicalPath(options.workspace);
@@ -127,9 +127,13 @@ export async function discoverWorkspaceHistories(options) {
         if (reports.has(provider))
             continue;
         const manual = MANUAL_EXPORT_PROVIDERS.has(provider);
-        reports.set(provider, providerReport(provider, manual ? 'export-required' : 'not-checked', manual ? 'manual-export' : 'unsupported', [], manual ? 'EXPLICIT_EXPORT_REQUIRED' : 'PROVIDER_NOT_CHECKED', manual
-            ? `Select and authorize a supported ${provider} export before importing it.`
-            : `No discovery strategy is registered for ${provider}.`));
+        const grokBuild = provider === 'grok-build';
+        reports.set(provider, providerReport(provider, manual ? 'export-required' : 'not-checked', manual ? 'manual-export' : 'unsupported', [], grokBuild ? 'CLI_EXPORT_REQUIRED'
+            : manual ? 'EXPLICIT_EXPORT_REQUIRED' : 'PROVIDER_NOT_CHECKED', grokBuild
+            ? 'Run `grok sessions list` or `grok sessions search`, then export an authorized session with `grok export <id> <id>.md`; Grok Build resolves $GROK_HOME itself.'
+            : manual
+                ? `Select and authorize a supported ${provider} export before importing it.`
+                : `No discovery strategy is registered for ${provider}.`));
     }
     const sources = candidates.sort(compareSources);
     const providers = [...reports.values()].sort((a, b) => a.provider.localeCompare(b.provider));

package/dist/src/skills/deployer.js

@@ -16,6 +16,7 @@ import { AGENT_SKILLS_SIDECAR_SCHEMA, AIWG_SKILL_CONTROL_FIELDS, createAgentSkil
 import { getImportedAgentSkill } from './importer.js';
 import { validateAgentSkillContent } from './validator.js';
 import { resolveHermesHomePath } from '../providers/hermes-home.js';
+import { museXdgSkillsDirRemediation, resolveMuseXdgSkillsDir, } from '../providers/muse-paths.js';
 import { GROKBOT_SKILLS_DIR_ENV, grokbotMissingRootRemediation, resolveGrokbotSkillsDir, } from '../providers/grokbot-paths.js';
 export const AGENT_SKILL_MANAGED_MARKER = '.aiwg-managed';
 export const AGENT_SKILL_DEPLOYMENT_SIDECAR = '.aiwg-agent-skill.json';
@@ -101,6 +102,33 @@ function resolvePolicy(target, options) {
             }
             reasons.push('uses the active HERMES_HOME skills surface with strict managed ownership markers');
             break;
+        case 'muse': {
+            // ADR scope rule 1: the default projection is the project
+            // <repo>/.agents/skills surface shared with antigravity, codex, and
+            // deepseek-harness. Muse reads both that root and its XDG user root,
+            // so writing the user root by default would list a skill twice.
+            // #234: an explicit user scope resolves the documented XDG root at
+            // deploy time — never ~/.muse — and bad XDG metadata fails closed.
+            if (options.scope === 'user') {
+                const home = resolvedHome(options);
+                const configured = resolveMuseXdgSkillsDir(process.env, home);
+                if (!configured) {
+                    root = '';
+                    status = 'unsupported';
+                    supported = false;
+                    reasons.push(museXdgSkillsDirRemediation(process.env, home));
+                    warnings.push('Agent Skills deploy for muse requires a valid absolute XDG_CONFIG_HOME; no filesystem root was invented');
+                }
+                else {
+                    root = configured;
+                    reasons.push('uses the Muse XDG user skills root ($XDG_CONFIG_HOME/muse/skills, default ~/.config/muse/skills) with strict managed ownership markers');
+                }
+            }
+            else {
+                reasons.push('uses the project .agents/skills surface shared with antigravity, codex, and deepseek-harness');
+            }
+            break;
+        }
         case 'openhuman':
             status = 'projected';
             reasons.push('uses the verified global one-level ~/.openhuman/skills layout');
@@ -307,13 +335,13 @@ function readDeploymentSidecar(targetPath, expectedName, expectedProvider) {
     }
 }
 /**
- * Codex, Antigravity, and DeepSeek Harness intentionally consume the same
- * portable project skill surface. A projection written for any member is
- * managed ownership for the others when the desired payload is otherwise
- * byte-identical.
+ * Codex, Antigravity, DeepSeek Harness, and Muse intentionally consume the
+ * same portable project skill surface (<repo>/.agents/skills). A projection
+ * written for any member is managed ownership for the others when the
+ * desired payload is otherwise byte-identical.
  */
 function providersShareProjectionSurface(actual, expected) {
-    const shared = new Set(['antigravity', 'codex', 'deepseek-harness']);
+    const shared = new Set(['antigravity', 'codex', 'deepseek-harness', 'muse']);
     return actual === expected || (shared.has(actual) && shared.has(expected));
 }
 function buildProjectionPlan(record, options) {

package/dist/src/smiths/context-pipeline/claude-hook.js

@@ -23,6 +23,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { buildProviderBootstrapBlock, PROVIDER_BOOTSTRAP_START, PROVIDER_BOOTSTRAP_END, } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
+import { assertSafeContextFile } from './context-file-safety.js';
 export const CLAUDE_HOOK_START = '<!-- AIWG:claude-md-hook:start -->';
 export const CLAUDE_HOOK_END = '<!-- AIWG:claude-md-hook:end -->';
 function buildClaudeArtifactOutputPolicy(policy = {}) {
@@ -65,6 +66,7 @@ export function buildClaudeHookBlock(policy = {}) {
  */
 export async function ensureClaudeMdHook(projectPath, opts = {}) {
     const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    await assertSafeContextFile(claudeMdPath);
     const result = {
         claudeMdPath,
         action: 'skipped',

package/dist/src/smiths/context-pipeline/context-file-safety.js

@@ -0,0 +1,18 @@
+import { lstat } from 'node:fs/promises';
+import { basename } from 'node:path';
+/** Never read or update a provider instruction file through a filesystem link. */
+export async function assertSafeContextFile(filePath) {
+    let stat;
+    try {
+        stat = await lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`Refusing unsafe ${basename(filePath)} target: ${filePath}`);
+    }
+}
+//# sourceMappingURL=context-file-safety.js.map

package/dist/src/smiths/context-pipeline/finalization.js

@@ -7,47 +7,16 @@
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 import { renderTrackerProtocol, resolveTrackerAuthority } from '../../tracker/capability-protocol.js';
+import { readConfig, readGitRemoteUrls } from '../../tracker/project-inputs.js';
 import { buildExternalLinksSection, replaceOrAppendExternalLinksBlock, } from './external-links-section.js';
 export const FINALIZATION_START = '<!-- aiwg-context-finalization:START -->';
 export const FINALIZATION_END = '<!-- aiwg-context-finalization:END -->';
 const AIWG_SIGNATURE_COMMENT = '<!-- aiwg-managed -->';
-const execFileAsync = promisify(execFile);
 function formatList(values) {
     return values.length > 0 ? values.join(', ') : 'none recorded';
 }
-async function readConfig(projectPath) {
-    try {
-        return await readAiwgConfig(projectPath);
-    }
-    catch {
-        return null;
-    }
-}
-async function readGitRemoteUrls(projectPath) {
-    try {
-        const { stdout } = await execFileAsync('git', ['-C', projectPath, 'remote', '-v'], {
-            maxBuffer: 1024 * 1024,
-        });
-        const urls = {};
-        for (const line of stdout.split(/\r?\n/)) {
-            const match = line.match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
-            if (!match)
-                continue;
-            const [, name, url, direction] = match;
-            if (direction === 'fetch' || !urls[name])
-                urls[name] = url;
-        }
-        return urls;
-    }
-    catch {
-        return {};
-    }
-}
 function displayProjectPath(projectPath, targetPath) {
     const relative = path.relative(projectPath, targetPath).replace(/\\/g, '/');
     if (relative && !relative.startsWith('..') && !path.isAbsolute(relative))

package/dist/src/smiths/context-pipeline/generator.js

@@ -20,6 +20,7 @@ import { writeNormalizedAiwgMd } from './finalization.js';
 import { shouldEmitAgentsMd, shouldEmitAiwgMd, shouldEmitClaudeMdHook } from './provider-policy.js';
 import { ensureClaudeMdHook } from './claude-hook.js';
 import { ensureManagedHook } from './managed-hook.js';
+import { assertSafeContextFile } from './context-file-safety.js';
 import { buildProviderBootstrapBlock, ensureWorkspaceContext, registerProviderContext, } from './workspace-context.js';
 import { projectControlPath } from '../../config/project-artifacts.js';
 const SECTION_TITLES = {
@@ -344,6 +345,17 @@ async function writeSpilloverBlock(projectPath, spilloverMarkdown, result) {
  * is present; otherwise it is skipped with a warning.
  */
 export async function generate(opts) {
+    // Check every startup/context output before writing the first one. A linked
+    // AGENTS.md or CLAUDE.md must not become an input to generated context, even
+    // when an additive hook or forced backup would otherwise read it.
+    const plannedFiles = [
+        ...(!opts.skip?.workspaceMd ? ['WORKSPACE.md'] : []),
+        ...(!opts.skip?.agentsMd && shouldEmitAgentsMd(opts.provider) ? ['AGENTS.md'] : []),
+        ...(!opts.skip?.aiwgMd && shouldEmitAiwgMd(opts.provider) ? ['AIWG.md'] : []),
+        ...(shouldEmitClaudeMdHook(opts.provider) ? ['CLAUDE.md'] : []),
+    ];
+    for (const file of plannedFiles)
+        await assertSafeContextFile(path.join(opts.projectPath, file));
     const result = {
         workspaceMdPath: '',
         aiwgMdPath: '',

package/dist/src/smiths/context-pipeline/index.js

@@ -22,7 +22,7 @@ export { generate, buildAgentsMd, renderEntry, renderSection, isOverwriteSafe, }
 export { sanitizeDescription, sanitizeTag, sanitizeTags } from './sanitizer.js';
 export { checkPathAllowed } from './allowlist.js';
 export { discoverDeployedArtifacts, discoverSection, } from './discovery.js';
-export { AGENTS_MD_PROVIDERS, shouldEmitContextFiles, shouldEmitAiwgMd, shouldEmitAgentsMd, shouldEmitClaudeMdHook, } from './provider-policy.js';
+export { AGENTS_MD_PROVIDERS, shouldEmitContextFiles, shouldEmitAiwgMd, shouldEmitAgentsMd, shouldEmitClaudeMdHook, buildMuseBridgeText, } from './provider-policy.js';
 export { generateAiwgMd } from './aiwg-md.js';
 export { CLAUDE_HOOK_START, CLAUDE_HOOK_END, buildClaudeHookBlock, ensureClaudeMdHook, } from './claude-hook.js';
 export { FINALIZATION_START, FINALIZATION_END, buildContextFinalizationBlock, buildNormalizedAiwgMd, replaceOrAppendFinalizationBlock, writeNormalizedAiwgMd, } from './finalization.js';

package/dist/src/smiths/context-pipeline/managed-hook.js

@@ -15,6 +15,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { buildProviderBootstrapBlock } from './workspace-context.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
+import { assertSafeContextFile } from './context-file-safety.js';
 export const CONTEXT_HOOK_START = '<!-- AIWG:context-hook:start -->';
 export const CONTEXT_HOOK_END = '<!-- AIWG:context-hook:end -->';
 /** The managed block — loads canonical workspace context before framework context. */
@@ -42,6 +43,7 @@ export function hasContextHook(content) {
  * operator-authored content. Additive by default (no `--force` needed).
  */
 export async function ensureManagedHook(filePath, opts = {}) {
+    await assertSafeContextFile(filePath);
     const base = path.basename(filePath);
     let block = buildContextHookBlock(opts.provider);
     const result = { path: filePath, action: 'skipped', warnings: [] };

package/dist/src/smiths/context-pipeline/muse-bridge.js

@@ -0,0 +1,50 @@
+/**
+ * Muse-native discover-first bridge text for the AGENTS.md managed section
+ * (#227).
+ *
+ * Muse Code reads project AGENTS.md natively — but only after the workspace
+ * is explicitly trusted (first-run trust prompt). The bridge therefore leads
+ * with the trust-gated load, follows the Muse-native instruction order
+ * (this AGENTS.md first, then WORKSPACE.md, then AIWG.md), and states the
+ * discover-first protocol (`aiwg discover` / `aiwg show`) with no auto-load
+ * claims for other AIWG paths. Artifact references and one-sentence
+ * summaries only — never full bodies — per
+ * docs/architecture/adr-muse-provider-target.md. No CLAUDE.md shim, no
+ * foreign-provider context file.
+ *
+ * Deterministic: static text only — no timestamps, no randomness — so
+ * `aiwg regenerate --provider muse` produces byte-identical output.
+ *
+ * This module is intentionally dependency-free: the bridge text is consumed
+ * by `buildProviderBootstrapBlock` (workspace-context.ts), which must not
+ * pull provider-policy.ts's module-evaluation side effects into every
+ * import graph.
+ *
+ * @issue #227
+ */
+export function buildMuseBridgeText() {
+    return [
+        'This file is the discover-first AIWG bridge for Muse Code. Muse loads',
+        'project AGENTS.md natively — but only after the workspace is explicitly',
+        'trusted (first-run trust prompt). Until the workspace is trusted, this',
+        'file does not load: trust the workspace when prompted, then start a new',
+        'Muse session so the bridge is read.',
+        '',
+        'Instruction order: this AGENTS.md first, then [WORKSPACE.md](./WORKSPACE.md)',
+        'for project/operator context, then [AIWG.md](./AIWG.md) (canonical source:',
+        '`.aiwg/AIWG.md`) for AIWG discovery, quickrefs, and framework routing.',
+        'Plain Markdown links are explicit reading instructions; AIWG does not',
+        'claim Muse auto-loads any other AIWG path on its own.',
+        '',
+        'Before improvising on any AIWG capability: run `aiwg discover "<intent>"`,',
+        'then `aiwg show <type> <name>` for the artifact you need. Prefer indexed',
+        'agents, skills, rules, and commands over guessing. Store artifact',
+        'references and one-sentence summaries only — never paste full artifact',
+        'bodies into context or memory.',
+        '',
+        'After `aiwg regenerate` or a redeploy, trust the workspace again if',
+        'prompted and start a new Muse session to re-read this file. Changes are',
+        'not picked up by reloading an IDE window.',
+    ].join('\n');
+}
+//# sourceMappingURL=muse-bridge.js.map

package/dist/src/smiths/context-pipeline/provider-policy.js

@@ -61,4 +61,9 @@ export function shouldEmitAgentsMd(provider) {
 export function shouldEmitClaudeMdHook(provider) {
     return getProviderDefinition(provider)?.paths.contextFiles.claudeMdHook ?? false;
 }
+// The Muse discover-first bridge text lives in ./muse-bridge.js (kept
+// dependency-free so consumers like buildProviderBootstrapBlock do not pull
+// this module's evaluation side effects into every import graph). Re-export
+// it here so the provider-policy surface stays the canonical policy home.
+export { buildMuseBridgeText } from './muse-bridge.js';
 //# sourceMappingURL=provider-policy.js.map

package/dist/src/smiths/context-pipeline/workspace-context.js

@@ -12,6 +12,7 @@ import * as path from 'node:path';
 import { buildAiwgMdContent } from './aiwg-md.js';
 import { buildNormalizedAiwgMd } from './finalization.js';
 import { getProviderDefinition, listProviderDefinitions, } from '../../providers/provider-definitions.js';
+import { buildMuseBridgeText } from './muse-bridge.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { projectAiwgPath, projectControlPath, resolveProjectAiwgDir, } from '../../config/project-artifacts.js';
 import { dominantLineEnding, withLineEnding } from './line-endings.js';
@@ -490,24 +491,29 @@ export function buildProviderBootstrapBlock(provider) {
         'guidance. Platform capability and safety constraints remain absolute; see WORKSPACE.md',
         '"Precedence" for the capability-versus-directive distinction.',
     ];
-    const loading = contract.loadMode === 'native-include'
-        ? [
-            'Load the canonical project context first, then the generated AIWG framework context:',
-            '',
-            provider === 'omp' ? '@../WORKSPACE.md' : '@WORKSPACE.md',
-            provider === 'omp' ? '@../AIWG.md' : '@AIWG.md',
-        ]
-        : contract.loadMode === 'config-registration'
+    // #227: Muse gets its own discover-first bridge text — Muse-native
+    // instruction order (this AGENTS.md first, then WORKSPACE.md, then AIWG.md)
+    // plus the trust-gated load caveat — instead of the generic prose-directive.
+    const loading = provider === 'muse'
+        ? [buildMuseBridgeText()]
+        : contract.loadMode === 'native-include'
             ? [
-                'WORKSPACE.md and AIWG.md are registered through the provider configuration.',
-                'Read and follow WORKSPACE.md first; use AIWG.md second for AIWG discovery and routing.',
-            ]
-            : [
-                'Read and follow [WORKSPACE.md](./WORKSPACE.md) first.',
-                'Then read [AIWG.md](./AIWG.md) for AIWG discovery, quickrefs, and framework routing.',
+                'Load the canonical project context first, then the generated AIWG framework context:',
                 '',
-                'These are explicit reading instructions. Plain Markdown links are not claimed to auto-load.',
-            ];
+                provider === 'omp' ? '@../WORKSPACE.md' : '@WORKSPACE.md',
+                provider === 'omp' ? '@../AIWG.md' : '@AIWG.md',
+            ]
+            : contract.loadMode === 'config-registration'
+                ? [
+                    'WORKSPACE.md and AIWG.md are registered through the provider configuration.',
+                    'Read and follow WORKSPACE.md first; use AIWG.md second for AIWG discovery and routing.',
+                ]
+                : [
+                    'Read and follow [WORKSPACE.md](./WORKSPACE.md) first.',
+                    'Then read [AIWG.md](./AIWG.md) for AIWG discovery, quickrefs, and framework routing.',
+                    '',
+                    'These are explicit reading instructions. Plain Markdown links are not claimed to auto-load.',
+                ];
     return [
         PROVIDER_BOOTSTRAP_START,
         '',

package/dist/src/smiths/hook-bridge/grok-build-translator.js

@@ -0,0 +1,64 @@
+/** Grok Build hook translator. Deployment writes project JSON only; trust remains an operator action. */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+export const GROK_EVENT_MAP = {
+    SessionStart: 'SessionStart',
+    SessionEnd: 'SessionEnd',
+    UserPromptSubmit: 'UserPromptSubmit',
+    PreToolUse: 'PreToolUse',
+    PostToolUse: 'PostToolUse',
+    Stop: 'Stop',
+};
+function safeId(id) {
+    return /^[a-z0-9][a-z0-9-]{0,62}$/.test(id) ? id : null;
+}
+export async function translateForGrokBuild(source, options) {
+    const result = { provider: 'grok-build', emittedPaths: [], warnings: [], skipped: false };
+    if (source.degradeOn?.includes('grok-build'))
+        return { ...result, skipped: true, skipReason: 'degrade-on declared grok-build' };
+    const id = safeId(source.id);
+    if (!id)
+        return { ...result, skipped: true, skipReason: 'hook id is not a safe Grok file name' };
+    const mapped = source.events.map(event => GROK_EVENT_MAP[event]).filter((event) => Boolean(event));
+    const unsupported = source.events.filter(event => !GROK_EVENT_MAP[event]);
+    if (unsupported.length)
+        result.warnings.push(`Unsupported Grok hook events: ${unsupported.join(', ')}`);
+    if (!mapped.length)
+        return { ...result, skipped: true, skipReason: 'no equivalent Grok hook events' };
+    const hooksDir = path.resolve(options.projectPath, '.grok', 'hooks');
+    const filePath = path.resolve(hooksDir, `aiwg-${id}.json`);
+    if (!filePath.startsWith(`${hooksDir}${path.sep}`))
+        return { ...result, skipped: true, skipReason: 'hook path escapes project hook root' };
+    const hooks = Object.fromEntries(mapped.map(event => [event, [{ hooks: [{ type: 'command', command: [source.command, ...(source.args || [])].join(' '), timeout: 10 }] }]]));
+    const document = { _aiwg_managed: true, _aiwg_id: id, hooks };
+    result.warnings.push('Project hook emitted without granting Grok trust; use /hooks-trust separately after review.');
+    if (source.events.includes('PreToolUse')) {
+        result.warnings.push('Only explicit PreToolUse JSON denial blocks; crashes, timeouts, malformed output, and all passive hook failures fail open.');
+    }
+    if (options.dryRun) {
+        result.emittedPaths.push(`${filePath} (dry-run)`);
+        return result;
+    }
+    await fs.mkdir(hooksDir, { recursive: true });
+    const dirInfo = await fs.lstat(hooksDir);
+    if (dirInfo.isSymbolicLink())
+        throw new Error('Refusing to write Grok hooks through a symbolic link');
+    try {
+        const info = await fs.lstat(filePath);
+        if (info.isSymbolicLink() || !info.isFile())
+            throw new Error('Refusing unsafe Grok hook target');
+        const current = JSON.parse(await fs.readFile(filePath, 'utf8'));
+        if (current._aiwg_managed !== true || current._aiwg_id !== id)
+            throw new Error(`Refusing to replace operator-managed Grok hook ${filePath}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const temp = `${filePath}.tmp-${process.pid}`;
+    await fs.writeFile(temp, `${JSON.stringify(document, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    await fs.rename(temp, filePath);
+    result.emittedPaths.push(filePath);
+    return result;
+}
+//# sourceMappingURL=grok-build-translator.js.map

package/dist/src/smiths/hook-bridge/index.js

@@ -13,6 +13,7 @@ import { translateForCodex } from './codex-translator.js';
 import { translateForCopilot } from './copilot-translator.js';
 import { translateForFactory } from './factory-translator.js';
 import { translateForHermes } from './hermes-translator.js';
+import { translateForGrokBuild } from './grok-build-translator.js';
 import { getProviderDefinition } from '../../providers/provider-definitions.js';
 export { AIWG_ENV_VARS, NATIVE_ENV_VAR_MAP } from './types.js';
 export { substituteEnvVars, generateShimBash, EXIT_CODE_MAP } from './shim.js';
@@ -20,6 +21,7 @@ export { translateForCodex, renderCodexHookToml, injectHookBlock as injectCodexH
 export { translateForCopilot } from './copilot-translator.js';
 export { translateForFactory } from './factory-translator.js';
 export { translateForHermes } from './hermes-translator.js';
+export { translateForGrokBuild, GROK_EVENT_MAP } from './grok-build-translator.js';
 export { loadHookSources } from './loader.js';
 /**
  * Provider id → translator function. Adding a new provider requires:
@@ -34,6 +36,7 @@ export const TRANSLATORS = {
     copilot: translateForCopilot,
     factory: translateForFactory,
     hermes: translateForHermes,
+    'grok-build': translateForGrokBuild,
 };
 function resolveHookTranslator(providerId) {
     const adapterKey = getProviderDefinition(providerId)?.adapters.hookBridge ?? providerId;