diff --git a/.changeset/init-git-root-promotion-warning.md b/.changeset/init-git-root-promotion-warning.md
new file mode 100644
index 000000000..1e8882405
--- /dev/null
+++ b/.changeset/init-git-root-promotion-warning.md
@@ -0,0 +1,29 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+fix(open-knowledge): make `ok init` git-root promotion visible + add `--content-dir`
+
+When `ok init` runs in a sub-folder of a git repo, it scaffolds `.ok/` at the
+git root and scopes the whole repo as content (one `.ok/` per git repo). That
+promotion previously surfaced only as a single `console.log` line on stdout,
+which `ok init 2>&1 | tail` / `| head` silently dropped — so a large repo could
+get whole-repo-scoped without the user noticing.
+
+- The promotion is now disclosed as a styled warning on stderr at decision
+  time, and repeated in the init summary directly next to the "Found N markdown
+  files" preview, naming the sub-folder and how to narrow scope.
+- New `ok init --content-dir <path>` flag scopes content to `<path>` (resolved
+  relative to the current directory, written to `.ok/config.yml` as
+  `content.dir`). `--content-dir .` from a promoted sub-folder scopes the
+  project to that folder. Paths outside the project root, missing paths, or
+  files are rejected with a clear usage error (exit 64). Supplying the flag
+  suppresses the whole-repo promotion warning (the scope choice was explicit).
+- New `ok init --json` flag prints a machine-readable summary to stdout
+  (`projectRoot`, `gitRootPromoted`, `promotedFromDir`, `contentDir`,
+  `contentDirRequested`, `contentDirApplied`, `contentFileCount`, `didGitInit`,
+  `mcpAction`, `editors[]`) so scripts and agents read the promotion + scope
+  signals as fields instead of scraping log text. Diagnostics stay on stderr;
+  stdout carries only the JSON document.
+
+Behavior of the promotion itself is unchanged.
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index 3cd7d96df..593d50ba7 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -35,6 +35,8 @@ import {
 } from '../native/toml-config-engine.ts';
 import {
   applySharingMode,
+  buildInitJsonSummary,
+  ContentDirError,
   classifyExistingMcpEntry,
   detectInstalledEditors,
   type EditorMcpResult,
@@ -45,6 +47,7 @@ import {
   LAUNCH_UI_CHAIN_V1,
   readExistingMcpEntry,
   resolveMcpScope,
+  resolveRequestedContentDir,
   resolveSharingMode,
   runInit,
   writeEditorMcpConfig,
@@ -1518,6 +1521,11 @@ describe('runInit — projectRoot threading', () => {
     expect(result.projectRoot).toBe(repo);
     expect(existsSync(join(repo, OK_DIR))).toBe(true);
     expect(existsSync(join(sub, OK_DIR))).toBe(false);
+    expect(result.gitRootPromoted).toBe(true);
+    expect(result.promotedFromDir).toBe('sub');
+    const output = formatInitResult(result, result.projectRoot);
+    expect(output).toContain('Content scope promoted to the git repo root');
+    expect(output).toContain('content.dir: sub');
   });
 
   it('returns projectRoot equal to cwd when cwd is the git root', async () => {
@@ -1534,6 +1542,10 @@ describe('runInit — projectRoot threading', () => {
 
     expect(result.projectRoot).toBe(repo);
     expect(existsSync(join(repo, OK_DIR))).toBe(true);
+    expect(result.gitRootPromoted).toBe(false);
+    expect(result.promotedFromDir).toBeUndefined();
+    const output = formatInitResult(result, result.projectRoot);
+    expect(output).not.toContain('Content scope promoted to the git repo root');
   });
 
   it('loadConfig succeeds when called against the resolved projectRoot', async () => {
@@ -1555,6 +1567,254 @@ describe('runInit — projectRoot threading', () => {
     expect(rootConfig).toBeDefined();
     expect(rootConfig.content.dir).toBe('.');
   });
+
+  it('--content-dir . from a sub-folder narrows scope to that folder', async () => {
+    const repo = join(fakeHome, 'repo-cd-dot');
+    const sub = join(repo, 'notes');
+    mkdirSync(sub, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    const result = await runInit({
+      cwd: sub,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+      contentDir: '.',
+    });
+
+    expect(result.projectRoot).toBe(repo);
+    expect(result.gitRootPromoted).toBe(true);
+    expect(result.contentDir).toBe('notes');
+    const { config } = loadConfig(result.projectRoot);
+    expect(config.content.dir).toBe('notes');
+
+    const output = formatInitResult(result, result.projectRoot);
+    expect(output).not.toContain('Content scope promoted to the git repo root');
+    expect(output).toContain('Content scope set to notes/');
+  });
+
+  it('--content-dir <subpath> narrows scope relative to cwd', async () => {
+    const repo = join(fakeHome, 'repo-cd-sub');
+    const nested = join(repo, 'docs', 'guides');
+    mkdirSync(nested, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    const result = await runInit({
+      cwd: repo,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+      contentDir: 'docs/guides',
+    });
+
+    expect(result.projectRoot).toBe(repo);
+    expect(result.contentDir).toBe('docs/guides');
+    const { config } = loadConfig(result.projectRoot);
+    expect(config.content.dir).toBe('docs/guides');
+  });
+
+  it('--content-dir outside the project root throws ContentDirError', async () => {
+    const repo = join(fakeHome, 'repo-cd-escape');
+    mkdirSync(repo, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    await expect(
+      runInit({
+        cwd: repo,
+        home: fakeHome,
+        installUserSkill: defaultInstallUserSkill,
+        scope: 'user',
+        contentDir: '..',
+      }),
+    ).rejects.toBeInstanceOf(ContentDirError);
+    expect(existsSync(join(repo, OK_DIR))).toBe(false);
+  });
+
+  it('--content-dir on re-init is ignored (config.yml already exists) and warns', async () => {
+    const repo = join(fakeHome, 'repo-cd-reinit');
+    const sub = join(repo, 'notes');
+    mkdirSync(sub, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    await runInit({
+      cwd: repo,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+    });
+    expect(loadConfig(repo).config.content.dir).toBe('.');
+
+    const result = await runInit({
+      cwd: sub,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+      contentDir: '.',
+    });
+    expect(result.contentDir).toBeUndefined();
+    expect(result.contentDirRequested).toBe('.');
+    expect(result.contentScaffoldFailed).toBe(false);
+    expect(loadConfig(repo).config.content.dir).toBe('.');
+    const output = formatInitResult(result, result.projectRoot);
+    expect(output).toContain('ignored');
+    expect(
+      buildInitJsonSummary(result, { contentDir: '.', contentFileCount: null }).contentDirApplied,
+    ).toBe(false);
+  });
+
+  it('does not claim "config.yml already exists" when content scaffolding failed', async () => {
+    const repo = join(fakeHome, 'repo-scaffold-fail');
+    mkdirSync(repo, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+    const base = await runInit({
+      cwd: repo,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+    });
+
+    const scaffoldFailed = {
+      ...base,
+      contentDirRequested: 'notes',
+      contentDir: undefined,
+      contentScaffoldFailed: true,
+    };
+    expect(formatInitResult(scaffoldFailed, base.projectRoot)).not.toContain('ignored');
+
+    const configExisted = {
+      ...base,
+      contentDirRequested: 'notes',
+      contentDir: undefined,
+      contentScaffoldFailed: false,
+    };
+    expect(formatInitResult(configExisted, base.projectRoot)).toContain('ignored');
+  });
+
+  it('buildInitJsonSummary projects a promoted, narrowed result into stable JSON fields', async () => {
+    const repo = join(fakeHome, 'repo-json');
+    const sub = join(repo, 'notes');
+    mkdirSync(sub, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    const result = await runInit({
+      cwd: sub,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+      contentDir: '.',
+    });
+
+    const summary = buildInitJsonSummary(result, { contentDir: 'notes', contentFileCount: 3 });
+    expect(summary.projectRoot).toBe(repo);
+    expect(summary.gitRootPromoted).toBe(true);
+    expect(summary.promotedFromDir).toBe('notes');
+    expect(summary.contentDir).toBe('notes');
+    expect(summary.contentDirRequested).toBe('.');
+    expect(summary.contentDirApplied).toBe(true);
+    expect(summary.contentFileCount).toBe(3);
+    expect(summary.previewError).toBeNull();
+    expect(JSON.parse(JSON.stringify(summary))).toEqual(summary);
+  });
+
+  it('buildInitJsonSummary surfaces previewError so a null count is unambiguous', async () => {
+    const repo = join(fakeHome, 'repo-json-previewerr');
+    mkdirSync(repo, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+    const base = await runInit({
+      cwd: repo,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+    });
+    const withPreviewError = { ...base, previewWarning: 'cannot access content directory' };
+    const summary = buildInitJsonSummary(withPreviewError, {
+      contentDir: '.',
+      contentFileCount: null,
+    });
+    expect(summary.contentFileCount).toBeNull();
+    expect(summary.previewError).toBe('cannot access content directory');
+  });
+
+  it('buildInitJsonSummary uses null for absent promotion / request / count', async () => {
+    const repo = join(fakeHome, 'repo-json-flat');
+    mkdirSync(repo, { recursive: true });
+    Bun.spawnSync({ cmd: ['git', 'init', '-q', repo], stdout: 'ignore', stderr: 'ignore' });
+
+    const result = await runInit({
+      cwd: repo,
+      home: fakeHome,
+      installUserSkill: defaultInstallUserSkill,
+      scope: 'user',
+    });
+
+    const summary = buildInitJsonSummary(result, { contentDir: '.', contentFileCount: null });
+    expect(summary.gitRootPromoted).toBe(false);
+    expect(summary.promotedFromDir).toBeNull();
+    expect(summary.contentDirRequested).toBeNull();
+    expect(summary.contentDirApplied).toBe(true);
+    expect(summary.contentFileCount).toBeNull();
+  });
+});
+
+describe('resolveRequestedContentDir', () => {
+  let root: string;
+  beforeEach(() => {
+    const raw = join(tmpdir(), `rrcd-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(raw, { recursive: true });
+    root = realpathSync(raw);
+    mkdirSync(join(root, 'sub'), { recursive: true });
+  });
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('returns "." when the request resolves to the project root itself', () => {
+    expect(resolveRequestedContentDir('.', root, root)).toBe('.');
+  });
+
+  it('returns the git-root-relative path for a descendant (cwd-relative input)', () => {
+    expect(resolveRequestedContentDir('sub', root, root)).toBe('sub');
+    expect(resolveRequestedContentDir('.', root, join(root, 'sub'))).toBe('sub');
+  });
+
+  it('throws when the resolved path escapes the project root', () => {
+    expect(() => resolveRequestedContentDir('..', root, root)).toThrow(ContentDirError);
+  });
+
+  it('throws when the path does not exist', () => {
+    expect(() => resolveRequestedContentDir('nope', root, root)).toThrow(ContentDirError);
+  });
+
+  it('throws when the path is a file, not a directory', () => {
+    writeFileSync(join(root, 'file.md'), '# x');
+    expect(() => resolveRequestedContentDir('file.md', root, root)).toThrow(ContentDirError);
+  });
+
+  it('reports a non-ENOENT stat error as "not accessible", not "does not exist"', () => {
+    writeFileSync(join(root, 'file.md'), '# x');
+    let msg = '';
+    try {
+      resolveRequestedContentDir('file.md/nested', root, root);
+    } catch (e) {
+      msg = e instanceof Error ? e.message : String(e);
+    }
+    expect(msg).toContain('not accessible');
+    expect(msg).not.toContain('does not exist');
+  });
+
+  it('resolves . when cwd reaches the project via a symlinked prefix', () => {
+    const linkParent = join(
+      tmpdir(),
+      `rrcd-link-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    symlinkSync(root, linkParent);
+    try {
+      expect(resolveRequestedContentDir('.', root, linkParent)).toBe('.');
+      expect(resolveRequestedContentDir('sub', root, linkParent)).toBe('sub');
+    } finally {
+      rmSync(linkParent, { force: true });
+    }
+  });
 });
 
 describe('resolveMcpScope', () => {
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index b2941c5e6..1123a886b 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -1,5 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { inspect } from 'node:util';
 import { atomicWriteFileSync, withFileLockSync } from '@inkeep/open-knowledge-core/server';
 import type {
   InstallUserSkillOptions,
@@ -27,7 +35,7 @@ import {
   parseTree as parseJsoncTree,
 } from 'jsonc-parser';
 import { stringify as stringifyToml } from 'smol-toml';
-import { OK_DIR } from '../constants.ts';
+import { CONFIG_FILENAME, OK_DIR } from '../constants.ts';
 import { formatPreviewBlock, type PreviewResult } from '../content/preview.ts';
 import { resolveProjectRoot } from '../integrations/resolve-project-root.ts';
 import {
@@ -370,6 +378,54 @@ interface InitCommandOptions {
   promptFn?: () => Promise<McpScope | null>;
   sharing?: 'shared' | 'local-only';
   sharingPromptFn?: (defaultMode: 'shared' | 'local-only') => Promise<'shared' | 'local-only'>;
+  contentDir?: string;
+}
+
+export class ContentDirError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ContentDirError';
+  }
+}
+
+export function resolveRequestedContentDir(
+  input: string,
+  projectRoot: string,
+  cwd: string,
+): string {
+  const abs = resolve(cwd, input);
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(abs);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      throw new ContentDirError(`--content-dir path does not exist: ${abs}`);
+    }
+    throw new ContentDirError(
+      `--content-dir path is not accessible (${code ?? 'unknown error'}): ${abs}`,
+    );
+  }
+  if (!stat.isDirectory()) {
+    throw new ContentDirError(`--content-dir must be a directory: ${abs}`);
+  }
+  const canonRoot = safeRealpath(projectRoot);
+  const canonAbs = safeRealpath(abs);
+  const rel = relative(canonRoot, canonAbs);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new ContentDirError(
+      `--content-dir must be inside the project root (${projectRoot}); got ${abs}`,
+    );
+  }
+  return rel === '' ? '.' : rel;
+}
+
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
 }
 
 interface InitCommandResult {
@@ -388,6 +444,11 @@ interface InitCommandResult {
    * Only set when `didGitInit` is also `true` AND no `.gitignore` was already
    * present at `projectRoot` — pre-existing files are never touched. */
   rootGitignoreCreated: boolean;
+  gitRootPromoted: boolean;
+  promotedFromDir?: string;
+  contentDir?: string;
+  contentDirRequested?: string;
+  contentScaffoldFailed: boolean;
   mcpAction: 'written' | 'overwritten' | 'skipped-missing' | 'skipped-flag' | 'failed' | 'declined';
   mcpPath: string;
   mcpError?: string;
@@ -802,11 +863,19 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
   const resolution = resolveProjectRoot(cwd, { homeDir: options.home });
   const projectRoot = resolution.projectRoot;
   const willScaffold = !existsSync(join(projectRoot, OK_DIR));
+  const promotedFromDir = resolution.gitRootPromoted ? relative(projectRoot, cwd) : undefined;
+  const contentDirScope =
+    options.contentDir !== undefined
+      ? resolveRequestedContentDir(options.contentDir, projectRoot, cwd)
+      : resolution.defaultContentDir;
   if (resolution.ancestorPromoted) {
     console.log(`[ok] Opened existing project at ${projectRoot}`);
-  } else if (resolution.gitRootPromoted && willScaffold) {
-    console.log(
-      `[ok] Initialized OK at ${projectRoot} — opened parent of ${relative(projectRoot, cwd)} because it contains a .git folder`,
+  } else if (resolution.gitRootPromoted && willScaffold && contentDirScope === '.') {
+    process.stderr.write(
+      `${warning(`[ok] Content scope promoted to the git repo root: ${projectRoot}`)}\n` +
+        `      Ran in ${promotedFromDir}/, but .ok/ lives at the git root (one .ok/ per git repo),\n` +
+        `      so the whole repo is now the content scope. To narrow it, re-run with\n` +
+        `      \`ok init --content-dir .\`, or set content.dir: ${promotedFromDir} in ${OK_DIR}/config.yml.\n`,
     );
   }
 
@@ -818,7 +887,7 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
 
   let contentResult: ReturnType<typeof initContent>;
   try {
-    contentResult = initContent(projectRoot, { contentDir: resolution.defaultContentDir });
+    contentResult = initContent(projectRoot, { contentDir: contentDirScope });
   } catch (err) {
     const fallbackPath = EDITOR_TARGETS.claude.configPath(projectRoot, options.home);
     return {
@@ -831,6 +900,10 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
       legacyProjectConfigs: [],
       didGitInit: gitResult.didInit,
       rootGitignoreCreated: false,
+      gitRootPromoted: resolution.gitRootPromoted,
+      promotedFromDir,
+      contentDirRequested: options.contentDir,
+      contentScaffoldFailed: true,
       mcpAction: 'failed',
       mcpPath: fallbackPath,
       mcpError: `Content scaffolding failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -838,6 +911,8 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
     };
   }
 
+  const configCreated = contentResult.created.includes(CONFIG_FILENAME);
+
   let rootGitignoreCreated = false;
   if (gitResult.didInit) {
     try {
@@ -969,6 +1044,11 @@ export async function runInit(options: InitCommandOptions = {}): Promise<InitCom
     skillInstall,
     didGitInit: gitResult.didInit,
     rootGitignoreCreated,
+    gitRootPromoted: resolution.gitRootPromoted,
+    promotedFromDir,
+    contentDir: configCreated ? contentDirScope : undefined,
+    contentDirRequested: options.contentDir,
+    contentScaffoldFailed: false,
     mcpAction: primary.action,
     mcpPath: primary.configPath,
     mcpError: 'error' in primary ? (primary as EditorMcpResult).error : undefined,
@@ -1267,6 +1347,42 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
     }
   }
 
+  if (
+    result.contentDirRequested !== undefined &&
+    result.contentDir === undefined &&
+    !result.contentScaffoldFailed
+  ) {
+    lines.push('');
+    lines.push(
+      warning(
+        `⚠ --content-dir ${result.contentDirRequested} ignored — ${OK_DIR}/config.yml already exists`,
+      ),
+    );
+    lines.push(`  Edit ${OK_DIR}/config.yml → content.dir directly to change the content scope.`);
+  } else if (result.contentDir !== undefined && result.contentDir !== '.') {
+    lines.push('');
+    lines.push(`Content scope set to ${result.contentDir}/ (content.dir in ${OK_DIR}/config.yml).`);
+  } else if (
+    result.gitRootPromoted &&
+    result.contentDir === '.' &&
+    result.contentDirRequested === undefined
+  ) {
+    lines.push('');
+    lines.push(warning('⚠ Content scope promoted to the git repo root'));
+    lines.push(
+      `  .ok/ was initialized at ${cwd} because it contains a .git folder (one .ok/ per git repo),`,
+    );
+    lines.push(
+      `  not the sub-folder you ran \`ok init\` in${result.promotedFromDir ? ` (${result.promotedFromDir})` : ''}. The whole repo is now the content scope.`,
+    );
+    if (result.promotedFromDir) {
+      lines.push(
+        `  To scope to just that sub-folder, re-run \`ok init --content-dir .\` from there, or set`,
+      );
+      lines.push(`  content.dir: ${result.promotedFromDir} in ${OK_DIR}/config.yml.`);
+    }
+  }
+
   if (result.preview) {
     lines.push('');
     lines.push(formatPreviewBlock(result.preview, cwd));
@@ -1309,6 +1425,58 @@ export function formatInitResult(result: InitCommandResult, cwd: string): string
   return lines.join('\n');
 }
 
+export interface InitJsonSummary {
+  projectRoot: string;
+  gitRootPromoted: boolean;
+  promotedFromDir: string | null;
+  contentDir: string;
+  contentDirRequested: string | null;
+  /** True when this run wrote `content.dir` (fresh `config.yml`); false when a
+   * pre-existing config left the requested scope unapplied. */
+  contentDirApplied: boolean;
+  /** Files the watcher will index under the content scope; `null` if preview
+   * failed — pair with `previewError` to distinguish a failure from 0 files. */
+  contentFileCount: number | null;
+  /** The preview/config-read failure message when `contentFileCount` is `null`
+   * because scope resolution threw; `null` when the preview ran (so a `null`
+   * `contentFileCount` alongside a `null` `previewError` genuinely means 0). */
+  previewError: string | null;
+  didGitInit: boolean;
+  mcpAction: InitCommandResult['mcpAction'];
+  editors: Array<{
+    editorId: EditorId;
+    label: string;
+    action: EditorMcpResult['action'];
+    configPath: string;
+    scope: 'project' | 'user';
+  }>;
+}
+
+export function buildInitJsonSummary(
+  result: InitCommandResult,
+  opts: { contentDir: string; contentFileCount: number | null },
+): InitJsonSummary {
+  return {
+    projectRoot: result.projectRoot,
+    gitRootPromoted: result.gitRootPromoted,
+    promotedFromDir: result.promotedFromDir ?? null,
+    contentDir: opts.contentDir,
+    contentDirRequested: result.contentDirRequested ?? null,
+    contentDirApplied: result.contentDir !== undefined,
+    contentFileCount: opts.contentFileCount,
+    previewError: result.previewWarning ?? null,
+    didGitInit: result.didGitInit,
+    mcpAction: result.mcpAction,
+    editors: result.editors.map((e) => ({
+      editorId: e.editorId,
+      label: e.label,
+      action: e.action,
+      configPath: e.configPath,
+      scope: e.configScope === 'project' ? 'project' : 'user',
+    })),
+  };
+}
+
 export function detectInstalledEditors(cwd: string, home?: string): EditorId[] {
   const detected: EditorId[] = [];
   for (const id of ALL_EDITOR_IDS) {
@@ -1319,6 +1487,23 @@ export function detectInstalledEditors(cwd: string, home?: string): EditorId[] {
   return detected;
 }
 
+function redirectStdoutConsoleToStderr(): () => void {
+  const orig = { log: console.log, info: console.info, debug: console.debug };
+  const toErr = (...args: unknown[]): void => {
+    process.stderr.write(
+      `${args.map((a) => (typeof a === 'string' ? a : inspect(a))).join(' ')}\n`,
+    );
+  };
+  console.log = toErr;
+  console.info = toErr;
+  console.debug = toErr;
+  return () => {
+    console.log = orig.log;
+    console.info = orig.info;
+    console.debug = orig.debug;
+  };
+}
+
 export function initCommand(): Command {
   return new Command('init')
     .description(
@@ -1330,6 +1515,11 @@ export function initCommand(): Command {
       '--dev-mcp',
       'Register a local dev MCP entry using node + packages/cli/dist/cli.mjs with debug logging',
     )
+    .option(
+      '--content-dir <dir>',
+      `Limit content to <dir> instead of the whole project. <dir> is interpreted relative to your current directory (e.g. "." = the folder you run the command in), then saved to ${OK_DIR}/config.yml as content.dir.`,
+    )
+    .option('--json', 'Emit a structured JSON summary to stdout (diagnostics stay on stderr)')
     .addOption(
       new Option(
         '--scope <scope>',
@@ -1355,6 +1545,8 @@ export function initCommand(): Command {
         scope?: McpScope;
         shared?: boolean;
         localOnly?: boolean;
+        contentDir?: string;
+        json?: boolean;
       }) => {
         const cwd = process.cwd();
 
@@ -1363,50 +1555,82 @@ export function initCommand(): Command {
           : opts.localOnly
             ? 'local-only'
             : undefined;
-        let result: InitCommandResult;
+        const restoreConsole = opts.json ? redirectStdoutConsoleToStderr() : null;
         try {
-          result = await runInit({
-            cwd,
-            mcp: opts.mcp,
-            devMcp: opts.devMcp,
-            scope: opts.scope,
-            sharing,
-          });
-        } catch (err) {
-          if (err instanceof GitNotAvailableError || err instanceof GitTooOldError) {
-            process.stderr.write(`${err.message}\n`);
-            process.exitCode = 78;
-            return;
+          let result: InitCommandResult;
+          try {
+            result = await runInit({
+              cwd,
+              mcp: opts.mcp,
+              devMcp: opts.devMcp,
+              scope: opts.scope,
+              sharing,
+              contentDir: opts.contentDir,
+            });
+          } catch (err) {
+            if (err instanceof ContentDirError) {
+              process.stderr.write(`${err.message}\n`);
+              process.exitCode = 64;
+              return;
+            }
+            if (err instanceof GitNotAvailableError || err instanceof GitTooOldError) {
+              process.stderr.write(`${err.message}\n`);
+              process.exitCode = 78;
+              return;
+            }
+            if (err instanceof ProjectGitInitError) {
+              process.stderr.write(
+                "open-knowledge could not initialize a git repo for this project. Re-run, or run 'git init' yourself in the project folder.\n",
+              );
+              if (err.stderr) process.stderr.write(`${err.stderr.trim()}\n`);
+              process.exitCode = 1;
+              return;
+            }
+            throw err;
           }
-          if (err instanceof ProjectGitInitError) {
-            process.stderr.write(
-              "open-knowledge could not initialize a git repo for this project. Re-run, or run 'git init' yourself in the project folder.\n",
-            );
-            if (err.stderr) process.stderr.write(`${err.stderr.trim()}\n`);
-            process.exitCode = 1;
-            return;
-          }
-          throw err;
-        }
 
-        try {
-          const { previewContent } = await import('../content/preview.ts');
+          let effectiveContentDir = result.contentDir ?? '.';
+          let contentFileCount: number | null = null;
           const { loadConfig } = await import('../config/loader.ts');
           const { resolveContentDir } = await import('@inkeep/open-knowledge-server');
-          const { config } = loadConfig(result.projectRoot);
-          const contentDir = resolveContentDir(config, result.projectRoot);
-          result.preview = previewContent({
-            projectDir: result.projectRoot,
-            contentDir,
-          });
-        } catch (e) {
-          result.previewWarning = e instanceof Error ? e.message : String(e);
-        }
+          let config: Awaited<ReturnType<typeof loadConfig>>['config'] | undefined;
+          try {
+            config = loadConfig(result.projectRoot).config;
+            effectiveContentDir = config.content.dir;
+          } catch (e) {
+            result.previewWarning = e instanceof Error ? e.message : String(e);
+          }
+          if (config) {
+            try {
+              const { previewContent } = await import('../content/preview.ts');
+              const contentDir = resolveContentDir(config, result.projectRoot);
+              result.preview = previewContent({
+                projectDir: result.projectRoot,
+                contentDir,
+              });
+              contentFileCount = result.preview.totalCount;
+            } catch (e) {
+              result.previewWarning = e instanceof Error ? e.message : String(e);
+            }
+          }
 
-        process.stdout.write(`${formatInitResult(result, result.projectRoot)}\n`);
+          if (opts.json) {
+            process.stdout.write(
+              `${JSON.stringify(
+                buildInitJsonSummary(result, { contentDir: effectiveContentDir, contentFileCount }),
+                null,
+                2,
+              )}\n`,
+            );
+          } else {
+            process.stdout.write(`${formatInitResult(result, result.projectRoot)}\n`);
+          }
 
-        if (result.editors.some((e) => e.action === 'failed') || result.mcpAction === 'failed') {
-          process.exitCode = 1;
+          if (result.editors.some((e) => e.action === 'failed') || result.mcpAction === 'failed') {
+            process.exitCode = 1;
+          }
+        } finally {
+          restoreConsole?.();
         }
       },
     );