@chronova/wiki-agent 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,9 @@
 # Wiki Agent
 
-A standalone Ollama-only documentation agent. It inspects your source code and generates a wiki under `.wiki/` in your project root.
+[![npm version](https://img.shields.io/npm/v/@chronova/wiki-agent.svg)](https://www.npmjs.com/package/@chronova/wiki-agent)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+A standalone Ollama-only documentation agent. It inspects your source code and generates a wiki under `.wiki/` in your project root, with optional publishing to the GitHub Wiki tab.
 
 ## Features
 
@@ -8,25 +11,27 @@ A standalone Ollama-only documentation agent. It inspects your source code and g
 - **Local or Cloud** — connect to a local Ollama server or Ollama Cloud with an API key
 - **TUI + Headless** — interactive terminal UI or `--print` for CI/CD
 - **Two commands** — `--init` to create docs from scratch, `--update` to refresh existing docs
+- **GitHub Wiki tab publishing** — `--wiki` flag generates a workflow that pushes generated pages directly to `<repo>.wiki.git`
 - **Configurable** — global config in `~/.wiki/`, project config in `.wiki/`
 - **GitHub Actions** — `--init` automatically creates a scheduled update workflow in your repo
 - **Repo instructions** — reads `AGENTS.md` or `CLAUDE.md` from the project root and follows all conventions documented there
-- **Change reports** — each run writes `.wiki/.last-update-report.md` with created/edited pages, used as the PR body in CI
-- **Self-invocation guard** — the agent cannot recursively invoke `wiki` or `wiki-agent` via shell commands
+- **Change reports** — each run writes `.wiki/.last-update-report.md` with created/edited pages, used as the staging PR body in CI
+- **Restricted toolset** — the agent can only read files, write under `.wiki/`, and run read-only git subcommands; there is no shell tool
 
 ## Quickstart
 
 ### 1. Install
 
-Build from source and install globally with bun:
+Install globally from npm:
 
 ```bash
-git clone https://github.com/nx-solutions-ug/wiki-agent.git
-cd wiki-agent
-npm install
-npx tsc -p tsconfig.json
-bun pm pack
-cd ~/.bun/install/global && bun add /path/to/wiki-agent/wiki-agent-0.1.0.tgz
+npm install -g @chronova/wiki-agent
+```
+
+Or with bun:
+
+```bash
+bun add -g @chronova/wiki-agent
 ```
 
 Verify the install:
@@ -52,12 +57,21 @@ This launches the TUI where you select Ollama Local or Cloud and enter your API
 # Initialize documentation (also creates .github/workflows/update-wiki.yml)
 wiki --init
 
+# Initialize and publish to the GitHub Wiki tab
+wiki --init --wiki
+
 # Update existing documentation
 wiki --update
 
+# Update and publish to the GitHub Wiki tab
+wiki --update --wiki
+
 # Headless mode (for CI)
 wiki --update --print
 
+# Headless mode with wiki tab publishing
+wiki --update --print --wiki
+
 # Specify a model override
 wiki --init --print --model llama3.2
 ```
@@ -109,21 +123,20 @@ Environment variables take priority over config files.
 
 ## GitHub Actions
 
-Running `wiki --init` automatically creates `.github/workflows/update-wiki.yml` in your repo. The workflow publishes generated pages to your repository's **GitHub Wiki tab**, not to the main repo's file tree:
+Running `wiki --init --wiki` automatically creates `.github/workflows/update-wiki.yml` in your repo. With `--wiki`, the workflow publishes generated pages to your repository's **GitHub Wiki tab**; without `--wiki` it only stages `.wiki/` and opens a staging PR.
 
 1. Generates a GitHub App token if `APP_CLIENT_ID` and `APP_PRIVATE_KEY` secrets are set (falls back to `GITHUB_TOKEN`)
 2. Checks out your repo, clones and builds wiki-agent from `nx-solutions-ug/wiki-agent`
-3. Runs `wiki --update --print` with your Ollama Cloud credentials, staging pages under `.wiki/`
+3. Runs `wiki --update --print --verbose` (with `--wiki` if the flag was passed at `--init` time), staging pages under `.wiki/`
 4. Probes the wiki remote (`<repo>.wiki.git`) with `git ls-remote` to detect whether the wiki has been initialized
-5. If there are content changes and the wiki is initialized: clones `<repo>.wiki.git`, syncs the `.wiki/` content (excluding `config.json`, `.last-update-report.md`, `.last-updated.json`) via `rsync`, commits on a `wiki/update-<timestamp>` branch, and pushes
-6. Opens a pull request against the wiki repo (`--repo <owner>/<repo>.wiki`, base `master`) with `.wiki/.last-update-report.md` as the body — a human merges to make updates live
-7. Always opens a `docs: wiki staging snapshot` pull request against the main repo with the `.wiki/` changes, so the staged content stays auditable
+5. If there are content changes and the wiki is initialized: clones `<repo>.wiki.git`, syncs the staged `.wiki/` content (excluding `config.json` and the run metadata) via `rsync`, commits, and **pushes directly to `master`** — the wiki goes live immediately (no PR, no review gate)
+6. Always opens a `docs: wiki staging snapshot` pull request against the main repo with the `.wiki/` changes, so the staged content stays auditable
 
 ### Bootstrap the wiki first
 
 GitHub wikis must be initialized once through the UI before they can be pushed to programmatically. Open the **Wiki** tab in your repository, create the first page (any content), then run the workflow. Until then the publish step is skipped with a warning; the staging PR still opens so you can inspect the generated content.
 
-The full workflow is written to `.github/workflows/update-wiki.yml` by `wiki --init`. See that file (or the template in [`src/agent.ts`](src/agent.ts) `createWorkflowFile`) for the authoritative, current definition. The steps in brief: generate token → checkout → build wiki-agent → run `--update --print` → probe wiki remote → if there are content changes and the wiki is initialized, clone `<repo>.wiki.git`, `rsync` the staged `.wiki/` content (excluding `config.json` and the run metadata), commit on `wiki/update-<timestamp>`, push → open a PR against the wiki repo (base `master`) → open a `docs: wiki staging snapshot` PR against the main repo.
+The full workflow is written to `.github/workflows/update-wiki.yml` by `wiki --init`. See that file (or the template in [`src/agent.ts`](src/agent.ts) `createWorkflowFile`) for the authoritative, current definition.
 
 ### Required secrets
 
@@ -160,7 +173,7 @@ Each run produces:
 ```
 
 - `.last-updated.json` — `{ "lastUpdated": "2026-07-17T10:30:00.000Z" }`
-- `.last-update-report.md` — markdown report listing created and edited pages, used as the PR body in CI
+- `.last-update-report.md` — markdown report listing created and edited pages, used as the staging PR body in CI
 - `index.md` files — auto-generated for each directory, listing pages and subdirectories with frontmatter titles/descriptions
 
 ## Development
@@ -175,11 +188,12 @@ bun pm pack
 ## How it works
 
 1. The agent reads `AGENTS.md` or `CLAUDE.md` from the project root and follows all conventions documented there
-2. It inspects your source code using filesystem tools (read, grep, glob, execute)
-3. It generates wiki pages under `.wiki/` with YAML frontmatter
+2. It inspects your source code using a restricted, read-only toolset: `read_file`, `ls`, `glob`, `grep`, `ast_grep`, `ast_search`, and a read-only `git` tool (whitelisted subcommands only — no mutating git, no shell)
+3. It generates wiki pages under `.wiki/` with YAML frontmatter using `write_file` and `edit_file` (the only mutating tools, constrained to `.wiki/`)
 4. After the run, `index.md` files are synchronized for each directory
 5. `.last-updated.json` and `.last-update-report.md` are written
 6. On `--init`, a GitHub Actions workflow is created for scheduled updates
 7. In update mode, only pages affected by recent changes are refreshed
+8. With `--wiki`, the workflow also publishes to the GitHub Wiki tab by pushing directly to `<repo>.wiki.git` `master`
 
-The agent uses a manual tool-calling loop with the Ollama chat API — no LangChain or LangGraph dependency. The recursion limit prevents infinite loops. The `execute` tool blocks self-invocation to prevent recursive runs.
+The agent uses a manual tool-calling loop with the Ollama chat API — no LangChain or LangGraph dependency. The recursion limit prevents infinite loops. There is no general-purpose shell tool; the agent cannot execute arbitrary commands on the host system.

package/dist/agent.js

@@ -250,7 +250,7 @@ async function createWorkflowFile(projectRoot, wikiPublish) {
         "",
     ];
     if (wikiPublish) {
-        workflow.push("      - name: Repository coordinates", "        id: coords", "        run: echo \"owner_repo=${GITHUB_REPOSITORY}\" >> $GITHUB_OUTPUT", "", "      - name: Detect wiki initialization", "        id: wiki-init", "        env:", "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "        run: |", "          REMOTE=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"", "          if git ls-remote --exit-code \"$REMOTE\" HEAD >/dev/null 2>&1; then", "            echo \"initialized=true\" >> $GITHUB_OUTPUT", "          else", "            echo \"initialized=false\" >> $GITHUB_OUTPUT", "            echo \"::warning::Wiki is not initialized. Create the first page in the GitHub UI (Wiki tab -> New Page), then rerun. Staging PR will still be opened.\" >> $GITHUB_OUTPUT", "          fi", "", "      - name: Publish to wiki repo", "        id: publish", "        if: steps.report.outputs.has_changes == 'true' && steps.wiki-init.outputs.initialized == 'true'", "        env:", "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "        run: |", "          BRANCH=\"wiki/update-${{ steps.timestamp.outputs.timestamp }}\"", "          WIKI_URL=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"", "          rm -rf /tmp/wiki", "          git clone \"$WIKI_URL\" /tmp/wiki", "          cd /tmp/wiki", "          git checkout -b \"$BRANCH\"", "          # --exclude='.git' protects the wiki clone's .git directory from --delete.", "          rsync -a --delete \\", "            --exclude='.git' \\", "            --exclude='.last-update-report.md' \\", "            --exclude='.last-updated.json' \\", "            --exclude='config.json' \\", "            \"$GITHUB_WORKSPACE/.wiki/\" ./", "          git add -A", "          if ! git diff --cached --quiet; then", "            git -c user.name='wiki-agent[bot]' -c user.email='bot@wiki-agent' \\", "              commit -m \"docs: update wiki\"", "            if ! git push origin \"$BRANCH\" 2>&1 | tee /tmp/wiki-push.log; then", "              echo \"::error::Failed to push to the wiki repo. Ensure the GitHub App has contents:write on the repository (which covers the wiki), or set a WIKI_PUSH_TOKEN secret with repo scope.\"", "              exit 1", "            fi", "            echo \"branch=$BRANCH\" >> $GITHUB_OUTPUT", "          else", "            echo \"::warning::No net wiki content changes after sync; skipping wiki push.\"", "            echo \"branch=\" >> $GITHUB_OUTPUT", "          fi", "", "      - name: Open wiki update pull request", "        if: steps.report.outputs.has_changes == 'true' && steps.wiki-init.outputs.initialized == 'true' && steps.publish.outputs.branch != ''", "        env:", "          GH_TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "        run: |", "          gh pr create --repo \"${{ steps.coords.outputs.owner_repo }}.wiki\" \\", "            --head \"wiki/update-${{ steps.timestamp.outputs.timestamp }}\" \\", "            --base master \\", "            --title \"docs: update wiki\" \\", "            --body-file .wiki/.last-update-report.md", "");
+        workflow.push("      - name: Repository coordinates", "        id: coords", "        run: echo \"owner_repo=${GITHUB_REPOSITORY}\" >> $GITHUB_OUTPUT", "", "      - name: Detect wiki initialization", "        id: wiki-init", "        env:", "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "        run: |", "          REMOTE=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"", "          if git ls-remote --exit-code \"$REMOTE\" HEAD >/dev/null 2>&1; then", "            echo \"initialized=true\" >> $GITHUB_OUTPUT", "          else", "            echo \"initialized=false\" >> $GITHUB_OUTPUT", "            echo \"::warning::Wiki is not initialized. Create the first page in the GitHub UI (Wiki tab -> New Page), then rerun. Staging PR will still be opened.\" >> $GITHUB_OUTPUT", "          fi", "", "      - name: Publish to wiki repo", "        id: publish", "        if: steps.report.outputs.has_changes == 'true' && steps.wiki-init.outputs.initialized == 'true'", "        env:", "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "        run: |", "          WIKI_URL=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"", "          rm -rf /tmp/wiki /tmp/wiki-flat", "          node /tmp/wiki-agent/dist/flatten-wiki.js \"$GITHUB_WORKSPACE/.wiki\" /tmp/wiki-flat", "          git clone \"$WIKI_URL\" /tmp/wiki", "          cd /tmp/wiki", "          # rsync the flattened wiki output (flat names, Home.md, _Sidebar.md).", "          # --exclude='.git' protects the wiki clone's .git directory from --delete.", "          rsync -a --delete \\", "            --exclude='.git' \\", "            /tmp/wiki-flat/ ./", "          git add -A", "          if ! git diff --cached --quiet; then", "            git -c user.name='wiki-agent[bot]' -c user.email='bot@wiki-agent' \\", "              commit -m \"docs: update wiki\"", "            if ! git push origin master 2>&1 | tee /tmp/wiki-push.log; then", "              echo \"::error::Failed to push to the wiki repo. Ensure the GitHub App has contents:write on the repository (which covers the wiki), or set a WIKI_PUSH_TOKEN secret with repo scope.\"", "              exit 1", "            fi", "            echo \"published=true\" >> $GITHUB_OUTPUT", "          else", "            echo \"::warning::No net wiki content changes after sync; skipping wiki push.\"", "            echo \"published=false\" >> $GITHUB_OUTPUT", "          fi");
     }
     workflow.push("      - name: Create wiki staging snapshot pull request", "        uses: peter-evans/create-pull-request@v8", "        if: steps.report.outputs.has_changes == 'true'", "        with:", "          token: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}", "          branch: wiki/staging-${{ steps.timestamp.outputs.timestamp }}", "          add-paths: .wiki", '          title: "docs: wiki staging snapshot"', '          body: ${{ steps.report.outputs.body }}');
     await writeFile(workflowPath, workflow.join("\n") + "\n", "utf8");

package/dist/flatten-wiki.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Flattens the nested .wiki/ directory structure into a flat set of
+ * GitHub Wiki-compatible files in the output directory.
+ *
+ * Conversion rules:
+ * - .wiki/index.md                  → Home.md (the wiki landing page)
+ * - .wiki/quickstart.md             → Quickstart.md
+ * - .wiki/architecture/index.md     → Architecture.md
+ * - .wiki/architecture/overview.md  → Architecture-Overview.md
+ * - .wiki/cli/usage.md               → CLI-Usage.md
+ * - Internal markdown links are rewritten from relative .md paths to flat
+ *   wiki page names (e.g. [Text](./cli/usage.md) → [Text](CLI-Usage))
+ * - _Sidebar.md is generated for navigation
+ * - Metadata files (.last-update-report.md, .last-updated.json, config.json, _plan.md) are excluded
+ *
+ * @param wikiRoot - path to the .wiki/ directory (source)
+ * @param outputDir - path to the output directory (will be created/cleaned)
+ */
+export declare function flattenWiki(wikiRoot: string, outputDir: string): Promise<void>;

package/dist/flatten-wiki.js

@@ -0,0 +1,227 @@
+import { readFile, writeFile, mkdir, rm, readdir } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Characters forbidden in GitHub Wiki page filenames.
+ * The wiki title is derived from the filename, so these must be stripped/replaced.
+ */
+const FORBIDDEN_CHARS = /[\\/:*?"<>|]/g;
+/** Files excluded from the wiki publish (metadata, config, plan). */
+const EXCLUDED = new Set([
+    ".last-update-report.md",
+    ".last-updated.json",
+    "config.json",
+    "_plan.md",
+]);
+/**
+ * Converts a filename like "github-actions" or "overview" to a GitHub Wiki
+ * page name. Dash/underscore-separated words become PascalCase:
+ * "github-actions" → "GitHub-Actions", "overview" → "Overview",
+ * "index" → "Home" (for the root index only).
+ */
+function toWikiPageName(filename) {
+    return filename
+        .split(/[-_]/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("-");
+}
+/**
+ * Cleans a filename for GitHub Wiki: replaces forbidden characters and
+ * spaces with dashes, collapses repeated dashes.
+ */
+function cleanWikiFilename(name) {
+    return name
+        .replace(FORBIDDEN_CHARS, "-")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Computes the flat wiki filename for a source .wiki/ file given its
+ * relative path. Examples:
+ *   index.md                  → Home.md
+ *   quickstart.md             → Quickstart.md
+ *   architecture/index.md     → Architecture.md
+ *   architecture/overview.md → Architecture-Overview.md
+ *   cli/usage.md              → CLI-Usage.md
+ */
+function flatWikiFilename(relPath) {
+    const parts = relPath.split(path.sep);
+    const basename = parts[parts.length - 1].replace(/\.md$/, "");
+    if (basename === "index") {
+        if (parts.length === 1) {
+            return "Home.md";
+        }
+        return `${toWikiPageName(parts[parts.length - 2])}.md`;
+    }
+    const nameParts = parts.slice(0, -1).map((p) => toWikiPageName(p));
+    nameParts.push(toWikiPageName(basename));
+    return `${cleanWikiFilename(nameParts.join("-"))}.md`;
+}
+/**
+ * Extracts the title from YAML frontmatter, falling back to the wiki name.
+ */
+function extractTitle(content, wikiName) {
+    const fmMatch = content.match(/^---\n[\s\S]*?title:\s*(.+?)\n[\s\S]*?---/);
+    if (fmMatch) {
+        return fmMatch[1].trim().replace(/['"]/g, "");
+    }
+    return wikiName.replace(/-/g, " ");
+}
+/**
+ * Recursively walks the source .wiki/ directory and collects all .md files
+ * with their relative paths, excluding metadata and config files.
+ */
+async function collectMarkdownFiles(srcDir, baseDir) {
+    const results = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absPath = path.join(dir, entry.name);
+            const relPath = path.relative(baseDir, absPath);
+            if (entry.isDirectory()) {
+                await walk(absPath);
+            }
+            else if (entry.name.endsWith(".md") && !EXCLUDED.has(entry.name)) {
+                results.push({ relPath, absPath });
+            }
+        }
+    }
+    await walk(srcDir);
+    return results;
+}
+/**
+ * Rewrites internal markdown links from the nested .wiki/ structure to
+ * flat wiki-page links. Uses a map of source-relative paths → flat wiki
+ * names to correctly resolve links like `./cli/usage.md` → `CLI-Usage`
+ * (not just `Usage`). Directory links like `./architecture/` resolve to
+ * the section's index page (`Architecture`). Anchor fragments are preserved.
+ *
+ * @param content - the markdown file content
+ * @param sourceRelDir - the directory of the source file, relative to .wiki/ (e.g. "cli", "")
+ * @param pathMap - map of source-relative .md paths (without ./ prefix) → flat wiki names
+ */
+function rewriteLinks(content, sourceRelDir, pathMap) {
+    return content.replace(/\[([^\]]*)\]\(([^)]+)\)/g, (match, text, url) => {
+        // Only rewrite internal .md links or directory links (not http URLs)
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            return match;
+        }
+        // Split off anchor fragment
+        const hashIdx = url.indexOf("#");
+        const anchor = hashIdx >= 0 ? url.slice(hashIdx) : "";
+        const linkPath = hashIdx >= 0 ? url.slice(0, hashIdx) : url;
+        // Resolve the link relative to the source file's directory
+        const resolved = path
+            .normalize(path.join(sourceRelDir, linkPath))
+            .replace(/^\.\//, "");
+        // Look up in the path map
+        const wikiName = pathMap.get(resolved);
+        if (wikiName) {
+            return `[${text}](${wikiName}${anchor})`;
+        }
+        // Handle directory links (e.g. ./architecture/ → architecture/index.md)
+        if (!linkPath.endsWith(".md")) {
+            const dirIndex = pathMap.get(`${resolved}/index.md`);
+            if (dirIndex) {
+                return `[${text}](${dirIndex}${anchor})`;
+            }
+            const dirIndexNoSlash = pathMap.get(`${resolved.replace(/\/$/, "")}/index.md`);
+            if (dirIndexNoSlash) {
+                return `[${text}](${dirIndexNoSlash}${anchor})`;
+            }
+        }
+        // Leave unresolvable links as-is
+        return match;
+    });
+}
+/**
+ * Generates the _Sidebar.md content from the collected pages, grouped by
+ * their original top-level directory (or "Guides" for root-level pages).
+ */
+function generateSidebar(pages) {
+    const sections = new Map();
+    for (const page of pages) {
+        const parts = page.relPath.split(path.sep);
+        const section = parts.length > 1 ? parts[0] : "Guides";
+        const key = toWikiPageName(section);
+        if (!sections.has(key)) {
+            sections.set(key, []);
+        }
+        sections.get(key).push({ wikiName: page.wikiName, title: page.title });
+    }
+    const lines = ["# Navigation", "", "- [Home](Home)", ""];
+    for (const [sectionName, sectionPages] of sections) {
+        lines.push(`## ${sectionName}`, "");
+        for (const page of sectionPages) {
+            if (page.wikiName === "Home")
+                continue;
+            lines.push(`- [${page.title}](${page.wikiName})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Flattens the nested .wiki/ directory structure into a flat set of
+ * GitHub Wiki-compatible files in the output directory.
+ *
+ * Conversion rules:
+ * - .wiki/index.md                  → Home.md (the wiki landing page)
+ * - .wiki/quickstart.md             → Quickstart.md
+ * - .wiki/architecture/index.md     → Architecture.md
+ * - .wiki/architecture/overview.md  → Architecture-Overview.md
+ * - .wiki/cli/usage.md               → CLI-Usage.md
+ * - Internal markdown links are rewritten from relative .md paths to flat
+ *   wiki page names (e.g. [Text](./cli/usage.md) → [Text](CLI-Usage))
+ * - _Sidebar.md is generated for navigation
+ * - Metadata files (.last-update-report.md, .last-updated.json, config.json, _plan.md) are excluded
+ *
+ * @param wikiRoot - path to the .wiki/ directory (source)
+ * @param outputDir - path to the output directory (will be created/cleaned)
+ */
+export async function flattenWiki(wikiRoot, outputDir) {
+    // Clean and create output dir
+    await rm(outputDir, { recursive: true, force: true });
+    await mkdir(outputDir, { recursive: true });
+    // Collect all markdown files
+    const files = await collectMarkdownFiles(wikiRoot, wikiRoot);
+    // Build a path map: source-relative path → flat wiki name
+    // e.g. "cli/usage.md" → "CLI-Usage", "index.md" → "Home"
+    const pathMap = new Map();
+    for (const file of files) {
+        const flatName = flatWikiFilename(file.relPath).replace(/\.md$/, "");
+        pathMap.set(file.relPath, flatName);
+    }
+    const pageInfos = [];
+    for (const file of files) {
+        const content = await readFile(file.absPath, "utf8");
+        const flatFile = flatWikiFilename(file.relPath);
+        const wikiName = flatFile.replace(/\.md$/, "");
+        // Determine the source file's directory relative to .wiki/
+        const sourceRelDir = path.dirname(file.relPath) === "." ? "" : path.dirname(file.relPath);
+        // Rewrite links
+        const rewritten = rewriteLinks(content, sourceRelDir, pathMap);
+        // Extract title for sidebar
+        const title = extractTitle(content, wikiName);
+        pageInfos.push({ relPath: file.relPath, wikiName, title });
+        // Write the file
+        await writeFile(path.join(outputDir, flatFile), rewritten, "utf8");
+    }
+    // Generate _Sidebar.md
+    const sidebar = generateSidebar(pageInfos);
+    await writeFile(path.join(outputDir, "_Sidebar.md"), sidebar, "utf8");
+}
+// CLI entrypoint: node dist/flatten-wiki.js <wiki-root> <output-dir>
+if (process.argv[1] && process.argv[1].endsWith("flatten-wiki.js")) {
+    const [wikiRoot, outputDir] = process.argv.slice(2);
+    if (!wikiRoot || !outputDir) {
+        console.error("Usage: node flatten-wiki.js <wiki-root> <output-dir>");
+        process.exit(1);
+    }
+    flattenWiki(wikiRoot, outputDir)
+        .then(() => console.log(`Flattened ${wikiRoot} to ${outputDir}/`))
+        .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/prompt.js

@@ -39,7 +39,14 @@ You cannot run build tools, package managers, test runners, scripts, or any prog
 
 # Output location
 - Write documentation under .wiki/ in the project root. Use paths such as .wiki/quickstart.md, .wiki/architecture/overview.md, .wiki/cli/usage.md.
-- Your output is published to the repository's GitHub Wiki tab after the run. Wiki page titles come from filenames, so never use the characters \ / : * ? " < > | in wiki file names.
+- Your output is published to the repository's GitHub Wiki tab after the run. A conversion step flattens the nested .wiki/ directory structure into the flat format GitHub Wikis require:
+  - .wiki/index.md becomes Home.md (the wiki landing page)
+  - .wiki/architecture/index.md becomes Architecture.md (section landing page)
+  - .wiki/architecture/overview.md becomes Architecture-Overview.md (dash-joined flat name)
+  - .wiki/cli/usage.md becomes CLI-Usage.md
+  - A _Sidebar.md navigation file is generated automatically from the page structure
+  - Internal markdown links (e.g. [Text](./architecture/overview.md)) are rewritten to flat wiki page names (e.g. [Text](Architecture-Overview))
+- Keep using nested directory paths and relative .md links in your source files — the conversion step handles the flattening. Never use the characters \ / : * ? " < > | in wiki file names.
 - Never write markdown files outside .wiki/.
 - Each wiki page must start with YAML frontmatter:
   ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronova/wiki-agent",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Standalone Ollama-only documentation agent",
   "type": "module",
   "bin": {