@skanl/brambo-environment 0.1.1

package/dist/executors.js

@@ -0,0 +1,109 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CLAUDE_MCP_TRAITS, CODEX_CONFIG_TRAITS, OPENCODE_CONFIG_TRAITS, readNativeMcpEntries, CLAUDE_MCP_TARGET_ID, CLAUDE_SKILLS_TARGET_ID, CODEX_CONFIG_TARGET_ID, CODEX_SKILLS_TARGET_ID, OPENCODE_CONFIG_TARGET_ID, OPENCODE_SKILLS_TARGET_ID, createClaudeMcpTarget, createClaudeSkillsTarget, createCodexConfigTarget, createCodexSkillsTarget, createOpenCodeConfigTarget, createOpenCodeSkillsTarget, } from '@skanl/brambo-projection';
+export const EXECUTOR_PROFILES = [
+    {
+        executorId: 'claude-code',
+        targetId: CLAUDE_MCP_TARGET_ID,
+        // `~/.claude` is the directory Claude Code creates for itself; `~/.claude.json`
+        // is the file it reads MCP servers from. Either one is evidence it has run
+        // here. The home directory itself is deliberately not evidence — it exists on
+        // every machine and would make detection answer "yes" unconditionally.
+        evidencePaths: (homeDir) => [join(homeDir, '.claude.json'), join(homeDir, '.claude')],
+        machineConfig: (homeDir) => join(homeDir, '.claude.json'),
+        projectConfig: (projectDir) => join(projectDir, '.mcp.json'),
+        createTarget: (filePath) => createClaudeMcpTarget({ filePath }),
+        readMcpEntries: async (filePath) => await readNativeMcpEntries(CLAUDE_MCP_TRAITS, { filePath }),
+        machineSkills: (homeDir) => join(homeDir, '.claude', 'skills'),
+        skillsTargetId: CLAUDE_SKILLS_TARGET_ID,
+        createSkillsTarget: (rootPath) => createClaudeSkillsTarget({ rootPath }),
+        // `settings.json`, NOT `~/.claude.json`: correction-01 measured that the
+        // previous build wrote `$.brambo.{tools,mcpServers,skills,hooks}` there, into
+        // a file whose schema has none of those keys. Brambo's corrected target does
+        // not touch this file at all, which is exactly why nothing would ever clean
+        // it without this entry.
+        legacyConfig: (homeDir) => ({
+            filePath: join(homeDir, '.claude', 'settings.json'),
+            fileFormat: 'jsonc',
+        }),
+    },
+    {
+        executorId: 'codex',
+        targetId: CODEX_CONFIG_TARGET_ID,
+        // ponytail: no `projectConfig`, because Codex reads MCP servers from
+        // `~/.codex/config.toml` alone — correction-01 verified no project-scope
+        // location, and brambo does not invent one. Consequence, reported per run
+        // rather than silent: `brambo project init` cannot bind Codex to a project.
+        // Upgrade path: a verified per-project Codex config, if Codex grows one.
+        evidencePaths: (homeDir) => [join(homeDir, '.codex', 'config.toml'), join(homeDir, '.codex')],
+        machineConfig: (homeDir) => join(homeDir, '.codex', 'config.toml'),
+        projectConfig: undefined,
+        createTarget: (filePath) => createCodexConfigTarget({ filePath }),
+        readMcpEntries: async (filePath) => await readNativeMcpEntries(CODEX_CONFIG_TRAITS, { filePath }),
+        machineSkills: (homeDir) => join(homeDir, '.codex', 'skills'),
+        skillsTargetId: CODEX_SKILLS_TARGET_ID,
+        createSkillsTarget: (rootPath) => createCodexSkillsTarget({ rootPath }),
+        // The harmful one. A `# BEGIN brambo-managed` block here carries foreign
+        // sub-keys inside `[tools]` and `[skills]`, which are real fixed structs, so
+        // a documented `--strict-config` run fails to load the ENTIRE file.
+        legacyConfig: (homeDir) => ({
+            filePath: join(homeDir, '.codex', 'config.toml'),
+            fileFormat: 'toml',
+        }),
+    },
+    {
+        executorId: 'opencode',
+        targetId: OPENCODE_CONFIG_TARGET_ID,
+        evidencePaths: (homeDir) => [
+            join(homeDir, '.config', 'opencode', 'opencode.json'),
+            join(homeDir, '.config', 'opencode'),
+        ],
+        machineConfig: (homeDir) => join(homeDir, '.config', 'opencode', 'opencode.json'),
+        projectConfig: (projectDir) => join(projectDir, 'opencode.json'),
+        createTarget: (filePath) => createOpenCodeConfigTarget({ filePath }),
+        readMcpEntries: async (filePath) => await readNativeMcpEntries(OPENCODE_CONFIG_TRAITS, { filePath }),
+        machineSkills: (homeDir) => join(homeDir, '.config', 'opencode', 'skills'),
+        skillsTargetId: OPENCODE_SKILLS_TARGET_ID,
+        createSkillsTarget: (rootPath) => createOpenCodeSkillsTarget({ rootPath }),
+        // The same file brambo's corrected target merges into, so the reserved key
+        // sits beside the `mcp` entries brambo writes today; it is dropped at decode
+        // (`onExcessProperty: 'ignore'`) and read by nothing.
+        legacyConfig: (homeDir) => ({
+            filePath: join(homeDir, '.config', 'opencode', 'opencode.json'),
+            fileFormat: 'jsonc',
+        }),
+    },
+];
+async function evidenceFor(path) {
+    try {
+        await stat(path);
+        return { path, exists: true };
+    }
+    catch (error) {
+        const code = error?.code;
+        // ENOENT and ENOTDIR are the two definitive absences: the path is not there,
+        // or a component of it is a file. Every other errno — EACCES, EPERM, ELOOP,
+        // an unreadable home — is brambo unable to LOOK, which is a different fact
+        // and is reported as one.
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { path, exists: false };
+        return { path, exists: undefined, error: code ?? String(error) };
+    }
+}
+/**
+ * Every executor brambo knows about, whether it was found, and the exact paths
+ * consulted for each. Returns the FULL catalogue on purpose: a run that detects
+ * nothing has to be able to tell the user what was looked for and where, and a
+ * list that omitted the misses could not.
+ */
+export async function detectExecutors(homeDir) {
+    return await Promise.all(EXECUTOR_PROFILES.map(async (profile) => {
+        const evidence = await Promise.all(profile.evidencePaths(homeDir).map(evidenceFor));
+        return {
+            executorId: profile.executorId,
+            targetId: profile.targetId,
+            present: evidence.some((candidate) => candidate.exists === true),
+            evidence,
+        };
+    }));
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { PROJECTION_ACTION_ID, initMachine, initProject, noExecutorsDetected, deliveryFor, scopeDirectory, storeFor, type EntryDelivery, type InitMachineOptions, type InitProjectOptions, type InitResult, type LegacyBlock, type SkippedExecutor, type TargetFailure, type TargetProjection, type UnprojectableEntry, } from './init.ts';
+export { DIAGNOSIS_FINDING_KINDS, FINDING_EXITS, diagnose, findingKindsFor, hasProblem, type Diagnosis, type DiagnoseOptions, type DiagnosisFinding, type DiagnosisFindingKind, type DiagnosisFindingSeverity, type DiagnosisTarget, type FindingExit, type WorktreeLeftover, } from './doctor.ts';
+export { remediate, type RemediateOptions, type RemediationReport } from './remediate.ts';
+export { EXECUTOR_PROFILES, detectExecutors, type EvidencePath, type ExecutorDetection, type ExecutorProfile } from './executors.ts';
+export { RegistryStore } from '@skanl/brambo-registry';
+export type { RegistryStoreOptions } from '@skanl/brambo-registry';
+export { BUNDLE_KIND, BUNDLE_VERSION, OMITTED_FIELDS, createBundle, isCredential, parseBundle, readBundle, serializeBundle, writeBundle } from '@skanl/brambo-registry';
+export type { OmittedEntry, OmittedField, RegistryBundle } from '@skanl/brambo-registry';
+export { DRIFT_KINDS, BRAMBO_VERSION, REGISTRY_ENTRY_TYPES, REMEDIATION_KINDS, REMOVABLE_ENTRY_TYPES, RETIRED_ENTRY_TYPES, expandRegistryEntryPaths, isRetiredEntryType, } from '@skanl/brambo-contracts';
+export type { DriftEntry, DriftKind, BramboErrorCode, ProjectionWarning, RegistryEntry, RegistryEntryType, RegistryScope, RemediationChange, RemediationKind, RemediationOutcome, RemediationRefusal, RetiredEntryType, StoredEntryType, } from '@skanl/brambo-contracts';
+export { createMemoryLogSink } from '@skanl/brambo-kernel';
+export type { LogRecord, LogSink, MemoryLogSink } from '@skanl/brambo-kernel';
+export { WRITABLE_CONFIG_KEYS, configPathFor, setConfigValue, type ConfigWriteOptions, type ConfigWriteResult, type WritableConfigKey, } from '@skanl/brambo-projection';
+export { ingestMachine } from './ingest.ts';
+export type { IngestMachineOptions, MachineIngest, MachineMcpIngest, MachineMcpSkip, MachineSkillsSkip, OwnedMcpEntry, } from './ingest.ts';
+export type { IngestOutcome, IngestWarning } from '@skanl/brambo-contracts';

package/dist/index.js

@@ -0,0 +1,60 @@
+export { PROJECTION_ACTION_ID, initMachine, initProject, noExecutorsDetected, 
+// The seams `brambo add` / `remove` / `list` bind to. Exported rather than
+// re-derived in the binding: `storeFor` is the ONE mapping from a scope to a
+// store, `scopeDirectory` is the trust boundary that keeps a project verb from
+// building a tree brambo was asked to bind rather than create, and
+// `deliveryFor` is what `add` reports its next step FROM — so the binding
+// holds no idea of which entry type has a location at which scope.
+deliveryFor, scopeDirectory, storeFor, } from './init.js';
+export { DIAGNOSIS_FINDING_KINDS, FINDING_EXITS, diagnose, findingKindsFor, hasProblem, } from './doctor.js';
+export { remediate } from './remediate.js';
+export { EXECUTOR_PROFILES, detectExecutors } from './executors.js';
+// Re-exported, not merely referenced. Under pnpm's strict layout a consumer that
+// installed `@skanl/brambo-environment` cannot resolve `@skanl/brambo-contracts`,
+// `@skanl/brambo-kernel` or `@skanl/brambo-registry` unless it declares them too — so a
+// surface whose result carries a `DriftEntry` and whose precondition is "put
+// entries in the registry first" has to hand back both, or the SDK promise is
+// only true inside this monorepo. The list is exactly that: what you need to
+// POPULATE the registry this projects from, READ a result, and OBSERVE the run.
+//
+// The closure is NOT total, and saying so is cheaper than a claim that rots:
+// `RegistryStoreOptions.onStaleLockBreak` takes a `StaleLockBreak`,
+// `ExecutorProfile.createTarget` returns a `ProjectionConfigTarget` and
+// `ExecutorProfile.createSkillsTarget` a `ProjectionMaterialiseTarget`, none of
+// which is re-exported. All three are reachable only by a consumer implementing
+// one of those callbacks; the ordinary path needs none of them. Recorded in
+// deferred-work.md rather than fixed by widening the surface on speculation.
+export { RegistryStore } from '@skanl/brambo-registry';
+// The bundle surface, for the same reason: a consumer holding a `RegistryStore`
+// can build the artifact and read what did not travel without resolving
+// `@skanl/brambo-registry` itself. `writeBundle` is here and this package still writes
+// no file — it names a capability its own guard test forbids it to PERFORM,
+// which is the whole point of a facade.
+export { BUNDLE_KIND, BUNDLE_VERSION, OMITTED_FIELDS, createBundle, isCredential, parseBundle, readBundle, serializeBundle, writeBundle } from '@skanl/brambo-registry';
+export { DRIFT_KINDS, 
+// `brambo --version`'s value, re-exported for the same reason every other
+// constant on this list is: `@skanl/brambo-cli` is a THIN BINDING on the
+// consumer tier, pinned by `packages/cli/test/run.test.ts` to
+// `@skanl/brambo-environment` and `@skanl/brambo-session` and nothing else.
+// M37.B put `import { BRAMBO_VERSION } from '@skanl/brambo-contracts'` at the top
+// of `run.ts` and the pin's own comment records the premise that broke:
+// "contracts moved to devDependencies once `describe()` stopped needing
+// `instanceof BramboError`: the shipped CLI imports only consumer-tier
+// packages". It did not any more, and the manifest and the import disagreed
+// for a whole milestone -- the published binary importing a package it did not
+// declare, which starts only because npm hoists the tree flat.
+BRAMBO_VERSION, REGISTRY_ENTRY_TYPES, REMEDIATION_KINDS, REMOVABLE_ENTRY_TYPES, RETIRED_ENTRY_TYPES, 
+// The read-time inverse of the store's write-time normalization. A caller
+// holding an entry in its PORTABLE form — the one a bundle carries — needs it
+// to get back to the real paths the store's surface takes, and re-normalizing
+// an already-normalized value corrupts it rather than being a no-op.
+expandRegistryEntryPaths, isRetiredEntryType, } from '@skanl/brambo-contracts';
+export { createMemoryLogSink } from '@skanl/brambo-kernel';
+// Re-exported, not reimplemented. This package may not touch the filesystem at
+// all (see test/guard.test.ts): the ledger is the sole authority for what brambo
+// writes, and the clause is blunt on purpose. The WRITER is forwarded so the CLI
+// reaches it through this facade -- the same shape as createMemoryLogSink above
+// -- while the atomic primitive it uses stays inside @skanl/brambo-projection, where a
+// previous story deliberately un-exported it.
+export { WRITABLE_CONFIG_KEYS, configPathFor, setConfigValue, } from '@skanl/brambo-projection';
+export { ingestMachine } from './ingest.js';

package/dist/ingest.d.ts

@@ -0,0 +1,60 @@
+import type { IngestOutcome } from '@skanl/brambo-contracts';
+import type { McpSourceDropped, McpSourceExclusion, McpSourceWarning, SkillsSourceWarning } from '@skanl/brambo-registry';
+/** Which skill candidate the ingest looked at and did not contribute, and why. */
+export type MachineSkillsSkip = SkillsSourceWarning;
+/** Which server candidate the ingest looked at and did not contribute, and why. */
+export type MachineMcpSkip = McpSourceWarning;
+export interface IngestMachineOptions {
+    /** Defaults to the OS home directory, like every other machine-scope command. */
+    readonly homeDir?: string;
+    /**
+     * Decide everything a writing run decides and write nothing.
+     *
+     * Forwarded to the ONE `ingestProviders` call rather than answered by a second
+     * pass here: a preview computed by different code than the write is a preview
+     * that can lie.
+     */
+    readonly dryRun?: boolean;
+}
+/** The mcp-server half of one run, beside the skills half it shares a call with. */
+export interface MachineMcpIngest {
+    /** The verified vendor config locations consulted, in profile order. */
+    readonly configPaths: readonly string[];
+    /** Candidates skipped: unreadable, an unusable id, or an ambiguous one. */
+    readonly skipped: readonly MachineMcpSkip[];
+    /**
+     * Servers left alone because brambo's own ledger claims them (D3), each paired
+     * with the `nativeLocation` that ledger record renders. The location is
+     * REPORTED and is deliberately not the match key: it is a rendering of the
+     * `targetId` and `entryId` that are, and matching on a rendering is how two
+     * answers come to differ.
+     */
+    readonly ownedByBrambo: readonly OwnedMcpEntry[];
+    /** Vendor keys the registry envelope cannot carry, per ingested server (D10). */
+    readonly dropped: readonly McpSourceDropped[];
+}
+export type OwnedMcpEntry = McpSourceExclusion;
+export interface MachineIngest {
+    readonly homeDir: string;
+    /** The machine registry document the run wrote to, or would have. */
+    readonly registryPath: string;
+    /** The verified skills roots consulted, in the order the profiles declare. */
+    readonly roots: readonly string[];
+    readonly dryRun: boolean;
+    readonly outcome: IngestOutcome;
+    /** Skill candidates skipped: not a skill, an unusable id, or an ambiguous one. */
+    readonly skipped: readonly MachineSkillsSkip[];
+    /** Skill directories left alone because brambo's own ledger claims them (D3). */
+    readonly ownedByBrambo: readonly string[];
+    /** The other half of the same run, reported so neither can go silent. */
+    readonly mcpServers: MachineMcpIngest;
+}
+/**
+ * Puts the skills and the MCP servers already on this machine into the machine
+ * registry, in ONE two-phase run over both origins.
+ *
+ * Additive, exactly as both ports document: an entry an origin stops listing is
+ * left in the registry untouched, and nothing is ever removed. Pruning is a
+ * separate decision and is deliberately not made here.
+ */
+export declare function ingestMachine(options?: IngestMachineOptions): Promise<MachineIngest>;

package/dist/ingest.js

@@ -0,0 +1,85 @@
+import { homedir } from 'node:os';
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+import { ProjectionLedger, SKILL_ENTRY_FILE } from '@skanl/brambo-projection';
+import { createMachineMcpSource, createMachineSkillsSource, ingestProviders } from '@skanl/brambo-registry';
+import { EXECUTOR_PROFILES } from './executors.js';
+import { scopeDirectory, storeFor } from './init.js';
+/**
+ * Puts the skills and the MCP servers already on this machine into the machine
+ * registry, in ONE two-phase run over both origins.
+ *
+ * Additive, exactly as both ports document: an entry an origin stops listing is
+ * left in the registry untouched, and nothing is ever removed. Pruning is a
+ * separate decision and is deliberately not made here.
+ */
+export async function ingestMachine(options = {}) {
+    const dryRun = options.dryRun === true;
+    // The same trust boundary every other machine-scope command applies, and the
+    // same `homedir()` call: a second spelling of "the home directory" is how two
+    // commands come to disagree about which registry they are talking about.
+    const home = await scopeDirectory('the home directory', options.homeDir ?? homedir());
+    const ledger = new ProjectionLedger({ homeDir: home });
+    const read = await ledger.read();
+    if (read.state === 'unreadable') {
+        // BEFORE the roots or the vendor documents are even listed, let alone
+        // written. Without the ledger brambo cannot tell its own projections apart
+        // from your skills and your servers, and ingesting brambo's own output is
+        // worse than not ingesting at all — so this is a refusal rather than a run
+        // that proceeds with a weaker guarantee.
+        throw new BramboError(BRAMBO_ERROR_CODES.projectionLedgerUnavailable, 
+        // Deliberately not opened with the word `brambo`: `test/printed-commands.ts`
+        // treats a backtick-quoted string that starts that way as a COMMAND, and
+        // this is a sentence.
+        `refusing to ingest without the ownership ledger, because without it brambo cannot tell its own projections from your skills and servers: ${read.warnings.map((warning) => warning.detail).join('; ')}`);
+    }
+    const ownedPaths = read.records.flatMap((record) => (record.ownedPaths ?? []).map((owned) => owned.path));
+    // ONE ledger read serves both origins. `targetId` + `entryId` is the match
+    // key; the `nativeLocation` beside it is carried into the report only.
+    const ownedEntries = read.records.map((record) => ({
+        targetId: record.targetId,
+        entryId: record.entryId,
+        nativeLocation: record.nativeLocation,
+    }));
+    // `machineSkills` and `machineConfig`, and nothing else. Every one of these was
+    // verified by running the real binary under an injected home; an executor whose
+    // skills location brambo has NOT proven carries `undefined` and contributes no
+    // root, which is the honest answer rather than a location brambo invented.
+    const roots = EXECUTOR_PROFILES.flatMap((profile) => profile.machineSkills === undefined ? [] : [profile.machineSkills(home)]);
+    const locations = EXECUTOR_PROFILES.map((profile) => {
+        const filePath = profile.machineConfig(home);
+        return { targetId: profile.targetId, filePath, read: async () => await profile.readMcpEntries(filePath) };
+    });
+    const skills = createMachineSkillsSource({ roots, entryFileName: SKILL_ENTRY_FILE, ownedPaths });
+    const servers = createMachineMcpSource({ locations, ownedEntries });
+    const store = storeFor('machine', home, home);
+    try {
+        // ONE call, both origins, one `dryRun`. Splitting it would give the two
+        // halves two chances to disagree about a store they both write to.
+        const outcome = await ingestProviders(store, {
+            toolProviders: [servers],
+            skillSources: [skills],
+            dryRun,
+        });
+        return {
+            homeDir: home,
+            registryPath: store.storePath('global'),
+            roots,
+            dryRun,
+            outcome,
+            skipped: [...skills.warnings],
+            ownedByBrambo: [...skills.excluded],
+            mcpServers: {
+                configPaths: locations.map((location) => location.filePath),
+                skipped: [...servers.warnings],
+                // Already whole: the source echoes back the ledger record it matched,
+                // so the location reported beside an exclusion is by construction the
+                // one that caused it, with no second lookup that could miss.
+                ownedByBrambo: [...servers.excluded],
+                dropped: [...servers.dropped],
+            },
+        };
+    }
+    finally {
+        await store.dispose();
+    }
+}

package/dist/init.d.ts

@@ -0,0 +1,325 @@
+import type { DriftEntry, BramboErrorCode, ProjectionTarget, ProjectionWarning, RegistryEntry, RegistryScope } from '@skanl/brambo-contracts';
+import type { LogSink } from '@skanl/brambo-kernel';
+import type { ProjectionMode } from '@skanl/brambo-projection';
+import { RegistryStore } from '@skanl/brambo-registry';
+import type { ExecutorDetection, ExecutorProfile } from './executors.ts';
+/**
+ * Subject PREFIX every projection record is written under. The subject is
+ * `${PROJECTION_ACTION_ID}#${targetId}` — bounded by brambo's own constants, so
+ * it can never be rejected by the sink's identifier rules the way a file path
+ * (unbounded length, arbitrary characters) could be.
+ *
+ * Exported because a reader of the record stream needs the same string brambo
+ * wrote; match with `subject.startsWith(PROJECTION_ACTION_ID + '#')`.
+ */
+export declare const PROJECTION_ACTION_ID = "environment.projection";
+/** A registry entry a target could not express natively, and why (correction-01 C5). */
+export interface UnprojectableEntry {
+    readonly entryId: string;
+    readonly reason: string;
+}
+/** A detected executor that was not projected into, and why. */
+export interface SkippedExecutor {
+    readonly executorId: string;
+    readonly reason: string;
+}
+/**
+ * A per-target failure, flattened to code and message. A live `Error` would
+ * serialise to `{}` for every caller that prints the result, and the code is the
+ * part a caller acts on.
+ */
+export interface TargetFailure {
+    readonly code: BramboErrorCode;
+    readonly message: string;
+}
+/**
+ * What happened to ONE executor's configuration. The four facts the caller has
+ * to be able to tell apart are separate fields rather than one status word,
+ * because they are not mutually exclusive: a single run can write one entry,
+ * report a second as drifted, and report a third as unprojectable.
+ *
+ *   written   — `written === true`: the file on disk changed.
+ *   unchanged — `written === false` with empty `drift` and no `error`.
+ *   drifted   — `drift` is non-empty; nothing in it was overwritten.
+ *   unprojectable — `unprojectable` is non-empty; nothing was written for those.
+ *   failed    — `error` is set; this target alone is affected.
+ */
+export interface TargetProjection {
+    readonly executorId: string;
+    readonly targetId: string;
+    /**
+     * The vendor's own location, as that vendor reads it: a configuration FILE in
+     * `targets`, a skills ROOT DIRECTORY in `skills`.
+     */
+    readonly filePath: string;
+    readonly written: boolean;
+    readonly drift: readonly DriftEntry[];
+    readonly unprojectable: readonly UnprojectableEntry[];
+    readonly error?: TargetFailure;
+}
+export interface InitResult {
+    readonly scope: 'machine' | 'project';
+    /** Brambo's own state directory for this scope; it exists once init returns. */
+    readonly bramboDir: string;
+    /** The registry store this run read from; it exists once init returns. */
+    readonly registryPath: string;
+    readonly ledgerPath: string;
+    /** Registry entries this run projected from, across every scope it can see. */
+    readonly entryCount: number;
+    /** EVERY executor brambo knows, found or not, with the paths consulted. */
+    readonly detected: readonly ExecutorDetection[];
+    readonly targets: readonly TargetProjection[];
+    /**
+     * The skills root of every detected executor whose location brambo has
+     * VERIFIED, one row each — a separate array rather than more `targets` rows
+     * because the two surfaces are not the same thing: one names a file brambo
+     * merges text into, the other a directory tree brambo materialises and, when a
+     * skill leaves the registry, removes. Empty where no verified location
+     * applies, which is every executor at project scope.
+     */
+    readonly skills: readonly TargetProjection[];
+    readonly skipped: readonly SkippedExecutor[];
+    readonly warnings: readonly ProjectionWarning[];
+}
+export interface InitMachineOptions {
+    /** Defaults to the OS home directory. */
+    readonly homeDir?: string;
+    /**
+     * Where the projection records go. Omitted, a memory sink is built and then
+     * dropped — the records are still produced, simply unread.
+     *
+     * ponytail: the caller owns the sink they pass, draining included. Read
+     * `sink.records` only after `await sink.drain()`.
+     */
+    readonly log?: LogSink;
+}
+export interface InitProjectOptions extends InitMachineOptions {
+    /** Defaults to `process.cwd()`. */
+    readonly projectDir?: string;
+}
+/**
+ * True when no executor was found — the caller's non-zero-exit condition.
+ *
+ * Takes the DETECTION, not an `InitResult`: `brambo doctor` has to answer the
+ * same question about the same evidence, and two spellings of "did brambo find
+ * anything" is how the two commands come to disagree about one machine.
+ */
+export declare function noExecutorsDetected(result: {
+    readonly detected: readonly ExecutorDetection[];
+}): boolean;
+/**
+ * The trust boundary. `homeDir` and `projectDir` are caller-supplied paths that
+ * decide where brambo creates directories and which vendor files it writes, so
+ * every one of them is resolved ONCE here and rejected unless it already names a
+ * directory.
+ *
+ * Three failures this closes, all of them observed: `homeDir: ''` — which is
+ * exactly `process.env.HOME ?? ''` in a consumer — resolves to the CWD and
+ * relocates the machine scope into whatever directory the process happens to be
+ * in; `brambo project init ~/typo` built the whole missing tree and wrote a
+ * vendor config into it; and `brambo project init ~/repo/.git` would have done
+ * the same inside a git directory. Brambo BINDS a project, it does not create one.
+ */
+export declare function scopeDirectory(label: string, value: string): Promise<string>;
+interface PlannedTarget {
+    readonly profile: ExecutorProfile;
+    readonly target: ProjectionTarget;
+}
+/**
+ * Brambo's OWN prior output still sitting in a vendor file (correction-01 C6).
+ *
+ * Every field of every row is produced by `runRemediation` under INSPECTION —
+ * the same call, in the same file, that `discard` performs. So the sentence
+ * `brambo doctor` prints about a legacy block is the sentence the remediation
+ * will act on, and the two cannot describe different regions.
+ */
+export interface LegacyBlock {
+    readonly executorId: string;
+    readonly targetId: string;
+    readonly filePath: string;
+    /** What brambo found and would remove, or why it will not touch it. */
+    readonly detail: string;
+    /** Bytes the file would lose; 0 when brambo refuses. */
+    readonly byteDelta: number;
+    readonly refusal?: TargetFailure;
+}
+export declare function targetsFor(scope: 'machine' | 'project', detected: readonly ExecutorDetection[], homeDir: string, projectDir: string): {
+    readonly planned: readonly PlannedTarget[];
+    /**
+     * The skills roots, planned only where the executor has a location brambo
+     * VERIFIED. Machine scope only: no executor has a project-scope skills
+     * location brambo has proven, so `brambo project init` materialises none and
+     * the skills stay reported as unprojectable — the same refusal that keeps
+     * Codex out of a project's MCP configuration.
+     */
+    readonly skills: readonly PlannedTarget[];
+    readonly skipped: readonly SkippedExecutor[];
+};
+/**
+ * A per-target row in BOTH modes. `changed` is the one fact whose SENTENCE the
+ * mode decides — the merged text differs from the bytes on disk — so it is named
+ * for the fact and never for the write: `initMachine`/`initProject` map it to
+ * `written`, `diagnose` maps it to `wouldWrite`, and neither reading can be
+ * mistaken for the other by a caller holding the wrong one.
+ */
+export interface ScopeTarget {
+    readonly executorId: string;
+    readonly targetId: string;
+    readonly filePath: string;
+    readonly changed: boolean;
+    readonly drift: readonly DriftEntry[];
+    readonly unprojectable: readonly UnprojectableEntry[];
+    readonly error?: TargetFailure;
+}
+/** Everything one scope's engine run produced, before either caller phrases it. */
+export interface ScopeReport {
+    readonly bramboDir: string;
+    /**
+     * This scope's registry document. Under `'apply'` it exists by the time the
+     * report is built; under `'inspect'` it is only a PATH, and whether anything
+     * is there is the answer to "has brambo been initialised here".
+     */
+    readonly registryPath: string;
+    readonly ledgerPath: string;
+    readonly entryCount: number;
+    readonly detected: readonly ExecutorDetection[];
+    readonly targets: readonly ScopeTarget[];
+    /** One row per VERIFIED skills root; see `InitResult.skills`. */
+    readonly skills: readonly ScopeTarget[];
+    readonly skipped: readonly SkippedExecutor[];
+    /**
+     * Brambo's own prior output found in a vendor file. Computed under `'inspect'`
+     * ONLY: `brambo init` neither reports nor removes it, because removing it is a
+     * decision and this story's rule is that a decision is a user's.
+     */
+    readonly legacy: readonly LegacyBlock[];
+    readonly warnings: readonly ProjectionWarning[];
+    /**
+     * Set ONLY under `'inspect'`, and only when brambo's own registry document
+     * could not be read. `'apply'` rethrows instead: projecting against a registry
+     * brambo cannot read would delete every entry it holds from every vendor file.
+     * When this is set, `targets` is EMPTY — with no registry there is nothing
+     * brambo can honestly say projecting would do.
+     */
+    readonly registryError?: TargetFailure;
+    /**
+     * Entries whose type brambo has RETIRED — readable, listed and removable, and
+     * never handed to a target. Reported by `brambo doctor` because a word brambo no
+     * longer has is a state a user has to be told about AND given an exit from;
+     * `brambo init` neither projects nor removes them, because removing an entry is
+     * a decision and a decision is a user's.
+     */
+    readonly retired: readonly RetiredEntry[];
+}
+/**
+ * One retired entry AND the document that actually holds it.
+ *
+ * The scope is carried rather than inferred, and that is the whole point of this
+ * type. `RegistryEntry` has no scope field and `store.list()` is the MERGED
+ * view, so a caller holding only the entry has to guess — and the only guess
+ * available is the scope being diagnosed. `brambo project doctor` reads the
+ * GLOBAL registry too, so that guess attributed a global entry to the (possibly
+ * empty) project document and told the user to run `brambo project remove`, which
+ * exits 1 for an entry that is not there. A finding that names a file must name
+ * the file the entry is actually in.
+ */
+export interface RetiredEntry {
+    readonly entry: RegistryEntry;
+    readonly scope: Exclude<RegistryScope, 'agent'>;
+    /** The document holding it — NOT necessarily the one being diagnosed. */
+    readonly registryPath: string;
+}
+export declare function storeFor(scope: 'machine' | 'project', homeDir: string, projectDir: string): RegistryStore;
+/**
+ * What would actually DELIVER one entry at one scope, and — when nothing at
+ * that scope would — which scope does.
+ *
+ * DERIVED, never asserted. `brambo add` used to end with a sentence written
+ * beside the command ("`brambo project init` puts it into every detected
+ * executor"), and for a project-scope SKILL that sentence was false: no
+ * executor has a project-scope skills root brambo has verified, machine-scope
+ * projection cannot see a project-scope entry, and the entry was inert forever
+ * while the command it named exited 0. A promise can be kept syntactically and
+ * broken in substance, which is exactly what the printed-command invariant
+ * cannot catch.
+ *
+ * So nothing here knows which entry TYPE has a location at which scope. It runs
+ * `targetsFor` — the same planner `brambo init` runs — and then asks each target
+ * it planned whether it would take THIS entry, in the target's own words:
+ *
+ *   - a config target is asked to merge into an EMPTY document. That call is
+ *     pure text (`nativeText: ''` is the contract's "the file does not exist
+ *     yet"), so no vendor file is read and none is written; an entry the target
+ *     cannot express comes back in `skippedEntryIds`.
+ *   - a materialise target is asked to PLAN. It describes what it would place
+ *     and never touches the destination, and where it refuses it says why.
+ *
+ * Consequence, and it is the point: giving any `ExecutorProfile` a project-scope
+ * skills root changes what `brambo add` prints with no edit to the CLI and none
+ * to this function, and removing every skills root changes it the other way.
+ */
+export interface EntryDelivery {
+    readonly scope: 'machine' | 'project';
+    /** The command that projects this scope. Always one the binary dispatches. */
+    readonly command: string;
+    /** Detected executors whose target for this scope would take the entry. */
+    readonly executorIds: readonly string[];
+    /** Where a target refused, in the target's own words. */
+    readonly reasons: readonly string[];
+    /**
+     * Set ONLY when nothing at this scope takes the entry and another scope
+     * would. Naming it is the difference between a dead end and a next step.
+     */
+    readonly elsewhere?: EntryDelivery;
+    /**
+     * Set when brambo could not work the answer out at all. The entry is already
+     * registered by the time this runs, so a failure here reports itself and
+     * never turns a completed registration into a failed command.
+     */
+    readonly undetermined?: string;
+}
+/**
+ * The command that projects one scope. One spelling, and `doctor.ts` is now a
+ * caller too: it named `brambo init` as the exit from a PROJECT's
+ * `not-initialised` and `out-of-date`, and that command exits 0 leaving the
+ * project exactly as it was.
+ */
+export declare function projectCommandFor(scope: 'machine' | 'project'): string;
+/**
+ * {@link EntryDelivery} for one scope, with the OTHER scope answered too
+ * whenever this one takes the entry nowhere.
+ *
+ * Contained: a target that throws while being asked leaves `undetermined` set
+ * rather than propagating, because the caller has already registered the entry
+ * and a message is not worth losing a completed write over.
+ */
+export declare function deliveryFor(entry: RegistryEntry, scope: 'machine' | 'project', homeDir: string, projectDir: string): Promise<EntryDelivery>;
+/**
+ * Registry -> detection -> projection engine, for one scope. `brambo init` and
+ * `brambo doctor` are THIS function under the two projection modes and nothing
+ * else: same entries, same detection, same targets, same engine call, same drift
+ * classification. Two code paths could disagree about what applying would do,
+ * and they would disagree exactly when a user is trying to fix something.
+ *
+ * Every line below either reads, or writes through the projection engine — which
+ * under `'inspect'` writes nothing at all.
+ */
+export declare function runScope(scope: 'machine' | 'project', homeDir: string, projectDir: string, log: LogSink | undefined, mode: ProjectionMode): Promise<ScopeReport>;
+/**
+ * Prepares this machine: brambo's own directory and registry store exist
+ * afterwards, and the global registry is projected into every detected
+ * executor's own machine-scope configuration.
+ *
+ * Idempotent. A second run over an unchanged registry writes no vendor byte and
+ * reports every target as unchanged.
+ */
+export declare function initMachine(options?: InitMachineOptions): Promise<InitResult>;
+/**
+ * Binds a project: brambo's own directory and project registry store exist under
+ * it afterwards, and the registry it can see — the project's entries over the
+ * machine's — is projected into every detected executor that has a project-scope
+ * configuration. An executor without one is reported as skipped, never written
+ * to somewhere it does not read.
+ */
+export declare function initProject(options?: InitProjectOptions): Promise<InitResult>;
+export {};