@comment-io/cli 0.1.1-alpha.9 → 0.1.2

package/shared/commentfs-sync.ts

@@ -1,1565 +0,0 @@
-import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
-
-export const COMMENTFS_VERSION = 1;
-export const DEFAULT_COMMENTFS_BASE_URL = 'https://comment.io';
-export const DEFAULT_SYNC_ROOT = join(homedir(), 'Comment Docs');
-export const COMMENT_DIR = '.comment';
-export const MANIFEST_FILE = 'manifest.json';
-export const CREDENTIALS_FILE = 'credentials.json';
-export const COMMENTFS_CONFIG_FILE = 'commentfs.json';
-
-export interface CommentFsManifestDoc {
-  slug: string;
-  title: string;
-  file: string;
-  sidecarDir?: string;
-  statusFile: string;
-  editFile: string;
-  authorshipFile?: string;
-  commentsFile?: string;
-  participantsFile?: string;
-  sourceUrl: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  baseUrl: string;
-  token?: string;
-  addedAt: string;
-  lastSyncedAt?: string;
-  lastRevision?: number;
-  lastMarkdownSha256?: string;
-  lastCanonicalMarkdownSha256?: string;
-  lastLocalChange?: CommentFsLocalChange;
-  lastSyncHealth?: CommentFsSyncHealth;
-  authMode?: 'user_api_key';
-}
-
-export interface CommentFsRecoveryRecord {
-  slug: string;
-  title: string;
-  file: string;
-  statusFile: string;
-  editFile: string;
-  sourceUrl: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  localChange: CommentFsLocalChange;
-  removedAt: string;
-}
-
-export interface CommentFsLocalChange {
-  detectedAt: string;
-  recoveryFile: string;
-  restoredCanonicalRevision: number;
-}
-
-export interface CommentFsManifest {
-  version: 1;
-  docs: CommentFsManifestDoc[];
-  recoveries?: CommentFsRecoveryRecord[];
-  remoteSyncCursor?: number;
-}
-
-export interface CommentFsConfig {
-  version: 1;
-  baseUrl: string;
-  userApiKey?: string;
-  updatedAt: string;
-}
-
-interface CommentFsCredentials {
-  version: 1;
-  docs: Record<string, { token: string; updatedAt: string }>;
-}
-
-export interface CommentFsSyncHealth {
-  status: 'ok' | 'error';
-  lastAttemptAt: string;
-  lastSuccessAt?: string;
-  lastErrorAt?: string;
-  lastError?: string;
-}
-
-export interface CommentFsDocResponse {
-  id?: string;
-  slug?: string;
-  title?: string;
-  markdown: string;
-  revision: number;
-  your_role?: string;
-  read_only?: boolean;
-  updated_at?: string;
-  authorship?: unknown;
-  blocks?: unknown;
-  comment_meta?: unknown;
-  participants?: unknown;
-  actors?: unknown;
-  your_token?: string;
-}
-
-export interface CommentFsDocRef {
-  slug: string;
-  token?: string;
-  baseUrl: string;
-  sourceUrl: string;
-}
-
-class CommentFsDeletedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'CommentFsDeletedError';
-  }
-}
-
-export interface SyncDocOptions {
-  rootDir?: string;
-  input: string;
-  token?: string;
-  userApiKey?: string;
-  baseUrl?: string;
-  agentHandle?: string;
-  filename?: string;
-  now?: () => Date;
-  fetchImpl?: typeof fetch;
-  homeDir?: string;
-}
-
-export interface SyncConfiguredOptions {
-  rootDir?: string;
-  baseUrl?: string;
-  userApiKey?: string;
-  full?: boolean;
-  now?: () => Date;
-  fetchImpl?: typeof fetch;
-  homeDir?: string;
-}
-
-export interface SyncDocResult {
-  ok: true;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  manifestPath: string;
-  revision: number;
-  changed: boolean;
-  localChangeDetected: boolean;
-  recoveryPath?: string;
-}
-
-export interface SyncDocFailure {
-  ok: false;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  manifestPath: string;
-  error: string;
-}
-
-export interface SyncDocUnselectedResult {
-  ok: true;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  manifestPath: string;
-  revision: number;
-  changed: true;
-  localChangeDetected: boolean;
-  recoveryPath?: string;
-  disabled: true;
-}
-
-export interface ExplainPathResult {
-  rootDir: string;
-  inputPath: string;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  sourceUrl: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  explanation: string;
-}
-
-export interface RecoverPathResult {
-  rootDir: string;
-  inputPath: string;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  recoveryPath: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  detectedAt: string;
-  restoredCanonicalRevision: number;
-  instructions: string;
-}
-
-export interface CommentFsStatusDoc {
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  sourceUrl: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  revision: number | null;
-  lastSyncedAt: string | null;
-  readOnly: boolean;
-  syncHealth: CommentFsSyncHealth | null;
-  localChange: CommentFsLocalChange | null;
-}
-
-export interface CommentFsStatus {
-  rootDir: string;
-  manifestPath: string;
-  docs: CommentFsStatusDoc[];
-}
-
-export interface CommentFsRepairResult {
-  slug: string;
-  title: string;
-  markdownPath: string;
-  existed: boolean;
-  repaired: boolean;
-}
-
-interface FetchDocOptions {
-  ref: CommentFsDocRef;
-  token?: string;
-  userApiKey?: string;
-  agentHandle?: string;
-  fetchImpl: typeof fetch;
-  homeDir: string;
-}
-
-interface RemoteSyncDoc {
-  slug: string;
-  enabled?: boolean;
-  title?: string | null;
-  last_known_revision?: number | null;
-}
-
-interface RemoteSyncChangesResponse {
-  cursor: number;
-  sync_docs: RemoteSyncDoc[];
-}
-
-export function parseCommentDocRef(input: string, defaultBaseUrl = DEFAULT_COMMENTFS_BASE_URL): CommentFsDocRef {
-  const trimmed = input.trim();
-  if (!trimmed) throw new Error('A Comment.io doc URL or slug is required.');
-
-  try {
-    const url = new URL(trimmed);
-    const parts = url.pathname.split('/').filter(Boolean);
-    let slug = '';
-    if ((parts[0] === 'd' || parts[0] === 'docs') && parts[1]) slug = decodeURIComponent(parts[1]);
-    else if (parts.length === 1) slug = decodeURIComponent(parts[0]);
-    if (!slug) throw new Error(`Could not find a document slug in ${trimmed}`);
-    if (!/^[A-Za-z0-9_-]+$/.test(slug)) {
-      throw new Error(`Invalid Comment.io slug: ${slug}`);
-    }
-    const sourceUrl = new URL(url.toString());
-    sourceUrl.username = '';
-    sourceUrl.password = '';
-    sourceUrl.searchParams.delete('token');
-    sourceUrl.searchParams.delete('access_token');
-    return {
-      slug,
-      token: url.searchParams.get('token') ?? undefined,
-      baseUrl: url.origin.replace(/\/$/, ''),
-      sourceUrl: sourceUrl.toString(),
-    };
-  } catch (error) {
-    if (error instanceof TypeError) {
-      const slug = trimmed.replace(/^@/, '');
-      if (!/^[A-Za-z0-9_-]+$/.test(slug)) {
-        throw new Error(`Invalid Comment.io slug: ${trimmed}`);
-      }
-      const baseUrl = defaultBaseUrl.replace(/\/$/, '');
-      return {
-        slug,
-        baseUrl,
-        sourceUrl: `${baseUrl}/d/${encodeURIComponent(slug)}`,
-      };
-    }
-    throw error;
-  }
-}
-
-export function safeMarkdownFilename(title: string | undefined, slug: string): string {
-  const seed = (title?.trim() || slug).normalize('NFKD');
-  const stem = seed
-    .replace(/[\u0300-\u036f]/g, '')
-    .toLowerCase()
-    .replace(/[^a-z0-9._ -]+/g, '')
-    .replace(/\s+/g, '-')
-    .replace(/[. -]+$/g, '')
-    .replace(/^[. -]+/g, '')
-    .slice(0, 80) || slug;
-  return stem.endsWith('.md') ? stem : `${stem}.md`;
-}
-
-function validateProjectionFilename(filename: string): string {
-  const trimmed = filename.trim();
-  if (
-    !trimmed ||
-    trimmed !== basename(trimmed) ||
-    trimmed.includes('\\') ||
-    trimmed === '.' ||
-    trimmed === '..'
-  ) {
-    throw new Error(`Invalid CommentFS projection filename: ${filename}`);
-  }
-  return trimmed.endsWith('.md') ? trimmed : `${trimmed}.md`;
-}
-
-export function manifestPath(rootDir: string): string {
-  return join(rootDir, COMMENT_DIR, MANIFEST_FILE);
-}
-
-function credentialsPath(rootDir: string): string {
-  return join(rootDir, COMMENT_DIR, CREDENTIALS_FILE);
-}
-
-export async function readManifest(rootDir: string): Promise<CommentFsManifest> {
-  const path = manifestPath(rootDir);
-  if (!existsSync(path)) return { version: COMMENTFS_VERSION, docs: [] };
-  const parsed = JSON.parse(await readFile(path, 'utf-8')) as CommentFsManifest;
-  if (parsed.version !== COMMENTFS_VERSION || !Array.isArray(parsed.docs)) {
-    throw new Error(`Unsupported CommentFS manifest at ${path}`);
-  }
-  return parsed;
-}
-
-export async function writeManifest(rootDir: string, manifest: CommentFsManifest): Promise<void> {
-  const path = manifestPath(rootDir);
-  await mkdir(dirname(path), { recursive: true, mode: 0o755 });
-  const sanitized: CommentFsManifest = {
-    ...manifest,
-    docs: manifest.docs.map(({ token: _token, ...doc }) => doc),
-    recoveries: manifest.recoveries?.slice(-100),
-  };
-  await writeJsonIfChanged(path, sanitized);
-}
-
-async function readCredentials(rootDir: string): Promise<CommentFsCredentials> {
-  const path = credentialsPath(rootDir);
-  if (!existsSync(path)) return { version: COMMENTFS_VERSION, docs: {} };
-  const parsed = JSON.parse(await readFile(path, 'utf-8')) as CommentFsCredentials;
-  if (parsed.version !== COMMENTFS_VERSION || !parsed.docs || typeof parsed.docs !== 'object') {
-    throw new Error(`Unsupported CommentFS credentials at ${path}`);
-  }
-  return parsed;
-}
-
-async function readDocCredential(rootDir: string, slug: string): Promise<string | undefined> {
-  const credentials = await readCredentials(rootDir);
-  return credentials.docs[slug]?.token;
-}
-
-async function saveDocCredential(rootDir: string, slug: string, token: string, now: string): Promise<void> {
-  const credentials = await readCredentials(rootDir);
-  if (credentials.docs[slug]?.token === token) {
-    const path = credentialsPath(rootDir);
-    if (existsSync(path)) await chmod(path, 0o600);
-    return;
-  }
-  credentials.docs[slug] = { token, updatedAt: now };
-  await writePrivateJsonIfChanged(credentialsPath(rootDir), credentials);
-}
-
-async function deleteDocCredential(rootDir: string, slug: string): Promise<void> {
-  const path = credentialsPath(rootDir);
-  if (!existsSync(path)) return;
-  const credentials = await readCredentials(rootDir);
-  if (!credentials.docs[slug]) return;
-  delete credentials.docs[slug];
-  await writePrivateJsonIfChanged(path, credentials);
-}
-
-export function commentFsConfigPath(homeDir = homedir()): string {
-  return join(homeDir, '.comment-io', COMMENTFS_CONFIG_FILE);
-}
-
-export async function readCommentFsConfig(homeDir = homedir()): Promise<CommentFsConfig | null> {
-  const path = commentFsConfigPath(homeDir);
-  if (!existsSync(path)) return null;
-  const parsed = JSON.parse(await readFile(path, 'utf-8')) as CommentFsConfig;
-  if (parsed.version !== COMMENTFS_VERSION) {
-    throw new Error(`Unsupported CommentFS config at ${path}`);
-  }
-  return parsed;
-}
-
-export async function saveCommentFsUserApiKey(options: {
-  userApiKey: string;
-  baseUrl?: string;
-  homeDir?: string;
-  now?: () => Date;
-}): Promise<{ path: string; config: CommentFsConfig }> {
-  const path = commentFsConfigPath(options.homeDir ?? homedir());
-  const config: CommentFsConfig = {
-    version: COMMENTFS_VERSION,
-    baseUrl: (options.baseUrl ?? DEFAULT_COMMENTFS_BASE_URL).replace(/\/$/, ''),
-    userApiKey: options.userApiKey.trim(),
-    updatedAt: (options.now ?? (() => new Date()))().toISOString(),
-  };
-  await writePrivateJsonIfChanged(path, config);
-  return { path, config };
-}
-
-export async function deleteCommentFsUserApiKey(homeDir = homedir()): Promise<{ path: string; removed: boolean }> {
-  const path = commentFsConfigPath(homeDir);
-  const removed = existsSync(path);
-  await rm(path, { force: true });
-  return { path, removed };
-}
-
-export async function syncOneCommentDoc(options: SyncDocOptions): Promise<SyncDocResult> {
-  const rootDir = resolve(options.rootDir ?? DEFAULT_SYNC_ROOT);
-  const now = options.now ?? (() => new Date());
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const homeDir = options.homeDir ?? homedir();
-  const ref = parseCommentDocRef(options.input, options.baseUrl ?? DEFAULT_COMMENTFS_BASE_URL);
-  const explicitToken = options.token;
-
-  await ensureRoot(rootDir);
-  const manifest = await readManifest(rootDir);
-  const existing = manifest.docs.find((doc) => doc.slug === ref.slug);
-  const useUserApiKeyAuth = Boolean(options.userApiKey) || existing?.authMode === 'user_api_key';
-  if (existing?.authMode === 'user_api_key' && !options.userApiKey) {
-    throw new Error('This CommentFS document requires a configured user API key. Run `comment sync login --api-key <user-api-key>` or set COMMENT_IO_USER_API_KEY.');
-  }
-  const storedToken = await readDocCredential(rootDir, ref.slug).catch(() => undefined);
-  const doc = await fetchCommentDoc({
-    ref,
-    token: useUserApiKeyAuth ? explicitToken : explicitToken ?? storedToken ?? existing?.token,
-    userApiKey: options.userApiKey,
-    agentHandle: options.agentHandle,
-    fetchImpl,
-    homeDir,
-  });
-  const title = doc.title?.trim() || ref.slug;
-  const file = options.filename
-    ? validateProjectionFilename(options.filename)
-    : existing?.file
-      ? validateProjectionFilename(existing.file)
-      : await chooseMarkdownFile(rootDir, manifest, title, ref.slug);
-  const markdownPath = join(rootDir, file);
-  const syncedAt = now().toISOString();
-  const sidecars = sidecarPaths(ref.slug);
-  const canonicalMarkdownSha = sha256(doc.markdown);
-  const projectedMarkdown = buildMarkdownProjection(doc.markdown, {
-    title,
-    sourceUrl: ref.sourceUrl,
-    statusPath: join(COMMENT_DIR, sidecars.statusFile),
-    editPath: join(COMMENT_DIR, sidecars.editFile),
-  });
-  const projectionMarkdownSha = sha256(projectedMarkdown);
-  const projectionExists = await fileExists(markdownPath);
-  const localMarkdown = projectionExists ? await readFile(markdownPath, 'utf-8') : undefined;
-  const localChangeDetected = Boolean(
-    existing?.lastMarkdownSha256 &&
-    localMarkdown !== undefined &&
-    sha256(localMarkdown) !== existing.lastMarkdownSha256,
-  );
-  const canonicalChanged =
-    !existing ||
-    existing.lastRevision !== doc.revision ||
-    (existing.lastCanonicalMarkdownSha256 ?? existing.lastMarkdownSha256) !== canonicalMarkdownSha ||
-    existing.lastMarkdownSha256 !== projectionMarkdownSha ||
-    !projectionExists;
-  const changed = canonicalChanged || localChangeDetected;
-  const refreshHealth = changed || existing?.lastSyncHealth?.status === 'error' || !existing?.lastSyncHealth;
-  const newLocalChange = localChangeDetected && localMarkdown !== undefined
-    ? await preserveLocalChange(rootDir, ref.slug, localMarkdown, syncedAt, doc.revision)
-    : undefined;
-  const localChange = newLocalChange ?? existing?.lastLocalChange;
-
-  const nextDoc: CommentFsManifestDoc = {
-    slug: ref.slug,
-    title,
-    file,
-    sidecarDir: sidecars.sidecarDir,
-    statusFile: sidecars.statusFile,
-    editFile: sidecars.editFile,
-    authorshipFile: sidecars.authorshipFile,
-    commentsFile: sidecars.commentsFile,
-    participantsFile: sidecars.participantsFile,
-    sourceUrl: ref.sourceUrl,
-    apiUrl: `${ref.baseUrl}/docs/${encodeURIComponent(ref.slug)}`,
-    apiDocsUrl: `${ref.baseUrl}/docs/${encodeURIComponent(ref.slug)}?docs`,
-    baseUrl: ref.baseUrl,
-    addedAt: existing?.addedAt ?? syncedAt,
-    lastSyncedAt: changed ? syncedAt : existing?.lastSyncedAt,
-    lastRevision: doc.revision,
-    lastMarkdownSha256: projectionMarkdownSha,
-    lastCanonicalMarkdownSha256: canonicalMarkdownSha,
-    lastLocalChange: localChange,
-    authMode: useUserApiKeyAuth && !explicitToken ? 'user_api_key' : existing?.authMode,
-    lastSyncHealth: refreshHealth
-      ? {
-          status: 'ok',
-          lastAttemptAt: syncedAt,
-          lastSuccessAt: syncedAt,
-        }
-      : existing.lastSyncHealth,
-  };
-
-  if (changed) {
-    await writeReadOnlyProjection(markdownPath, projectedMarkdown);
-  } else {
-    await ensureReadOnly(markdownPath);
-  }
-
-  if (existing) await removeSupersededSidecars(rootDir, existing, nextDoc);
-  const credentialToken = useUserApiKeyAuth
-    ? undefined
-    : doc.your_token ?? explicitToken ?? storedToken ?? existing?.token ?? ref.token;
-  if (useUserApiKeyAuth) await deleteDocCredential(rootDir, ref.slug);
-  else if (credentialToken) await saveDocCredential(rootDir, ref.slug, credentialToken, syncedAt);
-  if (newLocalChange) indexRecoveryRecord(manifest, nextDoc, newLocalChange, syncedAt);
-  await writeRootReadme(rootDir);
-  await writeDocSidecars(rootDir, nextDoc, doc, canonicalMarkdownSha, projectionMarkdownSha, changed ? syncedAt : nextDoc.lastSyncedAt ?? syncedAt);
-
-  const idx = manifest.docs.findIndex((entry) => entry.slug === ref.slug);
-  if (idx >= 0) manifest.docs[idx] = nextDoc;
-  else manifest.docs.push(nextDoc);
-  sortManifest(manifest);
-  await writeManifest(rootDir, manifest);
-
-  return {
-    ok: true,
-    slug: ref.slug,
-    title,
-    markdownPath,
-    statusPath: join(rootDir, COMMENT_DIR, nextDoc.statusFile),
-    editPath: join(rootDir, COMMENT_DIR, nextDoc.editFile),
-    manifestPath: manifestPath(rootDir),
-    revision: doc.revision,
-    changed,
-    localChangeDetected,
-    recoveryPath: localChangeDetected && localChange ? join(rootDir, localChange.recoveryFile) : undefined,
-  };
-}
-
-export async function syncConfiguredCommentDocs(options: SyncConfiguredOptions = {}): Promise<SyncDocResult[]> {
-  const results = await syncConfiguredCommentDocsSettled(options);
-  const firstFailure = results.find((result): result is SyncDocFailure => !result.ok);
-  if (firstFailure) throw new Error(firstFailure.error);
-  return results.filter((result): result is SyncDocResult => result.ok);
-}
-
-export async function syncConfiguredCommentDocsSettled(
-  options: SyncConfiguredOptions = {},
-): Promise<Array<SyncDocResult | SyncDocFailure>> {
-  const rootDir = resolve(options.rootDir ?? DEFAULT_SYNC_ROOT);
-  const manifest = await readManifest(rootDir);
-  const results: Array<SyncDocResult | SyncDocFailure> = [];
-  const credentials = await readCredentials(rootDir).catch(() => ({ version: COMMENTFS_VERSION, docs: {} }) as CommentFsCredentials);
-  const config = await readCommentFsConfig(options.homeDir ?? homedir()).catch(() => null);
-  const fallbackUserApiKey = options.userApiKey ?? process.env.COMMENT_IO_USER_API_KEY ?? config?.userApiKey;
-  for (const manifestDoc of manifest.docs) {
-    try {
-      const userApiKey = manifestDoc.authMode === 'user_api_key' ? fallbackUserApiKey : options.userApiKey;
-      if (manifestDoc.authMode === 'user_api_key' && !userApiKey) {
-        throw new Error('This CommentFS document requires a configured user API key. Run `comment sync login --api-key <user-api-key>` or set COMMENT_IO_USER_API_KEY.');
-      }
-      results.push(await syncOneCommentDoc({
-        rootDir,
-        input: manifestDoc.sourceUrl || manifestDoc.slug,
-        token: userApiKey ? undefined : credentials.docs[manifestDoc.slug]?.token ?? manifestDoc.token,
-        userApiKey,
-        baseUrl: manifestDoc.baseUrl,
-        filename: manifestDoc.file,
-        now: options.now,
-        fetchImpl: options.fetchImpl,
-        homeDir: options.homeDir,
-      }));
-    } catch (error) {
-      const attemptedAt = (options.now ?? (() => new Date()))().toISOString();
-      if (error instanceof CommentFsDeletedError) {
-        results.push(await removeUnselectedProjection(rootDir, await readManifest(rootDir), manifestDoc, attemptedAt));
-        continue;
-      }
-      const message = error instanceof Error ? error.message : String(error);
-      results.push(await recordSyncFailure(rootDir, manifestDoc, attemptedAt, message));
-    }
-  }
-  return results;
-}
-
-export async function syncRemoteSelectedCommentDocsSettled(
-  options: SyncConfiguredOptions = {},
-): Promise<Array<SyncDocResult | SyncDocFailure | SyncDocUnselectedResult>> {
-  const rootDir = resolve(options.rootDir ?? DEFAULT_SYNC_ROOT);
-  const config = await readCommentFsConfig(options.homeDir ?? homedir()).catch(() => null);
-  const baseUrl = (options.baseUrl ?? config?.baseUrl ?? DEFAULT_COMMENTFS_BASE_URL).replace(/\/$/, '');
-  const userApiKey = options.userApiKey ?? process.env.COMMENT_IO_USER_API_KEY ?? config?.userApiKey;
-  if (!userApiKey) {
-    throw new Error('Remote CommentFS sync polling requires --api-key or COMMENT_IO_USER_API_KEY.');
-  }
-
-  await ensureRoot(rootDir);
-  let manifest = await readManifest(rootDir);
-  const changes = options.full
-    ? await fetchRemoteSyncDocs({
-        baseUrl,
-        userApiKey,
-        fetchImpl: options.fetchImpl ?? fetch,
-      })
-    : await fetchRemoteSyncChanges({
-        baseUrl,
-        userApiKey,
-        since: manifest.remoteSyncCursor ?? 0,
-        fetchImpl: options.fetchImpl ?? fetch,
-      });
-
-  const results: Array<SyncDocResult | SyncDocFailure | SyncDocUnselectedResult> = [];
-  let hadSyncFailure = false;
-  for (const remoteDoc of changes.sync_docs) {
-    if (!remoteDoc.slug) continue;
-    manifest = await readManifest(rootDir);
-    const existing = manifest.docs.find((doc) => doc.slug === remoteDoc.slug);
-    if (remoteDoc.enabled === false) {
-      if (existing) {
-        const detectedAt = (options.now ?? (() => new Date()))().toISOString();
-        results.push(await removeUnselectedProjection(rootDir, manifest, existing, detectedAt));
-      }
-      continue;
-    }
-    try {
-      results.push(await syncOneCommentDoc({
-        rootDir,
-        input: remoteDoc.slug,
-        baseUrl,
-        filename: existing?.file,
-        userApiKey,
-        now: options.now,
-        fetchImpl: options.fetchImpl,
-        homeDir: options.homeDir,
-      }));
-    } catch (error) {
-      const attemptedAt = (options.now ?? (() => new Date()))().toISOString();
-      if (error instanceof CommentFsDeletedError && existing) {
-        results.push(await removeUnselectedProjection(rootDir, await readManifest(rootDir), existing, attemptedAt));
-        continue;
-      }
-      hadSyncFailure = true;
-      const message = error instanceof Error ? error.message : String(error);
-      if (existing) results.push(await recordSyncFailure(rootDir, existing, attemptedAt, message));
-      else {
-        results.push(await recordNewRemoteSyncFailure(rootDir, {
-          slug: remoteDoc.slug,
-          title: remoteDoc.title ?? remoteDoc.slug,
-          baseUrl,
-          attemptedAt,
-          error: message,
-        }));
-      }
-    }
-  }
-
-  manifest = await readManifest(rootDir);
-  if (!hadSyncFailure) {
-    manifest.remoteSyncCursor = changes.cursor;
-    await writeManifest(rootDir, manifest);
-  }
-  return results;
-}
-
-export async function explainCommentFsPath(inputPath: string): Promise<ExplainPathResult> {
-  const resolvedInput = resolve(inputPath);
-  const rootDir = await findSyncRoot(resolvedInput);
-  if (!rootDir) {
-    throw new Error(`No CommentFS manifest found for ${inputPath}`);
-  }
-
-  const manifest = await readManifest(rootDir);
-  const relativeInput = relative(rootDir, resolvedInput);
-  const normalized = relativeInput.split('/').join('/');
-  const doc = manifest.docs.find((entry) =>
-    normalized === entry.file ||
-    normalized === `${COMMENT_DIR}/${entry.statusFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.editFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.authorshipFile ?? sidecarPaths(entry.slug).authorshipFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.commentsFile ?? sidecarPaths(entry.slug).commentsFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.participantsFile ?? sidecarPaths(entry.slug).participantsFile}`
-  );
-  if (!doc) {
-    throw new Error(`${inputPath} is inside a CommentFS root but is not a synced Comment.io document path.`);
-  }
-
-  const result = {
-    rootDir,
-    inputPath: resolvedInput,
-    slug: doc.slug,
-    title: doc.title,
-    markdownPath: join(rootDir, doc.file),
-    statusPath: join(rootDir, COMMENT_DIR, doc.statusFile),
-    editPath: join(rootDir, COMMENT_DIR, doc.editFile),
-    sourceUrl: doc.sourceUrl,
-    apiUrl: doc.apiUrl,
-    apiDocsUrl: doc.apiDocsUrl,
-  };
-
-  return {
-    ...result,
-    explanation: buildPathExplanation(result),
-  };
-}
-
-export async function recoverCommentFsPath(inputPath: string): Promise<RecoverPathResult> {
-  const resolvedInput = resolve(inputPath);
-  const rootDir = await findSyncRoot(resolvedInput);
-  if (!rootDir) {
-    throw new Error(`No CommentFS manifest found for ${inputPath}`);
-  }
-
-  const manifest = await readManifest(rootDir);
-  const relativeInput = relative(rootDir, resolvedInput);
-  const normalized = relativeInput.split('/').join('/');
-  const isRecoveryPath = normalized.startsWith(`${COMMENT_DIR}/recovery/`);
-  if (isRecoveryPath) {
-    const activeDoc = manifest.docs.find((entry) => entry.lastLocalChange?.recoveryFile === normalized);
-    if (activeDoc?.lastLocalChange && await fileExists(join(rootDir, normalized))) {
-      return buildRecoverPathResult({
-        rootDir,
-        inputPath: resolvedInput,
-        slug: activeDoc.slug,
-        title: activeDoc.title,
-        markdownPath: join(rootDir, activeDoc.file),
-        statusPath: join(rootDir, COMMENT_DIR, activeDoc.statusFile),
-        editPath: join(rootDir, COMMENT_DIR, activeDoc.editFile),
-        recoveryFile: activeDoc.lastLocalChange.recoveryFile,
-        apiUrl: activeDoc.apiUrl,
-        apiDocsUrl: activeDoc.apiDocsUrl,
-        localChange: activeDoc.lastLocalChange,
-      });
-    }
-
-    const recovery = manifest.recoveries?.find((entry) =>
-      normalized === entry.localChange.recoveryFile
-    );
-    if (recovery && await fileExists(join(rootDir, normalized))) {
-      return buildRecoverPathResult({
-        rootDir,
-        inputPath: resolvedInput,
-        slug: recovery.slug,
-        title: recovery.title,
-        markdownPath: join(rootDir, recovery.file),
-        statusPath: join(rootDir, COMMENT_DIR, recovery.statusFile),
-        editPath: join(rootDir, COMMENT_DIR, recovery.editFile),
-        recoveryFile: recovery.localChange.recoveryFile,
-        apiUrl: recovery.apiUrl,
-        apiDocsUrl: recovery.apiDocsUrl,
-        localChange: recovery.localChange,
-      });
-    }
-
-    const prefixMatchedDoc = manifest.docs.find((entry) =>
-      basename(normalized).startsWith(`${safeRecoveryStem(entry.slug)}.`)
-    );
-    if (prefixMatchedDoc && await fileExists(join(rootDir, normalized))) {
-      throw new Error(`${inputPath} is a CommentFS recovery artifact, but this manifest does not have metadata for that specific artifact.`);
-    }
-
-    throw new Error(`${inputPath} is inside a CommentFS root but is not associated with a synced Comment.io document.`);
-  }
-
-  const doc = manifest.docs.find((entry) =>
-    normalized === entry.file ||
-    normalized === `${COMMENT_DIR}/${entry.statusFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.editFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.authorshipFile ?? sidecarPaths(entry.slug).authorshipFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.commentsFile ?? sidecarPaths(entry.slug).commentsFile}` ||
-    normalized === `${COMMENT_DIR}/${entry.participantsFile ?? sidecarPaths(entry.slug).participantsFile}`
-  );
-  if (!doc) {
-    throw new Error(`${inputPath} is inside a CommentFS root but is not associated with a synced Comment.io document.`);
-  }
-  const localChange = doc.lastLocalChange;
-  if (!localChange) {
-    throw new Error(`${doc.title} has no recorded local recovery artifact.`);
-  }
-
-  return buildRecoverPathResult({
-    rootDir,
-    inputPath: resolvedInput,
-    slug: doc.slug,
-    title: doc.title,
-    markdownPath: join(rootDir, doc.file),
-    statusPath: join(rootDir, COMMENT_DIR, doc.statusFile),
-    editPath: join(rootDir, COMMENT_DIR, doc.editFile),
-    recoveryFile: localChange.recoveryFile,
-    apiUrl: doc.apiUrl,
-    apiDocsUrl: doc.apiDocsUrl,
-    localChange,
-  });
-}
-
-function buildRecoverPathResult(options: {
-  rootDir: string;
-  inputPath: string;
-  slug: string;
-  title: string;
-  markdownPath: string;
-  statusPath: string;
-  editPath: string;
-  recoveryFile: string;
-  apiUrl: string;
-  apiDocsUrl: string;
-  localChange: CommentFsLocalChange;
-}): RecoverPathResult {
-  const recoveryPath = join(options.rootDir, options.recoveryFile);
-  return {
-    rootDir: options.rootDir,
-    inputPath: options.inputPath,
-    slug: options.slug,
-    title: options.title,
-    markdownPath: options.markdownPath,
-    statusPath: options.statusPath,
-    editPath: options.editPath,
-    recoveryPath,
-    apiUrl: options.apiUrl,
-    apiDocsUrl: options.apiDocsUrl,
-    detectedAt: options.localChange.detectedAt,
-    restoredCanonicalRevision: options.localChange.restoredCanonicalRevision,
-    instructions: [
-      `Recovery artifact for ${options.title} (${options.slug}): ${recoveryPath}`,
-      `Canonical projection was restored at revision ${options.localChange.restoredCanonicalRevision}.`,
-      'This command does not upload local markdown edits.',
-      `Use Comment.io UI or the API docs at ${options.apiDocsUrl} to apply any intended change explicitly.`,
-    ].join('\n'),
-  };
-}
-
-export async function getCommentFsStatus(rootDirOption?: string): Promise<CommentFsStatus> {
-  const rootDir = resolve(rootDirOption ?? DEFAULT_SYNC_ROOT);
-  const manifest = await readManifest(rootDir);
-  const docs: CommentFsStatusDoc[] = [];
-  for (const doc of manifest.docs) {
-    const markdownPath = join(rootDir, doc.file);
-    docs.push({
-      slug: doc.slug,
-      title: doc.title,
-      markdownPath,
-      statusPath: join(rootDir, COMMENT_DIR, doc.statusFile),
-      editPath: join(rootDir, COMMENT_DIR, doc.editFile),
-      sourceUrl: doc.sourceUrl,
-      apiUrl: doc.apiUrl,
-      apiDocsUrl: doc.apiDocsUrl,
-      revision: doc.lastRevision ?? null,
-      lastSyncedAt: doc.lastSyncedAt ?? null,
-      readOnly: await isReadOnly(markdownPath),
-      syncHealth: doc.lastSyncHealth ?? null,
-      localChange: doc.lastLocalChange ?? null,
-    });
-  }
-  return {
-    rootDir,
-    manifestPath: manifestPath(rootDir),
-    docs,
-  };
-}
-
-export async function repairCommentFsPermissions(rootDirOption?: string): Promise<CommentFsRepairResult[]> {
-  const rootDir = resolve(rootDirOption ?? DEFAULT_SYNC_ROOT);
-  const manifest = await readManifest(rootDir);
-  const results: CommentFsRepairResult[] = [];
-  for (const doc of manifest.docs) {
-    const markdownPath = join(rootDir, doc.file);
-    const existed = await fileExists(markdownPath);
-    const wasReadOnly = existed ? await isReadOnly(markdownPath) : false;
-    if (existed && !wasReadOnly) await ensureReadOnly(markdownPath);
-    results.push({
-      slug: doc.slug,
-      title: doc.title,
-      markdownPath,
-      existed,
-      repaired: existed && !wasReadOnly,
-    });
-  }
-  return results;
-}
-
-async function fetchCommentDoc(options: FetchDocOptions): Promise<CommentFsDocResponse> {
-  const explicitAuthToken = options.token ?? options.userApiKey;
-  let shareTokenError: Error | undefined;
-  if (options.ref.token && !explicitAuthToken) {
-    const shareUrl = new URL(`${options.ref.baseUrl}/docs/${encodeURIComponent(options.ref.slug)}`);
-    shareUrl.searchParams.set('token', options.ref.token);
-    try {
-      const shared = await requestDoc(shareUrl, undefined, options.fetchImpl);
-      if (shared.your_token) return shared;
-    } catch (error) {
-      shareTokenError = error instanceof Error ? error : new Error(String(error));
-    }
-  }
-
-  if (shareTokenError) throw shareTokenError;
-
-  const authToken = explicitAuthToken ?? await loadAgentSecret({
-    homeDir: options.homeDir,
-    agentHandle: options.agentHandle,
-  });
-
-  if (!authToken) {
-    if (shareTokenError) throw shareTokenError;
-    throw new Error(
-      'No Comment.io token available. Pass --token, use a share URL with ?token=, set COMMENT_IO_AGENT_SECRET, pass --api-key, or configure ~/.comment-io/agents.',
-    );
-  }
-
-  return requestDoc(
-    new URL(`${options.ref.baseUrl}/docs/${encodeURIComponent(options.ref.slug)}`),
-    authToken,
-    options.fetchImpl,
-  );
-}
-
-async function requestDoc(
-  url: URL,
-  bearerToken: string | undefined,
-  fetchImpl: typeof fetch,
-): Promise<CommentFsDocResponse> {
-  const headers = new Headers({ Accept: 'application/json' });
-  if (bearerToken) headers.set('Authorization', `Bearer ${bearerToken}`);
-  const response = await fetchImpl(url, { headers });
-  if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    if (response.status === 410) {
-      throw new CommentFsDeletedError(`Comment.io GET ${url.pathname} failed with 410: ${body}`);
-    }
-    throw new Error(`Comment.io GET ${url.pathname} failed with ${response.status}: ${body}`);
-  }
-  const doc = await response.json() as CommentFsDocResponse;
-  if (typeof doc.markdown !== 'string' || typeof doc.revision !== 'number') {
-    throw new Error(`Comment.io GET ${url.pathname} returned an invalid document payload.`);
-  }
-  return doc;
-}
-
-async function fetchRemoteSyncChanges(options: {
-  baseUrl: string;
-  userApiKey: string;
-  since: number;
-  fetchImpl: typeof fetch;
-}): Promise<RemoteSyncChangesResponse> {
-  const url = new URL(`${options.baseUrl}/auth/sync-docs/changes`);
-  url.searchParams.set('since', String(options.since));
-  const response = await options.fetchImpl(url, {
-    headers: {
-      Accept: 'application/json',
-      Authorization: `Bearer ${options.userApiKey}`,
-    },
-  });
-  if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    throw new Error(`Comment.io sync changes poll failed with ${response.status}: ${body}`);
-  }
-  const data = await response.json() as RemoteSyncChangesResponse;
-  if (!Array.isArray(data.sync_docs) || typeof data.cursor !== 'number') {
-    throw new Error('Comment.io sync changes poll returned an invalid payload.');
-  }
-  return data;
-}
-
-async function fetchRemoteSyncDocs(options: {
-  baseUrl: string;
-  userApiKey: string;
-  fetchImpl: typeof fetch;
-}): Promise<RemoteSyncChangesResponse> {
-  const url = new URL(`${options.baseUrl}/auth/sync-docs`);
-  url.searchParams.set('include_disabled', '1');
-  const response = await options.fetchImpl(url, {
-    headers: {
-      Accept: 'application/json',
-      Authorization: `Bearer ${options.userApiKey}`,
-    },
-  });
-  if (!response.ok) {
-    const body = await response.text().catch(() => '');
-    throw new Error(`Comment.io sync docs reconciliation failed with ${response.status}: ${body}`);
-  }
-  const data = await response.json() as RemoteSyncChangesResponse;
-  if (!Array.isArray(data.sync_docs) || typeof data.cursor !== 'number') {
-    throw new Error('Comment.io sync docs reconciliation returned an invalid payload.');
-  }
-  return data;
-}
-
-async function removeUnselectedProjection(
-  rootDir: string,
-  manifest: CommentFsManifest,
-  doc: CommentFsManifestDoc,
-  detectedAt: string,
-): Promise<SyncDocUnselectedResult> {
-  const markdownPath = join(rootDir, doc.file);
-  const statusPath = join(rootDir, COMMENT_DIR, doc.statusFile);
-  const editPath = join(rootDir, COMMENT_DIR, doc.editFile);
-  let localChange: CommentFsLocalChange | undefined;
-  if (doc.lastMarkdownSha256 && await fileExists(markdownPath)) {
-    const localMarkdown = await readFile(markdownPath, 'utf-8');
-    if (sha256(localMarkdown) !== doc.lastMarkdownSha256) {
-      localChange = await preserveLocalChange(rootDir, doc.slug, localMarkdown, detectedAt, doc.lastRevision ?? 0);
-    }
-  }
-  await Promise.all([
-    rm(markdownPath, { force: true }),
-    rm(statusPath, { force: true }),
-    rm(editPath, { force: true }),
-    doc.authorshipFile ? rm(join(rootDir, COMMENT_DIR, doc.authorshipFile), { force: true }) : Promise.resolve(),
-    doc.commentsFile ? rm(join(rootDir, COMMENT_DIR, doc.commentsFile), { force: true }) : Promise.resolve(),
-    doc.participantsFile ? rm(join(rootDir, COMMENT_DIR, doc.participantsFile), { force: true }) : Promise.resolve(),
-  ]);
-  const recoveryToIndex = localChange ?? doc.lastLocalChange;
-  if (recoveryToIndex) {
-    manifest.recoveries = [
-      ...(manifest.recoveries ?? []).filter((entry) => entry.localChange.recoveryFile !== recoveryToIndex.recoveryFile),
-      {
-        slug: doc.slug,
-        title: doc.title,
-        file: doc.file,
-        statusFile: doc.statusFile,
-        editFile: doc.editFile,
-        sourceUrl: doc.sourceUrl,
-        apiUrl: doc.apiUrl,
-        apiDocsUrl: doc.apiDocsUrl,
-        localChange: recoveryToIndex,
-        removedAt: detectedAt,
-      },
-    ];
-  }
-  manifest.docs = manifest.docs.filter((entry) => entry.slug !== doc.slug);
-  await deleteDocCredential(rootDir, doc.slug);
-  await writeManifest(rootDir, manifest);
-  return {
-    ok: true,
-    slug: doc.slug,
-    title: doc.title,
-    markdownPath,
-    statusPath,
-    editPath,
-    manifestPath: manifestPath(rootDir),
-    revision: doc.lastRevision ?? 0,
-    changed: true,
-    localChangeDetected: Boolean(localChange),
-    recoveryPath: recoveryToIndex ? join(rootDir, recoveryToIndex.recoveryFile) : undefined,
-    disabled: true,
-  };
-}
-
-function indexRecoveryRecord(
-  manifest: CommentFsManifest,
-  doc: CommentFsManifestDoc,
-  localChange: CommentFsLocalChange,
-  recordedAt: string,
-): void {
-  manifest.recoveries = [
-    ...(manifest.recoveries ?? []).filter((entry) => entry.localChange.recoveryFile !== localChange.recoveryFile),
-    {
-      slug: doc.slug,
-      title: doc.title,
-      file: doc.file,
-      statusFile: doc.statusFile,
-      editFile: doc.editFile,
-      sourceUrl: doc.sourceUrl,
-      apiUrl: doc.apiUrl,
-      apiDocsUrl: doc.apiDocsUrl,
-      localChange,
-      removedAt: recordedAt,
-    },
-  ];
-}
-
-async function loadAgentSecret(options: { homeDir: string; agentHandle?: string }): Promise<string | undefined> {
-  const envSecret = process.env.COMMENT_IO_AGENT_SECRET?.trim();
-  if (envSecret) return envSecret;
-
-  const agentsDir = join(options.homeDir, '.comment-io', 'agents');
-  const desired = options.agentHandle?.replace(/^@/, '').toLowerCase();
-  if (existsSync(agentsDir)) {
-    const files = (await readdir(agentsDir)).filter((file) => file.endsWith('.json')).sort();
-    for (const file of files) {
-      const handle = basename(file, '.json').toLowerCase();
-      if (desired && desired !== handle) continue;
-      try {
-        const cfg = JSON.parse(await readFile(join(agentsDir, file), 'utf-8')) as { agent_secret?: string };
-        if (cfg.agent_secret?.startsWith('as_')) return cfg.agent_secret;
-      } catch {
-        // Ignore malformed credential files, matching the MCP plugin behavior.
-      }
-    }
-  }
-
-  const legacy = join(options.homeDir, '.comment-io', 'config.json');
-  if (existsSync(legacy)) {
-    try {
-      const cfg = JSON.parse(await readFile(legacy, 'utf-8')) as { agent_secret?: string; handle?: string };
-      if (!desired || cfg.handle?.toLowerCase() === desired) {
-        if (cfg.agent_secret?.startsWith('as_')) return cfg.agent_secret;
-      }
-    } catch {
-      // Ignore malformed legacy config.
-    }
-  }
-
-  return undefined;
-}
-
-async function chooseMarkdownFile(
-  rootDir: string,
-  manifest: CommentFsManifest,
-  title: string,
-  slug: string,
-): Promise<string> {
-  const preferred = safeMarkdownFilename(title, slug);
-  const used = new Set(manifest.docs.map((doc) => doc.file));
-  if (!used.has(preferred) && !(await fileExists(join(rootDir, preferred)))) return preferred;
-
-  const stem = preferred.slice(0, -extname(preferred).length);
-  for (let i = 2; i < 1000; i += 1) {
-    const candidate = `${stem}-${i}.md`;
-    if (!used.has(candidate) && !(await fileExists(join(rootDir, candidate)))) return candidate;
-  }
-  throw new Error(`Could not choose a unique markdown filename for ${slug}`);
-}
-
-async function ensureRoot(rootDir: string): Promise<void> {
-  await mkdir(rootDir, { recursive: true, mode: 0o755 });
-  await mkdir(join(rootDir, COMMENT_DIR), { recursive: true, mode: 0o755 });
-}
-
-async function findSyncRoot(path: string): Promise<string | null> {
-  let current = existsSync(path) && (await stat(path)).isDirectory() ? path : dirname(path);
-  while (true) {
-    if (existsSync(manifestPath(current))) return current;
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-async function writeReadOnlyProjection(path: string, markdown: string): Promise<void> {
-  await mkdir(dirname(path), { recursive: true, mode: 0o755 });
-  const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
-  await writeFile(temp, markdown, { mode: 0o644 });
-  await rename(temp, path);
-  await ensureReadOnly(path);
-}
-
-async function preserveLocalChange(
-  rootDir: string,
-  sidecarStem: string,
-  localMarkdown: string,
-  detectedAt: string,
-  canonicalRevision: number,
-): Promise<CommentFsLocalChange> {
-  const recoveryDir = join(rootDir, COMMENT_DIR, 'recovery');
-  await mkdir(recoveryDir, { recursive: true, mode: 0o755 });
-  const stamp = detectedAt.replace(/[^0-9A-Za-z-]+/g, '-');
-  const stem = `${safeRecoveryStem(sidecarStem)}.${stamp}`;
-  let filename = `${stem}.local.md`;
-  for (let i = 2; await fileExists(join(recoveryDir, filename)); i += 1) {
-    filename = `${stem}-${i}.local.md`;
-  }
-  const recoveryFile = join(COMMENT_DIR, 'recovery', filename);
-  await writeFile(join(rootDir, recoveryFile), localMarkdown, { mode: 0o644 });
-  return {
-    detectedAt,
-    recoveryFile,
-    restoredCanonicalRevision: canonicalRevision,
-  };
-}
-
-function safeRecoveryStem(slug: string): string {
-  return slug.replace(/[^A-Za-z0-9_-]/g, '_') || 'doc';
-}
-
-async function recordSyncFailure(
-  rootDir: string,
-  manifestDoc: CommentFsManifestDoc,
-  attemptedAt: string,
-  error: string,
-): Promise<SyncDocFailure> {
-  const nextDoc: CommentFsManifestDoc = {
-    ...manifestDoc,
-    lastSyncHealth: {
-      status: 'error',
-      lastAttemptAt: attemptedAt,
-      lastSuccessAt: manifestDoc.lastSyncHealth?.lastSuccessAt ?? manifestDoc.lastSyncedAt,
-      lastErrorAt: attemptedAt,
-      lastError: error,
-    },
-  };
-  const manifest = await readManifest(rootDir);
-  const idx = manifest.docs.findIndex((entry) => entry.slug === manifestDoc.slug);
-  if (idx >= 0) manifest.docs[idx] = nextDoc;
-  sortManifest(manifest);
-  await writeManifest(rootDir, manifest);
-  await writeStatusSidecar(rootDir, nextDoc, {
-    revision: nextDoc.lastRevision ?? null,
-    role: null,
-    canonicalUpdatedAt: null,
-    lastSyncedAt: nextDoc.lastSyncedAt ?? null,
-    canonicalMarkdownSha256: nextDoc.lastCanonicalMarkdownSha256 ?? null,
-    projectionMarkdownSha256: nextDoc.lastMarkdownSha256 ?? null,
-    credentialPresent: Boolean(await readDocCredential(rootDir, nextDoc.slug).catch(() => undefined)),
-  });
-  return {
-    ok: false,
-    slug: nextDoc.slug,
-    title: nextDoc.title,
-    markdownPath: join(rootDir, nextDoc.file),
-    statusPath: join(rootDir, COMMENT_DIR, nextDoc.statusFile),
-    editPath: join(rootDir, COMMENT_DIR, nextDoc.editFile),
-    manifestPath: manifestPath(rootDir),
-    error,
-  };
-}
-
-async function recordNewRemoteSyncFailure(
-  rootDir: string,
-  options: {
-    slug: string;
-    title: string;
-    baseUrl: string;
-    attemptedAt: string;
-    error: string;
-  },
-): Promise<SyncDocFailure> {
-  const manifest = await readManifest(rootDir);
-  const sidecars = sidecarPaths(options.slug);
-  const file = await chooseMarkdownFile(rootDir, manifest, options.title, options.slug);
-  const manifestDoc: CommentFsManifestDoc = {
-    slug: options.slug,
-    title: options.title,
-    file,
-    sidecarDir: sidecars.sidecarDir,
-    statusFile: sidecars.statusFile,
-    editFile: sidecars.editFile,
-    authorshipFile: sidecars.authorshipFile,
-    commentsFile: sidecars.commentsFile,
-    participantsFile: sidecars.participantsFile,
-    sourceUrl: `${options.baseUrl}/d/${encodeURIComponent(options.slug)}`,
-    apiUrl: `${options.baseUrl}/docs/${encodeURIComponent(options.slug)}`,
-    apiDocsUrl: `${options.baseUrl}/docs/${encodeURIComponent(options.slug)}?docs`,
-    baseUrl: options.baseUrl,
-    addedAt: options.attemptedAt,
-    authMode: 'user_api_key',
-    lastSyncHealth: {
-      status: 'error',
-      lastAttemptAt: options.attemptedAt,
-      lastErrorAt: options.attemptedAt,
-      lastError: options.error,
-    },
-  };
-
-  await writeRootReadme(rootDir);
-  await writeTextIfChanged(join(rootDir, COMMENT_DIR, manifestDoc.editFile), buildEditInstructions(manifestDoc));
-  await writeStatusSidecar(rootDir, manifestDoc, {
-    revision: null,
-    role: null,
-    canonicalUpdatedAt: null,
-    lastSyncedAt: null,
-    canonicalMarkdownSha256: null,
-    projectionMarkdownSha256: null,
-    credentialPresent: false,
-  });
-  const idx = manifest.docs.findIndex((entry) => entry.slug === manifestDoc.slug);
-  if (idx >= 0) manifest.docs[idx] = manifestDoc;
-  else manifest.docs.push(manifestDoc);
-  sortManifest(manifest);
-  await writeManifest(rootDir, manifest);
-
-  return {
-    ok: false,
-    slug: options.slug,
-    title: options.title,
-    markdownPath: join(rootDir, file),
-    statusPath: join(rootDir, COMMENT_DIR, sidecars.statusFile),
-    editPath: join(rootDir, COMMENT_DIR, sidecars.editFile),
-    manifestPath: manifestPath(rootDir),
-    error: options.error,
-  };
-}
-
-async function ensureReadOnly(path: string): Promise<void> {
-  await chmod(path, 0o444);
-}
-
-async function writeDocSidecars(
-  rootDir: string,
-  manifestDoc: CommentFsManifestDoc,
-  doc: CommentFsDocResponse,
-  canonicalMarkdownSha256: string,
-  projectionMarkdownSha256: string,
-  syncedAt: string,
-): Promise<void> {
-  await writeStatusSidecar(rootDir, manifestDoc, {
-    revision: doc.revision,
-    role: doc.your_role ?? null,
-    canonicalUpdatedAt: doc.updated_at ?? null,
-    lastSyncedAt: syncedAt,
-    canonicalMarkdownSha256,
-    projectionMarkdownSha256,
-    credentialPresent: Boolean(await readDocCredential(rootDir, manifestDoc.slug).catch(() => undefined)),
-  });
-  await writeTextIfChanged(join(rootDir, COMMENT_DIR, manifestDoc.editFile), buildEditInstructions(manifestDoc));
-  await writeJsonIfChanged(join(rootDir, COMMENT_DIR, manifestDoc.authorshipFile ?? sidecarPaths(manifestDoc.slug).authorshipFile), {
-    version: COMMENTFS_VERSION,
-    slug: manifestDoc.slug,
-    authorship: doc.authorship ?? null,
-    actors: doc.actors ?? null,
-  });
-  await writeJsonIfChanged(join(rootDir, COMMENT_DIR, manifestDoc.commentsFile ?? sidecarPaths(manifestDoc.slug).commentsFile), {
-    version: COMMENTFS_VERSION,
-    slug: manifestDoc.slug,
-    blocks: doc.blocks ?? [],
-    comment_meta: doc.comment_meta ?? null,
-  });
-  await writeJsonIfChanged(join(rootDir, COMMENT_DIR, manifestDoc.participantsFile ?? sidecarPaths(manifestDoc.slug).participantsFile), {
-    version: COMMENTFS_VERSION,
-    slug: manifestDoc.slug,
-    participants: doc.participants ?? [],
-    actors: doc.actors ?? null,
-  });
-}
-
-async function writeStatusSidecar(
-  rootDir: string,
-  manifestDoc: CommentFsManifestDoc,
-  details: {
-    revision: number | null;
-    role: string | null;
-    canonicalUpdatedAt: string | null;
-    lastSyncedAt: string | null;
-    canonicalMarkdownSha256: string | null;
-    projectionMarkdownSha256: string | null;
-    credentialPresent: boolean;
-  },
-): Promise<void> {
-  const commentDir = join(rootDir, COMMENT_DIR);
-  const status = {
-    version: COMMENTFS_VERSION,
-    slug: manifestDoc.slug,
-    title: manifestDoc.title,
-    source_url: manifestDoc.sourceUrl,
-    api_url: manifestDoc.apiUrl,
-    api_docs_url: manifestDoc.apiDocsUrl,
-    markdown_file: manifestDoc.file,
-    revision: details.revision,
-    role: details.role,
-    canonical_updated_at: details.canonicalUpdatedAt,
-    last_synced_at: details.lastSyncedAt,
-    canonical_markdown_sha256: details.canonicalMarkdownSha256,
-    projection_markdown_sha256: details.projectionMarkdownSha256,
-    sync_health: manifestDoc.lastSyncHealth ?? null,
-    read_only_projection: true,
-    read_only_reason: 'Comment.io online state is canonical; local markdown is a read-only projection.',
-    sidecars: {
-      edit_instructions: manifestDoc.editFile,
-      authorship: manifestDoc.authorshipFile ?? sidecarPaths(manifestDoc.slug).authorshipFile,
-      comments: manifestDoc.commentsFile ?? sidecarPaths(manifestDoc.slug).commentsFile,
-      participants: manifestDoc.participantsFile ?? sidecarPaths(manifestDoc.slug).participantsFile,
-    },
-    auth: {
-      token_present: details.credentialPresent,
-      token_location: details.credentialPresent ? '.comment/credentials.json' : null,
-      agent_secret_supported: true,
-    },
-    local_change: manifestDoc.lastLocalChange ?? null,
-  };
-  await writeJsonIfChanged(join(commentDir, manifestDoc.statusFile), status);
-}
-
-async function writeRootReadme(rootDir: string): Promise<void> {
-  await writeTextIfChanged(join(rootDir, COMMENT_DIR, 'README.md'), [
-    '# Comment.io Synced Files',
-    '',
-    'Markdown files in this folder are read-only projections of online Comment.io documents.',
-    '',
-    'Do not edit synced markdown files directly. Use the Comment.io UI or the Comment.io API so edits go through canonical reconciliation, provenance, comments, and permissions.',
-    '',
-    'Useful commands:',
-    '- `comment sync status` shows projection health.',
-    '- `comment sync explain <path>` explains a synced markdown or sidecar path.',
-    '- `comment sync recover <path>` explains the latest preserved local edit artifact.',
-    '',
-    'For a specific file, read its `.comment/*.status.json` and `.comment/*.edit.md` sidecars.',
-    'The full agent API reference is available at https://comment.io/llms.txt and per-doc via the `api_docs_url` in status JSON.',
-    '',
-  ].join('\n'));
-}
-
-function buildEditInstructions(doc: CommentFsManifestDoc): string {
-  return [
-    `# Edit ${doc.title}`,
-    '',
-    'This file is synced from Comment.io and is not the edit surface.',
-    'To edit it, call the Comment.io API for this document or open the source URL in the browser.',
-    '',
-    `- Markdown projection: ../${doc.file}`,
-    `- Status JSON: ${doc.statusFile}`,
-    `- Authorship JSON: ${doc.authorshipFile ?? sidecarPaths(doc.slug).authorshipFile}`,
-    `- Comments JSON: ${doc.commentsFile ?? sidecarPaths(doc.slug).commentsFile}`,
-    `- Participants JSON: ${doc.participantsFile ?? sidecarPaths(doc.slug).participantsFile}`,
-    `- Source URL: ${doc.sourceUrl}`,
-    `- API URL: ${doc.apiUrl}`,
-    `- Per-doc API docs: ${doc.apiDocsUrl}`,
-    `- Full API reference: ${doc.baseUrl}/llms.txt`,
-    `- Explain this path: comment sync explain "${doc.file}"`,
-    '- Recover preserved local edits: comment sync recover <path>',
-    '',
-    '`COMMENT_IO_USER_API_KEY` is only for CommentFS read-only projection sync.',
-    'For API edits, use `COMMENT_IO_AGENT_SECRET`, a registered agent credential, or an edit-capable per-document token as the Bearer token.',
-    '',
-  ].join('\n');
-}
-
-function sidecarPaths(slug: string): {
-  sidecarDir: string;
-  statusFile: string;
-  editFile: string;
-  authorshipFile: string;
-  commentsFile: string;
-  participantsFile: string;
-} {
-  const safeSlug = slug.replace(/[^a-zA-Z0-9_-]/g, '_');
-  const sidecarDir = join('docs', safeSlug);
-  return {
-    sidecarDir,
-    statusFile: join(sidecarDir, 'status.json'),
-    editFile: join(sidecarDir, 'edit.md'),
-    authorshipFile: join(sidecarDir, 'authorship.json'),
-    commentsFile: join(sidecarDir, 'comments.json'),
-    participantsFile: join(sidecarDir, 'participants.json'),
-  };
-}
-
-function buildMarkdownProjection(
-  canonicalMarkdown: string,
-  details: { title: string; sourceUrl: string; statusPath: string; editPath: string },
-): string {
-  const header = [
-    '<!--',
-    'Synced from Comment.io. Local markdown is a read-only projection.',
-    'Edit through the Comment.io UI or API; do not edit this file directly.',
-    `Title: ${details.title}`,
-    `Source: ${details.sourceUrl}`,
-    `Metadata: ${details.statusPath}`,
-    `Edit instructions: ${details.editPath}`,
-    '-->',
-    '',
-  ].join('\n');
-  return `${header}${canonicalMarkdown}`;
-}
-
-async function removeSupersededSidecars(
-  rootDir: string,
-  oldDoc: CommentFsManifestDoc,
-  newDoc: CommentFsManifestDoc,
-): Promise<void> {
-  const oldFiles = [
-    oldDoc.statusFile,
-    oldDoc.editFile,
-    oldDoc.authorshipFile,
-    oldDoc.commentsFile,
-    oldDoc.participantsFile,
-  ].filter((file): file is string => typeof file === 'string');
-  const newFiles = new Set([
-    newDoc.statusFile,
-    newDoc.editFile,
-    newDoc.authorshipFile,
-    newDoc.commentsFile,
-    newDoc.participantsFile,
-  ].filter((file): file is string => typeof file === 'string'));
-  await Promise.all(oldFiles
-    .filter((file) => !newFiles.has(file))
-    .map((file) => rm(join(rootDir, COMMENT_DIR, file), { force: true })));
-}
-
-function buildPathExplanation(doc: Omit<ExplainPathResult, 'explanation'>): string {
-  return [
-    'This is a Comment.io synced file. Do not edit it directly.',
-    'Use the Comment.io UI or API so edits go through canonical reconciliation, provenance, comments, and permissions.',
-    '',
-    `Title: ${doc.title}`,
-    `Slug: ${doc.slug}`,
-    `Markdown projection: ${doc.markdownPath}`,
-    `Status JSON: ${doc.statusPath}`,
-    `Edit instructions: ${doc.editPath}`,
-    `Source URL: ${doc.sourceUrl}`,
-    `API URL: ${doc.apiUrl}`,
-    `Per-doc API docs: ${doc.apiDocsUrl}`,
-    '',
-    'For the full agent API reference, fetch /llms.txt from the same Comment.io host.',
-  ].join('\n');
-}
-
-async function writeJsonIfChanged(path: string, value: unknown): Promise<void> {
-  await writeTextIfChanged(path, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-async function writePrivateJsonIfChanged(path: string, value: unknown): Promise<void> {
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  const text = `${JSON.stringify(value, null, 2)}\n`;
-  if (existsSync(path)) {
-    const current = await readFile(path, 'utf-8');
-    if (current === text) {
-      await chmod(path, 0o600);
-      return;
-    }
-  }
-  await writeFile(path, text, { mode: 0o600 });
-  await chmod(path, 0o600);
-}
-
-async function writeTextIfChanged(path: string, value: string): Promise<void> {
-  await mkdir(dirname(path), { recursive: true, mode: 0o755 });
-  if (existsSync(path)) {
-    const current = await readFile(path, 'utf-8');
-    if (current === value) return;
-  }
-  await writeFile(path, value, { mode: 0o644 });
-}
-
-async function fileExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function isReadOnly(path: string): Promise<boolean> {
-  try {
-    return ((await stat(path)).mode & 0o222) === 0;
-  } catch {
-    return false;
-  }
-}
-
-function sortManifest(manifest: CommentFsManifest): void {
-  manifest.docs.sort((a, b) => a.file.localeCompare(b.file));
-}
-
-function sha256(value: string): string {
-  return createHash('sha256').update(value).digest('hex');
-}