@justyork/repo-mind 0.4.0 → 0.7.0

package/dist/agent-write-gate.d.ts

@@ -0,0 +1,7 @@
+export interface AgentWriteGate {
+    enabled: boolean;
+    reason: string;
+}
+/** Agent write tools are enabled when the kill-switch passes or REPOMIND_AGENT_WRITE=1. */
+export declare function getAgentWriteGate(cwd?: string): AgentWriteGate;
+export declare function isAgentWriteEnabled(cwd?: string): boolean;

package/dist/agent-write-gate.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveAbDemoRoot } from './ab-demo/paths.js';
+function readLatestAbResults(cwd) {
+    const latestPath = path.join(resolveAbDemoRoot(cwd), 'results', 'latest.json');
+    if (!fs.existsSync(latestPath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(latestPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Agent write tools are enabled when the kill-switch passes or REPOMIND_AGENT_WRITE=1. */
+export function getAgentWriteGate(cwd = process.cwd()) {
+    if (process.env.REPOMIND_AGENT_WRITE === '1') {
+        return { enabled: true, reason: 'REPOMIND_AGENT_WRITE=1' };
+    }
+    const latest = readLatestAbResults(cwd);
+    const pass = latest?.pass === true || latest?.arms?.pass === true;
+    if (pass) {
+        return { enabled: true, reason: 'ab-demo kill-switch pass' };
+    }
+    return {
+        enabled: false,
+        reason: 'Agent write is disabled until the ab-demo kill-switch passes. Set REPOMIND_AGENT_WRITE=1 to override locally.',
+    };
+}
+export function isAgentWriteEnabled(cwd = process.cwd()) {
+    return getAgentWriteGate(cwd).enabled;
+}

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
+import { runAbEval } from './commands/ab-eval.js';
 import { runCheck } from './commands/check.js';
 import { runExport } from './commands/export.js';
 import { runInit } from './commands/init.js';
 import { runPrepare } from './commands/prepare.js';
+import { runPublish } from './commands/publish.js';
 import { runSetup } from './commands/setup.js';
 import { runSyncLinks } from './commands/sync-links.js';
 import { runUi } from './commands/ui.js';
@@ -17,6 +19,8 @@ Usage:
   repo-mind export [--force] [--cwd <dir>]
   repo-mind prepare [--all] [--dry-run] [--cwd <dir>] [relative-path]
   repo-mind sync-links [--dry-run] [--no-convert-body] [--no-sync-related] [--cwd <dir>]
+  repo-mind publish [--pr] [--dry-run] [--draft <id>] [--message <text>] [--title <text>] [--body <text>] [--cwd <dir>]
+  repo-mind ab-eval --cwd <dir> [--questions <path>] [--output <path>] [--dry-run]
   repo-mind mcp
   repo-mind ui [--port <n>] [--cwd <dir>]
 
@@ -27,6 +31,8 @@ Commands:
   export  Write agents.md export to repo root
   prepare Add RepoMind frontmatter to markdown files (--all for batch)
   sync-links Convert markdown links to wikilinks and sync related frontmatter
+  publish   Publish active drafts to docs/; --pr opens a GitHub pull request
+  ab-eval   Live A/B eval on a project docs/ corpus (skyforge dogfood gate)
   mcp     Start the MCP stdio server
   ui      Confluence-style workspace over docs/ (127.0.0.1)
 `);
@@ -40,6 +46,10 @@ function parseArgs(argv) {
             flags.all = true;
             continue;
         }
+        if (arg === '--pr') {
+            flags.pr = true;
+            continue;
+        }
         if (arg === '--dry-run') {
             flags.dryRun = true;
             continue;
@@ -74,6 +84,58 @@ function parseArgs(argv) {
             i += 1;
             continue;
         }
+        if (arg === '--message' && rest[i + 1]) {
+            flags.message = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--title' && rest[i + 1]) {
+            flags.title = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--body' && rest[i + 1]) {
+            flags.body = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--draft' && rest[i + 1]) {
+            const existing = flags.draft;
+            const next = rest[i + 1];
+            flags.draft = existing ? `${existing},${next}` : next;
+            i += 1;
+            continue;
+        }
+        if (arg === '--questions' && rest[i + 1]) {
+            flags.questions = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--output' && rest[i + 1]) {
+            flags.output = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--record-scores' && rest[i + 1]) {
+            flags.recordScores = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--scores' && rest[i + 1]) {
+            flags.scores = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--baseline-transcript' && rest[i + 1]) {
+            flags.baselineTranscript = rest[i + 1];
+            i += 1;
+            continue;
+        }
+        if (arg === '--repomind-transcript' && rest[i + 1]) {
+            flags.repomindTranscript = rest[i + 1];
+            i += 1;
+            continue;
+        }
         if (arg === '--help' || arg === '-h') {
             flags.help = true;
         }
@@ -91,6 +153,16 @@ async function main() {
         !arg.startsWith('-') &&
         argv[index - 1] !== '--cwd' &&
         argv[index - 1] !== '--port' &&
+        argv[index - 1] !== '--message' &&
+        argv[index - 1] !== '--title' &&
+        argv[index - 1] !== '--body' &&
+        argv[index - 1] !== '--draft' &&
+        argv[index - 1] !== '--questions' &&
+        argv[index - 1] !== '--output' &&
+        argv[index - 1] !== '--record-scores' &&
+        argv[index - 1] !== '--scores' &&
+        argv[index - 1] !== '--baseline-transcript' &&
+        argv[index - 1] !== '--repomind-transcript' &&
         arg !== argv[1]);
     switch (command) {
         case 'init':
@@ -126,6 +198,36 @@ async function main() {
                 syncRelated: flags.noSyncRelated !== true,
             }));
             break;
+        case 'ab-eval':
+            process.exit(runAbEval({
+                cwd,
+                questions: typeof flags.questions === 'string' ? flags.questions : undefined,
+                output: typeof flags.output === 'string' ? flags.output : undefined,
+                dryRun: flags.dryRun === true,
+                recordScores: typeof flags.recordScores === 'string' ? flags.recordScores : undefined,
+                scoresFile: typeof flags.scores === 'string' ? flags.scores : undefined,
+                baselineTranscript: typeof flags.baselineTranscript === 'string'
+                    ? flags.baselineTranscript
+                    : undefined,
+                repomindTranscript: typeof flags.repomindTranscript === 'string'
+                    ? flags.repomindTranscript
+                    : undefined,
+            }));
+            break;
+        case 'publish':
+            process.exit(runPublish({
+                cwd,
+                pr: flags.pr === true,
+                dryRun: flags.dryRun === true,
+                message: typeof flags.message === 'string' ? flags.message : undefined,
+                prTitle: typeof flags.title === 'string' ? flags.title : undefined,
+                prBody: typeof flags.body === 'string' ? flags.body : undefined,
+                draftIds: typeof flags.draft === 'string'
+                    ? flags.draft.split(',').map((id) => id.trim()).filter(Boolean)
+                    : undefined,
+                skipPush: process.env.REPOMIND_PUBLISH_SKIP_REMOTE === '1',
+            }));
+            break;
         case 'mcp':
             await startMcpServer();
             break;

package/dist/commands/ab-eval.d.ts

@@ -0,0 +1,11 @@
+export interface AbEvalOptions {
+    cwd?: string;
+    questions?: string;
+    output?: string;
+    dryRun?: boolean;
+    recordScores?: string;
+    scoresFile?: string;
+    baselineTranscript?: string;
+    repomindTranscript?: string;
+}
+export declare function runAbEval(options?: AbEvalOptions): number;

package/dist/commands/ab-eval.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mergeHumanScores, runLiveEval } from '../ab-demo/live-eval.js';
+import { resolveAbDemoRoot, resultsDir } from '../ab-demo/paths.js';
+import { defaultSkyforgeQuestionsPath } from '../ab-demo/validate-questions.js';
+function printUsage() {
+    console.log(`repo-mind ab-eval — live A/B eval on a project docs/ corpus
+
+Usage:
+  repo-mind ab-eval --cwd <project> [--questions <path>] [--output <path>] [--dry-run]
+  repo-mind ab-eval --record-scores <results.json> [--scores <scores.json>] [--output <path>]
+
+Options:
+  --cwd <dir>              Project root with docs/ (required for eval run)
+  --questions <path>       Questions JSON (default: ab-demo/skyforge-questions.json)
+  --output <path>          Results JSON (default: ab-demo/results/skyforge-<date>.json)
+  --dry-run                Validate questions + anchors only
+  --record-scores <file>   Merge humanScores into results and compute pass
+  --scores <file>          JSON array of { questionId, baseline, repomind } scores
+  --baseline-transcript    Optional transcript JSONL for baseline token override
+  --repomind-transcript    Optional transcript JSONL for repomind token override
+`);
+}
+function parseScoresFile(filePath) {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    if (!Array.isArray(parsed)) {
+        throw new Error('--scores file must be a JSON array');
+    }
+    return parsed.map((raw, index) => {
+        if (!raw || typeof raw !== 'object') {
+            throw new Error(`scores[${index}] must be an object`);
+        }
+        const record = raw;
+        if (typeof record.questionId !== 'string' || typeof record.baseline !== 'number') {
+            throw new Error(`scores[${index}] requires questionId and baseline`);
+        }
+        if (typeof record.repomind !== 'number') {
+            throw new Error(`scores[${index}] requires repomind`);
+        }
+        return {
+            questionId: record.questionId,
+            baseline: record.baseline,
+            repomind: record.repomind,
+            reviewer: typeof record.reviewer === 'string' ? record.reviewer : undefined,
+            notes: typeof record.notes === 'string' ? record.notes : undefined,
+        };
+    });
+}
+function defaultOutputPath(abRoot) {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+    return path.join(resultsDir(abRoot), `skyforge-${stamp}.json`);
+}
+export function runAbEval(options = {}) {
+    if (options.recordScores) {
+        const scoresPath = options.scoresFile;
+        if (!scoresPath) {
+            console.error('--record-scores requires --scores <file>');
+            return 1;
+        }
+        try {
+            const scores = parseScoresFile(scoresPath);
+            const merged = mergeHumanScores(options.recordScores, scores, options.output);
+            console.log(`pass: ${merged.pass}`);
+            console.log(`tokenPass: ${merged.tokenPass}, hallucinationPass: ${merged.hallucinationPass}`);
+            if (merged.categoryWins) {
+                for (const row of merged.categoryWins) {
+                    console.log(`  ${row.category}: repomindWins=${row.repomindWins} (hallucination ${row.repomindHallucinationTotal} vs ${row.baselineHallucinationTotal})`);
+                }
+            }
+            console.log(`wrote ${options.output ?? options.recordScores}`);
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message);
+            return 1;
+        }
+    }
+    const cwd = options.cwd;
+    if (!cwd) {
+        console.error('--cwd is required for live eval');
+        printUsage();
+        return 1;
+    }
+    const abRoot = resolveAbDemoRoot(cwd);
+    const questionsFile = options.questions ?? defaultSkyforgeQuestionsPath(abRoot);
+    const outputPath = options.output ?? defaultOutputPath(abRoot);
+    try {
+        return runLiveEval({
+            cwd,
+            questionsFile,
+            outputPath,
+            dryRun: options.dryRun,
+            baselineTranscript: options.baselineTranscript,
+            repomindTranscript: options.repomindTranscript,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        return 1;
+    }
+}

package/dist/commands/publish.d.ts

@@ -0,0 +1,11 @@
+export interface PublishOptions {
+    cwd?: string;
+    pr?: boolean;
+    dryRun?: boolean;
+    message?: string;
+    prTitle?: string;
+    prBody?: string;
+    draftIds?: string[];
+    skipPush?: boolean;
+}
+export declare function runPublish(options?: PublishOptions): number;

package/dist/commands/publish.js

@@ -0,0 +1,91 @@
+import path from 'node:path';
+import { runCheck } from './check.js';
+import { DocIndex } from '../index/doc-index.js';
+import { formatDryRunPublishPr, runPublishPr } from '../git/publish-pr.js';
+import { batchPublishDrafts, defaultCommitMessage, defaultPrBody, defaultPrTitle, } from '../publish/batch-publish.js';
+import { openDraftsDb } from '../ui/db/drafts-db.js';
+export function runPublish(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const index = new DocIndex(cwd);
+    const knowledgeRoot = index.getKnowledgeRoot();
+    if (!knowledgeRoot) {
+        console.error('no docs/ found — run `repo-mind init` or create a docs/ directory');
+        return 1;
+    }
+    const db = openDraftsDb(knowledgeRoot);
+    try {
+        const active = db.listActive();
+        if (active.length === 0) {
+            console.error('no active drafts to publish');
+            return 1;
+        }
+        const batch = batchPublishDrafts(index, db, {
+            draftIds: options.draftIds,
+            dryRun: options.dryRun,
+        });
+        if (batch.failures.length > 0) {
+            for (const failure of batch.failures) {
+                console.error(`${failure.slug}: ${failure.message}`);
+            }
+            return 1;
+        }
+        if (batch.published.length === 0) {
+            console.error('no drafts matched the publish request');
+            return 1;
+        }
+        if (!options.dryRun) {
+            const checkCode = runCheck({ cwd });
+            if (checkCode !== 0) {
+                console.error('publish aborted — fix check violations before committing');
+                return checkCode;
+            }
+        }
+        for (const item of batch.published) {
+            if (options.dryRun) {
+                console.log(`dry-run: would publish ${item.slug} → ${item.path}`);
+            }
+            else {
+                const relativePath = path.relative(path.dirname(knowledgeRoot), item.path);
+                console.log(`published ${item.slug} → ${relativePath}`);
+            }
+        }
+        if (!options.pr) {
+            return 0;
+        }
+        const repoRoot = path.dirname(knowledgeRoot);
+        const message = options.message ?? defaultCommitMessage(batch.published);
+        const prTitle = options.prTitle ?? defaultPrTitle(batch.published);
+        const prBody = options.prBody ?? defaultPrBody(batch.published);
+        const prResult = runPublishPr({
+            repoRoot,
+            published: batch.published,
+            message,
+            prTitle,
+            prBody,
+            dryRun: options.dryRun,
+            skipPush: options.skipPush,
+        });
+        if (!prResult.ok) {
+            console.error(`${prResult.error.code}: ${prResult.error.message}`);
+            if (prResult.error.hint) {
+                console.error(prResult.error.hint);
+            }
+            return 1;
+        }
+        if (options.dryRun) {
+            console.log(formatDryRunPublishPr(batch.published, prResult.data));
+            return 0;
+        }
+        console.log(`branch: ${prResult.data.branch}`);
+        if (prResult.data.pushed) {
+            console.log(`pushed: origin/${prResult.data.branch}`);
+        }
+        if (prResult.data.prUrl) {
+            console.log(`pr: ${prResult.data.prUrl}`);
+        }
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/git/git-exec.d.ts

@@ -0,0 +1,19 @@
+export declare class GitCommandError extends Error {
+    readonly command: string;
+    constructor(command: string, message: string);
+}
+export declare function commandExists(command: string): boolean;
+export declare function findGitRoot(startDir: string): string | null;
+export declare function gitExec(repoRoot: string, args: string[]): string;
+export declare function toRepoRelativePath(repoRoot: string, absolutePath: string): string;
+export declare function currentBranch(repoRoot: string): string;
+export declare function branchExists(repoRoot: string, branchName: string): boolean;
+export declare function createBranch(repoRoot: string, branchName: string): void;
+export declare function stagePaths(repoRoot: string, relativePaths: string[]): void;
+export declare function commitStaged(repoRoot: string, message: string): string;
+export declare function pushBranch(repoRoot: string, branchName: string): void;
+export declare function createPullRequest(repoRoot: string, options: {
+    title: string;
+    body: string;
+    base?: string;
+}): string;

package/dist/git/git-exec.js

@@ -0,0 +1,89 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+export class GitCommandError extends Error {
+    command;
+    constructor(command, message) {
+        super(message);
+        this.name = 'GitCommandError';
+        this.command = command;
+    }
+}
+export function commandExists(command) {
+    try {
+        execFileSync(command, ['--version'], { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findGitRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (fs.existsSync(path.join(current, '.git'))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+export function gitExec(repoRoot, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (error) {
+        const stderr = error && typeof error === 'object' && 'stderr' in error
+            ? String(error.stderr)
+            : String(error);
+        throw new GitCommandError(`git ${args.join(' ')}`, stderr.trim() || 'git command failed');
+    }
+}
+export function toRepoRelativePath(repoRoot, absolutePath) {
+    return path.relative(repoRoot, absolutePath).replace(/\\/g, '/');
+}
+export function currentBranch(repoRoot) {
+    return gitExec(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+export function branchExists(repoRoot, branchName) {
+    try {
+        gitExec(repoRoot, ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createBranch(repoRoot, branchName) {
+    gitExec(repoRoot, ['checkout', '-b', branchName]);
+}
+export function stagePaths(repoRoot, relativePaths) {
+    if (relativePaths.length === 0) {
+        return;
+    }
+    gitExec(repoRoot, ['add', '--', ...relativePaths]);
+}
+export function commitStaged(repoRoot, message) {
+    return gitExec(repoRoot, ['commit', '-m', message]);
+}
+export function pushBranch(repoRoot, branchName) {
+    gitExec(repoRoot, ['push', '-u', 'origin', branchName]);
+}
+export function createPullRequest(repoRoot, options) {
+    const args = ['pr', 'create', '--title', options.title, '--body', options.body];
+    if (options.base) {
+        args.push('--base', options.base);
+    }
+    return execFileSync('gh', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}

package/dist/git/publish-pr.d.ts

@@ -0,0 +1,33 @@
+import { type PublishedDraft } from '../publish/batch-publish.js';
+export type PublishPrErrorCode = 'ENOENT_REPO' | 'NO_CHANGES' | 'GH_MISSING' | 'GIT_ERROR' | 'PUSH_FAILED';
+export interface PublishPrSuccess {
+    branch: string;
+    commitMessage: string;
+    stagedPaths: string[];
+    prUrl?: string;
+    pushed: boolean;
+}
+export interface PublishPrError {
+    code: PublishPrErrorCode;
+    message: string;
+    hint?: string;
+}
+export type PublishPrResult = {
+    ok: true;
+    data: PublishPrSuccess;
+} | {
+    ok: false;
+    error: PublishPrError;
+};
+export interface PublishPrOptions {
+    repoRoot: string;
+    published: PublishedDraft[];
+    message: string;
+    prTitle: string;
+    prBody: string;
+    dryRun?: boolean;
+    skipPush?: boolean;
+    baseBranch?: string;
+}
+export declare function runPublishPr(options: PublishPrOptions): PublishPrResult;
+export declare function formatDryRunPublishPr(published: PublishedDraft[], result: PublishPrSuccess): string;

package/dist/git/publish-pr.js

@@ -0,0 +1,121 @@
+import { commandExists, createBranch, createPullRequest, findGitRoot, GitCommandError, pushBranch, stagePaths, commitStaged, } from '../git/git-exec.js';
+import { buildPublishBranchName, relativeDocsPaths, resolveUniqueBranchName, } from '../publish/batch-publish.js';
+export function runPublishPr(options) {
+    const gitRoot = findGitRoot(options.repoRoot);
+    if (!gitRoot) {
+        return {
+            ok: false,
+            error: {
+                code: 'ENOENT_REPO',
+                message: 'no git repository found — initialize git first',
+            },
+        };
+    }
+    const stagedPaths = relativeDocsPaths(gitRoot, options.published
+        .map((item) => item.path)
+        .filter((item) => item !== '(dry-run)' && item !== '(unresolved)'));
+    if (stagedPaths.length === 0) {
+        return {
+            ok: false,
+            error: { code: 'NO_CHANGES', message: 'no published files to commit' },
+        };
+    }
+    const branch = resolveUniqueBranchName(gitRoot, buildPublishBranchName(options.published));
+    if (options.dryRun) {
+        return {
+            ok: true,
+            data: {
+                branch,
+                commitMessage: options.message,
+                stagedPaths,
+                pushed: false,
+            },
+        };
+    }
+    try {
+        createBranch(gitRoot, branch);
+        stagePaths(gitRoot, stagedPaths);
+        commitStaged(gitRoot, options.message);
+    }
+    catch (error) {
+        const message = error instanceof GitCommandError ? error.message : String(error);
+        return {
+            ok: false,
+            error: { code: 'GIT_ERROR', message, hint: 'Resolve git state and retry publish --pr.' },
+        };
+    }
+    if (options.skipPush) {
+        return {
+            ok: true,
+            data: {
+                branch,
+                commitMessage: options.message,
+                stagedPaths,
+                pushed: false,
+            },
+        };
+    }
+    if (!commandExists('gh')) {
+        return {
+            ok: false,
+            error: {
+                code: 'GH_MISSING',
+                message: 'GitHub CLI (gh) is not installed',
+                hint: `Branch ${branch} was created locally with commit staged paths. Install gh and run: gh pr create`,
+            },
+        };
+    }
+    try {
+        pushBranch(gitRoot, branch);
+    }
+    catch (error) {
+        const message = error instanceof GitCommandError ? error.message : String(error);
+        return {
+            ok: false,
+            error: {
+                code: 'PUSH_FAILED',
+                message,
+                hint: `Branch ${branch} exists locally. Configure a remote and push manually.`,
+            },
+        };
+    }
+    try {
+        const prUrl = createPullRequest(gitRoot, {
+            title: options.prTitle,
+            body: options.prBody,
+            base: options.baseBranch,
+        });
+        return {
+            ok: true,
+            data: {
+                branch,
+                commitMessage: options.message,
+                stagedPaths,
+                prUrl,
+                pushed: true,
+            },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: {
+                code: 'GIT_ERROR',
+                message,
+                hint: `Branch ${branch} was pushed. Create the PR manually with gh pr create.`,
+            },
+        };
+    }
+}
+export function formatDryRunPublishPr(published, result) {
+    const lines = [
+        'dry-run: would publish drafts:',
+        ...published.map((item) => `  - ${item.slug} (${item.title})`),
+        `dry-run: would create branch ${result.branch}`,
+        `dry-run: would commit ${result.stagedPaths.length} file(s):`,
+        ...result.stagedPaths.map((item) => `  - ${item}`),
+        `dry-run: would push and run gh pr create`,
+    ];
+    return lines.join('\n');
+}

package/dist/index/slug.d.ts

@@ -1,5 +1,7 @@
 export declare const SLUG_PATTERN: RegExp;
 export declare function isValidSlug(slug: string): boolean;
+/** Derives a kebab-case slug from a human title. */
+export declare function slugFromTitle(title: string): string;
 /** Builds a stable slug from a path relative to the docs root. */
 export declare function slugFromRelativePath(relativePath: string): string;
 export declare function resolveDocPath(knowledgeRoot: string, typeDir: string, slug: string): string | null;