the-local 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# the-local
+
+Ship Claude Code **locals** (resident expert subagents) from npm packages into a
+host TS/JS app — the TypeScript port of the [`the_local`](https://github.com/tylercschneider/the_local)
+Ruby gem. A provider package commits its agent `.md` files; a host runs
+`the-local install` to copy the aggregated set from its direct dependencies into
+`.claude/agents/`, plus a delegation rule in `CLAUDE.md`.
+
+> Status: early. Core install pipeline + CLI are in place and tested. See the
+> open issues for remaining work (contract doc, npm publish, workspace support).
+
+## The model
+
+- **Providers commit locals.** A package ships pre-rendered agent files at
+  `the-local/agents/<prefix>-<name>.md` and declares them in its `package.json`.
+- **Hosts install verbatim.** `the-local install` reads the host's direct
+  `dependencies`, copies each provider's committed `.md` byte-for-byte into
+  `.claude/agents/`, and writes the delegation trigger into `CLAUDE.md`.
+- **Direct-dependency scope.** Only the host's direct dependencies contribute
+  locals; transitive providers are filtered out.
+- **Cross-language contract.** The agent `.md` format and the `CLAUDE.md`
+  `<!-- the_local:begin -->` / `<!-- the_local:end -->` markers are identical to
+  the Ruby gem's, so a Ruby gem and a TS package install into the same host
+  without clobbering each other. See [`docs/contract.md`](docs/contract.md).
+
+## Use (host app)
+
+```sh
+npx the-local install   # or: refresh
+```
+
+## Declare locals (provider package)
+
+```jsonc
+// package.json
+{
+  "the-local": {
+    "prefix": "keystone",
+    "scope": "UI — pages, forms, tables",
+    "agentsDir": "the-local/agents"
+  }
+}
+```
+
+Then commit `the-local/agents/keystone-*.md` alongside your code.
+
+## Develop
+
+```sh
+pnpm install
+pnpm test        # vitest
+pnpm typecheck
+pnpm lint
+pnpm build       # emits dist/, including the the-local CLI
+```

package/dist/agent.d.ts

@@ -0,0 +1,11 @@
+export interface Agent {
+    prefix: string;
+    name: string;
+    description: string;
+    tools: string;
+    body: string;
+    knowledge?: string | string[];
+}
+export declare function qualifiedName(agent: Pick<Agent, "prefix" | "name">): string;
+export declare function agentFilename(agent: Pick<Agent, "prefix" | "name">): string;
+export declare function toMarkdown(agent: Agent): string;

package/dist/agent.js

@@ -0,0 +1,23 @@
+export function qualifiedName(agent) {
+    return `${agent.prefix}-${agent.name}`;
+}
+export function agentFilename(agent) {
+    return `${qualifiedName(agent)}.md`;
+}
+export function toMarkdown(agent) {
+    const knowledge = Array.isArray(agent.knowledge)
+        ? agent.knowledge.join("\n\n")
+        : (agent.knowledge ?? "");
+    return [
+        "---",
+        `name: ${qualifiedName(agent)}`,
+        `description: ${agent.description}`,
+        `tools: ${agent.tools}`,
+        "---",
+        "",
+        agent.body,
+        "",
+        knowledge,
+        "",
+    ].join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function run(argv: string[], hostDir: string): number;
+export declare function main(argv: string[], cwd: string): Promise<number>;
+export declare function isEntrypoint(moduleUrl: string, invokedPath: string | undefined): boolean;

package/dist/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { installLocals } from "./installer.js";
+import { buildProvider, scaffoldProvider } from "./provider.js";
+const COMMANDS = new Set(["install", "refresh"]);
+export function run(argv, hostDir) {
+    const command = argv[0] ?? "install";
+    if (!COMMANDS.has(command)) {
+        process.stderr.write(`the-local: unknown command "${command}" (expected install, refresh, provider, or build)\n`);
+        return 1;
+    }
+    const { providers, agents } = installLocals(hostDir);
+    process.stdout.write(`the-local: installed ${agents.length} agent(s) from ${providers.length} provider(s).\n`);
+    return 0;
+}
+// Dispatches every command. The provider-authoring commands run from a package
+// directory; install/refresh fall through to `run`. Async because `build` loads
+// the provider's config by dynamic import.
+export async function main(argv, cwd) {
+    const [command, target] = argv;
+    if (command === "provider") {
+        const { config, created } = scaffoldProvider(target ?? cwd);
+        process.stdout.write(created
+            ? `the-local: scaffolded provider "${config.prefix}" — edit the-local.config.js, then run the-local build.\n`
+            : `the-local: the-local.config.js already exists; run the-local build to re-render.\n`);
+        return 0;
+    }
+    if (command === "build") {
+        const written = await buildProvider(target ?? cwd);
+        process.stdout.write(`the-local: rendered ${written.length} agent(s).\n`);
+        return 0;
+    }
+    return run(argv, cwd);
+}
+// Node sets `import.meta.url` to the module's real path, but leaves
+// `process.argv[1]` as the symlink npm creates in `node_modules/.bin`. Resolve
+// the symlink before comparing so the CLI still runs when invoked via `npx`.
+export function isEntrypoint(moduleUrl, invokedPath) {
+    if (!invokedPath)
+        return false;
+    return moduleUrl === pathToFileURL(realpathSync(invokedPath)).href;
+}
+if (isEntrypoint(import.meta.url, process.argv[1])) {
+    void main(process.argv.slice(2), process.cwd()).then((code) => process.exit(code));
+}

package/dist/companion.d.ts

@@ -0,0 +1,2 @@
+import type { Agent } from "./agent.js";
+export declare const companionAgents: Agent[];

package/dist/companion.js

@@ -0,0 +1,49 @@
+import { reference } from "./reference.js";
+// the-local's own locals — the companion that makes the-local its own provider,
+// dogfooding the same model every other provider uses. Each agent carries the
+// reference verbatim as its knowledge; the rendered files live committed under
+// the-local/agents/ and are what a host installs.
+const PREFIX = "the-local";
+export const companionAgents = [
+    {
+        prefix: PREFIX,
+        name: "info",
+        description: "Use to learn how the-local works — providers, the committed-.md install " +
+            "model, the delegation trigger, and the direct-dependency scope rule.",
+        tools: "Read",
+        body: "You explain how the-local works, answering only from the reference: " +
+            "providers ship committed locals, `the-local install` copies them verbatim " +
+            "into a host's .claude/agents/, the CLAUDE.md delegation trigger makes the " +
+            "host delegate, and only direct dependencies contribute. You make no changes.",
+        knowledge: reference,
+    },
+    {
+        prefix: PREFIX,
+        name: "install",
+        description: "Use to add the-local to a host app and set it up correctly.",
+        tools: "Bash, Read, Edit",
+        body: "You set the-local up in a host package or app, following the reference's " +
+            "install section exactly: add the-local to the host's dependencies, install, " +
+            "run `the-local install` to sync locals into .claude/agents/ and write the " +
+            "delegation trigger, and re-run it after dependency changes. You do not " +
+            "invent steps the reference does not list.",
+        knowledge: reference,
+    },
+    {
+        prefix: PREFIX,
+        name: "develop",
+        description: "Use PROACTIVELY to turn a package into a the-local provider — declaring " +
+            "the provider block, authoring the locals, and committing the rendered " +
+            "agents. MUST BE USED instead of wiring a provider by hand.",
+        tools: "Read, Write, Edit, Grep",
+        body: "You turn a package into a the-local provider following the reference's " +
+            "provider-author workflow: add the `the-local` block to package.json, author " +
+            "the standard locals (info, install, and a domain worker) with a guide as " +
+            "their knowledge, and render each to the-local/agents/. The deliverable is " +
+            "the committed, shipped the-local/agents/*.md — that is the whole contract a " +
+            "host reads from disk; a host never loads the package, so unless those files " +
+            "are committed and in package.json's files allowlist, the package contributes " +
+            "nothing. You keep them in sync with toMarkdown.",
+        knowledge: reference,
+    },
+];

package/dist/discovery.d.ts

@@ -0,0 +1,8 @@
+export interface DiscoveredProvider {
+    packageName: string;
+    prefix: string;
+    scope: string | null;
+    agentFiles: string[];
+}
+export declare function directDependencies(hostDir: string): string[];
+export declare function discoverProviders(hostDir: string): DiscoveredProvider[];

package/dist/discovery.js

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_AGENTS_DIR = "the-local/agents";
+function readManifest(packageJsonPath) {
+    if (!existsSync(packageJsonPath))
+        return null;
+    return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+}
+export function directDependencies(hostDir) {
+    const manifest = readManifest(join(hostDir, "package.json"));
+    return Object.keys(manifest?.dependencies ?? {});
+}
+export function discoverProviders(hostDir) {
+    const nodeModulesDir = join(hostDir, "node_modules");
+    const providers = [];
+    for (const dependency of directDependencies(hostDir)) {
+        const packageDir = join(nodeModulesDir, dependency);
+        const manifest = readManifest(join(packageDir, "package.json"));
+        const declaration = manifest?.["the-local"];
+        if (!manifest || !declaration)
+            continue;
+        const prefix = declaration.prefix ?? dependency;
+        const agentsDir = join(packageDir, declaration.agentsDir ?? DEFAULT_AGENTS_DIR);
+        if (!existsSync(agentsDir)) {
+            throw new Error(`the-local: ${dependency} declares the-local locals but ships no committed agents at ` +
+                `${declaration.agentsDir ?? DEFAULT_AGENTS_DIR}. Build and commit them in ${dependency}.`);
+        }
+        const agentFiles = readdirSync(agentsDir)
+            .filter((entry) => entry.endsWith(".md"))
+            .sort()
+            .map((entry) => join(agentsDir, entry));
+        providers.push({ packageName: dependency, prefix, scope: declaration.scope ?? null, agentFiles });
+    }
+    return providers;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type Agent, agentFilename, qualifiedName, toMarkdown } from "./agent.js";
+export { BEGIN_MARKER, END_MARKER, type ProviderTrigger, delegationRule, mergeTrigger } from "./trigger.js";
+export { type ScopeInput, allowedProviders } from "./scope.js";
+export { type DiscoveredProvider, directDependencies, discoverProviders } from "./discovery.js";
+export { type InstallResult, installAgents, installLocals, writeTrigger } from "./installer.js";
+export { reference } from "./reference.js";
+export { companionAgents } from "./companion.js";
+export { type ProviderAgentSpec, type ProviderConfig, buildProvider, prefixFromName, renderProvider, scaffoldProvider, starterConfig, } from "./provider.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { agentFilename, qualifiedName, toMarkdown } from "./agent.js";
+export { BEGIN_MARKER, END_MARKER, delegationRule, mergeTrigger } from "./trigger.js";
+export { allowedProviders } from "./scope.js";
+export { directDependencies, discoverProviders } from "./discovery.js";
+export { installAgents, installLocals, writeTrigger } from "./installer.js";
+export { reference } from "./reference.js";
+export { companionAgents } from "./companion.js";
+export { buildProvider, prefixFromName, renderProvider, scaffoldProvider, starterConfig, } from "./provider.js";

package/dist/installer.d.ts

@@ -0,0 +1,9 @@
+import { type DiscoveredProvider } from "./discovery.js";
+import { type ProviderTrigger } from "./trigger.js";
+export declare function installAgents(hostDir: string, providers: DiscoveredProvider[]): string[];
+export declare function writeTrigger(hostDir: string, providers: ProviderTrigger[], filename?: string): void;
+export interface InstallResult {
+    providers: DiscoveredProvider[];
+    agents: string[];
+}
+export declare function installLocals(hostDir: string): InstallResult;

package/dist/installer.js

@@ -0,0 +1,29 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { discoverProviders } from "./discovery.js";
+import { delegationRule, mergeTrigger } from "./trigger.js";
+const AGENTS_DIR = ".claude/agents";
+export function installAgents(hostDir, providers) {
+    const destination = join(hostDir, AGENTS_DIR);
+    mkdirSync(destination, { recursive: true });
+    const written = [];
+    for (const provider of providers) {
+        for (const source of provider.agentFiles) {
+            const target = join(destination, basename(source));
+            copyFileSync(source, target);
+            written.push(target);
+        }
+    }
+    return written;
+}
+export function writeTrigger(hostDir, providers, filename = "CLAUDE.md") {
+    const path = join(hostDir, filename);
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    writeFileSync(path, `${mergeTrigger(existing, delegationRule(providers))}\n`);
+}
+export function installLocals(hostDir) {
+    const providers = discoverProviders(hostDir);
+    const agents = installAgents(hostDir, providers);
+    writeTrigger(hostDir, providers);
+    return { providers, agents };
+}

package/dist/provider.d.ts

@@ -0,0 +1,16 @@
+import { type Agent } from "./agent.js";
+export declare function prefixFromName(packageName: string): string;
+export interface ProviderConfig {
+    prefix: string;
+    scope?: string;
+    agentsDir?: string;
+    agents: ProviderAgentSpec[];
+}
+export type ProviderAgentSpec = Omit<Agent, "prefix">;
+export declare function renderProvider(config: ProviderConfig, packageDir: string): string[];
+export declare function starterConfig(packageName: string): ProviderConfig;
+export declare function scaffoldProvider(packageDir: string): {
+    config: ProviderConfig;
+    created: boolean;
+};
+export declare function buildProvider(packageDir: string): Promise<string[]>;

package/dist/provider.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { agentFilename, toMarkdown } from "./agent.js";
+const DEFAULT_AGENTS_DIR = "the-local/agents";
+// The agent filename namespace defaults to the package name with any npm scope
+// dropped: `@event-engine/core` -> `core`.
+export function prefixFromName(packageName) {
+    return packageName.replace(/^@[^/]+\//, "");
+}
+// Render each config agent to `<packageDir>/<agentsDir>/<prefix>-<name>.md` and
+// return the written paths. Pure apart from the writes — the same render used
+// for the-local's own companion, generalised to any provider config.
+export function renderProvider(config, packageDir) {
+    const agentsDir = join(packageDir, config.agentsDir ?? DEFAULT_AGENTS_DIR);
+    mkdirSync(agentsDir, { recursive: true });
+    return config.agents.map((spec) => {
+        const agent = { prefix: config.prefix, ...spec };
+        const path = join(agentsDir, agentFilename(agent));
+        writeFileSync(path, toMarkdown(agent));
+        return path;
+    });
+}
+const CONFIG_FILE = "the-local.config.js";
+// The starter config a freshly-scaffolded provider gets: the standard interface
+// of a read-only `info` explainer and a `develop` domain worker, with TODO
+// placeholders the author fills in. Mirrors the Ruby provider generator.
+export function starterConfig(packageName) {
+    const prefix = prefixFromName(packageName);
+    const knowledge = `## ${prefix}\n\nTODO: document ${packageName} — what it does, how to use it, the conventions to enforce.`;
+    return {
+        prefix,
+        scope: `TODO: one-line phrase describing ${packageName}'s domain`,
+        agents: [
+            {
+                name: "info",
+                description: `Use to learn what ${packageName} offers and how to use it.`,
+                tools: "Read",
+                body: `You explain ${packageName}, answering only from the reference. You make no changes.`,
+                knowledge,
+            },
+            {
+                name: "develop",
+                description: `Use PROACTIVELY for work involving ${packageName}.`,
+                tools: "Read, Write, Edit, Grep",
+                body: `You do work involving ${packageName}, following the reference's conventions exactly.`,
+                knowledge,
+            },
+        ],
+    };
+}
+// Scaffold the provider side into a package: write a starter config (without
+// clobbering an authored one). Later cycles wire package.json and render.
+export function scaffoldProvider(packageDir) {
+    const manifestPath = join(packageDir, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const config = starterConfig(manifest.name);
+    // Never clobber an authored config: if one already exists, the package is a
+    // provider already — leave its config, package.json, and rendered agents
+    // alone and let `the-local build` re-render from the author's config.
+    const configPath = join(packageDir, CONFIG_FILE);
+    const created = !existsSync(configPath);
+    if (!created)
+        return { config, created };
+    writeFileSync(configPath, `export default ${JSON.stringify(config, null, 2)};\n`);
+    const agentsDir = config.agentsDir ?? DEFAULT_AGENTS_DIR;
+    manifest["the-local"] = { prefix: config.prefix, scope: config.scope, agentsDir };
+    const files = Array.isArray(manifest.files) ? manifest.files : [];
+    if (!files.includes(agentsDir))
+        files.push(agentsDir);
+    manifest.files = files;
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    renderProvider(config, packageDir);
+    return { config, created };
+}
+// Re-render a provider's committed agents from its authored `the-local.config.js`
+// (the analog of Ruby's `rake the_local:build`). Loaded by dynamic import so the
+// config stays plain ESM data with no toolchain — run after editing the config.
+export async function buildProvider(packageDir) {
+    const configUrl = pathToFileURL(join(packageDir, CONFIG_FILE)).href;
+    const loaded = (await import(configUrl));
+    return renderProvider(loaded.default, packageDir);
+}

package/dist/reference.d.ts

@@ -0,0 +1 @@
+export declare const reference = "## the-local\n\n> **DO NOT** explore the the-local package source code. This reference is the\n> complete user-facing API, embedded verbatim into every the-local local so\n> their guidance never drifts. Keep it the single source of truth.\n\nthe-local is the engine that lets any npm package or app ship resident Claude\nCode expert subagents (\"locals\") that know its conventions. A provider package\ndeclares its locals and commits them as rendered `.md` files; the-local installs\nthe aggregated set from every directly-depended provider into a consuming app's\n`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.\n\n### The model\n\n- **Providers ship committed locals.** A provider declares itself in its\n  `package.json` with a `\"the-local\"` block and commits one rendered file per\n  local at `the-local/agents/<prefix>-<name>.md`. **These committed files are the\n  contract** \u2014 they are what a host reads. A provider can build them from a\n  companion + `toMarkdown`, but the committed `.md` is all a host ever sees.\n- **Install discovers committed `.md` on disk.** In a host, `the-local install`\n  reads each direct dependency's committed `the-local/agents/*.md` straight from\n  its package path under `node_modules` and copies them into `.claude/agents/`\n  byte-for-byte \u2014 no provider code is loaded. Output depends only on the provider\n  package version, so it is a true carbon copy across every app, and a fragile\n  provider can't crash the install.\n- **The delegation trigger.** Install also writes a generated block into the\n  host's `CLAUDE.md`, between the `<!-- the_local:begin -->` and\n  `<!-- the_local:end -->` markers, telling the host agent to delegate to these\n  locals. This is what makes delegation actually happen. The markers are shared\n  with the Ruby `the_local` gem, so a gem and an npm package never clobber each\n  other's block.\n- **Direct-dependency scope.** Only the host's direct dependencies contribute\n  locals; transitive providers are filtered out, so a host gets exactly the\n  experts for the packages it chose.\n\n### Install (in any package or app)\n\n1. Add `the-local` to the host's `package.json` dependencies and install it.\n2. Run `the-local install` (or `npx the-local install`). This syncs every direct\n   provider's committed locals into `.claude/agents/` and writes the delegation\n   trigger into `CLAUDE.md`. It runs from the host's working directory.\n3. Re-run `the-local install` after any dependency change (a provider added,\n   removed, or upgraded) to bring the host's locals back in sync. The package\n   only exposes the command; a script or hook can automate re-running it.\n\n### Author a provider (turn a package into a provider)\n\n1. Add a `\"the-local\"` block to the package's `package.json` and create the\n   `the-local/agents/` directory.\n2. Write each local in the standard interface \u2014 `info` (read-only explainer),\n   `install` (sets the package up in a host), and a domain worker (`develop` for\n   libraries, `operate` for CLIs) \u2014 tailoring its `description`, `tools`, and\n   `body` to your package, with a guide as its embedded `knowledge`.\n3. Render each local to `the-local/agents/<prefix>-<name>.md` with `toMarkdown`,\n   then **commit and ship** those files (they must be in `package.json`'s `files`\n   allowlist). This is the whole contract: a host discovers your locals by\n   reading these committed files from your package on disk \u2014 it never loads your\n   code \u2014 so if they aren't committed and shipped, you contribute nothing, and if\n   they are, you contribute everything. A drift test asserting each committed\n   file equals its `toMarkdown` keeps the artifact honest.\n\n### The package.json declaration\n\n```json\n{\n  \"the-local\": {\n    \"prefix\": \"my-pkg\",\n    \"scope\": \"one-line domain phrase\",\n    \"agentsDir\": \"the-local/agents\"\n  }\n}\n```\n\n- `prefix` is the agent filename namespace; defaults to the package name.\n- `scope` is a one-line domain phrase used to generate the delegation trigger;\n  omit it for a bare `- <prefix>-* agents` bullet.\n- `agentsDir` is the path to the committed `.md` files, relative to the package\n  root; it defaults to `the-local/agents`.\n\n### Conventions\n\n- The committed `.md` files are the contract; commit them, and never render in\n  the host at install time.\n- A local's guide documents the providing package only and stays the single\n  source of truth; never let a rendered `.md` drift from `toMarkdown`.\n- Only direct dependencies contribute, so depend on a provider directly to gain\n  its locals.";

package/dist/reference.js

@@ -0,0 +1,92 @@
+// the-local's own knowledge guide, embedded verbatim as the `knowledge` of
+// every companion agent (info / install / develop). This is the single source
+// of truth for how the-local works; the rendered companion `.md` files are
+// built from it, so it must describe the port's actual behaviour. Keep it free
+// of a trailing newline so `toMarkdown` ends each agent on a single newline.
+export const reference = `## the-local
+
+> **DO NOT** explore the the-local package source code. This reference is the
+> complete user-facing API, embedded verbatim into every the-local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the-local is the engine that lets any npm package or app ship resident Claude
+Code expert subagents ("locals") that know its conventions. A provider package
+declares its locals and commits them as rendered \`.md\` files; the-local installs
+the aggregated set from every directly-depended provider into a consuming app's
+\`.claude/agents/\`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers ship committed locals.** A provider declares itself in its
+  \`package.json\` with a \`"the-local"\` block and commits one rendered file per
+  local at \`the-local/agents/<prefix>-<name>.md\`. **These committed files are the
+  contract** — they are what a host reads. A provider can build them from a
+  companion + \`toMarkdown\`, but the committed \`.md\` is all a host ever sees.
+- **Install discovers committed \`.md\` on disk.** In a host, \`the-local install\`
+  reads each direct dependency's committed \`the-local/agents/*.md\` straight from
+  its package path under \`node_modules\` and copies them into \`.claude/agents/\`
+  byte-for-byte — no provider code is loaded. Output depends only on the provider
+  package version, so it is a true carbon copy across every app, and a fragile
+  provider can't crash the install.
+- **The delegation trigger.** Install also writes a generated block into the
+  host's \`CLAUDE.md\`, between the \`<!-- the_local:begin -->\` and
+  \`<!-- the_local:end -->\` markers, telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen. The markers are shared
+  with the Ruby \`the_local\` gem, so a gem and an npm package never clobber each
+  other's block.
+- **Direct-dependency scope.** Only the host's direct dependencies contribute
+  locals; transitive providers are filtered out, so a host gets exactly the
+  experts for the packages it chose.
+
+### Install (in any package or app)
+
+1. Add \`the-local\` to the host's \`package.json\` dependencies and install it.
+2. Run \`the-local install\` (or \`npx the-local install\`). This syncs every direct
+   provider's committed locals into \`.claude/agents/\` and writes the delegation
+   trigger into \`CLAUDE.md\`. It runs from the host's working directory.
+3. Re-run \`the-local install\` after any dependency change (a provider added,
+   removed, or upgraded) to bring the host's locals back in sync. The package
+   only exposes the command; a script or hook can automate re-running it.
+
+### Author a provider (turn a package into a provider)
+
+1. Add a \`"the-local"\` block to the package's \`package.json\` and create the
+   \`the-local/agents/\` directory.
+2. Write each local in the standard interface — \`info\` (read-only explainer),
+   \`install\` (sets the package up in a host), and a domain worker (\`develop\` for
+   libraries, \`operate\` for CLIs) — tailoring its \`description\`, \`tools\`, and
+   \`body\` to your package, with a guide as its embedded \`knowledge\`.
+3. Render each local to \`the-local/agents/<prefix>-<name>.md\` with \`toMarkdown\`,
+   then **commit and ship** those files (they must be in \`package.json\`'s \`files\`
+   allowlist). This is the whole contract: a host discovers your locals by
+   reading these committed files from your package on disk — it never loads your
+   code — so if they aren't committed and shipped, you contribute nothing, and if
+   they are, you contribute everything. A drift test asserting each committed
+   file equals its \`toMarkdown\` keeps the artifact honest.
+
+### The package.json declaration
+
+\`\`\`json
+{
+  "the-local": {
+    "prefix": "my-pkg",
+    "scope": "one-line domain phrase",
+    "agentsDir": "the-local/agents"
+  }
+}
+\`\`\`
+
+- \`prefix\` is the agent filename namespace; defaults to the package name.
+- \`scope\` is a one-line domain phrase used to generate the delegation trigger;
+  omit it for a bare \`- <prefix>-* agents\` bullet.
+- \`agentsDir\` is the path to the committed \`.md\` files, relative to the package
+  root; it defaults to \`the-local/agents\`.
+
+### Conventions
+
+- The committed \`.md\` files are the contract; commit them, and never render in
+  the host at install time.
+- A local's guide documents the providing package only and stays the single
+  source of truth; never let a rendered \`.md\` drift from \`toMarkdown\`.
+- Only direct dependencies contribute, so depend on a provider directly to gain
+  its locals.`;

package/dist/scope.d.ts

@@ -0,0 +1,6 @@
+export interface ScopeInput {
+    providerNames: string[];
+    directDependencies: string[];
+    installedPackages: string[];
+}
+export declare function allowedProviders(input: ScopeInput): string[];

package/dist/scope.js

@@ -0,0 +1,4 @@
+export function allowedProviders(input) {
+    const { providerNames, directDependencies, installedPackages } = input;
+    return [...new Set(providerNames)].filter((name) => directDependencies.includes(name) || !installedPackages.includes(name));
+}

package/dist/trigger.d.ts

@@ -0,0 +1,8 @@
+export declare const BEGIN_MARKER = "<!-- the_local:begin -->";
+export declare const END_MARKER = "<!-- the_local:end -->";
+export interface ProviderTrigger {
+    prefix: string;
+    scope?: string | null;
+}
+export declare function delegationRule(providers: ProviderTrigger[]): string;
+export declare function mergeTrigger(existing: string, rule: string): string;

package/dist/trigger.js

@@ -0,0 +1,32 @@
+export const BEGIN_MARKER = "<!-- the_local:begin -->";
+export const END_MARKER = "<!-- the_local:end -->";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function bullet(provider) {
+    const target = `${provider.prefix}-* agents`;
+    return `- ${provider.scope ? `${provider.scope} → ${target}` : target}`;
+}
+export function delegationRule(providers) {
+    return [
+        BEGIN_MARKER,
+        "## Delegate to your locals",
+        "",
+        "This project has installed expert subagents. Before doing work yourself,",
+        "check whether a local owns it and delegate — never work from memory on",
+        "something a local covers:",
+        "",
+        providers.map(bullet).join("\n"),
+        "",
+        "See each agent's description for specifics.",
+        END_MARKER,
+    ].join("\n");
+}
+export function mergeTrigger(existing, rule) {
+    const section = new RegExp(`${escapeRegExp(BEGIN_MARKER)}[\\s\\S]*?${escapeRegExp(END_MARKER)}`);
+    if (section.test(existing))
+        return existing.replace(section, rule);
+    if (existing.trim() === "")
+        return rule;
+    return `${existing.replace(/\r?\n$/, "")}\n\n${rule}`;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "the-local",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Ship Claude Code locals from npm packages into a host TS/JS app — the TypeScript port of the the_local Ruby gem.",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DYB-Development/the-local.git"
+  },
+  "homepage": "https://github.com/DYB-Development/the-local#readme",
+  "bugs": "https://github.com/DYB-Development/the-local/issues",
+  "files": ["dist", "README.md", "the-local/agents"],
+  "the-local": {
+    "prefix": "the-local",
+    "scope": "Claude Code locals — packages ship subagents that the-local installs into a host app",
+    "agentsDir": "the-local/agents"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "the-local": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "build:agents": "pnpm build && node scripts/build-companion.mjs",
+    "prepare": "pnpm build",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.17.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^2.1.8"
+  }
+}

package/the-local/agents/the-local-develop.md

@@ -0,0 +1,95 @@
+---
+name: the-local-develop
+description: Use PROACTIVELY to turn a package into a the-local provider — declaring the provider block, authoring the locals, and committing the rendered agents. MUST BE USED instead of wiring a provider by hand.
+tools: Read, Write, Edit, Grep
+---
+
+You turn a package into a the-local provider following the reference's provider-author workflow: add the `the-local` block to package.json, author the standard locals (info, install, and a domain worker) with a guide as their knowledge, and render each to the-local/agents/. The deliverable is the committed, shipped the-local/agents/*.md — that is the whole contract a host reads from disk; a host never loads the package, so unless those files are committed and in package.json's files allowlist, the package contributes nothing. You keep them in sync with toMarkdown.
+
+## the-local
+
+> **DO NOT** explore the the-local package source code. This reference is the
+> complete user-facing API, embedded verbatim into every the-local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the-local is the engine that lets any npm package or app ship resident Claude
+Code expert subagents ("locals") that know its conventions. A provider package
+declares its locals and commits them as rendered `.md` files; the-local installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers ship committed locals.** A provider declares itself in its
+  `package.json` with a `"the-local"` block and commits one rendered file per
+  local at `the-local/agents/<prefix>-<name>.md`. **These committed files are the
+  contract** — they are what a host reads. A provider can build them from a
+  companion + `toMarkdown`, but the committed `.md` is all a host ever sees.
+- **Install discovers committed `.md` on disk.** In a host, `the-local install`
+  reads each direct dependency's committed `the-local/agents/*.md` straight from
+  its package path under `node_modules` and copies them into `.claude/agents/`
+  byte-for-byte — no provider code is loaded. Output depends only on the provider
+  package version, so it is a true carbon copy across every app, and a fragile
+  provider can't crash the install.
+- **The delegation trigger.** Install also writes a generated block into the
+  host's `CLAUDE.md`, between the `<!-- the_local:begin -->` and
+  `<!-- the_local:end -->` markers, telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen. The markers are shared
+  with the Ruby `the_local` gem, so a gem and an npm package never clobber each
+  other's block.
+- **Direct-dependency scope.** Only the host's direct dependencies contribute
+  locals; transitive providers are filtered out, so a host gets exactly the
+  experts for the packages it chose.
+
+### Install (in any package or app)
+
+1. Add `the-local` to the host's `package.json` dependencies and install it.
+2. Run `the-local install` (or `npx the-local install`). This syncs every direct
+   provider's committed locals into `.claude/agents/` and writes the delegation
+   trigger into `CLAUDE.md`. It runs from the host's working directory.
+3. Re-run `the-local install` after any dependency change (a provider added,
+   removed, or upgraded) to bring the host's locals back in sync. The package
+   only exposes the command; a script or hook can automate re-running it.
+
+### Author a provider (turn a package into a provider)
+
+1. Add a `"the-local"` block to the package's `package.json` and create the
+   `the-local/agents/` directory.
+2. Write each local in the standard interface — `info` (read-only explainer),
+   `install` (sets the package up in a host), and a domain worker (`develop` for
+   libraries, `operate` for CLIs) — tailoring its `description`, `tools`, and
+   `body` to your package, with a guide as its embedded `knowledge`.
+3. Render each local to `the-local/agents/<prefix>-<name>.md` with `toMarkdown`,
+   then **commit and ship** those files (they must be in `package.json`'s `files`
+   allowlist). This is the whole contract: a host discovers your locals by
+   reading these committed files from your package on disk — it never loads your
+   code — so if they aren't committed and shipped, you contribute nothing, and if
+   they are, you contribute everything. A drift test asserting each committed
+   file equals its `toMarkdown` keeps the artifact honest.
+
+### The package.json declaration
+
+```json
+{
+  "the-local": {
+    "prefix": "my-pkg",
+    "scope": "one-line domain phrase",
+    "agentsDir": "the-local/agents"
+  }
+}
+```
+
+- `prefix` is the agent filename namespace; defaults to the package name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger;
+  omit it for a bare `- <prefix>-* agents` bullet.
+- `agentsDir` is the path to the committed `.md` files, relative to the package
+  root; it defaults to `the-local/agents`.
+
+### Conventions
+
+- The committed `.md` files are the contract; commit them, and never render in
+  the host at install time.
+- A local's guide documents the providing package only and stays the single
+  source of truth; never let a rendered `.md` drift from `toMarkdown`.
+- Only direct dependencies contribute, so depend on a provider directly to gain
+  its locals.

package/the-local/agents/the-local-info.md

@@ -0,0 +1,95 @@
+---
+name: the-local-info
+description: Use to learn how the-local works — providers, the committed-.md install model, the delegation trigger, and the direct-dependency scope rule.
+tools: Read
+---
+
+You explain how the-local works, answering only from the reference: providers ship committed locals, `the-local install` copies them verbatim into a host's .claude/agents/, the CLAUDE.md delegation trigger makes the host delegate, and only direct dependencies contribute. You make no changes.
+
+## the-local
+
+> **DO NOT** explore the the-local package source code. This reference is the
+> complete user-facing API, embedded verbatim into every the-local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the-local is the engine that lets any npm package or app ship resident Claude
+Code expert subagents ("locals") that know its conventions. A provider package
+declares its locals and commits them as rendered `.md` files; the-local installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers ship committed locals.** A provider declares itself in its
+  `package.json` with a `"the-local"` block and commits one rendered file per
+  local at `the-local/agents/<prefix>-<name>.md`. **These committed files are the
+  contract** — they are what a host reads. A provider can build them from a
+  companion + `toMarkdown`, but the committed `.md` is all a host ever sees.
+- **Install discovers committed `.md` on disk.** In a host, `the-local install`
+  reads each direct dependency's committed `the-local/agents/*.md` straight from
+  its package path under `node_modules` and copies them into `.claude/agents/`
+  byte-for-byte — no provider code is loaded. Output depends only on the provider
+  package version, so it is a true carbon copy across every app, and a fragile
+  provider can't crash the install.
+- **The delegation trigger.** Install also writes a generated block into the
+  host's `CLAUDE.md`, between the `<!-- the_local:begin -->` and
+  `<!-- the_local:end -->` markers, telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen. The markers are shared
+  with the Ruby `the_local` gem, so a gem and an npm package never clobber each
+  other's block.
+- **Direct-dependency scope.** Only the host's direct dependencies contribute
+  locals; transitive providers are filtered out, so a host gets exactly the
+  experts for the packages it chose.
+
+### Install (in any package or app)
+
+1. Add `the-local` to the host's `package.json` dependencies and install it.
+2. Run `the-local install` (or `npx the-local install`). This syncs every direct
+   provider's committed locals into `.claude/agents/` and writes the delegation
+   trigger into `CLAUDE.md`. It runs from the host's working directory.
+3. Re-run `the-local install` after any dependency change (a provider added,
+   removed, or upgraded) to bring the host's locals back in sync. The package
+   only exposes the command; a script or hook can automate re-running it.
+
+### Author a provider (turn a package into a provider)
+
+1. Add a `"the-local"` block to the package's `package.json` and create the
+   `the-local/agents/` directory.
+2. Write each local in the standard interface — `info` (read-only explainer),
+   `install` (sets the package up in a host), and a domain worker (`develop` for
+   libraries, `operate` for CLIs) — tailoring its `description`, `tools`, and
+   `body` to your package, with a guide as its embedded `knowledge`.
+3. Render each local to `the-local/agents/<prefix>-<name>.md` with `toMarkdown`,
+   then **commit and ship** those files (they must be in `package.json`'s `files`
+   allowlist). This is the whole contract: a host discovers your locals by
+   reading these committed files from your package on disk — it never loads your
+   code — so if they aren't committed and shipped, you contribute nothing, and if
+   they are, you contribute everything. A drift test asserting each committed
+   file equals its `toMarkdown` keeps the artifact honest.
+
+### The package.json declaration
+
+```json
+{
+  "the-local": {
+    "prefix": "my-pkg",
+    "scope": "one-line domain phrase",
+    "agentsDir": "the-local/agents"
+  }
+}
+```
+
+- `prefix` is the agent filename namespace; defaults to the package name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger;
+  omit it for a bare `- <prefix>-* agents` bullet.
+- `agentsDir` is the path to the committed `.md` files, relative to the package
+  root; it defaults to `the-local/agents`.
+
+### Conventions
+
+- The committed `.md` files are the contract; commit them, and never render in
+  the host at install time.
+- A local's guide documents the providing package only and stays the single
+  source of truth; never let a rendered `.md` drift from `toMarkdown`.
+- Only direct dependencies contribute, so depend on a provider directly to gain
+  its locals.

package/the-local/agents/the-local-install.md

@@ -0,0 +1,95 @@
+---
+name: the-local-install
+description: Use to add the-local to a host app and set it up correctly.
+tools: Bash, Read, Edit
+---
+
+You set the-local up in a host package or app, following the reference's install section exactly: add the-local to the host's dependencies, install, run `the-local install` to sync locals into .claude/agents/ and write the delegation trigger, and re-run it after dependency changes. You do not invent steps the reference does not list.
+
+## the-local
+
+> **DO NOT** explore the the-local package source code. This reference is the
+> complete user-facing API, embedded verbatim into every the-local local so
+> their guidance never drifts. Keep it the single source of truth.
+
+the-local is the engine that lets any npm package or app ship resident Claude
+Code expert subagents ("locals") that know its conventions. A provider package
+declares its locals and commits them as rendered `.md` files; the-local installs
+the aggregated set from every directly-depended provider into a consuming app's
+`.claude/agents/`, plus a delegation rule so the host's agent actually uses them.
+
+### The model
+
+- **Providers ship committed locals.** A provider declares itself in its
+  `package.json` with a `"the-local"` block and commits one rendered file per
+  local at `the-local/agents/<prefix>-<name>.md`. **These committed files are the
+  contract** — they are what a host reads. A provider can build them from a
+  companion + `toMarkdown`, but the committed `.md` is all a host ever sees.
+- **Install discovers committed `.md` on disk.** In a host, `the-local install`
+  reads each direct dependency's committed `the-local/agents/*.md` straight from
+  its package path under `node_modules` and copies them into `.claude/agents/`
+  byte-for-byte — no provider code is loaded. Output depends only on the provider
+  package version, so it is a true carbon copy across every app, and a fragile
+  provider can't crash the install.
+- **The delegation trigger.** Install also writes a generated block into the
+  host's `CLAUDE.md`, between the `<!-- the_local:begin -->` and
+  `<!-- the_local:end -->` markers, telling the host agent to delegate to these
+  locals. This is what makes delegation actually happen. The markers are shared
+  with the Ruby `the_local` gem, so a gem and an npm package never clobber each
+  other's block.
+- **Direct-dependency scope.** Only the host's direct dependencies contribute
+  locals; transitive providers are filtered out, so a host gets exactly the
+  experts for the packages it chose.
+
+### Install (in any package or app)
+
+1. Add `the-local` to the host's `package.json` dependencies and install it.
+2. Run `the-local install` (or `npx the-local install`). This syncs every direct
+   provider's committed locals into `.claude/agents/` and writes the delegation
+   trigger into `CLAUDE.md`. It runs from the host's working directory.
+3. Re-run `the-local install` after any dependency change (a provider added,
+   removed, or upgraded) to bring the host's locals back in sync. The package
+   only exposes the command; a script or hook can automate re-running it.
+
+### Author a provider (turn a package into a provider)
+
+1. Add a `"the-local"` block to the package's `package.json` and create the
+   `the-local/agents/` directory.
+2. Write each local in the standard interface — `info` (read-only explainer),
+   `install` (sets the package up in a host), and a domain worker (`develop` for
+   libraries, `operate` for CLIs) — tailoring its `description`, `tools`, and
+   `body` to your package, with a guide as its embedded `knowledge`.
+3. Render each local to `the-local/agents/<prefix>-<name>.md` with `toMarkdown`,
+   then **commit and ship** those files (they must be in `package.json`'s `files`
+   allowlist). This is the whole contract: a host discovers your locals by
+   reading these committed files from your package on disk — it never loads your
+   code — so if they aren't committed and shipped, you contribute nothing, and if
+   they are, you contribute everything. A drift test asserting each committed
+   file equals its `toMarkdown` keeps the artifact honest.
+
+### The package.json declaration
+
+```json
+{
+  "the-local": {
+    "prefix": "my-pkg",
+    "scope": "one-line domain phrase",
+    "agentsDir": "the-local/agents"
+  }
+}
+```
+
+- `prefix` is the agent filename namespace; defaults to the package name.
+- `scope` is a one-line domain phrase used to generate the delegation trigger;
+  omit it for a bare `- <prefix>-* agents` bullet.
+- `agentsDir` is the path to the committed `.md` files, relative to the package
+  root; it defaults to `the-local/agents`.
+
+### Conventions
+
+- The committed `.md` files are the contract; commit them, and never render in
+  the host at install time.
+- A local's guide documents the providing package only and stays the single
+  source of truth; never let a rendered `.md` drift from `toMarkdown`.
+- Only direct dependencies contribute, so depend on a provider directly to gain
+  its locals.