gitnexushub 0.4.2 → 0.4.3

package/dist/api.d.ts

@@ -72,6 +72,55 @@ export interface SyncJobStatus {
     phase: string | null;
     error: string | null;
 }
+export interface ResolveRepoResult {
+    repoId: string;
+    fullName: string;
+    status: string;
+    indexedAt: string | null;
+    lastCommit: string | null;
+    permissions: {
+        read: boolean;
+        write: boolean;
+    };
+}
+export interface WikiUploadStartParams {
+    mode: 'full' | 'incremental';
+    fromCommit?: string;
+    clientVersion?: string;
+    clientModel?: string;
+}
+export interface WikiUploadStartResult {
+    sessionId: string;
+    status: 'active';
+    startedAt: string;
+}
+export interface WikiUploadPagePayload {
+    slug: string;
+    title: string;
+    contentMd: string;
+}
+export interface WikiUploadFinishParams {
+    moduleTree: unknown;
+    receivedSlugs: string[];
+}
+export interface WikiConfig {
+    serverGenerationEnabled: boolean;
+    clientUploadAvailable: boolean;
+    clientCommand: string;
+}
+export interface WikiUploadSessionRow {
+    id: string;
+    userId: string;
+    status: 'active' | 'finished' | 'aborted' | 'stale';
+    mode: 'full' | 'incremental';
+    pagesReceived: number;
+    startedAt: string;
+    finishedAt: string | null;
+}
+export interface WikiUploadStatus {
+    active: WikiUploadSessionRow | null;
+    last: WikiUploadSessionRow | null;
+}
 export declare class HubAPI {
     private hubUrl;
     private token;
@@ -81,6 +130,7 @@ export declare class HubAPI {
     private get authHeaders();
     private request;
     private post;
+    private postJson;
     getMe(): Promise<UserProfile>;
     listRepos(): Promise<HubRepo[]>;
     getConnectContext(repoFullName: string): Promise<ConnectContext>;
@@ -92,4 +142,41 @@ export declare class HubAPI {
         tarball: NodeJS.ReadableStream;
     }): Promise<SyncResult>;
     syncStatus(repoId: string, jobId: string): Promise<SyncJobStatus>;
+    resolveRepoByRemote(remote: string): Promise<ResolveRepoResult>;
+    wikiUploadStart(repoId: string, params: WikiUploadStartParams): Promise<WikiUploadStartResult>;
+    wikiUploadPage(repoId: string, sessionId: string, page: WikiUploadPagePayload): Promise<{
+        slug: string;
+        pagesReceived: number;
+    }>;
+    wikiUploadFinish(repoId: string, sessionId: string, params: WikiUploadFinishParams): Promise<{
+        sessionId: string;
+        pagesPersisted: number;
+    }>;
+    wikiUploadAbort(repoId: string, sessionId: string): Promise<{
+        sessionId: string;
+        status: string;
+    }>;
+    wikiUploadStatus(repoId: string): Promise<WikiUploadStatus>;
+    getWikiConfig(): Promise<WikiConfig>;
+    wikiGroupingContext(repoId: string): Promise<any>;
+    wikiLeafContext(repoId: string, moduleName: string, filePaths: string[]): Promise<any>;
+    wikiOverviewContext(repoId: string, moduleFiles: Record<string, string[]>): Promise<any>;
+    wikiPromptTemplates(repoId: string): Promise<{
+        grouping: {
+            system: string;
+            user: string;
+        };
+        module: {
+            system: string;
+            user: string;
+        };
+        parent: {
+            system: string;
+            user: string;
+        };
+        overview: {
+            system: string;
+            user: string;
+        };
+    }>;
 }

package/dist/api.js

@@ -49,6 +49,22 @@ export class HubAPI {
         }
         return res.json();
     }
+    async postJson(path, body, extraHeaders = {}) {
+        const res = await fetch(`${this.hubUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                ...this.authHeaders,
+                'Content-Type': 'application/json',
+                ...extraHeaders,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || `HTTP ${res.status}`);
+        }
+        return res.json();
+    }
     async getMe() {
         return this.request('/auth/me');
     }
@@ -103,4 +119,39 @@ export class HubAPI {
     async syncStatus(repoId, jobId) {
         return this.request(`/api/repos/${repoId}/sync/${jobId}`);
     }
+    async resolveRepoByRemote(remote) {
+        return this.postJson('/api/repos/resolve', { remote });
+    }
+    async wikiUploadStart(repoId, params) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/start`, params);
+    }
+    async wikiUploadPage(repoId, sessionId, page) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/page`, { slug: page.slug, title: page.title, content_md: page.contentMd }, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadFinish(repoId, sessionId, params) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/finish`, params, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadAbort(repoId, sessionId) {
+        return this.postJson(`/api/repos/${repoId}/wiki/upload/abort`, {}, { 'X-Wiki-Upload-Session': sessionId });
+    }
+    async wikiUploadStatus(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/upload/status`);
+    }
+    async getWikiConfig() {
+        return this.request(`/api/wiki-config`);
+    }
+    async wikiGroupingContext(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/context/grouping`);
+    }
+    async wikiLeafContext(repoId, moduleName, filePaths) {
+        const params = new URLSearchParams({ name: moduleName, files: filePaths.join(',') });
+        return this.request(`/api/repos/${repoId}/wiki/context/leaf?${params}`);
+    }
+    async wikiOverviewContext(repoId, moduleFiles) {
+        const params = new URLSearchParams({ moduleFiles: JSON.stringify(moduleFiles) });
+        return this.request(`/api/repos/${repoId}/wiki/context/overview?${params}`);
+    }
+    async wikiPromptTemplates(repoId) {
+        return this.request(`/api/repos/${repoId}/wiki/context/prompts`);
+    }
 }

package/dist/git-remote.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Canonicalizes a git remote URL into "host/path" form so that two variants
+ * of the same upstream (https vs ssh, with/without `.git`, with/without creds)
+ * compare equal. Returns null if the input isn't a recognizable git URL.
+ */
+export declare function canonicalizeGitRemote(raw: string): string | null;

package/dist/git-remote.js

@@ -0,0 +1,57 @@
+const CASE_INSENSITIVE_HOSTS = new Set([
+    'github.com',
+    'gitlab.com',
+    'bitbucket.org',
+    'codeberg.org',
+    'gitea.com',
+]);
+/**
+ * Canonicalizes a git remote URL into "host/path" form so that two variants
+ * of the same upstream (https vs ssh, with/without `.git`, with/without creds)
+ * compare equal. Returns null if the input isn't a recognizable git URL.
+ */
+export function canonicalizeGitRemote(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    // Reject local paths before URL parsing
+    if (trimmed.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(trimmed))
+        return null;
+    if (trimmed.startsWith('file://'))
+        return null;
+    let host;
+    let pathPart;
+    // SCP-style: user@host:path
+    const scpMatch = trimmed.match(/^(?:([^@]+)@)?([^:/@]+):([^:].*)$/);
+    if (scpMatch && !trimmed.includes('://')) {
+        host = scpMatch[2];
+        pathPart = scpMatch[3];
+    }
+    else {
+        try {
+            const url = new URL(trimmed);
+            if (!['http:', 'https:', 'ssh:', 'git:'].includes(url.protocol))
+                return null;
+            host = url.hostname;
+            pathPart = url.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!host)
+        return null;
+    // Strip leading/trailing slashes and .git suffix
+    pathPart = pathPart
+        .replace(/^\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/i, '');
+    if (!pathPart)
+        return null;
+    // Lowercase host always; lowercase path only for known case-insensitive hosts
+    const lowerHost = host.toLowerCase();
+    const normalizedPath = CASE_INSENSITIVE_HOSTS.has(lowerHost) ? pathPart.toLowerCase() : pathPart;
+    return `${lowerHost}/${normalizedPath}`;
+}

package/dist/index.js

@@ -18,6 +18,7 @@ import { removeProjectContext } from './context.js';
 import { runSync } from './sync-command.js';
 import { ok, info, warn, fail, resolveAuth, DEFAULT_HUB_URL, EDITORS } from './cli-helpers.js';
 import { runConnect } from './connect-command.js';
+import { registerWikiCommand } from './wiki/index.js';
 const BANNER = [
     ' ██████╗ ██╗████████╗███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗',
     '██╔════╝ ██║╚══██╔══╝████╗  ██║██╔════╝╚██╗██╔╝██║   ██║██╔════╝',
@@ -110,6 +111,8 @@ program
         process.exit(1);
     }
 });
+// ─── wiki commands ────────────────────────────────────────────────
+registerWikiCommand(program);
 program.parse();
 // ─── Disconnect Flow ──────────────────────────────────────────────
 async function runDisconnect(opts) {

package/dist/wiki/abort-command.d.ts

@@ -0,0 +1,7 @@
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare function runWikiAbort(deps: ResolveContextDeps): Promise<{
+    sessionId: string;
+    status: string;
+} | {
+    noActive: true;
+}>;

package/dist/wiki/abort-command.js

@@ -0,0 +1,15 @@
+import { resolveWikiContext } from './resolve-context.js';
+import { GnxError, ErrorCode } from './errors.js';
+export async function runWikiAbort(deps) {
+    const ctx = await resolveWikiContext(deps, { skipClaudeChecks: true });
+    const status = await ctx.api.wikiUploadStatus(ctx.hubRepoId);
+    if (!status.active) {
+        return { noActive: true };
+    }
+    try {
+        return await ctx.api.wikiUploadAbort(ctx.hubRepoId, status.active.id);
+    }
+    catch (err) {
+        throw new GnxError(ErrorCode.NETWORK, 'failed to abort session', { cause: err });
+    }
+}

package/dist/wiki/claude.d.ts

@@ -0,0 +1,12 @@
+export interface ClaudeGenerationResult {
+    text: string;
+    durationMs: number;
+}
+export interface ClaudeRunner {
+    run(prompt: string, opts: {
+        cwd: string;
+        model?: string;
+        allowedTools?: string[];
+    }): Promise<ClaudeGenerationResult>;
+}
+export declare function createClaudeRunner(): ClaudeRunner;

package/dist/wiki/claude.js

@@ -0,0 +1,48 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { GnxError, ErrorCode } from './errors.js';
+const DEFAULT_ALLOWED_TOOLS = [
+    'Read',
+    'Grep',
+    'mcp__gitnexus__context',
+    'mcp__gitnexus__query',
+    'mcp__gitnexus__group_list',
+    'mcp__gitnexus__group_contracts',
+    'mcp__gitnexus__cypher',
+];
+export function createClaudeRunner() {
+    return {
+        async run(prompt, opts) {
+            const start = Date.now();
+            let finalText = '';
+            try {
+                for await (const msg of query({
+                    prompt,
+                    options: {
+                        cwd: opts.cwd,
+                        model: opts.model,
+                        allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+                    },
+                })) {
+                    const m = msg;
+                    if (m.type === 'result' && typeof m.result === 'string') {
+                        finalText = m.result;
+                    }
+                }
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                if (/auth|login|credentials/i.test(msg)) {
+                    throw new GnxError(ErrorCode.CLAUDE_AUTH_FAILED, 'Claude Code authentication failed', {
+                        hint: 're-authenticate: run `claude /login`',
+                        cause: err,
+                    });
+                }
+                throw new GnxError(ErrorCode.GENERATION_FAILED, `Claude Code error: ${msg}`, {
+                    cause: err,
+                });
+            }
+            const durationMs = Date.now() - start;
+            return { text: finalText, durationMs };
+        },
+    };
+}

package/dist/wiki/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Typed errors with stable exit codes for `gnx wiki *` commands.
+ *
+ * Exit code ranges (keep stable — used by shell scripts / CI):
+ *  10-19   local git problems
+ *  20-29   repo resolution / Hub repo state
+ *  30-39   auth / config problems
+ *  40-49   Claude Code problems
+ *  50-59   network / Hub reachability
+ *  60-69   permissions (403, read-only)
+ *  70-79   session conflict / rate limit
+ *  80-89   upload validation / in-flight failures
+ */
+export declare enum ErrorCode {
+    NOT_GIT_REPO = "NOT_GIT_REPO",
+    NO_COMMITS = "NO_COMMITS",
+    NO_REMOTE = "NO_REMOTE",
+    UNPARSEABLE_REMOTE = "UNPARSEABLE_REMOTE",
+    LOCAL_PATH_REMOTE = "LOCAL_PATH_REMOTE",
+    NOT_CONNECTED = "NOT_CONNECTED",
+    CONFIG_CORRUPT = "CONFIG_CORRUPT",
+    AUTH_INVALID = "AUTH_INVALID",
+    CLAUDE_NOT_INSTALLED = "CLAUDE_NOT_INSTALLED",
+    CLAUDE_MCP_MISSING = "CLAUDE_MCP_MISSING",
+    CLAUDE_AUTH_FAILED = "CLAUDE_AUTH_FAILED",
+    NETWORK = "NETWORK",
+    HUB_UNREACHABLE = "HUB_UNREACHABLE",
+    REPO_NOT_ON_HUB = "REPO_NOT_ON_HUB",
+    REPO_NOT_INDEXED = "REPO_NOT_INDEXED",
+    REPO_READ_ONLY = "REPO_READ_ONLY",
+    SESSION_CONFLICT = "SESSION_CONFLICT",
+    RATE_LIMITED = "RATE_LIMITED",
+    PAGE_VALIDATION = "PAGE_VALIDATION",
+    PAGE_TOO_LARGE = "PAGE_TOO_LARGE",
+    GENERATION_FAILED = "GENERATION_FAILED",
+    USER_ABORTED = "USER_ABORTED",
+    UNKNOWN = "UNKNOWN"
+}
+export interface GnxErrorOptions {
+    hint?: string;
+    cause?: unknown;
+}
+export declare class GnxError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: number;
+    readonly hint?: string;
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, opts?: GnxErrorOptions);
+}

package/dist/wiki/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Typed errors with stable exit codes for `gnx wiki *` commands.
+ *
+ * Exit code ranges (keep stable — used by shell scripts / CI):
+ *  10-19   local git problems
+ *  20-29   repo resolution / Hub repo state
+ *  30-39   auth / config problems
+ *  40-49   Claude Code problems
+ *  50-59   network / Hub reachability
+ *  60-69   permissions (403, read-only)
+ *  70-79   session conflict / rate limit
+ *  80-89   upload validation / in-flight failures
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["NOT_GIT_REPO"] = "NOT_GIT_REPO";
+    ErrorCode["NO_COMMITS"] = "NO_COMMITS";
+    ErrorCode["NO_REMOTE"] = "NO_REMOTE";
+    ErrorCode["UNPARSEABLE_REMOTE"] = "UNPARSEABLE_REMOTE";
+    ErrorCode["LOCAL_PATH_REMOTE"] = "LOCAL_PATH_REMOTE";
+    ErrorCode["NOT_CONNECTED"] = "NOT_CONNECTED";
+    ErrorCode["CONFIG_CORRUPT"] = "CONFIG_CORRUPT";
+    ErrorCode["AUTH_INVALID"] = "AUTH_INVALID";
+    ErrorCode["CLAUDE_NOT_INSTALLED"] = "CLAUDE_NOT_INSTALLED";
+    ErrorCode["CLAUDE_MCP_MISSING"] = "CLAUDE_MCP_MISSING";
+    ErrorCode["CLAUDE_AUTH_FAILED"] = "CLAUDE_AUTH_FAILED";
+    ErrorCode["NETWORK"] = "NETWORK";
+    ErrorCode["HUB_UNREACHABLE"] = "HUB_UNREACHABLE";
+    ErrorCode["REPO_NOT_ON_HUB"] = "REPO_NOT_ON_HUB";
+    ErrorCode["REPO_NOT_INDEXED"] = "REPO_NOT_INDEXED";
+    ErrorCode["REPO_READ_ONLY"] = "REPO_READ_ONLY";
+    ErrorCode["SESSION_CONFLICT"] = "SESSION_CONFLICT";
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["PAGE_VALIDATION"] = "PAGE_VALIDATION";
+    ErrorCode["PAGE_TOO_LARGE"] = "PAGE_TOO_LARGE";
+    ErrorCode["GENERATION_FAILED"] = "GENERATION_FAILED";
+    ErrorCode["USER_ABORTED"] = "USER_ABORTED";
+    ErrorCode["UNKNOWN"] = "UNKNOWN";
+})(ErrorCode || (ErrorCode = {}));
+const EXIT_CODES = {
+    [ErrorCode.NOT_GIT_REPO]: 10,
+    [ErrorCode.NO_COMMITS]: 11,
+    [ErrorCode.NO_REMOTE]: 12,
+    [ErrorCode.UNPARSEABLE_REMOTE]: 13,
+    [ErrorCode.LOCAL_PATH_REMOTE]: 14,
+    [ErrorCode.REPO_NOT_INDEXED]: 20,
+    [ErrorCode.REPO_NOT_ON_HUB]: 21,
+    [ErrorCode.NOT_CONNECTED]: 30,
+    [ErrorCode.CONFIG_CORRUPT]: 31,
+    [ErrorCode.AUTH_INVALID]: 32,
+    [ErrorCode.CLAUDE_NOT_INSTALLED]: 40,
+    [ErrorCode.CLAUDE_MCP_MISSING]: 41,
+    [ErrorCode.CLAUDE_AUTH_FAILED]: 42,
+    [ErrorCode.NETWORK]: 50,
+    [ErrorCode.HUB_UNREACHABLE]: 51,
+    [ErrorCode.REPO_READ_ONLY]: 62,
+    [ErrorCode.SESSION_CONFLICT]: 70,
+    [ErrorCode.RATE_LIMITED]: 72,
+    [ErrorCode.PAGE_VALIDATION]: 80,
+    [ErrorCode.PAGE_TOO_LARGE]: 81,
+    [ErrorCode.GENERATION_FAILED]: 82,
+    [ErrorCode.USER_ABORTED]: 130,
+    [ErrorCode.UNKNOWN]: 1,
+};
+export class GnxError extends Error {
+    code;
+    exitCode;
+    hint;
+    cause;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = 'GnxError';
+        this.code = code;
+        this.exitCode = EXIT_CODES[code];
+        this.hint = opts.hint;
+        this.cause = opts.cause;
+    }
+}

package/dist/wiki/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerWikiCommand(program: Command): void;

package/dist/wiki/index.js

@@ -0,0 +1,98 @@
+import pc from 'picocolors';
+import { ok, info, warn, fail } from '../cli-helpers.js';
+import { buildRealDeps, REAL_DEFAULT_MODEL } from './real-deps.js';
+import { runWikiUpload } from './upload-command.js';
+import { runWikiStatus } from './status-command.js';
+import { runWikiAbort } from './abort-command.js';
+import { GnxError } from './errors.js';
+function reportError(err) {
+    if (err instanceof GnxError) {
+        fail(err.message);
+        if (err.hint)
+            console.error(`    ${pc.dim(err.hint)}`);
+        process.exit(err.exitCode);
+    }
+    fail(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+export function registerWikiCommand(program) {
+    const wiki = program.command('wiki').description('Client-side wiki generation and upload');
+    wiki
+        .command('upload')
+        .description('Generate the wiki locally with Claude Code and upload it to the Hub')
+        .option('--mode <mode>', 'full | incremental', 'full')
+        .option('--model <model>', 'Claude model to use', REAL_DEFAULT_MODEL)
+        .action(async (opts) => {
+        const cwd = process.cwd();
+        const deps = buildRealDeps(cwd);
+        if (opts.model)
+            deps.model = opts.model;
+        const ac = new AbortController();
+        const onSig = () => {
+            warn('interrupt received, aborting session...');
+            ac.abort();
+        };
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+        try {
+            info(`Resolving repo context...`);
+            const result = await runWikiUpload({ cwd, mode: opts.mode, model: opts.model, abortSignal: ac.signal }, deps);
+            ok(`Uploaded ${result.pagesPersisted} pages.`);
+            if (result.failedSlugs.length > 0) {
+                warn(`${result.failedSlugs.length} page(s) failed: ${result.failedSlugs.join(', ')}`);
+            }
+        }
+        catch (err) {
+            reportError(err);
+        }
+        finally {
+            process.off('SIGINT', onSig);
+            process.off('SIGTERM', onSig);
+        }
+    });
+    wiki
+        .command('status')
+        .description('Show the wiki upload status for the current repo')
+        .action(async () => {
+        try {
+            const deps = buildRealDeps(process.cwd());
+            const status = await runWikiStatus(deps);
+            info(`Repo: ${pc.bold(status.fullName)} (${status.canonicalRemote})`);
+            info(`Hub indexed commit: ${status.hubIndexedCommit ?? '(none)'}`);
+            if (status.active) {
+                info(`Active session: ${pc.yellow(status.active.id)} ` +
+                    `started ${status.active.startedAt}, ` +
+                    `${status.active.pagesReceived} pages received`);
+            }
+            else {
+                info('No active upload session.');
+            }
+            if (status.last) {
+                info(`Last session: ${status.last.status}, ` +
+                    `${status.last.pagesReceived} pages, ` +
+                    `started ${status.last.startedAt}`);
+            }
+        }
+        catch (err) {
+            reportError(err);
+        }
+    });
+    wiki
+        .command('abort')
+        .description('Abort the active wiki upload session for the current repo')
+        .action(async () => {
+        try {
+            const deps = buildRealDeps(process.cwd());
+            const result = await runWikiAbort(deps);
+            if ('noActive' in result) {
+                info('No active session to abort.');
+            }
+            else {
+                ok(`Aborted session ${result.sessionId}`);
+            }
+        }
+        catch (err) {
+            reportError(err);
+        }
+    });
+}

package/dist/wiki/prompts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Prompt templates for client-side wiki generation via Claude Code headless.
+ *
+ * The runner passes these prompts to Claude Code with the user's repo as cwd
+ * and read-only tools (Read, Grep) plus the gitnexus MCP tools available.
+ * Graph context comes from the Hub via MCP — no local LadybugDB needed.
+ */
+export declare function renderModuleTreePrompt(fullName: string): string;
+export declare function renderPagePrompt(fullName: string, moduleSlug: string, moduleTitle: string): string;
+export declare const MODULE_TREE_PROMPT_TEMPLATE: string;
+export declare const PAGE_PROMPT_TEMPLATE: string;

package/dist/wiki/prompts.js

@@ -0,0 +1,72 @@
+/**
+ * Prompt templates for client-side wiki generation via Claude Code headless.
+ *
+ * The runner passes these prompts to Claude Code with the user's repo as cwd
+ * and read-only tools (Read, Grep) plus the gitnexus MCP tools available.
+ * Graph context comes from the Hub via MCP — no local LadybugDB needed.
+ */
+export function renderModuleTreePrompt(fullName) {
+    return `You are generating a repository wiki for the repo "${fullName}".
+
+Your task: produce a JSON module hierarchy for this repo.
+
+Use these MCP tools (they query the live Hub-indexed graph):
+  - mcp__gitnexus__context       — overview of the repo
+  - mcp__gitnexus__group_list    — existing cluster/module groupings
+  - mcp__gitnexus__query         — concept/code search
+
+Output ONLY valid JSON with this exact shape (no prose, no markdown fences):
+
+{
+  "modules": [
+    {
+      "slug": "kebab-case-slug",
+      "title": "Human-Readable Title",
+      "summary": "One-sentence description",
+      "files": ["optional/representative/file.ts"]
+    }
+  ]
+}
+
+Rules:
+- 6–15 top-level modules (adjust based on repo size).
+- "slug" MUST match ^[a-z0-9][a-z0-9/_-]*$ and be unique within the array.
+- Include an "overview" module as the first entry.
+- Group by responsibility, not file type. "parser" > "typescript-files".
+- No duplicates, no empty strings, no trailing punctuation in titles.`;
+}
+export function renderPagePrompt(fullName, moduleSlug, moduleTitle) {
+    return `You are writing a single wiki page for the repo "${fullName}".
+
+Module: "${moduleSlug}" (${moduleTitle})
+
+Use these tools freely:
+  - mcp__gitnexus__context       — caller/callee graph for symbols
+  - mcp__gitnexus__query         — concept search across the codebase
+  - mcp__gitnexus__group_contracts — structural facts about a group
+  - Read, Grep                   — inspect local files in the repo for concrete snippets
+
+Output: a single Markdown document starting with "# ${moduleTitle}" as the H1.
+
+Structure:
+  # ${moduleTitle}
+
+  One-paragraph summary.
+
+  ## Responsibilities
+  - Bulleted list of what this module owns.
+
+  ## Key Components
+  Short sections per major symbol/class/function with a brief explanation.
+  Include short code blocks (<= 20 lines) from the actual repo when illustrative.
+
+  ## How It Fits In
+  How this module connects to the rest of the system (callers, callees, flows).
+
+Rules:
+- Return ONLY the markdown — no preamble, no conclusion, no "Here's the wiki page".
+- Do not invent symbols or file paths. If you're unsure, query the graph.
+- Keep the total length under 50 KB.`;
+}
+export const MODULE_TREE_PROMPT_TEMPLATE = renderModuleTreePrompt('__FULL_NAME__');
+export const PAGE_PROMPT_TEMPLATE = renderPagePrompt('__FULL_NAME__', '__SLUG__', '__TITLE__');

package/dist/wiki/real-deps.d.ts

@@ -0,0 +1,9 @@
+import { createClaudeRunner } from './claude.js';
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare const REAL_CLIENT_VERSION: string;
+export declare const REAL_DEFAULT_MODEL: string;
+export declare function buildRealDeps(cwd: string): ResolveContextDeps & {
+    createClaudeRunner: typeof createClaudeRunner;
+    clientVersion: string;
+    model: string;
+};

package/dist/wiki/real-deps.js

@@ -0,0 +1,63 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { HubAPI } from '../api.js';
+import { loadConfig as loadConnectConfig } from '../config.js';
+import { createClaudeRunner } from './claude.js';
+export const REAL_CLIENT_VERSION = 'gnx/' + (process.env.npm_package_version ?? 'dev');
+export const REAL_DEFAULT_MODEL = process.env.GNX_WIKI_MODEL ?? 'claude-sonnet-4-6';
+function runGit(cwd, args) {
+    try {
+        return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString('utf-8')
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function buildRealDeps(cwd) {
+    return {
+        cwd,
+        loadConfig: loadConnectConfig,
+        getGitRoot: (c) => runGit(c, ['rev-parse', '--show-toplevel']),
+        getGitRemoteUrl: (c) => runGit(c, ['remote', 'get-url', 'origin']),
+        getGitHead: (c) => runGit(c, ['rev-parse', 'HEAD']),
+        getGitDirty: (c) => {
+            const out = runGit(c, ['status', '--porcelain']);
+            return (out?.length ?? 0) > 0;
+        },
+        buildApi: (hubUrl, token) => new HubAPI(hubUrl, token),
+        verifyClaudeCodeInstalled: async () => {
+            try {
+                execFileSync('claude', ['--version'], { stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        verifyClaudeCodeMcpRegistered: async (hubUrl) => {
+            try {
+                const claudeJson = path.join(os.homedir(), '.claude.json');
+                if (!fs.existsSync(claudeJson))
+                    return false;
+                const parsed = JSON.parse(fs.readFileSync(claudeJson, 'utf-8'));
+                const mcpServers = parsed?.mcpServers ?? {};
+                for (const key of Object.keys(mcpServers)) {
+                    const entry = mcpServers[key];
+                    if (entry?.url && String(entry.url).startsWith(hubUrl))
+                        return true;
+                }
+                return false;
+            }
+            catch {
+                return false;
+            }
+        },
+        createClaudeRunner,
+        clientVersion: REAL_CLIENT_VERSION,
+        model: REAL_DEFAULT_MODEL,
+    };
+}

package/dist/wiki/resolve-context.d.ts

@@ -0,0 +1,31 @@
+import type { HubAPI } from '../api.js';
+export interface WikiContext {
+    repoRoot: string;
+    headCommit: string;
+    isDirty: boolean;
+    canonicalRemote: string;
+    hubRepoId: string;
+    hubFullName: string;
+    hubIndexedCommit: string | null;
+    hubIndexedStatus: string;
+    hubUrl: string;
+    api: HubAPI;
+}
+export interface ResolveContextDeps {
+    cwd: string;
+    loadConfig: () => Promise<{
+        hubToken?: string;
+        hubUrl?: string;
+    }>;
+    getGitRemoteUrl: (cwd: string) => string | null;
+    getGitRoot: (cwd: string) => string | null;
+    getGitHead: (cwd: string) => string | null;
+    getGitDirty: (cwd: string) => boolean;
+    buildApi: (hubUrl: string, token: string) => HubAPI;
+    verifyClaudeCodeInstalled: () => Promise<boolean>;
+    verifyClaudeCodeMcpRegistered: (hubUrl: string) => Promise<boolean>;
+}
+export interface ResolveContextOptions {
+    skipClaudeChecks?: boolean;
+}
+export declare function resolveWikiContext(deps: ResolveContextDeps, opts?: ResolveContextOptions): Promise<WikiContext>;

package/dist/wiki/resolve-context.js

@@ -0,0 +1,82 @@
+import { canonicalizeGitRemote } from '../git-remote.js';
+import { GnxError, ErrorCode } from './errors.js';
+export async function resolveWikiContext(deps, opts = {}) {
+    const repoRoot = deps.getGitRoot(deps.cwd);
+    if (!repoRoot) {
+        throw new GnxError(ErrorCode.NOT_GIT_REPO, 'not a git repository', {
+            hint: 'cd into your project, or run: gnx wiki upload <path>',
+        });
+    }
+    const headCommit = deps.getGitHead(repoRoot);
+    if (!headCommit) {
+        throw new GnxError(ErrorCode.NO_COMMITS, 'git repository has no commits yet', {
+            hint: 'commit something before generating a wiki',
+        });
+    }
+    const rawRemote = deps.getGitRemoteUrl(repoRoot);
+    if (!rawRemote) {
+        throw new GnxError(ErrorCode.NO_REMOTE, "no 'origin' remote found", {
+            hint: 'add one with: git remote add origin <url>',
+        });
+    }
+    if (rawRemote.startsWith('/') ||
+        /^[a-zA-Z]:[\\/]/.test(rawRemote) ||
+        rawRemote.startsWith('file://')) {
+        throw new GnxError(ErrorCode.LOCAL_PATH_REMOTE, `origin points at a local path ('${rawRemote}')`, { hint: 'gnx needs a public/forge URL to match against the Hub' });
+    }
+    const canonicalRemote = canonicalizeGitRemote(rawRemote);
+    if (!canonicalRemote) {
+        throw new GnxError(ErrorCode.UNPARSEABLE_REMOTE, `origin is '${rawRemote}' which isn't a recognized git URL`, { hint: 'pass --remote <name> to use a different remote' });
+    }
+    const isDirty = deps.getGitDirty(repoRoot);
+    const config = await deps.loadConfig();
+    if (!config.hubToken) {
+        throw new GnxError(ErrorCode.NOT_CONNECTED, 'not connected to the Hub', {
+            hint: 'run: gnx connect <token>',
+        });
+    }
+    const hubUrl = config.hubUrl || 'https://gitnexus-enterprise-production.up.railway.app';
+    if (!opts.skipClaudeChecks) {
+        if (!(await deps.verifyClaudeCodeInstalled())) {
+            throw new GnxError(ErrorCode.CLAUDE_NOT_INSTALLED, "Claude Code isn't installed or on PATH", {
+                hint: 'install: https://claude.com/claude-code',
+            });
+        }
+        if (!(await deps.verifyClaudeCodeMcpRegistered(hubUrl))) {
+            throw new GnxError(ErrorCode.CLAUDE_MCP_MISSING, "Claude Code isn't wired to the Hub MCP server", { hint: 're-run: gnx connect' });
+        }
+    }
+    const api = deps.buildApi(hubUrl, config.hubToken);
+    let resolve;
+    try {
+        resolve = await api.resolveRepoByRemote(canonicalRemote);
+    }
+    catch (err) {
+        const msg = err?.message ?? String(err);
+        if (msg.includes('404') || msg.toLowerCase().includes('not found')) {
+            throw new GnxError(ErrorCode.REPO_NOT_ON_HUB, `${canonicalRemote} isn't indexed on the Hub`, {
+                hint: 'add it with: gnx index <owner>/<repo>',
+                cause: err,
+            });
+        }
+        throw new GnxError(ErrorCode.NETWORK, `Hub request failed: ${msg}`, { cause: err });
+    }
+    if (resolve.status !== 'ready') {
+        throw new GnxError(ErrorCode.REPO_NOT_INDEXED, `${resolve.fullName} is on the Hub but still ${resolve.status}`, { hint: 'wait for indexing, or run: gnx sync --wait' });
+    }
+    if (!resolve.permissions.write) {
+        throw new GnxError(ErrorCode.REPO_READ_ONLY, `you have read-only access to ${resolve.fullName}`, { hint: 'wiki uploads require write access — ask an owner to grant write' });
+    }
+    return {
+        repoRoot,
+        headCommit,
+        isDirty,
+        canonicalRemote,
+        hubRepoId: resolve.repoId,
+        hubFullName: resolve.fullName,
+        hubIndexedCommit: resolve.lastCommit,
+        hubIndexedStatus: resolve.status,
+        hubUrl,
+        api,
+    };
+}

package/dist/wiki/session.d.ts

@@ -0,0 +1,33 @@
+import type { HubAPI } from '../api.js';
+export interface ModuleNode {
+    slug: string;
+    title: string;
+    summary?: string;
+    files?: string[];
+}
+export interface GeneratePageFn {
+    (node: ModuleNode): Promise<{
+        title: string;
+        contentMd: string;
+    }>;
+}
+export interface RunSessionDeps {
+    api: HubAPI;
+    repoId: string;
+    mode: 'full' | 'incremental';
+    fromCommit: string;
+    clientVersion: string;
+    clientModel: string;
+    modules: ModuleNode[];
+    moduleTree: unknown;
+    generatePage: GeneratePageFn;
+    onPageStart?: (slug: string) => void;
+    onPageDone?: (slug: string, bytes: number) => void;
+    onPageFail?: (slug: string, err: unknown) => void;
+}
+export interface RunSessionResult {
+    sessionId: string;
+    pagesPersisted: number;
+    failedSlugs: string[];
+}
+export declare function runWikiUploadSession(deps: RunSessionDeps): Promise<RunSessionResult>;

package/dist/wiki/session.js

@@ -0,0 +1,72 @@
+import { GnxError, ErrorCode } from './errors.js';
+export async function runWikiUploadSession(deps) {
+    const { api, repoId } = deps;
+    const started = await api.wikiUploadStart(repoId, {
+        mode: deps.mode,
+        fromCommit: deps.fromCommit,
+        clientVersion: deps.clientVersion,
+        clientModel: deps.clientModel,
+    });
+    const sessionId = started.sessionId;
+    const receivedSlugs = [];
+    const failedSlugs = [];
+    let aborted = false;
+    const abortOnce = async (reason) => {
+        if (aborted)
+            return;
+        aborted = true;
+        try {
+            await api.wikiUploadAbort(repoId, sessionId);
+        }
+        catch {
+            /* ignore secondary errors */
+        }
+        throw reason instanceof Error
+            ? reason
+            : new GnxError(ErrorCode.GENERATION_FAILED, String(reason));
+    };
+    for (const mod of deps.modules) {
+        deps.onPageStart?.(mod.slug);
+        let page;
+        try {
+            page = await deps.generatePage(mod);
+        }
+        catch (err) {
+            failedSlugs.push(mod.slug);
+            deps.onPageFail?.(mod.slug, err);
+            try {
+                page = await deps.generatePage(mod);
+                failedSlugs.splice(failedSlugs.indexOf(mod.slug), 1);
+            }
+            catch (err2) {
+                deps.onPageFail?.(mod.slug, err2);
+                continue;
+            }
+        }
+        if (!page.contentMd || !page.contentMd.trim()) {
+            failedSlugs.push(mod.slug);
+            deps.onPageFail?.(mod.slug, new Error('empty generation result'));
+            continue;
+        }
+        try {
+            await api.wikiUploadPage(repoId, sessionId, {
+                slug: mod.slug,
+                title: page.title,
+                contentMd: page.contentMd,
+            });
+            receivedSlugs.push(mod.slug);
+            deps.onPageDone?.(mod.slug, Buffer.byteLength(page.contentMd, 'utf8'));
+        }
+        catch (err) {
+            await abortOnce(err);
+        }
+    }
+    if (receivedSlugs.length === 0) {
+        await abortOnce(new GnxError(ErrorCode.GENERATION_FAILED, 'no pages were generated successfully'));
+    }
+    const finished = await api.wikiUploadFinish(repoId, sessionId, {
+        moduleTree: deps.moduleTree,
+        receivedSlugs,
+    });
+    return { sessionId, pagesPersisted: finished.pagesPersisted, failedSlugs };
+}

package/dist/wiki/status-command.d.ts

@@ -0,0 +1,8 @@
+import type { ResolveContextDeps } from './resolve-context.js';
+export declare function runWikiStatus(deps: ResolveContextDeps): Promise<{
+    fullName: string;
+    canonicalRemote: string;
+    hubIndexedCommit: string | null;
+    active: unknown;
+    last: unknown;
+}>;

package/dist/wiki/status-command.js

@@ -0,0 +1,12 @@
+import { resolveWikiContext } from './resolve-context.js';
+export async function runWikiStatus(deps) {
+    const ctx = await resolveWikiContext(deps, { skipClaudeChecks: true });
+    const status = await ctx.api.wikiUploadStatus(ctx.hubRepoId);
+    return {
+        fullName: ctx.hubFullName,
+        canonicalRemote: ctx.canonicalRemote,
+        hubIndexedCommit: ctx.hubIndexedCommit,
+        active: status.active,
+        last: status.last,
+    };
+}

package/dist/wiki/upload-command.d.ts

@@ -0,0 +1,19 @@
+import type { ClaudeRunner } from './claude.js';
+import { type ResolveContextDeps } from './resolve-context.js';
+export interface RunWikiUploadOptions {
+    cwd: string;
+    mode?: 'full' | 'incremental';
+    model?: string;
+    abortSignal?: AbortSignal;
+}
+export interface RunWikiUploadDeps extends ResolveContextDeps {
+    createClaudeRunner: () => ClaudeRunner;
+    clientVersion: string;
+    model: string;
+}
+export interface RunWikiUploadResult {
+    pagesPersisted: number;
+    failedSlugs: string[];
+    sessionId: string;
+}
+export declare function runWikiUpload(opts: RunWikiUploadOptions, deps: RunWikiUploadDeps): Promise<RunWikiUploadResult>;

package/dist/wiki/upload-command.js

@@ -0,0 +1,300 @@
+import { resolveWikiContext } from './resolve-context.js';
+import { runWikiUploadSession } from './session.js';
+import { GnxError, ErrorCode } from './errors.js';
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function parseModuleTree(raw) {
+    const cleaned = raw
+        .trim()
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/```$/, '')
+        .trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree response was not valid JSON', {
+            cause: err,
+        });
+    }
+    if (parsed && !Array.isArray(parsed.modules) && typeof parsed === 'object') {
+        const modules = [];
+        for (const [name, files] of Object.entries(parsed)) {
+            if (!Array.isArray(files))
+                continue;
+            const slug = slugify(name);
+            if (!slug)
+                continue;
+            modules.push({
+                slug,
+                title: name,
+                files: files.filter((f) => typeof f === 'string'),
+            });
+        }
+        if (modules.length > 0)
+            return modules;
+    }
+    throw new GnxError(ErrorCode.GENERATION_FAILED, 'module tree had no valid modules');
+}
+const SPLIT_FILE_THRESHOLD = 20;
+function splitBySubdirectory(parentName, files) {
+    const subGroups = new Map();
+    for (const fp of files) {
+        const parts = fp.replace(/\\/g, '/').split('/');
+        const subDir = parts.length > 2 ? parts.slice(0, 2).join('/') : parts[0];
+        let group = subGroups.get(subDir);
+        if (!group) {
+            group = [];
+            subGroups.set(subDir, group);
+        }
+        group.push(fp);
+    }
+    const basenames = Array.from(subGroups.keys()).map((s) => s.split('/').pop());
+    const hasCollisions = new Set(basenames).size < basenames.length;
+    return Array.from(subGroups.entries()).map(([subDir, subFiles]) => {
+        const label = hasCollisions ? subDir.replace(/\//g, '-') : subDir.split('/').pop();
+        return {
+            slug: slugify(`${parentName}-${label}`),
+            title: `${parentName} — ${label}`,
+            files: subFiles,
+        };
+    });
+}
+function applyModuleSplitting(modules) {
+    for (const node of modules) {
+        const files = node.files ?? [];
+        if (files.length > SPLIT_FILE_THRESHOLD) {
+            const children = splitBySubdirectory(node.title, files);
+            if (children.length > 1) {
+                node.children = children;
+                node.files = [];
+            }
+        }
+    }
+    return modules;
+}
+function flattenModuleTree(tree) {
+    const leaves = [];
+    const parents = [];
+    for (const node of tree) {
+        if (node.children && node.children.length > 0) {
+            for (const child of node.children)
+                leaves.push(child);
+            parents.push(node);
+        }
+        else {
+            leaves.push(node);
+        }
+    }
+    return { leaves, parents };
+}
+function extractPageMarkdown(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('```')) {
+        return trimmed
+            .replace(/^```(?:markdown)?\s*/i, '')
+            .replace(/```$/, '')
+            .trim();
+    }
+    return trimmed;
+}
+function fillTemplate(template, vars) {
+    let result = template;
+    for (const [key, value] of Object.entries(vars)) {
+        result = result.replaceAll(`{{${key}}}`, value);
+    }
+    return result;
+}
+export async function runWikiUpload(opts, deps) {
+    const ctx = await resolveWikiContext(deps);
+    if (opts.abortSignal?.aborted)
+        throw new GnxError(ErrorCode.USER_ABORTED, 'aborted before session start');
+    const runner = deps.createClaudeRunner();
+    const [prompts, groupingCtx] = await Promise.all([
+        ctx.api.wikiPromptTemplates(ctx.hubRepoId),
+        ctx.api.wikiGroupingContext(ctx.hubRepoId),
+    ]);
+    // Phase 1: Module tree
+    const groupingPrompt = fillTemplate(prompts.grouping.user, {
+        COMMUNITY_GROUPS: groupingCtx.communityGroups,
+        INTER_COMMUNITY_EDGES: groupingCtx.interCommunityEdges,
+        CROSS_COMMUNITY_PROCESSES: groupingCtx.crossCommunityProcesses,
+        FILE_LIST: groupingCtx.filesWithExports,
+        DIRECTORY_TREE: groupingCtx.directoryTree,
+    });
+    const moduleTreeRaw = await runner.run(`${prompts.grouping.system}\n\n${groupingPrompt}`, {
+        cwd: ctx.repoRoot,
+        model: deps.model,
+        allowedTools: [],
+    });
+    const rawModules = parseModuleTree(moduleTreeRaw.text);
+    const modules = applyModuleSplitting(rawModules);
+    const { leaves, parents } = flattenModuleTree(modules);
+    const allPageNodes = [...leaves, ...parents];
+    const moduleRegistry = allPageNodes.map((m) => `- [${m.title}](${m.slug}.md)`).join('\n');
+    const generatedPages = new Map();
+    if (opts.abortSignal?.aborted)
+        throw new GnxError(ErrorCode.USER_ABORTED, 'aborted before page generation');
+    // Phase 2a: Leaf pages
+    const generateLeafPage = async (node) => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during page generation');
+        const filePaths = node.files ?? [];
+        let leafCtx;
+        try {
+            leafCtx = await ctx.api.wikiLeafContext(ctx.hubRepoId, node.title, filePaths);
+        }
+        catch {
+            leafCtx = {
+                sourceCode: '',
+                intraCalls: 'None',
+                outgoingCalls: 'None',
+                incomingCalls: 'None',
+                processes: 'No execution flows detected.',
+            };
+        }
+        const reg = allPageNodes
+            .filter((m) => m.slug !== node.slug)
+            .map((m) => `- [${m.title}](${m.slug}.md)`)
+            .join('\n');
+        const pagePrompt = fillTemplate(prompts.module.user, {
+            MODULE_NAME: node.title,
+            SOURCE_CODE: leafCtx.sourceCode,
+            INTRA_CALLS: leafCtx.intraCalls,
+            OUTGOING_CALLS: leafCtx.outgoingCalls,
+            INCOMING_CALLS: leafCtx.incomingCalls,
+            PROCESSES: leafCtx.processes,
+            MODULE_REGISTRY: reg,
+        });
+        const result = await runner.run(`${prompts.module.system}\n\n${pagePrompt}`, {
+            cwd: ctx.repoRoot,
+            model: deps.model,
+            allowedTools: [],
+        });
+        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        generatedPages.set(node.slug, content);
+        return { title: node.title, contentMd: content };
+    };
+    // Phase 2b: Parent pages
+    const generateParentPage = async (node) => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during parent page generation');
+        const childDocs = (node.children ?? [])
+            .map((child) => {
+            const content = generatedPages.get(child.slug);
+            return content
+                ? `#### ${child.title}\n${content.slice(0, 800).trim()}`
+                : `#### ${child.title}\n(Documentation not yet generated)`;
+        })
+            .join('\n\n');
+        const allChildFiles = (node.children ?? []).flatMap((c) => c.files ?? []);
+        let parentCtx;
+        try {
+            parentCtx = await ctx.api.wikiLeafContext(ctx.hubRepoId, node.title, allChildFiles);
+        }
+        catch {
+            parentCtx = { intraCalls: 'None', processes: 'No execution flows detected.' };
+        }
+        const reg = allPageNodes
+            .filter((m) => m.slug !== node.slug)
+            .map((m) => `- [${m.title}](${m.slug}.md)`)
+            .join('\n');
+        const parentPrompt = fillTemplate(prompts.parent.user, {
+            MODULE_NAME: node.title,
+            CHILDREN_DOCS: childDocs,
+            CROSS_MODULE_CALLS: parentCtx.intraCalls ?? 'None',
+            CROSS_PROCESSES: parentCtx.processes ?? 'No execution flows detected.',
+            MODULE_REGISTRY: reg,
+        });
+        const result = await runner.run(`${prompts.parent.system}\n\n${parentPrompt}`, {
+            cwd: ctx.repoRoot,
+            model: deps.model,
+            allowedTools: [],
+        });
+        const content = `# ${node.title}\n\n${extractPageMarkdown(result.text)}`;
+        generatedPages.set(node.slug, content);
+        return { title: node.title, contentMd: content };
+    };
+    // Phase 3: Overview page
+    const generateOverview = async () => {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'aborted during overview generation');
+        const moduleSummaries = modules
+            .map((m) => {
+            const content = generatedPages.get(m.slug);
+            return content
+                ? `#### ${m.title}\n${content.slice(0, 600).trim()}`
+                : `#### ${m.title}\n(Documentation pending)`;
+        })
+            .join('\n\n');
+        const moduleFiles = {};
+        for (const m of modules) {
+            const files = m.children ? m.children.flatMap((c) => c.files ?? []) : (m.files ?? []);
+            if (files.length > 0)
+                moduleFiles[m.title] = files;
+        }
+        let overviewCtx;
+        try {
+            overviewCtx = await ctx.api.wikiOverviewContext(ctx.hubRepoId, moduleFiles);
+        }
+        catch {
+            overviewCtx = {
+                interModuleEdges: 'No inter-module call edges detected',
+                topProcesses: 'No execution flows detected.',
+            };
+        }
+        const overviewPrompt = fillTemplate(prompts.overview.user, {
+            PROJECT_INFO: `Repository: ${ctx.hubFullName}`,
+            MODULE_SUMMARIES: moduleSummaries,
+            MODULE_EDGES: overviewCtx.interModuleEdges,
+            TOP_PROCESSES: overviewCtx.topProcesses,
+            MODULE_REGISTRY: moduleRegistry,
+        });
+        const result = await runner.run(`${prompts.overview.system}\n\n${overviewPrompt}`, {
+            cwd: ctx.repoRoot,
+            model: deps.model,
+            allowedTools: [],
+        });
+        return { title: 'Overview', contentMd: extractPageMarkdown(result.text) };
+    };
+    // Execute: leaves → parents → overview
+    const overviewNode = { slug: 'overview', title: 'Overview', files: [] };
+    const orderedModules = [...leaves, ...parents, overviewNode];
+    const generatePageByType = async (node) => {
+        if (node.slug === 'overview' && (node.files ?? []).length === 0)
+            return generateOverview();
+        const treeNode = parents.find((p) => p.slug === node.slug);
+        if (treeNode?.children)
+            return generateParentPage(treeNode);
+        return generateLeafPage(node);
+    };
+    const moduleTree = orderedModules.map((m) => ({
+        name: m.title,
+        slug: m.slug,
+        summary: m.summary,
+        files: m.files,
+    }));
+    try {
+        return await runWikiUploadSession({
+            api: ctx.api,
+            repoId: ctx.hubRepoId,
+            mode: opts.mode ?? 'full',
+            fromCommit: ctx.headCommit,
+            clientVersion: deps.clientVersion,
+            clientModel: deps.model,
+            modules: orderedModules,
+            moduleTree,
+            generatePage: generatePageByType,
+        });
+    }
+    catch (err) {
+        if (opts.abortSignal?.aborted)
+            throw new GnxError(ErrorCode.USER_ABORTED, 'user aborted', { cause: err });
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexushub",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Connect your editor to GitNexus Hub — one command MCP setup + project context",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",
@@ -35,6 +35,7 @@
     "prepare": "npm run build"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.109",
     "commander": "^12.0.0",
     "picocolors": "^1.1.1",
     "tar-stream": "^3.1.8"