feat(relay,core): add monorepo support to init command and workspace discovery

Introduce domscribe.config.json for monorepo setups where the frontend app
lives in a subdirectory (e.g. apps/web). The init wizard now asks if the
project is a monorepo and writes a config file at the repo root pointing
to the app root.

Updated getWorkspaceRoot() discovery chain to check for config files in
addition to .domscribe/ directories, so all CLI commands (serve, stop,
status) and MCP connections resolve the app root automatically.

Also fixes package manager detection in monorepos by checking lockfiles
at the repo root rather than the app subdirectory.

Author: Narrator

README.md

@@ -292,6 +292,18 @@ module.exports = {
 
 For plugin configuration options, see the [`@domscribe/transform` README](./packages/domscribe-transform/README.md).
 
+#### Monorepos
+
+If your frontend app is in a subdirectory (e.g. `apps/web`), pass `--app-root` during init:
+
+```bash
+npx domscribe init --app-root apps/web
+```
+
+Or run `npx domscribe init` and follow the prompts — the wizard asks if you're in a monorepo.
+
+This creates a `domscribe.config.json` at your repo root that tells all Domscribe tools where your app lives. CLI commands (`serve`, `stop`, `status`) and agent MCP connections automatically resolve the app root from this config — no extra flags needed.
+
 ### Agent-Side — Connect Your Coding Agent
 
 Domscribe exposes 12 tools and 4 prompts via MCP. Agent plugins bundle the MCP config and a skill file that teaches the agent how to use the tools effectively.

packages/domscribe-core/src/index.ts

@@ -5,6 +5,7 @@
 
 // Export all types
 export * from './lib/types/annotation.js';
+export * from './lib/types/config.js';
 export * from './lib/types/manifest.js';
 export * from './lib/types/nullable.js';
 

packages/domscribe-core/src/lib/constants/index.ts

@@ -119,6 +119,7 @@ export const PATHS = {
   AGENT_INSTRUCTIONS: '.domscribe/agent-instructions',
 
   // Config files
+  CONFIG_JSON_FILE: 'domscribe.config.json',
   CONFIG_FILE: 'domscribe.config.ts',
   CONFIG_JS_FILE: 'domscribe.config.js',
   VALIDATION_RECIPE: 'domscribe.validation.yaml',

packages/domscribe-core/src/lib/types/config.ts

@@ -0,0 +1,23 @@
+/**
+ * Domscribe project configuration schema.
+ * @module @domscribe/core/types/config
+ */
+import { z } from 'zod';
+
+/**
+ * Schema for `domscribe.config.json`.
+ *
+ * @remarks
+ * Used in monorepo setups where the coding agent starts at the repo root
+ * but the frontend app lives in a subdirectory. The config file sits at
+ * the repo root and points to the app root where `.domscribe/` is located.
+ */
+export const DomscribeConfigSchema = z.object({
+  appRoot: z
+    .string()
+    .describe(
+      'Relative path from the config file to the frontend app root directory',
+    ),
+});
+
+export type DomscribeConfig = z.infer<typeof DomscribeConfigSchema>;

packages/domscribe-relay/README.md

@@ -24,6 +24,8 @@ domscribe mcp       # Run as MCP server via stdio
 
 For use in agent MCP configuration, the standalone `domscribe-mcp` binary runs the MCP server directly over stdio without the HTTP/WebSocket relay.
 
+**Monorepo support:** All commands automatically resolve the app root from a `domscribe.config.json` file when run from a monorepo root. Run `domscribe init --app-root <path>` to generate the config, or let the interactive wizard detect it.
+
 ## Annotation Lifecycle
 
 A developer clicks an element in the running app, types an instruction, and submits it. The annotation moves through the following states:

packages/domscribe-relay/src/cli/commands/init.command.ts

@@ -14,6 +14,7 @@ interface InitCommandOptions {
   agent?: string;
   framework?: string;
   pm?: string;
+  appRoot?: string;
 }
 
 export const InitCommand = new Command('init')
@@ -26,6 +27,7 @@ export const InitCommand = new Command('init')
     `Framework + bundler (${FRAMEWORK_IDS.join(', ')})`,
   )
   .option('--pm <name>', `Package manager (${PACKAGE_MANAGER_IDS.join(', ')})`)
+  .option('--app-root <path>', 'Path to frontend app root (for monorepos)')
   .action(async (options: InitCommandOptions) => {
     try {
       if (options.agent && !AGENT_IDS.includes(options.agent as never)) {
@@ -58,6 +60,7 @@ export const InitCommand = new Command('init')
         agent: options.agent as InitOptions['agent'],
         framework: options.framework as InitOptions['framework'],
         pm: options.pm as InitOptions['pm'],
+        appRoot: options.appRoot,
       };
 
       await runInitWizard(initOptions);

packages/domscribe-relay/src/cli/config-loader.spec.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+import { findConfigFile, loadAppRoot } from './config-loader.js';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}));
+
+describe('findConfigFile', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should return JSON config path when it exists', () => {
+    // Arrange
+    vi.mocked(existsSync).mockImplementation(
+      (p) => String(p) === '/project/domscribe.config.json',
+    );
+
+    // Act
+    const result = findConfigFile('/project');
+
+    // Assert
+    expect(result).toBe('/project/domscribe.config.json');
+  });
+
+  it('should prefer JSON over JS and TS', () => {
+    // Arrange
+    vi.mocked(existsSync).mockReturnValue(true);
+
+    // Act
+    const result = findConfigFile('/project');
+
+    // Assert
+    expect(result).toBe('/project/domscribe.config.json');
+  });
+
+  it('should fall back to JS when JSON does not exist', () => {
+    // Arrange
+    vi.mocked(existsSync).mockImplementation(
+      (p) => String(p) === '/project/domscribe.config.js',
+    );
+
+    // Act
+    const result = findConfigFile('/project');
+
+    // Assert
+    expect(result).toBe('/project/domscribe.config.js');
+  });
+
+  it('should return undefined when no config file exists', () => {
+    // Arrange
+    vi.mocked(existsSync).mockReturnValue(false);
+
+    // Act
+    const result = findConfigFile('/project');
+
+    // Assert
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('loadAppRoot', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should parse valid JSON and resolve appRoot', () => {
+    // Arrange
+    vi.mocked(readFileSync).mockReturnValue(
+      JSON.stringify({ appRoot: './apps/web' }),
+    );
+
+    // Act
+    const result = loadAppRoot('/monorepo/domscribe.config.json');
+
+    // Assert
+    expect(result).toBe('/monorepo/apps/web');
+  });
+
+  it('should resolve relative paths with parent traversal', () => {
+    // Arrange
+    vi.mocked(readFileSync).mockReturnValue(
+      JSON.stringify({ appRoot: '../frontend' }),
+    );
+
+    // Act
+    const result = loadAppRoot('/monorepo/config/domscribe.config.json');
+
+    // Assert
+    expect(result).toBe('/monorepo/frontend');
+  });
+
+  it('should throw on missing appRoot field', () => {
+    // Arrange
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({}));
+
+    // Act & Assert
+    expect(() => loadAppRoot('/project/domscribe.config.json')).toThrow();
+  });
+
+  it('should throw on invalid JSON', () => {
+    // Arrange
+    vi.mocked(readFileSync).mockReturnValue('not json');
+
+    // Act & Assert
+    expect(() => loadAppRoot('/project/domscribe.config.json')).toThrow();
+  });
+});

packages/domscribe-relay/src/cli/config-loader.ts

@@ -0,0 +1,41 @@
+/**
+ * Domscribe config file discovery and loading.
+ * @module @domscribe/relay/cli/config-loader
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { DomscribeConfigSchema, PATHS } from '@domscribe/core';
+
+/**
+ * Config filenames to scan, in priority order.
+ * JSON is preferred; `.js` and `.ts` are reserved for future use.
+ */
+const CONFIG_FILENAMES = [
+  PATHS.CONFIG_JSON_FILE,
+  PATHS.CONFIG_JS_FILE,
+  PATHS.CONFIG_FILE,
+] as const;
+
+/**
+ * Find a Domscribe config file in the given directory.
+ * Returns the absolute path to the first match, or `undefined`.
+ */
+export function findConfigFile(dir: string): string | undefined {
+  for (const name of CONFIG_FILENAMES) {
+    const filePath = path.join(dir, name);
+    if (existsSync(filePath)) return filePath;
+  }
+  return undefined;
+}
+
+/**
+ * Read a `domscribe.config.json` and resolve the `appRoot` to an absolute path
+ * relative to the config file's directory.
+ */
+export function loadAppRoot(configPath: string): string {
+  const raw = readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw) as unknown;
+  const config = DomscribeConfigSchema.parse(parsed);
+  return path.resolve(path.dirname(configPath), config.appRoot);
+}

packages/domscribe-relay/src/cli/init/framework-step.ts

@@ -142,8 +142,8 @@ export async function runFrameworkStep(
     return;
   }
 
-  // Detect and confirm package manager
-  const detected = detectPackageManager(cwd);
+  // Detect package manager from the repo root (lockfiles live there, not in app subdirs)
+  const detected = detectPackageManager(process.cwd());
   const pm = await confirmPackageManager(detected, options);
 
   const installCmd = buildInstallCommand(pm, framework.package);

packages/domscribe-relay/src/cli/init/init-wizard.spec.ts

@@ -12,6 +12,10 @@ vi.mock('./agent-step.js', () => ({
   runAgentStep: vi.fn().mockResolvedValue(undefined),
 }));
 
+vi.mock('./monorepo-step.js', () => ({
+  runMonorepoStep: vi.fn().mockResolvedValue({ appRoot: '/resolved/app/root' }),
+}));
+
 vi.mock('./framework-step.js', () => ({
   runFrameworkStep: vi.fn().mockResolvedValue(undefined),
 }));
@@ -41,15 +45,20 @@ describe('runInitWizard', () => {
     );
   });
 
-  it('should call steps in order: agent → framework → gitignore', async () => {
+  it('should call steps in order: agent → monorepo → framework → gitignore', async () => {
     // Arrange
     const callOrder: string[] = [];
     const { runAgentStep } = await import('./agent-step.js');
+    const { runMonorepoStep } = await import('./monorepo-step.js');
     const { runFrameworkStep } = await import('./framework-step.js');
     const { runGitignoreStep } = await import('./gitignore-step.js');
     vi.mocked(runAgentStep).mockImplementation(async () => {
       callOrder.push('agent');
     });
+    vi.mocked(runMonorepoStep).mockImplementation(async () => {
+      callOrder.push('monorepo');
+      return { appRoot: process.cwd() };
+    });
     vi.mocked(runFrameworkStep).mockImplementation(async () => {
       callOrder.push('framework');
     });
@@ -61,28 +70,62 @@ describe('runInitWizard', () => {
     await runInitWizard(baseOptions);
 
     // Assert
-    expect(callOrder).toEqual(['agent', 'framework', 'gitignore']);
+    expect(callOrder).toEqual(['agent', 'monorepo', 'framework', 'gitignore']);
   });
 
-  it('should pass options through to both steps', async () => {
+  it('should pass appRoot from monorepo step to framework step', async () => {
+    // Arrange
+    const { runMonorepoStep } = await import('./monorepo-step.js');
+    const { runFrameworkStep } = await import('./framework-step.js');
+    vi.mocked(runMonorepoStep).mockResolvedValue({
+      appRoot: '/monorepo/apps/web',
+    });
+
+    // Act
+    await runInitWizard(baseOptions);
+
+    // Assert
+    expect(runFrameworkStep).toHaveBeenCalledWith(
+      baseOptions,
+      '/monorepo/apps/web',
+    );
+  });
+
+  it('should pass cwd (not appRoot) to gitignore step', async () => {
+    // Arrange
+    const { runMonorepoStep } = await import('./monorepo-step.js');
+    const { runGitignoreStep } = await import('./gitignore-step.js');
+    vi.mocked(runMonorepoStep).mockResolvedValue({
+      appRoot: '/monorepo/apps/web',
+    });
+
+    // Act
+    await runInitWizard(baseOptions);
+
+    // Assert
+    expect(runGitignoreStep).toHaveBeenCalledWith(baseOptions, process.cwd());
+  });
+
+  it('should pass options through to all steps', async () => {
     // Arrange
     const options: InitOptions = {
       force: true,
       dryRun: true,
       agent: 'claude-code',
       framework: 'next',
       pm: 'pnpm',
+      appRoot: 'apps/web',
     };
     const { runAgentStep } = await import('./agent-step.js');
-    const { runFrameworkStep } = await import('./framework-step.js');
+    const { runMonorepoStep } = await import('./monorepo-step.js');
     const { runGitignoreStep } = await import('./gitignore-step.js');
 
     // Act
     await runInitWizard(options);
 
     // Assert
     expect(runAgentStep).toHaveBeenCalledWith(options);
-    expect(runFrameworkStep).toHaveBeenCalledWith(options, process.cwd());
+    expect(runMonorepoStep).toHaveBeenCalledWith(options, process.cwd());
     expect(runGitignoreStep).toHaveBeenCalledWith(options, process.cwd());
   });
 });