@chappibunny/repolens 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,13 +2,75 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.2.0
+
+### ✨ Config Migration
+
+- **`repolens migrate` now patches `.repolens.yml`**: Automatically adds `configVersion: 1` to legacy config files that are missing it. Creates a `.repolens.yml.backup` before modifying. Supports both `.yml` and `.yaml` extensions, dry-run mode, and graceful handling of parse errors or missing configs.
+
+### � Bug Fixes
+
+- **GitHub Wiki empty pages**: Fixed branch mismatch where `git init` created a `main` branch but GitHub Wiki serves from `master`. Now explicitly initializes with `master` and pushes to `refs/heads/master`. Also added content validation to skip pages with empty content.
+
+### �📝 Documentation
+
+- Updated all documentation to reflect v1.2.0 version references
+- Updated TROUBLESHOOTING.md with `migrate` auto-fix hint for missing `configVersion`
+- Updated KNOWN_ISSUES.md planned improvements (removed shipped features)
+- Updated ROADMAP.md with v1.1.0 shipped items
+
+## 1.1.0
+
+### ✨ GitHub Wiki Publisher UX Enhancement
+
+Major upgrade to the wiki output quality — better information hierarchy, audience-aware navigation, and richer page structure.
+
+- **Audience-grouped Home page**: Pages organized by reader (Stakeholders, Engineers, New Contributors, Change Tracking) instead of a flat list
+- **Page descriptions**: Each link on Home includes a one-line summary of the page's purpose
+- **Status rail**: Home page now shows a metadata table (project, branch, page count, publisher, source)
+- **Recommended reading order**: Guided path through the docs for first-time readers
+- **Grouped sidebar**: Navigation split into Overview and Architecture sections (plus Custom Pages)
+- **Page metadata headers**: Every page gets a `[← Home](Home)` back-link, audience tag, and branch indicator
+- **Cleaner footer**: Compact format with branch context and Home link
+- **New constants**: `PAGE_DESCRIPTIONS`, `AUDIENCE_GROUPS`, `SIDEBAR_GROUPS`, `PAGE_AUDIENCE`
+- **New helpers**: `getPageDisplayTitle()`, `getCustomPageKeys()`, `wikiLink()`, `pageHeader()`
+
+### 🐛 Bug Fixes
+- **Temperature still sent to GPT-5**: `DEFAULT_TEMPERATURE = 0.2` always leaked into API requests even after v1.0.1 fixes — the fallback chain (`temperature ?? aiConfig.temperature ?? DEFAULT_TEMPERATURE`) guaranteed it was never `undefined`. Removed the default entirely; temperature is now only sent when explicitly configured via `REPOLENS_AI_TEMPERATURE` env var or `ai.temperature` in config.
+
+## 1.0.1
+
+### 🐛 Bug Fixes
+- **GPT-5 API compatibility**: Use `max_completion_tokens` instead of deprecated `max_tokens` parameter
+- **GPT-5 temperature handling**: Omit `temperature` from API requests for models that only support the default value (e.g. gpt-5-mini)
+- Removed all hardcoded `temperature: 0.2` overrides from AI section generators
+- Removed `REPOLENS_AI_TEMPERATURE` from CI workflow and `.env.example`
+- Updated `init` scaffolding to omit temperature from default config
+
+### 🔧 Improvements
+- Upgraded GitHub Actions: checkout v4.2.2, setup-node v4.2.0, Node.js 22
+
 ## 1.0.0
 
 ### 🎉 Stable Release
 
 RepoLens v1.0.0 marks the first stable release with a frozen public API. All CLI commands, configuration schema, and plugin interfaces are now covered by semantic versioning guarantees. See [STABILITY.md](STABILITY.md) for the full contract.
 
+### ✨ New Features
+- **GitHub Wiki Publisher**: Publish documentation directly to your repository's Wiki tab
+  - Git-based: clones wiki repo, writes pages, commits and pushes
+  - Generates `Home.md` index, `_Sidebar.md` navigation, `_Footer.md`
+  - Branch filtering via `github_wiki.branches` in `.repolens.yml`
+  - Auto-detects repository from `GITHUB_REPOSITORY` env or git remote
+  - Token sanitization in error messages (never leaks `GITHUB_TOKEN`)
+  - Config: `sidebar` and `footer` toggles
+  - 17 tests covering publishing, branch filtering, config validation, and security
+
 ### 🐛 Bug Fixes
+- **GPT-5 API compatibility**: Use `max_completion_tokens` instead of deprecated `max_tokens` parameter
+- **GPT-5 temperature handling**: Omit `temperature` from API requests for models that only support the default value (e.g. gpt-5-mini)
+- **Git identity in wiki publisher**: Set committer name/email (`RepoLens Bot`) so CI runners can commit
+- **Publisher allowlist**: Added `github_wiki` to `validate.js` publisher validation (was only in `config-schema.js`)
 - **Doctor false-success**: `repolens doctor` now correctly exits with code 2 when `runDoctor()` reports failures (previously always printed "validation passed")
 - **Feedback exit code**: `repolens feedback` now exits with code 1 when feedback fails to send (previously exited 0)
 - **Unknown flags**: `repolens --unknown-flag` now prints an error instead of silently running publish

package/README.md

@@ -16,7 +16,7 @@
 
 AI-assisted documentation intelligence system that generates architecture docs for engineers AND readable system docs for stakeholders
 
-**Current Status**: v1.0.0 — Stable Release
+**Current Status**: v1.2.0 — Stable Release
 
 RepoLens automatically generates and maintains living architecture documentation by analyzing your repository structure, extracting meaningful insights from your package.json, and creating visual dependency graphs. Run it once, or let it auto-update on every push.
 
@@ -124,7 +124,7 @@ RepoLens automatically detects:
 ✅ **Deterministic Fallback** - Always generates docs even if AI unavailable  
 ✅ **Business Domain Inference** - Automatically maps code to business functions  
 ✅ **Data Flow Analysis** - Understands how information moves through your system  
-✅ **Multiple Publishers** - Output to Notion, Confluence, Markdown, or all three  
+✅ **Multiple Publishers** - Output to Notion, Confluence, GitHub Wiki, Markdown, or all four  
 ✅ **Branch-Aware** - Prevent doc conflicts across branches  
 ✅ **GitHub Actions** - Autonomous operation on every push  
 ✅ **Team Notifications** - Discord integration with rich embeds (NEW in v0.6.0)  
@@ -230,10 +230,12 @@ npm link
 Install from a specific version:
 
 ```bash
-npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v1.0.0/chappibunny-repolens-1.0.0.tgz
+npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v1.2.0/chappibunny-repolens-1.2.0.tgz
 ```
 </details>
 
+> **Having install problems?** See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for solutions to common issues like `ENOTEMPTY`, `npm ci` failures, and stale versions.
+
 ---
 
 ## 🎓 Complete Onboarding Guide
@@ -313,6 +315,14 @@ publishers:
 ```
 Maximum visibility: Notion for async collaboration, Confluence for enterprise docs, Markdown for local backups.
 
+**GitHub Wiki** (ideal for open source):
+```yaml
+publishers:
+  - github_wiki
+  - markdown
+```
+Docs live alongside your code — accessible from the repo's Wiki tab. Requires `GITHUB_TOKEN`.
+
 ### Step 3: Enable AI Features (Optional)
 
 **AI-enhanced documentation adds natural language explanations for non-technical audiences.**
@@ -336,7 +346,6 @@ REPOLENS_AI_API_KEY=sk-xxxxxxxxxxxxx
 # Optional: Customize provider
 REPOLENS_AI_BASE_URL=https://api.openai.com/v1
 REPOLENS_AI_MODEL=gpt-5-mini
-REPOLENS_AI_TEMPERATURE=0.3
 REPOLENS_AI_MAX_TOKENS=2000
 ```
 
@@ -346,7 +355,6 @@ REPOLENS_AI_MAX_TOKENS=2000
 ai:
   enabled: true              # Enable AI features
   mode: hybrid               # hybrid, full, or off
-  temperature: 0.3           # Lower = more focused (0.0-1.0)
   max_tokens: 2000           # Token limit per request
 
 features:
@@ -944,11 +952,14 @@ features:
 | `configVersion` | number | **Yes** | Schema version (must be `1`) |
 | `project.name` | string | Yes | Project name |
 | `project.docs_title_prefix` | string | No | Prefix for documentation titles (default: project name) |
-| `publishers` | array | Yes | Output targets: `notion`, `confluence`, `markdown` (+ plugin publishers) |
+| `publishers` | array | Yes | Output targets: `notion`, `confluence`, `github_wiki`, `markdown` (+ plugin publishers) |
 | `plugins` | array | No | Plugin paths or npm package names |
 | `notion.branches` | array | No | Branch whitelist for Notion publishing. Supports globs. |
 | `notion.includeBranchInTitle` | boolean | No | Add `[branch-name]` to titles (default: `true`) |
 | `confluence.branches` | array | No | Branch whitelist for Confluence publishing. Supports globs. |
+| `github_wiki.branches` | array | No | Branch whitelist for GitHub Wiki publishing. Supports globs. |
+| `github_wiki.sidebar` | boolean | No | Generate `_Sidebar.md` navigation (default: `true`) |
+| `github_wiki.footer` | boolean | No | Generate `_Footer.md` (default: `true`) |
 | `discord.enabled` | boolean | No | Enable Discord notifications (default: `true` if webhook set) |
 | `discord.notifyOn` | string | No | Notification policy: `always`, `significant`, `never` (default: `significant`) |
 | `discord.significantThreshold` | number | No | Change % threshold for notifications (default: `10`) |
@@ -962,8 +973,8 @@ features:
 | `features` | object | No | Feature flags (boolean values) |
 | `ai.enabled` | boolean | No | Enable AI-powered documentation |
 | `ai.mode` | string | No | AI mode: `hybrid`, `full`, or `off` |
-| `ai.temperature` | number | No | Generation temperature (0\u20132) |
-| `ai.max_tokens` | number | No | Max tokens per request (>0) |
+| `ai.temperature` | number | No | Generation temperature (0–2). Not supported by all models (e.g. gpt-5-mini ignores it) |
+| `ai.max_tokens` | number | No | Max completion tokens per request (>0) |
 
 ---
 
@@ -993,6 +1004,13 @@ Optional for Discord notifications:
 |----------|----------|-------------|
 | `DISCORD_WEBHOOK_URL` | No | Discord webhook URL for team notifications |
 
+Required for GitHub Wiki publisher:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITHUB_TOKEN` | Yes | Personal access token or Actions `${{ secrets.GITHUB_TOKEN }}` |
+| `GITHUB_REPOSITORY` | No | `owner/repo` (auto-detected from git remote in Actions) |
+
 **Local Development:** Create `.env` file in project root  
 **GitHub Actions:** Add as repository secrets in Settings → Secrets and variables → Actions
 
@@ -1077,7 +1095,7 @@ npm test
 - Integration workflows
 - Doctor command validation
 
-**Coverage:** 163 tests passing across 14 test files
+**Coverage:** 180 tests passing across 15 test files
 
 ### Test Package Installation Locally
 
@@ -1088,7 +1106,7 @@ Simulates the full user installation experience:
 npm pack
 
 # Install globally from tarball
-npm install -g chappibunny-repolens-1.0.0.tgz
+npm install -g chappibunny-repolens-1.2.0.tgz
 
 # Verify
 repolens --version
@@ -1137,6 +1155,7 @@ repolens/
 │   │   ├── publish.js       # Publishing pipeline
 │   │   ├── notion.js        # Notion API integration
 │   │   ├── confluence.js    # Confluence REST API integration
+│   │   ├── github-wiki.js   # GitHub Wiki publisher (git-based)
 │   │   └── markdown.js      # Local Markdown generation
 │   ├── integrations/
 │   │   └── discord.js       # Discord webhook notifications
@@ -1156,7 +1175,7 @@ repolens/
 │       ├── telemetry.js     # Opt-in error tracking + performance timers
 │       ├── errors.js        # Enhanced error messages with guidance
 │       └── update-check.js  # Version update notifications
-├── tests/                   # Vitest test suite (163 tests across 14 files)
+├── tests/                   # Vitest test suite (180 tests across 15 files)
 ├── .repolens.yml            # Dogfooding config
 ├── package.json
 ├── CHANGELOG.md
@@ -1211,14 +1230,14 @@ See [RELEASE.md](./RELEASE.md) for detailed workflow.
 
 ## 🗺️ Roadmap
 
-**Current Status:** v1.0.0 — Stable Release
+**Current Status:** v1.2.0 — Stable Release
 
 ### v1.0 — Complete ✅
 
 - [x] CLI commands: `init`, `doctor`, `publish`, `migrate`, `watch`, `feedback`, `version`, `help`
 - [x] Config schema v1 with validation (frozen)
 - [x] Auto-discovery of `.repolens.yml`
-- [x] Publishers: Notion + Confluence + Markdown
+- [x] Publishers: Notion + Confluence + GitHub Wiki + Markdown
 - [x] Branch-aware publishing with filtering
 - [x] Smart tech stack detection from package.json
 - [x] Unicode dependency diagrams (no external deps)
@@ -1227,7 +1246,7 @@ See [RELEASE.md](./RELEASE.md) for detailed workflow.
 - [x] GitHub Actions automation (publish + release)
 - [x] PR architecture diff comments
 - [x] Performance guardrails (10k warning, 50k limit)
-- [x] Comprehensive test suite (163 tests across 14 files)
+- [x] Comprehensive test suite (180 tests across 15 files)
 - [x] Security hardening (secret detection, injection prevention, fuzzing)
 - [x] Discord notifications with rich embeds
 - [x] Documentation coverage & health scoring
@@ -1250,7 +1269,7 @@ See [RELEASE.md](./RELEASE.md) for detailed workflow.
 
 ### Future
 
-- [ ] Additional publishers (GitHub Wiki, Obsidian)
+- [ ] Additional publishers (Obsidian)
 - [ ] VS Code extension
 - [ ] GitHub App
 
@@ -1266,6 +1285,8 @@ MIT
 
 ## 💬 Support & Contact
 
+- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — installation, config, publishing, AI, and CI/CD issues
+- **Diagnostics**: Run `npx @chappibunny/repolens doctor` to validate your setup
 - **Issues**: [GitHub Issues](https://github.com/CHAPIBUNNY/repolens/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/CHAPIBUNNY/repolens/discussions)
 - **Email**: Contact repository maintainers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/ai/generate-sections.js

@@ -25,7 +25,6 @@ export async function generateExecutiveSummary(context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createExecutiveSummaryPrompt(context),
-    temperature: 0.2,
     maxTokens: 1500
   });
   
@@ -47,7 +46,6 @@ export async function generateSystemOverview(context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createSystemOverviewPrompt(context),
-    temperature: 0.2,
     maxTokens: 1200
   });
   
@@ -68,7 +66,6 @@ export async function generateBusinessDomains(context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createBusinessDomainsPrompt(context),
-    temperature: 0.2,
     maxTokens: 2000
   });
   
@@ -89,7 +86,6 @@ export async function generateArchitectureOverview(context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createArchitectureOverviewPrompt(context),
-    temperature: 0.2,
     maxTokens: 1800
   });
   
@@ -110,7 +106,6 @@ export async function generateDataFlows(flows, context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createDataFlowsPrompt(flows, context),
-    temperature: 0.2,
     maxTokens: 1800
   });
   
@@ -131,7 +126,6 @@ export async function generateDeveloperOnboarding(context) {
   const result = await generateText({
     system: SYSTEM_PROMPT,
     user: createDeveloperOnboardingPrompt(context),
-    temperature: 0.2,
     maxTokens: 2200
   });
   

package/src/ai/provider.js

@@ -4,7 +4,6 @@ import { warn, info } from "../utils/logger.js";
 import { executeAIRequest } from "../utils/rate-limit.js";
 
 const DEFAULT_TIMEOUT_MS = 60000;
-const DEFAULT_TEMPERATURE = 0.2;
 const DEFAULT_MAX_TOKENS = 2500;
 
 export async function generateText({ system, user, temperature, maxTokens, config }) {
@@ -27,8 +26,8 @@ export async function generateText({ system, user, temperature, maxTokens, confi
   const model = process.env.REPOLENS_AI_MODEL || "gpt-5-mini";
   const timeoutMs = parseInt(process.env.REPOLENS_AI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
   
-  // Use config values as fallback for temperature/maxTokens
-  const resolvedTemp = temperature ?? aiConfig.temperature ?? DEFAULT_TEMPERATURE;
+  // Use config values as fallback for maxTokens; temperature only when explicitly set
+  const resolvedTemp = temperature ?? aiConfig.temperature ?? undefined;
   const resolvedMaxTokens = maxTokens ?? aiConfig.max_tokens ?? DEFAULT_MAX_TOKENS;
   
   // Validate configuration
@@ -81,21 +80,28 @@ async function callOpenAICompatibleAPI({ baseUrl, apiKey, model, system, user, t
     const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     
     try {
+      // Build request body — omit temperature if not supported by model
+      const body = {
+        model,
+        messages: [
+          { role: "system", content: system },
+          { role: "user", content: user }
+        ],
+        max_completion_tokens: maxTokens
+      };
+      // Only send temperature when explicitly configured — some models
+      // (e.g. gpt-5-mini) reject any non-default value
+      if (temperature != null) {
+        body.temperature = temperature;
+      }
+
       const response = await fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "Authorization": `Bearer ${apiKey}`
         },
-        body: JSON.stringify({
-          model,
-          messages: [
-            { role: "system", content: system },
-            { role: "user", content: user }
-          ],
-          temperature,
-          max_tokens: maxTokens
-        }),
+        body: JSON.stringify(body),
         signal: controller.signal
       });
       
@@ -136,7 +142,7 @@ export function getAIConfig() {
     provider: process.env.REPOLENS_AI_PROVIDER || "openai_compatible",
     model: process.env.REPOLENS_AI_MODEL || "gpt-5-mini",
     hasApiKey: !!process.env.REPOLENS_AI_API_KEY,
-    temperature: parseFloat(process.env.REPOLENS_AI_TEMPERATURE || DEFAULT_TEMPERATURE),
+    temperature: process.env.REPOLENS_AI_TEMPERATURE ? parseFloat(process.env.REPOLENS_AI_TEMPERATURE) : undefined,
     maxTokens: parseInt(process.env.REPOLENS_AI_MAX_TOKENS || DEFAULT_MAX_TOKENS)
   };
 }

package/src/core/config-schema.js

@@ -8,7 +8,7 @@
  */
 
 const CURRENT_SCHEMA_VERSION = 1;
-const SUPPORTED_PUBLISHERS = ["notion", "markdown", "confluence"];
+const SUPPORTED_PUBLISHERS = ["notion", "markdown", "confluence", "github_wiki"];
 const SUPPORTED_PAGE_KEYS = [
   "system_overview",
   "module_catalog",
@@ -193,6 +193,31 @@ export function validateConfig(config) {
     }
   }
 
+  // Validate GitHub Wiki configuration (optional)
+  if (config.github_wiki !== undefined) {
+    if (typeof config.github_wiki !== "object" || Array.isArray(config.github_wiki)) {
+      errors.push("github_wiki must be an object");
+    } else {
+      if (config.github_wiki.branches !== undefined) {
+        if (!Array.isArray(config.github_wiki.branches)) {
+          errors.push("github_wiki.branches must be an array");
+        } else {
+          config.github_wiki.branches.forEach((branch, idx) => {
+            if (typeof branch !== "string") {
+              errors.push(`github_wiki.branches[${idx}] must be a string`);
+            }
+          });
+        }
+      }
+      if (config.github_wiki.sidebar !== undefined && typeof config.github_wiki.sidebar !== "boolean") {
+        errors.push("github_wiki.sidebar must be a boolean");
+      }
+      if (config.github_wiki.footer !== undefined && typeof config.github_wiki.footer !== "boolean") {
+        errors.push("github_wiki.footer must be a boolean");
+      }
+    }
+  }
+
   // Validate Discord configuration (optional)
   if (config.discord !== undefined) {
     if (typeof config.discord !== "object" || Array.isArray(config.discord)) {

package/src/init.js

@@ -105,7 +105,6 @@ CONFLUENCE_PARENT_PAGE_ID=
 # REPOLENS_AI_API_KEY=sk-...
 # REPOLENS_AI_BASE_URL=https://api.openai.com/v1
 # REPOLENS_AI_MODEL=gpt-5-mini
-# REPOLENS_AI_TEMPERATURE=0.3
 # REPOLENS_AI_MAX_TOKENS=2000
 `;
 
@@ -206,7 +205,6 @@ AI features add natural language explanations for non-technical stakeholders.
    ai:
      enabled: true
      mode: hybrid
-     temperature: 0.3
    
    features:
      executive_summary: true
@@ -607,7 +605,6 @@ function buildWizardConfig(answers) {
     lines.push(`ai:`);
     lines.push(`  enabled: true`);
     lines.push(`  mode: hybrid`);
-    lines.push(`  temperature: 0.3`);
     lines.push(``);
     lines.push(`features:`);
     lines.push(`  executive_summary: true`);

package/src/migrate.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import yaml from "js-yaml";
 import { info, warn, error as logError } from "./utils/logger.js";
 import { trackMigration } from "./utils/telemetry.js";
 
@@ -105,6 +106,78 @@ $2$3`
   return migrated;
 }
 
+/**
+ * Find .repolens.yml config file in the target directory
+ */
+async function findConfigFile(targetDir) {
+  const candidates = [".repolens.yml", ".repolens.yaml"];
+  for (const name of candidates) {
+    const filePath = path.join(targetDir, name);
+    try {
+      await fs.access(filePath);
+      return filePath;
+    } catch {
+      // not found, try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Migrate .repolens.yml config file — add configVersion: 1 if missing
+ * Returns { migrated: boolean, filePath: string|null }
+ */
+async function migrateConfigFile(targetDir, options = {}) {
+  const { dryRun = false } = options;
+
+  const configPath = await findConfigFile(targetDir);
+  if (!configPath) {
+    return { migrated: false, filePath: null, reason: "no-config" };
+  }
+
+  const filename = path.basename(configPath);
+  console.log(`\n📄 Checking config: ${filename}`);
+
+  const raw = await fs.readFile(configPath, "utf8");
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch {
+    warn(`   ⚠️  Could not parse ${filename} — skipping config migration`);
+    return { migrated: false, filePath: configPath, reason: "parse-error" };
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    warn(`   ⚠️  ${filename} is empty or not a mapping — skipping config migration`);
+    return { migrated: false, filePath: configPath, reason: "invalid-structure" };
+  }
+
+  if (parsed.configVersion != null) {
+    info("   ✅ configVersion already present");
+    return { migrated: false, filePath: configPath, reason: "already-present" };
+  }
+
+  info("   🔧 Missing configVersion — adding configVersion: 1");
+
+  // Prepend configVersion: 1 to preserve existing formatting
+  const migratedContent = `configVersion: 1\n${raw}`;
+
+  if (dryRun) {
+    info("   🔍 DRY RUN: No changes written");
+    return { migrated: true, filePath: configPath, reason: "dry-run" };
+  }
+
+  // Backup original
+  const backupPath = `${configPath}.backup`;
+  await fs.writeFile(backupPath, raw, "utf8");
+  info(`   💾 Backup saved: ${path.basename(backupPath)}`);
+
+  await fs.writeFile(configPath, migratedContent, "utf8");
+  info(`   ✅ Migrated: ${filename}`);
+
+  return { migrated: true, filePath: configPath, reason: "migrated" };
+}
+
 /**
  * Find all workflow files in .github/workflows
  */
@@ -170,18 +243,17 @@ export async function runMigrate(targetDir = process.cwd(), options = {}) {
     
     const workflowFiles = await findWorkflowFiles(targetDir);
 
+    let migratedCount = 0;
+    let skippedCount = 0;
+
     if (workflowFiles.length === 0) {
       warn("⚠️  No workflow files found in .github/workflows/");
       info("\n💡 If you haven't set up GitHub Actions yet:");
       info("   Run: repolens init");
-      return;
+    } else {
+      info(`   Found ${workflowFiles.length} workflow file(s)`);
     }
 
-    info(`   Found ${workflowFiles.length} workflow file(s)`);
-
-    let migratedCount = 0;
-    let skippedCount = 0;
-
     for (const workflowPath of workflowFiles) {
       const filename = path.basename(workflowPath);
       console.log(`\n📄 Checking: ${filename}`);
@@ -221,6 +293,16 @@ export async function runMigrate(targetDir = process.cwd(), options = {}) {
       migratedCount++;
     }
 
+    // === Config File Migration ===
+    const configResult = await migrateConfigFile(targetDir, { dryRun });
+    let configMigrated = false;
+    if (configResult.migrated) {
+      migratedCount++;
+      configMigrated = true;
+    } else if (configResult.reason === "no-config") {
+      info("\n📄 No .repolens.yml found — skipping config migration");
+    }
+
     // Summary
     console.log("\n" + "─".repeat(60));
     console.log("📊 Migration Summary:");
@@ -248,7 +330,7 @@ export async function runMigrate(targetDir = process.cwd(), options = {}) {
     trackMigration(migratedCount, skippedCount);
     
     // Return results for telemetry tracking
-    return { migratedCount, skippedCount };
+    return { migratedCount, skippedCount, configMigrated };
 
   } catch (err) {
     logError(`Migration failed: ${err.message}`);

package/src/publishers/github-wiki.js

@@ -0,0 +1,461 @@
+// GitHub Wiki Publisher for RepoLens
+//
+// Publishes rendered documentation to a GitHub repository's wiki.
+// The wiki is a separate git repo at {repo-url}.wiki.git.
+//
+// Environment Variables:
+// - GITHUB_TOKEN: Personal access token or Actions token (required)
+// - GITHUB_REPOSITORY: owner/repo (auto-set in Actions, or detected from git remote)
+//
+// Config (.repolens.yml):
+//   github_wiki:
+//     branches: [main]           # Optional branch filter
+//     sidebar: true              # Generate _Sidebar.md (default: true)
+//     footer: true               # Generate _Footer.md (default: true)
+
+import { execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { info, warn } from "../utils/logger.js";
+import { getCurrentBranch, getBranchQualifiedTitle, normalizeBranchName } from "../utils/branch.js";
+
+const PAGE_ORDER = [
+  "executive_summary",
+  "system_overview",
+  "business_domains",
+  "architecture_overview",
+  "module_catalog",
+  "route_map",
+  "api_surface",
+  "data_flows",
+  "change_impact",
+  "system_map",
+  "developer_onboarding",
+  "graphql_schema",
+  "type_graph",
+  "dependency_graph",
+  "architecture_drift",
+  "arch_diff",
+];
+
+const PAGE_TITLES = {
+  executive_summary: "Executive Summary",
+  system_overview: "System Overview",
+  business_domains: "Business Domains",
+  architecture_overview: "Architecture Overview",
+  module_catalog: "Module Catalog",
+  route_map: "Route Map",
+  api_surface: "API Surface",
+  data_flows: "Data Flows",
+  change_impact: "Change Impact",
+  system_map: "System Map",
+  developer_onboarding: "Developer Onboarding",
+  graphql_schema: "GraphQL Schema",
+  type_graph: "Type Graph",
+  dependency_graph: "Dependency Graph",
+  architecture_drift: "Architecture Drift",
+  arch_diff: "Architecture Diff",
+};
+
+const PAGE_DESCRIPTIONS = {
+  executive_summary: "High-level project summary for non-technical readers.",
+  system_overview: "Snapshot of stack, scale, structure, and detected capabilities.",
+  business_domains: "Functional areas inferred from the repository and business logic.",
+  architecture_overview: "Layered technical view of the system and its major components.",
+  module_catalog: "Structured inventory of modules, directories, and responsibilities.",
+  route_map: "Frontend routes and page structure detected across the application.",
+  api_surface: "Detected endpoints, handlers, methods, and API structure.",
+  data_flows: "How information moves through the system and its major pathways.",
+  change_impact: "Contextual architecture changes and likely downstream effects.",
+  system_map: "Visual map of system relationships and dependencies.",
+  developer_onboarding: "What a new engineer needs to understand the repository quickly.",
+  graphql_schema: "GraphQL types, operations, and schema structure.",
+  type_graph: "Type-level relationships and structural coupling across the codebase.",
+  dependency_graph: "Module and package dependency relationships.",
+  architecture_drift: "Detected drift between intended and current architecture patterns.",
+  arch_diff: "Architecture-level diff across branches or revisions.",
+};
+
+// Audience-based grouping for Home page
+const AUDIENCE_GROUPS = [
+  {
+    title: "For Stakeholders",
+    emoji: "📊",
+    keys: ["executive_summary", "business_domains", "data_flows"],
+  },
+  {
+    title: "For Engineers",
+    emoji: "🔧",
+    keys: [
+      "architecture_overview", "module_catalog", "api_surface",
+      "route_map", "system_map", "graphql_schema", "type_graph",
+      "dependency_graph", "architecture_drift",
+    ],
+  },
+  {
+    title: "For New Contributors",
+    emoji: "🚀",
+    keys: ["developer_onboarding", "system_overview"],
+  },
+  {
+    title: "Change Tracking",
+    emoji: "📋",
+    keys: ["change_impact", "arch_diff"],
+  },
+];
+
+// Sidebar grouping (compact navigation)
+const SIDEBAR_GROUPS = [
+  {
+    title: "Overview",
+    keys: [
+      "executive_summary", "system_overview", "business_domains",
+      "data_flows", "developer_onboarding",
+    ],
+  },
+  {
+    title: "Architecture",
+    keys: [
+      "architecture_overview", "module_catalog", "route_map",
+      "api_surface", "system_map", "graphql_schema", "type_graph",
+      "dependency_graph", "architecture_drift", "arch_diff", "change_impact",
+    ],
+  },
+];
+
+// Audience labels for page metadata headers
+const PAGE_AUDIENCE = {
+  executive_summary: "Stakeholders · Leadership",
+  system_overview: "All Audiences",
+  business_domains: "Stakeholders · Product",
+  architecture_overview: "Engineers · Tech Leads",
+  module_catalog: "Engineers",
+  route_map: "Engineers",
+  api_surface: "Engineers",
+  data_flows: "Stakeholders · Engineers",
+  change_impact: "Engineers · Tech Leads",
+  system_map: "All Audiences",
+  developer_onboarding: "New Contributors",
+  graphql_schema: "Engineers",
+  type_graph: "Engineers",
+  dependency_graph: "Engineers",
+  architecture_drift: "Engineers · Tech Leads",
+  arch_diff: "Engineers · Tech Leads",
+};
+
+/**
+ * Get the display title for a page key.
+ */
+function getPageDisplayTitle(key) {
+  return PAGE_TITLES[key] || key.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Get custom page keys not in the standard order.
+ */
+function getCustomPageKeys(pageKeys) {
+  return pageKeys.filter((key) => !PAGE_ORDER.includes(key));
+}
+
+/**
+ * Detect the GitHub repository (owner/repo) from environment or git remote.
+ */
+function detectGitHubRepo() {
+  if (process.env.GITHUB_REPOSITORY) {
+    return process.env.GITHUB_REPOSITORY;
+  }
+
+  try {
+    const remoteUrl = execSync("git remote get-url origin", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+
+    const httpsMatch = remoteUrl.match(/github\.com\/([^/]+\/[^/.]+)/);
+    if (httpsMatch) return httpsMatch[1];
+
+    const sshMatch = remoteUrl.match(/github\.com:([^/]+\/[^/.]+)/);
+    if (sshMatch) return sshMatch[1];
+  } catch {
+    // git command failed
+  }
+
+  return null;
+}
+
+/**
+ * Build the authenticated wiki clone URL.
+ */
+function buildWikiCloneUrl(repo, token) {
+  return `https://x-access-token:${token}@github.com/${repo}.wiki.git`;
+}
+
+/**
+ * Convert a page key to a wiki-safe filename.
+ */
+function pageFileName(key) {
+  const title = getPageDisplayTitle(key);
+  return title.replace(/\s+/g, "-") + ".md";
+}
+
+/**
+ * Build a wiki link for a page key.
+ */
+function wikiLink(key) {
+  const display = getPageDisplayTitle(key);
+  const slug = pageFileName(key).replace(/\.md$/, "");
+  return `[[${display}|${slug}]]`;
+}
+
+/**
+ * Generate the Home.md page — audience-grouped with descriptions and status.
+ */
+function generateHome(pageKeys, projectName, branch, repo) {
+  const title = getBranchQualifiedTitle(projectName + " Documentation", branch);
+  const lines = [
+    `# ${title}`,
+    "",
+    `> Architecture documentation for **${projectName}**, auto-generated by [RepoLens](https://github.com/CHAPIBUNNY/repolens).`,
+    "",
+    "## Status",
+    "",
+    `| | |`,
+    `|---|---|`,
+    `| **Project** | ${projectName} |`,
+    `| **Branch** | \`${branch}\` |`,
+    `| **Pages** | ${pageKeys.length} |`,
+    `| **Publisher** | GitHub Wiki |`,
+    `| **Source** | [RepoLens](https://github.com/CHAPIBUNNY/repolens) |`,
+    "",
+    "---",
+    "",
+  ];
+
+  // Audience-grouped sections
+  for (const group of AUDIENCE_GROUPS) {
+    const activeKeys = group.keys.filter((k) => pageKeys.includes(k));
+    if (activeKeys.length === 0) continue;
+
+    lines.push(`## ${group.emoji} ${group.title}`, "");
+    for (const key of activeKeys) {
+      const desc = PAGE_DESCRIPTIONS[key] || "";
+      lines.push(`- ${wikiLink(key)}${desc ? " — " + desc : ""}`);
+    }
+    lines.push("");
+  }
+
+  // Custom / plugin pages
+  const customKeys = getCustomPageKeys(pageKeys);
+  if (customKeys.length > 0) {
+    lines.push("## 🧩 Custom Pages", "");
+    for (const key of customKeys.sort()) {
+      const desc = PAGE_DESCRIPTIONS[key] || "";
+      lines.push(`- ${wikiLink(key)}${desc ? " — " + desc : ""}`);
+    }
+    lines.push("");
+  }
+
+  // Recommended reading order
+  lines.push(
+    "---",
+    "",
+    "## 📖 Recommended Reading Order",
+    "",
+    "1. [[Executive Summary|Executive-Summary]] — Start here for a quick overview",
+    "2. [[System Overview|System-Overview]] — Understand the stack and scale",
+    "3. [[Architecture Overview|Architecture-Overview]] — Deep dive into system design",
+    "4. [[Developer Onboarding|Developer-Onboarding]] — Get started contributing",
+    "",
+    "---",
+    "",
+    `*This wiki is auto-generated. Manual edits will be overwritten on the next publish.*`,
+  );
+
+  return lines.join("\n");
+}
+
+/**
+ * Generate _Sidebar.md — grouped navigation.
+ */
+function generateSidebar(pageKeys, projectName, branch) {
+  const title = getBranchQualifiedTitle(projectName, branch);
+  const lines = [`### ${title}`, "", "[[Home]]", ""];
+
+  for (const group of SIDEBAR_GROUPS) {
+    const activeKeys = group.keys.filter((k) => pageKeys.includes(k));
+    if (activeKeys.length === 0) continue;
+
+    lines.push(`**${group.title}**`, "");
+    for (const key of activeKeys) {
+      lines.push(`- ${wikiLink(key)}`);
+    }
+    lines.push("");
+  }
+
+  // Custom / plugin pages
+  const customKeys = getCustomPageKeys(pageKeys);
+  if (customKeys.length > 0) {
+    lines.push("**Custom Pages**", "");
+    for (const key of customKeys.sort()) {
+      lines.push(`- ${wikiLink(key)}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---", `*[RepoLens](https://github.com/CHAPIBUNNY/repolens)*`);
+  return lines.join("\n");
+}
+
+/**
+ * Generate _Footer.md.
+ */
+function generateFooter(branch) {
+  const branchNote = branch !== "main" && branch !== "master"
+    ? ` · Branch: \`${branch}\``
+    : "";
+  return [
+    "---",
+    `📚 Generated by [RepoLens](https://github.com/CHAPIBUNNY/repolens)${branchNote} · [← Home](Home)`,
+  ].join("\n");
+}
+
+/**
+ * Build a metadata header to prepend to each page.
+ */
+function pageHeader(key, branch) {
+  const audience = PAGE_AUDIENCE[key] || "All Audiences";
+  return [
+    `[← Home](Home)`,
+    "",
+    `> **Audience:** ${audience} · **Branch:** \`${branch}\` · **Generated by** [RepoLens](https://github.com/CHAPIBUNNY/repolens)`,
+    "",
+    "---",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Run a git command in the specified directory.
+ * Token is never exposed in error output.
+ */
+function git(args, cwd) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+  } catch (err) {
+    const sanitized = (err.stderr || err.message || "").replace(
+      /x-access-token:[^\s@]+/g,
+      "x-access-token:***"
+    );
+    throw new Error(`Git command failed: git ${args.split(" ")[0]} — ${sanitized}`);
+  }
+}
+
+/**
+ * Publish rendered pages to GitHub Wiki.
+ */
+export async function publishToGitHubWiki(cfg, renderedPages) {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error(
+      "Missing GITHUB_TOKEN. Required for GitHub Wiki publishing.\n" +
+      "In GitHub Actions, this is available as ${{ secrets.GITHUB_TOKEN }}.\n" +
+      "Locally, create a PAT with repo scope: https://github.com/settings/tokens"
+    );
+  }
+
+  const repo = detectGitHubRepo();
+  if (!repo) {
+    throw new Error(
+      "Could not detect GitHub repository. Set GITHUB_REPOSITORY=owner/repo\n" +
+      "or ensure git remote 'origin' points to a GitHub URL."
+    );
+  }
+
+  const branch = getCurrentBranch();
+  const wikiConfig = cfg.github_wiki || {};
+  const includeSidebar = wikiConfig.sidebar !== false;
+  const includeFooter = wikiConfig.footer !== false;
+  const projectName = cfg.project?.name || repo.split("/")[1] || "RepoLens";
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "repolens-wiki-"));
+
+  try {
+    const cloneUrl = buildWikiCloneUrl(repo, token);
+
+    try {
+      git(`clone --depth 1 ${cloneUrl} .`, tmpDir);
+    } catch {
+      warn("Wiki repository not found — initializing. Enable the wiki tab in GitHub repo settings.");
+      // GitHub Wiki uses 'master' as default branch; ensure compatibility
+      // regardless of the local git init.defaultBranch setting
+      git("init -b master", tmpDir);
+      git(`remote add origin ${cloneUrl}`, tmpDir);
+    }
+
+    // Only include pages that have actual content
+    const populatedPages = Object.entries(renderedPages).filter(
+      ([, markdown]) => markdown && markdown.trim().length > 0
+    );
+    const pageKeys = populatedPages.map(([key]) => key);
+
+    // Write Home.md
+    const home = generateHome(pageKeys, projectName, branch, repo);
+    await fs.writeFile(path.join(tmpDir, "Home.md"), home, "utf8");
+
+    // Write each rendered page with metadata header
+    for (const [key, markdown] of populatedPages) {
+      const fileName = pageFileName(key);
+      const header = pageHeader(key, branch);
+      await fs.writeFile(path.join(tmpDir, fileName), header + markdown, "utf8");
+    }
+
+    // Generate sidebar
+    if (includeSidebar) {
+      const sidebar = generateSidebar(pageKeys, projectName, branch);
+      await fs.writeFile(path.join(tmpDir, "_Sidebar.md"), sidebar, "utf8");
+    }
+
+    // Generate footer
+    if (includeFooter) {
+      const footer = generateFooter(branch);
+      await fs.writeFile(path.join(tmpDir, "_Footer.md"), footer, "utf8");
+    }
+
+    // Stage, commit, push
+    git("config user.name \"RepoLens Bot\"", tmpDir);
+    git("config user.email \"repolens@users.noreply.github.com\"", tmpDir);
+    git("add -A", tmpDir);
+
+    try {
+      execSync("git diff --cached --quiet", { cwd: tmpDir, stdio: "pipe" });
+      info("GitHub Wiki is already up to date — no changes to push.");
+      return;
+    } catch {
+      // There are staged changes — continue to commit
+    }
+
+    const branchLabel = branch !== "main" && branch !== "master" ? ` [${branch}]` : "";
+    const commitMsg = `docs: update RepoLens documentation${branchLabel}`;
+    git(`commit -m "${commitMsg}"`, tmpDir);
+
+    // GitHub Wiki serves from 'master'; push explicitly to master
+    git("push origin HEAD:refs/heads/master", tmpDir);
+    info(`GitHub Wiki published (${pageKeys.length} pages): https://github.com/${repo}/wiki`);
+
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Check if GitHub Wiki publishing secrets are available.
+ */
+export function hasGitHubWikiSecrets() {
+  return !!process.env.GITHUB_TOKEN;
+}

package/src/publishers/index.js

@@ -1,7 +1,8 @@
 import { publishToNotion } from "./publish.js";
 import { publishToMarkdown } from "./markdown.js";
 import { publishToConfluence, hasConfluenceSecrets } from "./confluence.js";
-import { shouldPublishToNotion, shouldPublishToConfluence, getCurrentBranch } from "../utils/branch.js";
+import { publishToGitHubWiki, hasGitHubWikiSecrets } from "./github-wiki.js";
+import { shouldPublishToNotion, shouldPublishToConfluence, shouldPublishToGitHubWiki, getCurrentBranch } from "../utils/branch.js";
 import { info, warn } from "../utils/logger.js";
 import { trackPublishing } from "../utils/telemetry.js";
 import { collectMetrics } from "../utils/metrics.js";
@@ -80,6 +81,27 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     }
   }
 
+  // GitHub Wiki publishing (opt-in if secrets configured)
+  if (publishers.includes("github_wiki") || hasGitHubWikiSecrets() && publishers.includes("github_wiki")) {
+    if (!hasGitHubWikiSecrets()) {
+      info("Skipping GitHub Wiki publish: GITHUB_TOKEN not configured");
+      info("In GitHub Actions, add GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} to your env");
+    } else if (shouldPublishToGitHubWiki(cfg, currentBranch)) {
+      info(`Publishing to GitHub Wiki from branch: ${currentBranch}`);
+      try {
+        await publishToGitHubWiki(cfg, renderedPages);
+        publishedTo.push("github_wiki");
+      } catch (err) {
+        publishStatus = "failure";
+        throw err;
+      }
+    } else {
+      const allowedBranches = cfg.github_wiki?.branches?.join(", ") || "none configured";
+      warn(`Skipping GitHub Wiki publish: branch "${currentBranch}" not in allowed list (${allowedBranches})`);
+      info("To publish from this branch, add it to github_wiki.branches in .repolens.yml");
+    }
+  }
+
   // Run plugin publishers
   if (pluginManager) {
     const pluginPublishers = pluginManager.getPublishers();

package/src/utils/branch.js

@@ -112,6 +112,33 @@ export function shouldPublishToConfluence(config, currentBranch = getCurrentBran
   });
 }
 
+/**
+ * Check if current branch should publish to GitHub Wiki
+ * Based on config.github_wiki.branches setting
+ */
+export function shouldPublishToGitHubWiki(config, currentBranch = getCurrentBranch()) {
+  if (!config.github_wiki) {
+    return true;
+  }
+
+  if (!config.github_wiki.branches || config.github_wiki.branches.length === 0) {
+    return true;
+  }
+
+  return config.github_wiki.branches.some(pattern => {
+    if (pattern === currentBranch) {
+      return true;
+    }
+
+    if (pattern.includes("*")) {
+      const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+      return regex.test(currentBranch);
+    }
+
+    return false;
+  });
+}
+
 /**
  * Get branch-qualified page title
  */

package/src/utils/validate.js

@@ -135,7 +135,7 @@ function validatePublishers(publishers) {
     return errors;
   }
   
-  const validPublishers = ["notion", "markdown", "confluence"];
+  const validPublishers = ["notion", "markdown", "confluence", "github_wiki"];
   
   if (Array.isArray(publishers)) {
     for (const pub of publishers) {