buddy-agent-harness 0.6.0 → 0.7.0

package/src/diagnose-mcp/mcp-secrets.ts

@@ -0,0 +1,101 @@
+import type { McpServer } from './mcp-model.ts'
+
+/**
+ * Finding a literal credential in MCP configuration, without ever handling one.
+ *
+ * `doctor` is safe to run from a session-start hook, so its output lands in agent context on every
+ * session and from there into transcripts. A value it echoes is amplified far past the file it came
+ * from. Every function here answers **where**, never **what**: the return is a field path, and the
+ * value never leaves this module.
+ *
+ * That is also why the redaction lives here rather than in a formatter. `doctor` renders three ways
+ * — TOON, `--format text`, and `--format json` — and trusting each of them to mask is three chances
+ * to drift. A value that never enters the finding cannot be printed by any of them.
+ */
+
+/**
+ * Words that mark a field as credential-bearing wherever they appear in its name. Each is one that
+ * effectively never turns up inside an innocent word, so a bare substring test is safe and catches
+ * the run-together spellings a segment test would miss — `MYTOKEN`, `githubsecret`.
+ */
+const credentialWord = /token|secret|password|passwd|credential/i
+
+/**
+ * Words that mark a field only when they are a **segment** of its name. `key` and `auth` are the
+ * two that matter, and both are common inside words that carry nothing — `MONKEY`, `AUTHOR`,
+ * `KEYSTONE_URL`. Matching them as substrings reports those, and a scanner that cries wolf on a
+ * hook-run command is one people stop reading.
+ */
+const credentialSegment = new Set(['key', 'apikey', 'auth', 'authorization', 'bearer'])
+
+/** A field name split the two ways these are written: `API_KEY` and `apiKey` alike. */
+function segmentsOf(key: string): string[] {
+	return key
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean)
+		.map((segment) => segment.toLowerCase())
+}
+
+/**
+ * A value that **names** a secret instead of holding one, in the forms the supported hosts
+ * document: `${VAR}`, `$VAR`, and the `${env:VAR}` / `${input:id}` variants.
+ *
+ * Classification is by shape, not by content. An entropy test on the value would be a guess about
+ * a string this module has already decided not to look at, and it would fail in both directions —
+ * a short password is low-entropy and a base64 configuration blob is high.
+ */
+const reference = /\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*/
+
+/**
+ * A credential-bearing field passes when it carries a reference anywhere in it, because the common
+ * legitimate form is a template rather than a bare variable — `Bearer ${LINEAR_TOKEN}` is the
+ * documented way to write an authorization header, and requiring the whole value to be a reference
+ * would report every correct one.
+ */
+function holdsLiteral(value: string): boolean {
+	return !reference.test(value)
+}
+
+function credentialKey(key: string): boolean {
+	return credentialWord.test(key) || segmentsOf(key).some((segment) => credentialSegment.has(segment))
+}
+
+/**
+ * Whether a URL carries a credential in itself. Two shapes: a password in the userinfo component,
+ * and a credential-named query parameter holding a literal. Neither value is read past the test.
+ *
+ * A URL that does not parse is not reported. It is malformed rather than leaky, and guessing at its
+ * structure with a regular expression is how a scanner starts matching the thing it must not touch.
+ */
+function urlHoldsCredential(value: string): boolean {
+	let url: URL
+	try {
+		url = new URL(value)
+	} catch {
+		return false
+	}
+	if (url.password) return true
+	for (const [key, parameter] of url.searchParams) if (credentialKey(key) && holdsLiteral(parameter)) return true
+	return false
+}
+
+function literalsIn(field: 'env' | 'headers', values: Readonly<Record<string, string>> | undefined): string[] {
+	return Object.entries(values ?? {})
+		.filter(([key, value]) => credentialKey(key) && holdsLiteral(value))
+		.map(([key]) => `${field}.${key}`)
+}
+
+/**
+ * Every field of one server holding a literal credential, as a path within that server.
+ *
+ * The path is the whole answer. It is never a truncated value: `sk-ab…` is a leak into the same
+ * transcript and buys a reader nothing the field name does not already give them.
+ */
+export function credentialFields(server: McpServer): string[] {
+	return [
+		...literalsIn('env', server.env),
+		...literalsIn('headers', server.headers),
+		...(server.url && urlHoldsCredential(server.url) ? ['url'] : []),
+	]
+}

package/src/diagnose-mcp/mcp-sources.ts

@@ -0,0 +1,131 @@
+import { parse as parseToml } from 'smol-toml'
+import { parseJsonWithComments } from '../diagnose-bridges/json-with-comments.ts'
+import type { Position } from '../diagnose-bridges/locator.ts'
+import type { McpConfig } from '../harness-registry/mcp-config.ts'
+import { isRecord } from '../is-record/is-record.ts'
+import type { McpServer, McpTransport } from './mcp-model.ts'
+
+/** Where the golden set lives, and why it is namespaced rather than sitting at `.agents/mcp.json`. */
+export const goldenSetPath = '.agents/buddy-agent-harness/mcp.toml'
+
+/** The table the golden set keeps its servers under. */
+const goldenKey = 'servers'
+
+export type ParsedServers =
+	/** The file is absent. Nothing to compare, and not a fault. */
+	| { kind: 'absent' }
+	| { kind: 'servers'; servers: Map<string, McpServer> }
+	| { kind: 'unreadable'; position?: Position | undefined }
+
+function stringMap(value: unknown): Record<string, string> | undefined {
+	if (!isRecord(value)) return undefined
+	const entries = Object.entries(value).filter(([, item]) => typeof item === 'string') as [string, string][]
+	return entries.length ? Object.fromEntries(entries) : undefined
+}
+
+const transports = new Set<string>(['stdio', 'http', 'sse'])
+
+/**
+ * The transport a host entry describes. Hosts spell it `type` (Claude Code, VS Code) or
+ * `transport`, and several state it nowhere and leave it implied by which of `url` and `command`
+ * is present. Inferring it is what lets a `url` entry in one file compare equal to a `type: http`
+ * entry in another.
+ */
+function transportOf(entry: Record<string, unknown>): McpTransport | undefined {
+	const declared = entry['type'] ?? entry['transport']
+	if (typeof declared === 'string' && transports.has(declared)) return declared as McpTransport
+	if (typeof entry['url'] === 'string') return 'http'
+	if (typeof entry['command'] === 'string') return 'stdio'
+	return undefined
+}
+
+/**
+ * One host entry, or one golden entry, in the canonical model. The two formats carry the same
+ * field names — the divergence between hosts is the file, the top-level key, and the serialization,
+ * not the entry — so one reader serves both directions of the comparison.
+ *
+ * A field whose value is the wrong type is dropped rather than carried through. A `timeout` that
+ * is a string is not a timeout, and letting it into the model would report a divergence whose real
+ * cause is a typo the finding does not name.
+ */
+function serverFrom(entry: Record<string, unknown>): McpServer {
+	const args = Array.isArray(entry['args']) && entry['args'].every((item) => typeof item === 'string')
+	const transport = transportOf(entry)
+	const env = stringMap(entry['env'])
+	const headers = stringMap(entry['headers'])
+	return {
+		...(transport ? { transport } : {}),
+		...(typeof entry['command'] === 'string' ? { command: entry['command'] } : {}),
+		...(args ? { args: entry['args'] as string[] } : {}),
+		...(env ? { env } : {}),
+		...(typeof entry['url'] === 'string' ? { url: entry['url'] } : {}),
+		...(headers ? { headers } : {}),
+		...(typeof entry['description'] === 'string' ? { description: entry['description'] } : {}),
+		...(typeof entry['enabled'] === 'boolean' ? { enabled: entry['enabled'] } : {}),
+		...(typeof entry['timeout'] === 'number' ? { timeout: entry['timeout'] } : {}),
+		...(typeof entry['source'] === 'string' ? { source: entry['source'] } : {}),
+	}
+}
+
+function serversUnder(document: unknown, key: string): Map<string, McpServer> {
+	const table = isRecord(document) ? document[key] : undefined
+	if (!isRecord(table)) return new Map()
+	return new Map(
+		Object.entries(table)
+			.filter(([, entry]) => isRecord(entry))
+			.map(([name, entry]) => [name, serverFrom(entry as Record<string, unknown>)]),
+	)
+}
+
+/**
+ * The position out of a thrown parse error, and nothing else out of it.
+ *
+ * `smol-toml` reports `line` and `column` on the error alongside a `codeblock` quoting the source,
+ * and its `message` embeds that same code block. Both are unusable: in a file of MCP configuration
+ * the line a parser failed on is exactly the line holding the credential. Only the two numbers are
+ * read, and anything thrown that does not carry them is reported without a position rather than by
+ * reaching for its message.
+ *
+ * Exported because that restriction is the point of the function rather than an implementation
+ * detail of it, and it is verified directly.
+ */
+export function positionOf(error: unknown): Position | undefined {
+	if (!isRecord(error)) return undefined
+	const { line, column } = error
+	return typeof line === 'number' && typeof column === 'number' ? { line, column } : undefined
+}
+
+/** The golden set, parsed. Absent is the common case and is not a fault. */
+export function parseGoldenSet(source: string | undefined): ParsedServers {
+	if (source === undefined) return { kind: 'absent' }
+	try {
+		return { kind: 'servers', servers: serversUnder(parseToml(source), goldenKey) }
+	} catch (error) {
+		return { kind: 'unreadable', position: positionOf(error) }
+	}
+}
+
+/**
+ * One harness's MCP configuration, parsed. The file is read for its own key and nothing else:
+ * `.gemini/settings.json` also carries the instruction bridge, and a reader that treated the whole
+ * file as MCP would report the rest of a user's settings as servers it does not recognize.
+ *
+ * JSON is parsed with comments stripped, because Gemini CLI's loader strips them too and a
+ * settings file may legally carry them.
+ */
+export function parseTarget(config: McpConfig, source: string | undefined): ParsedServers {
+	if (source === undefined) return { kind: 'absent' }
+	if (config.format === 'toml') {
+		try {
+			return { kind: 'servers', servers: serversUnder(parseToml(source), config.key) }
+		} catch {
+			return { kind: 'unreadable' }
+		}
+	}
+	const document = parseJsonWithComments(source)
+	// `parseJsonWithComments` answers `undefined` for a file that does not parse. A file whose
+	// literal content is `null` parses and holds no servers, which reads the same here and is
+	// reported the same way it would be for `{}`.
+	if (document === undefined) return { kind: 'unreadable' }
+	return { kind: 'servers', servers: serversUnder(document, config.key) }
+}

package/src/diagnose-nonstandard/diagnose-nonstandard.ts

@@ -0,0 +1,109 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { filesUnder } from '../diagnose-bridges/directory-files.ts'
+import { type NonstandardProblem, type RepairAction, repairFor } from '../diagnose-bridges/doctor-guidance.ts'
+import { harnessRegistry } from '../harness-registry/harness-registry.ts'
+import type { NonstandardArtifact, NonstandardKind } from '../harness-registry/nonstandard-artifact.ts'
+
+/**
+ * The fifth section of `doctor`: configuration that works for exactly one harness.
+ *
+ * The other four ask whether something is broken. This one asks how far what is there reaches, and
+ * reports the answer when it is "one harness". Nothing here is a fault — a Cursor rule does what it
+ * says — so nothing here is repaired by correcting it. Each finding names the canonical form it
+ * would convert to, so a repository can be walked toward one where every harness file is generated
+ * from a canonical source rather than authored beside it.
+ *
+ * Read-only, like every other part of `doctor`.
+ */
+export type NonstandardFinding = {
+	/** Repository-relative path of the artifact, POSIX-separated. */
+	path: string
+	problem: NonstandardProblem
+	detail: string
+	/** The conversion. `command` is always empty: every one of these is judgment about content. */
+	repair: RepairAction
+}
+
+export type DiagnoseNonstandardOptions = {
+	root: string
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+const problemOf: Record<NonstandardKind, NonstandardProblem> = {
+	instructions: 'nonstandard-instructions',
+	rule: 'nonstandard-rule',
+	command: 'nonstandard-command',
+	skill: 'nonstandard-skill',
+	subagent: 'nonstandard-subagent',
+}
+
+/**
+ * A `.mdc` rule splits on whether its scoping is load-bearing. `globs:` with a value binds the rule
+ * to paths, and `AGENTS.md` has no equivalent — it scopes by directory nesting only — so that one
+ * converts to a skill, or stays. Without it the rule is always-on prose, which `AGENTS.md` holds
+ * verbatim. Read from frontmatter rather than assumed, because the two need different conversions
+ * and guessing wrong sends prose to the wrong destination.
+ */
+function scopedByGlobs(body: string): boolean {
+	const block = /^---\n([\s\S]*?)\n---/.exec(body)
+	if (!block) return false
+	const globs = /^globs:[ \t]*(.*)$/m.exec(block[1] as string)
+	const value = globs?.[1]?.trim()
+	return value !== undefined && value.length > 0 && value !== '[]'
+}
+
+/** Every skill directory below `directory`, named by its `SKILL.md`. */
+function skillFiles(directory: string): string[] {
+	return filesUnder(directory).filter((file) => file.endsWith('SKILL.md'))
+}
+
+/**
+ * A harness directory that is a symlink is a projection someone already made, not configuration
+ * authored here — reporting it would tell a repository to convert what it already converted.
+ */
+function authoredHere(path: string): boolean {
+	try {
+		return !lstatSync(path).isSymbolicLink()
+	} catch {
+		return false
+	}
+}
+
+function artifactFiles(root: string, artifact: NonstandardArtifact): string[] {
+	const absolute = join(root, artifact.path)
+	// A path that is not there fails this too — `lstat` throws and the catch reads as "not ours".
+	if (!authoredHere(absolute)) return []
+	if (artifact.shape === 'file') return [artifact.path]
+	const below = artifact.kind === 'skill' ? skillFiles(absolute) : filesUnder(absolute)
+	return below.map((file) => posix.join(artifact.path, file))
+}
+
+/**
+ * Unlike the other detectors this takes no harness preference and no enabled set. An artifact is
+ * reachable by one harness whether or not that harness is enabled here — a `.cursorrules` in a
+ * repository nobody opens in Cursor is still instruction content `AGENTS.md` does not carry — so
+ * filtering by the enabled set would hide exactly the drift worth converting.
+ */
+export function diagnoseNonstandard({ root, cli }: DiagnoseNonstandardOptions): NonstandardFinding[] {
+	const findings: NonstandardFinding[] = []
+
+	for (const harness of harnessRegistry) {
+		for (const artifact of harness.project.nonstandard ?? []) {
+			for (const path of artifactFiles(root, artifact)) {
+				const kind =
+					artifact.kind === 'rule' && path.endsWith('.mdc') && !scopedByGlobs(readFileSync(join(root, path), 'utf8'))
+						? 'instructions'
+						: artifact.kind
+				const problem = problemOf[kind]
+				const { detail, repair } = repairFor(problem)
+				findings.push({ path, problem, detail, repair: repair({ file: path }, cli) })
+			}
+		}
+	}
+
+	// No dedupe: one artifact is declared by one harness, and `harness-registry.test.ts` holds that
+	// invariant. Collapsing a duplicate here would hide the registry mistake rather than surface it.
+	return findings.sort((left, right) => left.path.localeCompare(right.path))
+}

package/src/harness-registry/harness-registry.ts

@@ -1,6 +1,8 @@
 import { lstatSync } from 'node:fs'
 import { join } from 'node:path'
 import type { InstructionBridge } from './instruction-bridge.ts'
+import type { McpConfig } from './mcp-config.ts'
+import type { NonstandardArtifact } from './nonstandard-artifact.ts'
 
 export type HarnessName =
 	| 'claude-code'
@@ -24,6 +26,15 @@ export type HarnessScopeName = 'project' | 'user'
  * `skillsDirectory` is the projection target the harness needs to see `.agents/skills` at this
  * scope. A harness that reads `.agents/skills` natively there has none, and is never projected into.
  *
+ * `mcpConfig` is where this harness keeps its MCP servers at this scope. Unlike the other two it
+ * is not a bridge into a canonical file the harness cannot read — it is the harness's own
+ * configuration, which `doctor` compares against the golden set and never writes.
+ *
+ * `nonstandard` is what this harness reads that no other harness can. Unlike the three above it is
+ * not something the tool maintains — it is what a repository accumulated before it was canonical,
+ * and `doctor` reports it so it can be converted. Declared here because the paths are per harness
+ * and belong beside the harness's other paths, not in a second list that would drift from this one.
+ *
  * `instructionBridge` is the same question for `AGENTS.md`: what the harness needs at this scope in
  * order to read it. It belongs per scope for the same reason `skillsDirectory` does — the file
  * differs. Unlike `skillsDirectory`, the `init` command does not write it; the `init` skill does. It
@@ -33,6 +44,8 @@ export type HarnessScope = {
 	detect: string
 	skillsDirectory?: string
 	instructionBridge?: InstructionBridge
+	mcpConfig?: McpConfig
+	nonstandard?: readonly NonstandardArtifact[]
 }
 
 export type Harness = {
@@ -75,28 +88,108 @@ export const harnessRegistry: readonly Harness[] = [
 			detect: '.claude',
 			skillsDirectory: '.claude/skills',
 			instructionBridge: { kind: 'import', path: 'CLAUDE.md' },
+			mcpConfig: { path: '.mcp.json', key: 'mcpServers', format: 'json' },
+			nonstandard: [
+				{ path: '.claude/commands', shape: 'directory', kind: 'command' },
+				{ path: '.claude/rules', shape: 'directory', kind: 'rule' },
+				{ path: '.claude/agents', shape: 'directory', kind: 'subagent' },
+			],
 		},
 		user: { detect: '.claude', skillsDirectory: '.claude/skills' },
 	},
-	{ name: 'cursor', project: { detect: '.cursor' }, user: { detect: '.cursor' } },
-	{ name: 'codex', project: { detect: '.codex' }, user: { detect: '.codex' } },
-	{ name: 'copilot-cli', project: { detect: '.github/skills' }, user: { detect: '.copilot' } },
+	{
+		name: 'cursor',
+		project: {
+			detect: '.cursor',
+			mcpConfig: { path: '.cursor/mcp.json', key: 'mcpServers', format: 'json' },
+			nonstandard: [
+				{ path: '.cursorrules', shape: 'file', kind: 'instructions' },
+				{ path: '.cursor/rules', shape: 'directory', kind: 'rule' },
+				{ path: '.cursor/commands', shape: 'directory', kind: 'command' },
+				{ path: '.cursor/skills', shape: 'directory', kind: 'skill' },
+			],
+		},
+		user: { detect: '.cursor' },
+	},
+	{
+		name: 'codex',
+		project: {
+			detect: '.codex',
+			mcpConfig: { path: '.codex/config.toml', key: 'mcp_servers', format: 'toml' },
+			nonstandard: [{ path: '.codex/skills', shape: 'directory', kind: 'skill' }],
+		},
+		user: { detect: '.codex' },
+	},
+	{
+		name: 'copilot-cli',
+		project: {
+			detect: '.github/skills',
+			nonstandard: [
+				{ path: '.github/copilot-instructions.md', shape: 'file', kind: 'instructions' },
+				{ path: '.github/instructions', shape: 'directory', kind: 'instructions' },
+				{ path: '.github/skills', shape: 'directory', kind: 'skill' },
+			],
+		},
+		user: { detect: '.copilot' },
+	},
 	{
 		name: 'gemini-cli',
 		project: {
 			detect: '.gemini',
 			instructionBridge: { kind: 'settings-entry', path: '.gemini/settings.json', key: 'context.fileName' },
+			mcpConfig: { path: '.gemini/settings.json', key: 'mcpServers', format: 'json', shared: true },
+			nonstandard: [
+				{ path: 'GEMINI.md', shape: 'file', kind: 'instructions' },
+				{ path: '.gemini/skills', shape: 'directory', kind: 'skill' },
+			],
 		},
 		user: { detect: '.gemini' },
 	},
 	{ name: 'devin-desktop', project: { detect: '.devin' } },
 	{
 		name: 'windsurf',
-		project: { detect: '.windsurf', skillsDirectory: '.windsurf/skills' },
+		project: {
+			detect: '.windsurf',
+			skillsDirectory: '.windsurf/skills',
+			nonstandard: [
+				{ path: '.windsurfrules', shape: 'file', kind: 'instructions' },
+				{ path: '.windsurf/rules', shape: 'directory', kind: 'rule' },
+			],
+		},
 		deprecated: 'devin-desktop',
 	},
 ]
 
+const harnessNames = new Set<string>(harnessRegistry.map((harness) => harness.name))
+
+function isHarnessName(value: string): value is HarnessName {
+	return harnessNames.has(value)
+}
+
+/**
+ * The `--harness` option, as names this registry knows. Both commands take the option and neither
+ * owns what a name means, so the parse lives beside the list it validates against: a harness added
+ * to the registry is accepted by both commands with nothing else to change, and the rejection reads
+ * the same either way.
+ *
+ * An unknown name throws rather than being dropped. A caller that asked for a harness by name and
+ * got a report about the two default ones has been told the wrong thing about their repository.
+ */
+export function parseHarnesses(value: string | undefined): HarnessName[] {
+	const requested = (value ?? '')
+		.split(',')
+		.map((name) => name.trim())
+		.filter(Boolean)
+	const unsupported = requested.filter((name) => !isHarnessName(name))
+	if (unsupported.length)
+		throw new Error(
+			`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
+				.map((harness) => harness.name)
+				.join(', ')}.`,
+		)
+	return requested.filter(isHarnessName)
+}
+
 /** Enabled whether or not the repository already contains their directories. */
 const defaultHarnesses: readonly HarnessName[] = ['claude-code', 'cursor']
 

package/src/harness-registry/mcp-config.ts

@@ -0,0 +1,37 @@
+/**
+ * Where one harness keeps its MCP server configuration at one scope, as that harness's own vendor
+ * documents it.
+ *
+ * Recorded per scope like everything else in a `HarnessScope`, and populated at **project** scope
+ * only. Much of the world's MCP configuration lives at user scope — `~/.codex/config.toml`,
+ * `~/.claude.json`, `claude_desktop_config.json` — and the registry records user scope as
+ * described and diagnosable, never written. Reading a user's home directory into output that
+ * lands in every session's transcript is a wider blast radius than diagnosis needs, so those paths
+ * stay out until something needs them.
+ *
+ * A harness with no documented project-scope MCP file gets no entry. Copilot CLI is the case that
+ * matters: its own documentation states that `.vscode/mcp.json` "is not read by Copilot CLI", and
+ * names `~/.copilot/mcp-config.json` instead. That is a documented absence, not a gap — see
+ * `.research/mcp-canonical-location/` (E-MCP-11).
+ */
+export type McpConfig = {
+	/** Repository-relative path of the file, as the vendor documents it. */
+	path: string
+	/**
+	 * The key the servers sit under. Not one key across hosts: `mcpServers` for Claude Code, Cursor,
+	 * and Gemini CLI, `mcp_servers` for Codex, `servers` for VS Code. Reading the wrong one finds
+	 * nothing and reports a repository as unconfigured.
+	 */
+	key: string
+	/**
+	 * How the file is serialized. It decides the parser, and it is also why comparison is semantic:
+	 * the same server in TOML and in JSON shares no bytes.
+	 */
+	format: 'json' | 'toml'
+	/**
+	 * Set when the file holds far more than MCP configuration. `.gemini/settings.json` also carries
+	 * the instruction bridge, so anything reading it must take its key and leave the rest alone —
+	 * and anything writing it must never rewrite the file wholesale.
+	 */
+	shared?: true
+}

package/src/harness-registry/nonstandard-artifact.ts

@@ -0,0 +1,39 @@
+/**
+ * Configuration a harness reads that no other harness can, declared per harness beside the paths
+ * `doctor` already knows about it.
+ *
+ * These are not faults. Every one of them works — for exactly one harness — which is the whole
+ * problem: the guidance in a Cursor rule reaches Cursor and nothing else, and nobody finds out
+ * except by noticing an agent behaving differently in another tool. `doctor` surfaces them so they
+ * can be converted, one at a time, toward a repository whose agent configuration is canonical and
+ * whose harness files are generated from it. Zero of these is the north star, not a release gate.
+ *
+ * `kind` carries the conversion, because the canonical form differs per kind and nothing else about
+ * the artifact does. It is what a finding routes on.
+ */
+export type NonstandardKind =
+	/** Prose an `AGENTS.md` can hold verbatim. The harness file becomes a generated bridge. */
+	| 'instructions'
+	/**
+	 * A rule scoped to paths. A skill is the portable form *where the scoping is incidental* — a
+	 * skill is loaded on relevance rather than by glob, so guidance whose whole point is "these
+	 * files and no others" has no equivalent yet, and converting it would lose the scoping.
+	 */
+	| 'rule'
+	/** A harness command. Claude Code merged commands into skills, so a skill is the portable form. */
+	| 'command'
+	/** A skill kept under a harness directory rather than the canonical one. */
+	| 'skill'
+	/** A subagent. No cross-harness format exists, so surfacing it *is* reporting that gap. */
+	| 'subagent'
+
+export type NonstandardArtifact = {
+	/**
+	 * Repository-relative path. A file is reported as itself; a directory is reported per file
+	 * below it, so each one can be converted on its own rather than as an all-or-nothing batch.
+	 */
+	path: string
+	/** Whether `path` names one file or a directory to walk. */
+	shape: 'file' | 'directory'
+	kind: NonstandardKind
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export { run } from './cli.ts'
 export type {
 	BridgeFinding,
 	BridgeKind,
@@ -14,8 +15,17 @@ export type {
 	InstructionStatus,
 } from './diagnose-bridges/diagnose-instructions.ts'
 export { diagnoseInstructions } from './diagnose-bridges/diagnose-instructions.ts'
-export { doctorCommand } from './diagnose-bridges/doctor.command.ts'
-export type { BridgeProblem, DoctorProblem, InstructionProblem, Repair } from './diagnose-bridges/doctor-guidance.ts'
+export type { DoctorReport } from './diagnose-bridges/doctor.command.ts'
+export { buildDoctorReport, doctorCommand } from './diagnose-bridges/doctor.command.ts'
+export type {
+	BridgeProblem,
+	ConfigurationFault,
+	ConfigurationProblem,
+	DoctorProblem,
+	InstructionProblem,
+	McpProblem,
+	Repair,
+} from './diagnose-bridges/doctor-guidance.ts'
 export {
 	bridgeRepairs,
 	doctorRepairs,
@@ -24,9 +34,15 @@ export {
 	renderDoctorSkill,
 } from './diagnose-bridges/doctor-guidance.ts'
 export type { DivergenceDirection } from './diagnose-bridges/git-bridge-state.ts'
+export type { DiagnoseMcpOptions } from './diagnose-mcp/diagnose-mcp.ts'
+export { diagnoseMcp } from './diagnose-mcp/diagnose-mcp.ts'
+export type { McpDirection } from './diagnose-mcp/mcp-baseline.ts'
+export type { McpField, McpServer, McpTransport } from './diagnose-mcp/mcp-model.ts'
+export { goldenSetPath } from './diagnose-mcp/mcp-sources.ts'
 export type { Harness, HarnessName, HarnessScope, HarnessScopeName } from './harness-registry/harness-registry.ts'
 export { harnessRegistry } from './harness-registry/harness-registry.ts'
 export type { InstructionBridge } from './harness-registry/instruction-bridge.ts'
+export type { McpConfig } from './harness-registry/mcp-config.ts'
 export { activate, harnessCommand, initCommand } from './initialize-harnesses/init.command.ts'
 export type { InitializeOptions, InitializeResult } from './initialize-harnesses/initialize-harnesses.ts'
 export { initializeHarnesses } from './initialize-harnesses/initialize-harnesses.ts'

package/src/initialize-harnesses/init.command.ts

@@ -1,8 +1,9 @@
 import type { cli } from 'clibuilder'
-import { command, z } from 'clibuilder'
+import { command, exitCodes, z } from 'clibuilder'
 import { parseFormat, writeResult } from '../command-output/command-output.ts'
 import { doctorCommand } from '../diagnose-bridges/doctor.command.ts'
-import { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'
+import { parseHarnesses } from '../harness-registry/harness-registry.ts'
+import { parseForce } from '../skill-projection/skill-projection.ts'
 import { initializeHarnesses } from './initialize-harnesses.ts'
 
 export const initCommand: cli.Command = command({
@@ -22,8 +23,9 @@ export const initCommand: cli.Command = command({
 			type: z.optional(z.boolean()),
 		},
 		force: {
-			description: 'Replace conflicting target skill directories.',
-			type: z.optional(z.boolean()),
+			description:
+				'Replace conflicting target skill directories. Names the targets to replace, comma-separated (e.g. .claude/skills); given alone it replaces every conflicting target.',
+			type: z.optional(z.string()),
 		},
 		format: {
 			description: 'Output format: toon (default), json, or text for a human-readable report.',
@@ -34,29 +36,22 @@ export const initCommand: cli.Command = command({
 	run(args) {
 		try {
 			const format = parseFormat(args.format)
-			const requested = args.harness
-				?.split(',')
-				.map((name) => name.trim())
-				.filter(Boolean)
-			const unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))
-			if (unsupported?.length)
-				throw new Error(
-					`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
-						.map((harness) => harness.name)
-						.join(', ')}.`,
-				)
+			const harnesses = parseHarnesses(args.harness)
 			writeResult(
 				initializeHarnesses({
 					root: args.root ?? process.cwd(),
-					...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),
+					...(harnesses.length ? { harnesses } : {}),
 					...(args.copy === undefined ? {} : { copy: args.copy }),
-					...(args.force === undefined ? {} : { force: args.force }),
+					...(args.force === undefined ? {} : { force: parseForce(args.force) }),
 				}),
 				format,
 			)
+			return exitCodes.success
 		} catch (error) {
 			process.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness initialization failed.'}\n`)
-			process.exitCode = 1
+			// Returned, not written: a command that writes the code reports its failure past `run`
+			// rather than to it, leaving a caller that is not the process no way to learn of it.
+			return exitCodes.error
 		}
 	},
 })