@chappibunny/repolens 1.12.4 → 1.13.0

package/CHANGELOG.md

@@ -2,7 +2,21 @@
 
 All notable changes to RepoLens will be documented in this file.
 
-## Unreleased
+## 1.13.0
+
+### Obsidian vault publisher
+
+Publish generated docs into a folder in a local Obsidian vault. No network calls and no credentials.
+
+- New publisher: `obsidian` (`src/publishers/obsidian.js`)
+- Notes get YAML frontmatter (`title`, `aliases`, `tags`, `type`, `project`, `branch`) and an index note (`RepoLens.md`) with wikilinks
+- Markdown links to generated pages become `[[wikilinks]]`. External URLs and fenced code blocks are left alone
+- Re-running publish is idempotent: identical notes are not rewritten, and notes RepoLens previously published but no longer generates are removed. Other files in the folder stay
+- `obsidian.folder` must resolve inside `obsidian.vault`. Absolute folders, `..`, and symlinks that leave the vault are rejected
+- Optional config on schema v1: `obsidian.vault`, `obsidian.folder`, `obsidian.branches`, `obsidian.index`, `obsidian.frontmatter`, `obsidian.wikilinks`. Existing configs keep working
+- `repolens init` can select the Obsidian publisher and ask for a vault path
+- `repolens doctor` checks that `obsidian.vault` is set and does not require env vars for it
+- Wikilink rewriting is a linear scan with bounded label and target lengths. The previous link regex was polynomial on hostile markdown (CodeQL)
 
 ### Security
 
@@ -10,8 +24,12 @@ All notable changes to RepoLens will be documented in this file.
 
 ### Docs
 
+- `docs/ROADMAP.md` now summarizes what shipped from v1.1.0 through v1.12.4, and marks the VS Code extension and the Obsidian publisher as shipped
+- README roadmap matches `docs/ROADMAP.md`
 - The README no longer hard-codes the release version. It points at `package.json`, which is the source of the version
 - Test totals are no longer hard-coded in the README, development guide, or security guide. The tests badge follows the `test.yml` workflow status
+- Handbook pages (README, `docs/*`, `SECURITY.md`, `CONTRIBUTING.md`, and `.github/copilot-instructions.md`) describe 1.13.0 and the Obsidian publisher
+- Corrected drift against the code: `scan.ignore` (there is no `scan.exclude`), `publish` has no `--dry-run`, CI installs with `npm ci`, the publish workflow is `repolens.yml`, diagrams are Unicode, and local files use two filename schemes. `outputs.pages` stays the frozen allowlist; the generator still emits the full 17-document plan unless `documentation.sections` or `features` filters it
 
 ## 1.12.4
 

package/README.md

@@ -15,7 +15,7 @@
 
 **Your architecture docs are already outdated.** RepoLens fixes that.
 
-RepoLens scans your repository, generates living architecture documentation, and publishes it to Notion, Confluence, GitHub Wiki, or Markdown — automatically on every push. Engineers get technical docs. Stakeholders get readable system overviews. Nobody writes a word.
+RepoLens scans your repository, generates living architecture documentation, and publishes it to Notion, Confluence, GitHub Wiki, Obsidian, or Markdown — automatically on every push. Engineers get technical docs. Stakeholders get readable system overviews. Nobody writes a word.
 
 > Stable as of v1.0 — [API guarantees](docs/STABILITY.md) · [Security hardened](SECURITY.md) · version from [`package.json`](package.json)
 
@@ -83,7 +83,7 @@ CONFLUENCE_SPACE_KEY=DOCS
 npx @chappibunny/repolens publish
 ```
 
-**Done!** Your docs are now live in Notion, Confluence, and/or `.repolens/` directory.
+**Done!** Numbered notes and the Markdown publisher’s files are in `.repolens/`. Notion, Confluence, GitHub Wiki, and Obsidian publish only when you configure them. Obsidian needs `obsidian.vault` in `.repolens.yml` and does not use an API key.
 
 **🔄 Upgrading from v0.3.0 or earlier?**
 Run `npx @chappibunny/repolens migrate` to automatically update your workflow files. See [MIGRATION.md](docs/MIGRATION.md) for details.
@@ -96,9 +96,9 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 
 | Audience | Documents |
 |---|---|
-| **Stakeholders** (founders, PMs, ops) | Executive Summary · Business Domains · Data Flows |
-| **Everyone** | System Overview · Developer Onboarding · Change Impact · Architecture Drift · Code Health |
-| **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map · GraphQL Schema · TypeScript Type Graph · Dependency Graph · Security Hotspots |
+| **Stakeholders** | Executive Summary |
+| **Mixed** | System Overview · Business Domains · Route Map · Data Flows · Change Impact · System Map · Architecture Drift · Code Health |
+| **Engineers** | Architecture Overview · Module Catalog · API Surface · Developer Onboarding · GraphQL Schema · TypeScript Type Graph · Dependency Graph · Security Hotspots |
 
 **Two modes:** Deterministic (free, fast, always works) or AI-Enhanced (optional — GitHub Models, OpenAI, Anthropic, Google, Azure, Ollama).
 
@@ -110,7 +110,7 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 |---|---|
 | 🤖 **Autonomous** | Runs on every push via GitHub Actions — docs stay evergreen |
 | 👥 **Multi-Audience** | Technical docs + stakeholder-readable overviews from one scan |
-| 📤 **Multi-Publisher** | Notion, Confluence, GitHub Wiki, Markdown — or all four at once |
+| 📤 **Multi-Publisher** | Notion, Confluence, GitHub Wiki, Obsidian, Markdown — together or one at a time |
 | 🧠 **AI-Assisted** | Optional AI with zero-hallucination policy (structured context only) |
 | 🔍 **Smart Detection** | Frameworks, domains, data flows, dependencies, drift — all automatic |
 | 🔌 **Extensible** | Plugin system for custom renderers, publishers, and hooks |
@@ -155,7 +155,7 @@ The extension reads your `.repolens.yml` configuration and provides an interacti
 
 ## 🎓 Onboarding Guide
 
-Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki, Discord, and CI/CD automation.
+Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki, Obsidian, Discord, and CI/CD automation.
 
 **[→ Full Onboarding Guide](docs/ONBOARDING.md)**
 
@@ -183,28 +183,11 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 
 ## 📸 Example Output
 
-### System Map with Dependencies
-
-```mermaid
-graph LR
-    CLI[bin/repolens<br/>1 file] --> Core[src/core<br/>4 files]
-    Publishers[src/publishers<br/>6 files] --> Core
-    Publishers --> Renderers[src/renderers<br/>4 files]
-    Publishers --> Utils[src/utils<br/>10 files]
-    Renderers --> Core
-    Delivery[src/delivery<br/>1 file] --> Publishers
-    Tests[tests<br/>15 files] -. tests .-> CLI
-    Tests -. tests .-> Core
-    Tests -. tests .-> Publishers
-    
-    style CLI fill:#9b59b6,color:#fff
-    style Core fill:#f39c12,color:#000
-    style Publishers fill:#27ae60,color:#fff
-    style Renderers fill:#27ae60,color:#fff
-    style Delivery fill:#16a085,color:#fff
-    style Utils fill:#95a5a6,color:#000
-    style Tests fill:#e67e22,color:#fff
-```
+### System map
+
+Published system maps are Unicode diagrams drawn from import edges. RepoLens does not emit Mermaid.
+
+The publisher set in 1.13.0 is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 
@@ -255,7 +238,7 @@ When you open a pull request, RepoLens posts:
 
 | Guide | Description |
 |---|---|
-| [Onboarding Guide](docs/ONBOARDING.md) | Step-by-step setup: publishers, AI, Notion, Confluence, Discord |
+| [Onboarding Guide](docs/ONBOARDING.md) | Step-by-step setup: publishers, AI, Notion, Confluence, GitHub Wiki, Obsidian, Discord |
 | [Configuration](docs/CONFIGURATION.md) | Complete `.repolens.yml` schema and examples |
 | [Environment Variables](docs/ENVIRONMENT.md) | All env vars by publisher and feature |
 | [Architecture](docs/ARCHITECTURE.md) | Pipeline diagram, project structure |
@@ -285,10 +268,16 @@ v1.0+ features complete — CLI, config schema, and plugin interface are frozen.
 
 **Completed:**
 - [x] VS Code extension ([available on Marketplace](https://marketplace.visualstudio.com/items?itemName=CHAPIBUNNY.repolens-architecture))
+- [x] Obsidian vault publisher (local notes with wikilinks and frontmatter)
 
 **Next:**
-- [ ] Obsidian publisher
-- [ ] GitHub App
+- [ ] GitHub App for automated setup and status checks
+- [ ] Slack notifications
+- [ ] Custom webhook support
+- [ ] Cross-repository architecture analysis
+- [ ] Security boundary validation
+- [ ] Interactive HTML documentation output
+- [ ] Architecture decision records (ADR) generation
 
 See [ROADMAP.md](docs/ROADMAP.md) for detailed planning.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.12.4",
+  "version": "1.13.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",
@@ -36,6 +36,7 @@
     "metrics",
     "team-collaboration",
     "discord",
+    "obsidian",
     "ai-documentation"
   ],
   "repository": {

package/src/core/config-schema.js

@@ -8,7 +8,7 @@
  */
 
 const CURRENT_SCHEMA_VERSION = 1;
-const SUPPORTED_PUBLISHERS = ["notion", "markdown", "confluence", "github_wiki"];
+const SUPPORTED_PUBLISHERS = ["notion", "markdown", "confluence", "github_wiki", "obsidian"];
 const SUPPORTED_PAGE_KEYS = [
   "system_overview",
   "module_catalog",
@@ -218,6 +218,51 @@ export function validateConfig(config) {
     }
   }
 
+  // Validate Obsidian configuration (optional, local vault — no network)
+  if (config.obsidian !== undefined) {
+    if (typeof config.obsidian !== "object" || Array.isArray(config.obsidian) || config.obsidian === null) {
+      errors.push("obsidian must be an object");
+    } else {
+      if (config.obsidian.vault !== undefined) {
+        if (typeof config.obsidian.vault !== "string" || config.obsidian.vault.trim() === "") {
+          errors.push("obsidian.vault must be a non-empty string");
+        } else if (config.obsidian.vault.includes("\0")) {
+          errors.push("obsidian.vault contains a null byte");
+        }
+      }
+      if (config.obsidian.folder !== undefined) {
+        if (typeof config.obsidian.folder !== "string" || config.obsidian.folder.trim() === "") {
+          errors.push("obsidian.folder must be a non-empty string");
+        } else if (config.obsidian.folder.includes("\0")) {
+          errors.push("obsidian.folder contains a null byte");
+        } else if (
+          config.obsidian.folder.startsWith("/") ||
+          config.obsidian.folder.startsWith("\\") ||
+          /^[A-Za-z]:[\\/]/.test(config.obsidian.folder) ||
+          config.obsidian.folder.split(/[\\/]/).some((part) => part === "..")
+        ) {
+          errors.push("obsidian.folder must be a relative path inside the vault");
+        }
+      }
+      if (config.obsidian.branches !== undefined) {
+        if (!Array.isArray(config.obsidian.branches)) {
+          errors.push("obsidian.branches must be an array");
+        } else {
+          config.obsidian.branches.forEach((branch, idx) => {
+            if (typeof branch !== "string") {
+              errors.push(`obsidian.branches[${idx}] must be a string`);
+            }
+          });
+        }
+      }
+      for (const flag of ["index", "frontmatter", "wikilinks"]) {
+        if (config.obsidian[flag] !== undefined && typeof config.obsidian[flag] !== "boolean") {
+          errors.push(`obsidian.${flag} must be a boolean`);
+        }
+      }
+    }
+  }
+
   // Validate Discord configuration (optional)
   if (config.discord !== undefined) {
     if (typeof config.discord !== "object" || Array.isArray(config.discord)) {
@@ -379,6 +424,7 @@ const VALID_CONFIG_KEYS = [
   "notion",
   "confluence",
   "github_wiki",
+  "obsidian",
   "discord",
   "features",
   "ai",

package/src/doctor.js

@@ -204,6 +204,14 @@ export async function runDoctor(targetDir = process.cwd()) {
       );
     }
 
+    if (cfg.publishers.includes("obsidian")) {
+      if (typeof cfg.obsidian?.vault === "string" && cfg.obsidian.vault.trim() !== "") {
+        ok(`Obsidian vault configured (${cfg.obsidian.vault}) — local publisher, no credentials`);
+      } else {
+        warn("obsidian.vault is not set — required to publish into an Obsidian vault");
+      }
+    }
+
     if (cfg.ai?.enabled || process.env.REPOLENS_AI_ENABLED === "true") {
       const aiProvider = process.env.REPOLENS_AI_PROVIDER || "openai_compatible";
       if (aiProvider === "github") {
@@ -218,7 +226,12 @@ export async function runDoctor(targetDir = process.cwd()) {
     }
 
     if (envChecks.length === 0) {
-      ok("No publisher-specific env vars required (Markdown only)");
+      const localPublishers = [];
+      if (cfg.publishers.includes("markdown")) localPublishers.push("Markdown");
+      if (cfg.publishers.includes("obsidian")) localPublishers.push("Obsidian");
+      ok(localPublishers.length > 0
+        ? `No publisher-specific env vars required (${localPublishers.join(" and ")} only)`
+        : "No publisher-specific env vars required");
     }
 
     for (const check of envChecks) {

package/src/init.js

@@ -5,7 +5,7 @@ import { spawn } from "node:child_process";
 import { info, warn } from "./utils/logger.js";
 import { isNonInteractiveEnvironment } from "./utils/interactive.js";
 
-const PUBLISHER_CHOICES = ["markdown", "notion", "confluence", "github_wiki"];
+const PUBLISHER_CHOICES = ["markdown", "notion", "confluence", "github_wiki", "obsidian"];
 
 // ============================================================================
 // URL PARSING HELPERS
@@ -435,6 +435,10 @@ If you configured Notion credentials during setup, documentation will publish au
    - \`NOTION_TOKEN\` — Get from https://www.notion.so/my-integrations
    - \`NOTION_PARENT_PAGE_ID\` — The page where docs will be published
 
+### Obsidian and GitHub Wiki
+
+Obsidian writes notes into a folder in a local vault. Set \`obsidian.vault\` in \`.repolens.yml\`. No API key and no network. GitHub Wiki needs \`github_wiki\` in \`publishers\` and \`GITHUB_TOKEN\`.
+
 ### Confluence Publishing
 
 To publish documentation to Atlassian Confluence:
@@ -472,23 +476,20 @@ The workflow token is \`contents: read\` plus \`pull-requests: write\`. That is
 
 ## 📊 Generated Documentation
 
-RepoLens generates documentation in two modes:
+RepoLens generates 17 documents by default. Diagrams are Unicode.
 
-### Deterministic Mode (Default - Free)
-- **System Overview** — Technical profile and stats
-- **Module Catalog** — Complete code inventory
-- **API Surface** — Internal endpoints + external integrations
-- **Route Map** — Application routes
-- **System Map** — Unicode architecture diagram
-- **Architecture Diff** — Change tracking
+### Always written
+- **System Overview**, **Module Catalog**, **API Surface**, **Route Map**, **System Map** (Unicode diagram), **Architecture Diff**
+- **GraphQL Schema**, **Type Graph**, **Dependency Graph**, **Architecture Drift**, **Security Hotspots**, **Code Health**
 
-### AI-Enhanced Mode (Optional - Requires API Key)
-Adds 5 natural language documents readable by non-technical audiences:
+### AI-Enhanced Mode (Optional)
+These documents use AI when it is enabled, and a deterministic fallback when it is not:
 - **Executive Summary** — Project overview for leadership
 - **Business Domains** — What the system does by function
 - **Architecture Overview** — Layered technical analysis
-- **Data Flows** — How information moves through system
+- **Data Flows** — How information moves through the system
 - **Developer Onboarding** — Getting started guide
+- **Change Impact** and the hybrid pages above (module catalog, route map, API surface, system map)
 
 ## 🤖 Enabling AI Features
 
@@ -529,11 +530,7 @@ No API key signup needed. Uses \`gpt-4o-mini\` by default.
 
 **Cost estimate**: $0.10-$0.40 per run for typical projects (or free with GitHub Models)
 
-See [AI.md](https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md) for full documentation
-- **Module Catalog** — Detected code modules
-- **API Surface** — REST API endpoints
-- **Route Map** — Application routes
-- **System Map** — Architecture diagram (Unicode ASCII art)
+See [AI.md](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/AI.md) for full documentation.
 
 ## ⚙️ Configuration
 
@@ -547,8 +544,8 @@ Edit \`.repolens.yml\` to customize:
 ## 📚 Learn More
 
 - [RepoLens GitHub](https://github.com/CHAPIBUNNY/repolens)
-- [Configuration Docs](https://github.com/CHAPIBUNNY/repolens#configuration)
-- [Troubleshooting](https://github.com/CHAPIBUNNY/repolens#troubleshooting)
+- [Configuration](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/CONFIGURATION.md)
+- [Troubleshooting](https://github.com/CHAPIBUNNY/repolens/blob/main/docs/TROUBLESHOOTING.md)
 `;
 
 async function fileExists(filePath) {
@@ -754,6 +751,17 @@ function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
     `#     - main        # Only publish from main branch`,
     `#     - develop     # Or add specific branches`,
     ``,
+    `# Optional: Publish into a local Obsidian vault (no network)`,
+    `# publishers also needs: - obsidian`,
+    `# obsidian:`,
+    `#   vault: "/path/to/vault"     # absolute, or relative to this repo`,
+    `#   folder: "RepoLens/my-app"   # stays inside the vault`,
+    `#   branches:`,
+    `#     - main`,
+    `#   index: true`,
+    `#   frontmatter: true`,
+    `#   wikilinks: true`,
+    ``,
     `# Optional: GitHub integration for SVG diagram hosting`,
     `# github:`,
     `#   owner: "your-username"`,
@@ -1156,6 +1164,20 @@ async function runInteractiveWizard(repoRoot) {
       githubSecretsNeeded.push("CONFLUENCE_URL", "CONFLUENCE_EMAIL", "CONFLUENCE_API_TOKEN", "CONFLUENCE_SPACE_KEY", "CONFLUENCE_PARENT_PAGE_ID");
     }
 
+    // Obsidian vault (local path only — no credentials)
+    let obsidian = null;
+    if (publishers.includes("obsidian")) {
+      info("\n📝 Obsidian Vault");
+      info("   Notes are written into a folder in your vault. Nothing is uploaded.");
+      const vault = (await ask("   Vault path (absolute, or relative to the repo): ")).trim();
+      const folderDefault = `RepoLens/${projectName}`;
+      const folder = (await ask(`   Folder inside the vault (${folderDefault}): `)).trim();
+      obsidian = { vault, folder: folder || folderDefault };
+      if (!vault) {
+        warn("   No vault path yet. Add obsidian.vault to .repolens.yml before publishing.");
+      }
+    }
+
     // GitHub Wiki setup
     if (publishers.includes("github_wiki")) {
       info("\n📝 GitHub Wiki Setup");
@@ -1278,7 +1300,7 @@ async function runInteractiveWizard(repoRoot) {
 
     // 6. Branch filtering
     info("\n🌿 Branch Filtering");
-    info("   Limits which branches can publish to Notion/Confluence.");
+    info("   Limits which branches can publish to Notion, Confluence, and Obsidian.");
     const branchInput = (await ask("   Allowed branches (comma-separated, default: main): ")).trim() || "main";
     const branches = branchInput.split(",").map((b) => b.trim()).filter(Boolean);
 
@@ -1336,7 +1358,8 @@ async function runInteractiveWizard(repoRoot) {
       branches, 
       enableDiscord,
       credentials,
-      githubSecretsNeeded: uniqueSecrets
+      githubSecretsNeeded: uniqueSecrets,
+      obsidian,
     };
   } finally {
     rl.close();
@@ -1348,6 +1371,7 @@ const PUBLISHER_DESCRIPTIONS = {
   notion: "Notion workspace pages",
   confluence: "Atlassian Confluence pages",
   github_wiki: "Repository wiki pages",
+  obsidian: "Local Obsidian vault folder",
 };
 
 /**
@@ -1380,6 +1404,22 @@ function buildWizardConfig(answers) {
     lines.push(`  branches:`);
     for (const b of answers.branches) lines.push(`    - ${b}`);
   }
+  if (answers.publishers.includes("obsidian")) {
+    lines.push(``);
+    lines.push(`obsidian:`);
+    if (answers.obsidian?.vault) {
+      lines.push(`  vault: ${JSON.stringify(answers.obsidian.vault)}`);
+    }
+    const folder = answers.obsidian?.folder || `RepoLens/${answers.projectName}`;
+    lines.push(`  folder: ${JSON.stringify(folder)}`);
+    if (answers.branches?.length) {
+      lines.push(`  branches:`);
+      for (const b of answers.branches) lines.push(`    - ${b}`);
+    }
+    lines.push(`  index: true`);
+    lines.push(`  frontmatter: true`);
+    lines.push(`  wikilinks: true`);
+  }
 
   if (answers.enableDiscord) {
     lines.push(``);

package/src/publishers/index.js

@@ -2,7 +2,8 @@ import { publishToNotion } from "./publish.js";
 import { publishToMarkdown } from "./markdown.js";
 import { publishToConfluence, hasConfluenceSecrets } from "./confluence.js";
 import { publishToGitHubWiki, hasGitHubWikiSecrets } from "./github-wiki.js";
-import { shouldPublishToNotion, shouldPublishToConfluence, shouldPublishToGitHubWiki, getCurrentBranch, branchMatches } from "../utils/branch.js";
+import { publishToObsidian } from "./obsidian.js";
+import { shouldPublishToNotion, shouldPublishToConfluence, shouldPublishToGitHubWiki, shouldPublishToObsidian, getCurrentBranch, branchMatches } from "../utils/branch.js";
 import { resolveOutputDir } from "../utils/safe-path.js";
 import { info, warn } from "../utils/logger.js";
 import { trackPublishing } from "../utils/telemetry.js";
@@ -96,6 +97,25 @@ export async function publishDocs(cfg, renderedPages, scanResult, pluginManager
     }
   }
 
+  // Obsidian vault (local files only — no credentials, no network)
+  if (publishers.includes("obsidian")) {
+    if (shouldPublishToObsidian(cfg, currentBranch)) {
+      info(`Publishing to Obsidian vault from branch: ${currentBranch}`);
+      try {
+        await publishToObsidian(cfg, renderedPages);
+        publishedTo.push("obsidian");
+      } catch (err) {
+        warn(`Obsidian publish failed: ${err.message}`);
+        publishErrors.push({ publisher: "obsidian", error: err });
+        publishStatus = "partial";
+      }
+    } else {
+      const allowedBranches = cfg.obsidian?.branches?.join(", ") || "none configured";
+      warn(`Skipping Obsidian publish: branch "${currentBranch}" not in allowed list (${allowedBranches})`);
+      info("To publish from this branch, add it to obsidian.branches in .repolens.yml");
+    }
+  }
+
   // GitHub Wiki publishing (opt-in if secrets configured)
   if (publishers.includes("github_wiki") || hasGitHubWikiSecrets() && publishers.includes("github_wiki")) {
     if (!hasGitHubWikiSecrets()) {

package/src/publishers/obsidian.js

@@ -0,0 +1,716 @@
+// Obsidian vault publisher for RepoLens.
+//
+// Writes generated notes into a folder inside a local Obsidian vault.
+// Notes use YAML frontmatter and wikilinks. Updates are in-place and
+// idempotent. Every path is contained inside the vault. No network.
+//
+// Config (.repolens.yml), all fields optional except vault at publish time:
+//   obsidian:
+//     vault: "/path/to/vault"     # absolute, or relative to the repo
+//     folder: "RepoLens/my-app"   # relative directory inside the vault
+//     branches: [main]            # optional branch filter (enforced by the orchestrator)
+//     index: true                 # map-of-content note (default: true)
+//     frontmatter: true           # YAML properties (default: true)
+//     wikilinks: true             # rewrite markdown links (default: true)
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info, warn } from "../utils/logger.js";
+import { getCurrentBranch } from "../utils/branch.js";
+import { isInsideRoot, safeFileName } from "../utils/safe-path.js";
+
+const INDEX_NOTE = "RepoLens";
+const MANIFEST_FILE = ".repolens-obsidian.json";
+
+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",
+  "security_hotspots",
+  "code_health",
+];
+
+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",
+  security_hotspots: "Security Hotspots",
+  code_health: "Code Health",
+};
+
+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.",
+  architecture_overview: "Layered technical view of the system.",
+  module_catalog: "Inventory of modules and responsibilities.",
+  route_map: "Frontend routes and page structure.",
+  api_surface: "Detected endpoints, handlers, and API structure.",
+  data_flows: "How information moves through the system.",
+  change_impact: "Architecture changes and likely downstream effects.",
+  system_map: "Visual map of system relationships.",
+  developer_onboarding: "What a new engineer needs to know first.",
+  graphql_schema: "GraphQL types, operations, and schema structure.",
+  type_graph: "Type-level relationships across the codebase.",
+  dependency_graph: "Module and package dependency relationships.",
+  architecture_drift: "Drift between intended and current architecture.",
+  arch_diff: "Architecture-level diff across revisions.",
+  security_hotspots: "Security anti-patterns with CWE classification.",
+  code_health: "Complexity and unified health scores.",
+};
+
+const PAGE_TAGS = {
+  executive_summary: "stakeholders",
+  system_overview: "overview",
+  business_domains: "stakeholders",
+  architecture_overview: "engineers",
+  module_catalog: "engineers",
+  route_map: "engineers",
+  api_surface: "engineers",
+  data_flows: "stakeholders",
+  change_impact: "engineers",
+  system_map: "overview",
+  developer_onboarding: "onboarding",
+  graphql_schema: "engineers",
+  type_graph: "engineers",
+  dependency_graph: "engineers",
+  architecture_drift: "engineers",
+  arch_diff: "engineers",
+  security_hotspots: "security",
+  code_health: "engineers",
+};
+
+const AUDIENCE_GROUPS = [
+  {
+    title: "For Stakeholders",
+    keys: ["executive_summary", "business_domains", "data_flows"],
+  },
+  {
+    title: "For Engineers",
+    keys: [
+      "architecture_overview", "module_catalog", "api_surface",
+      "route_map", "system_map", "graphql_schema", "type_graph",
+      "dependency_graph", "architecture_drift", "security_hotspots", "code_health",
+    ],
+  },
+  {
+    title: "For New Contributors",
+    keys: ["developer_onboarding", "system_overview"],
+  },
+  {
+    title: "Change Tracking",
+    keys: ["change_impact", "arch_diff"],
+  },
+];
+
+function displayTitle(key) {
+  return PAGE_TITLES[key] || String(key).replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Reduce a note title to a single path segment Obsidian and Windows can store.
+ */
+export function sanitizeNoteName(name) {
+  const cleaned = String(name ?? "")
+    .replace(/[<>:"|?*\u0000-\u001f\\/]/g, " ")
+    .replace(/\.\.+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/[. ]+$/g, "")
+    .replace(/^\.+/, "");
+  if (!cleaned || cleaned === "." || cleaned === "..") return "Note";
+  return cleaned;
+}
+
+function noteStemForKey(key, useWikilinks) {
+  if (!useWikilinks) {
+    const file = safeFileName(`${key}.md`, "document.md");
+    return sanitizeNoteName(file.replace(/\.md$/i, ""));
+  }
+  return sanitizeNoteName(displayTitle(key));
+}
+
+function allocateNotes(keys, useWikilinks) {
+  const used = new Set([INDEX_NOTE]);
+  const notes = [];
+  for (const key of keys) {
+    const base = noteStemForKey(key, useWikilinks);
+    let name = base;
+    let n = 2;
+    while (used.has(name)) {
+      const suffix = n === 2 ? key : `${key} ${n}`;
+      name = sanitizeNoteName(`${base} (${suffix})`);
+      n += 1;
+      if (n > 50) {
+        throw new Error(`Could not allocate a unique Obsidian note name for ${key}`);
+      }
+    }
+    used.add(name);
+    notes.push({ key, name, fileName: `${name}.md` });
+  }
+  return notes;
+}
+
+function yamlQuote(value) {
+  return JSON.stringify(String(value));
+}
+
+function buildFrontmatter(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      const items = value.filter((item) => item != null && String(item).length > 0);
+      if (items.length === 0) continue;
+      lines.push(`${key}:`);
+      for (const item of items) lines.push(`  - ${yamlQuote(item)}`);
+    } else if (typeof value === "boolean" || typeof value === "number") {
+      lines.push(`${key}: ${value}`);
+    } else {
+      lines.push(`${key}: ${yamlQuote(value)}`);
+    }
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
+function ensureTrailingNewline(text) {
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+const MAX_LINK_LABEL = 500;
+const MAX_LINK_TARGET = 2048;
+
+/**
+ * Rewrite inline markdown links to Obsidian wikilinks.
+ * Fenced code blocks are left untouched. http(s) and other URLs stay as links.
+ *
+ * The scan is a single forward pass. Label and target lengths are capped so
+ * a hostile document cannot trigger polynomial backtracking.
+ * @param {string} markdown
+ * @param {Map<string, string>} linkMap basename/stem → note name
+ */
+export function rewriteMarkdownToWikilinks(markdown, linkMap) {
+  const source = String(markdown ?? "");
+  const fences = fencedCodeRanges(source);
+  const parts = [];
+  let i = 0;
+  let fenceIndex = 0;
+
+  while (i < source.length) {
+    if (fenceIndex < fences.length && i === fences[fenceIndex][0]) {
+      parts.push(source.slice(fences[fenceIndex][0], fences[fenceIndex][1]));
+      i = fences[fenceIndex][1];
+      fenceIndex += 1;
+      continue;
+    }
+
+    const nextFence = fenceIndex < fences.length ? fences[fenceIndex][0] : source.length;
+    const link = scanInlineLink(source, i);
+    if (link && link.end <= nextFence) {
+      const converted = toWikilink(link.embed, link.label, link.target, linkMap);
+      parts.push(converted ?? link.raw);
+      i = link.end;
+      continue;
+    }
+
+    parts.push(source[i]);
+    i += 1;
+  }
+
+  return parts.join("");
+}
+
+/**
+ * Pairs of ``` fences, as [start, end) indexes. An unclosed fence is not a range.
+ * Each search starts at the previous match, so this is linear in the input length.
+ */
+function fencedCodeRanges(source) {
+  const ranges = [];
+  let i = 0;
+  while (i < source.length) {
+    const open = source.indexOf("```", i);
+    if (open === -1) break;
+    const close = source.indexOf("```", open + 3);
+    if (close === -1) break;
+    ranges.push([open, close + 3]);
+    i = close + 3;
+  }
+  return ranges;
+}
+
+/**
+ * Match `![label](target)` or `[label](target)` at `index`.
+ * Label: 0–500 chars, no brackets or newlines. Target: 1–2048 chars, no
+ * parentheses or whitespace. Returns null when the text at `index` is not a link.
+ */
+function scanInlineLink(source, index) {
+  let cursor = index;
+  let embed = false;
+  if (source[cursor] === "!" && source[cursor + 1] === "[") {
+    embed = true;
+    cursor += 1;
+  }
+  if (source[cursor] !== "[") return null;
+
+  const labelStart = cursor + 1;
+  const labelEnd = readLinkLabel(source, labelStart);
+  if (labelEnd < 0 || source[labelEnd + 1] !== "(") return null;
+
+  const targetStart = labelEnd + 2;
+  const targetEnd = readLinkTarget(source, targetStart);
+  if (targetEnd < 0) return null;
+
+  return {
+    embed,
+    label: source.slice(labelStart, labelEnd),
+    target: source.slice(targetStart, targetEnd),
+    raw: source.slice(index, targetEnd + 1),
+    end: targetEnd + 1,
+  };
+}
+
+function readLinkLabel(source, start) {
+  const limit = Math.min(source.length, start + MAX_LINK_LABEL);
+  let i = start;
+  while (i < limit) {
+    const ch = source[i];
+    if (ch === "]" || ch === "[" || ch === "\n") break;
+    i += 1;
+  }
+  if (i >= source.length || source[i] !== "]") return -1;
+  return i;
+}
+
+function readLinkTarget(source, start) {
+  const limit = Math.min(source.length, start + MAX_LINK_TARGET);
+  let i = start;
+  while (i < limit) {
+    const ch = source[i];
+    if (ch === "(" || ch === ")" || ch.charCodeAt(0) <= 32) break;
+    i += 1;
+  }
+  if (i === start || i >= source.length || source[i] !== ")") return -1;
+  return i;
+}
+
+function toWikilink(isEmbed, label, rawTarget, linkMap) {
+  const target = String(rawTarget ?? "").trim();
+  if (!target) return null;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) return null;
+
+  if (target.startsWith("#")) {
+    const heading = safeHeading(target.slice(1));
+    if (!heading) return null;
+    return isEmbed ? `![[#${heading}]]` : `[[#${heading}]]`;
+  }
+
+  const hashAt = target.indexOf("#");
+  const pathPart = hashAt === -1 ? target : target.slice(0, hashAt);
+  const hash = hashAt === -1 ? "" : target.slice(hashAt + 1);
+  let decoded = pathPart;
+  try {
+    decoded = decodeURIComponent(pathPart);
+  } catch {
+    decoded = pathPart;
+  }
+  if (path.isAbsolute(decoded) || /^[A-Za-z]:[\\/]/.test(decoded)) return null;
+
+  const base = path.posix.basename(decoded.replace(/\\/g, "/"));
+  if (!base || base === "." || base === "..") return null;
+
+  const stem = base.replace(/\.md$/i, "");
+  const known = lookupNote(linkMap, base) || lookupNote(linkMap, stem);
+  const isMarkdown = /\.md$/i.test(base);
+
+  if (!known && !isMarkdown && !isEmbed) return null;
+  if (!known && isEmbed && !isMarkdown) {
+    return `![[${base}]]`;
+  }
+
+  const dest = known || sanitizeNoteName(stem);
+  const heading = hash ? safeHeading(hash) : "";
+  const targetNote = heading ? `${dest}#${heading}` : dest;
+  if (isEmbed) return `![[${targetNote}]]`;
+  const alias = String(label ?? "").trim();
+  if (!alias || alias === dest || alias === targetNote) return `[[${targetNote}]]`;
+  return `[[${targetNote}|${alias.replaceAll("|", "\\|")}]]`;
+}
+
+function safeHeading(raw) {
+  let decoded = raw;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    decoded = raw;
+  }
+  return decoded.replace(/[\]|#^]/g, "").trim();
+}
+
+function lookupNote(linkMap, token) {
+  if (!token) return null;
+  return linkMap.get(token) || linkMap.get(token.toLowerCase()) || null;
+}
+
+function buildLinkMap(notes) {
+  const map = new Map();
+  for (const note of notes) {
+    const aliases = [note.name, note.fileName, note.key, `${note.key}.md`, displayTitle(note.key)];
+    for (const alias of aliases) {
+      map.set(alias, note.name);
+      map.set(alias.toLowerCase(), note.name);
+    }
+  }
+  return map;
+}
+
+function defaultFolder(cfg) {
+  const raw = cfg.project?.name || "project";
+  const slug = sanitizeNoteName(String(raw).replace(/^\.+/, "")) || "project";
+  return path.join("RepoLens", slug);
+}
+
+function assertRelativeFolder(folder) {
+  if (typeof folder !== "string" || folder.trim() === "") {
+    throw new Error("obsidian.folder must be a non-empty relative path inside the vault");
+  }
+  if (folder.includes("\0")) {
+    throw new Error("obsidian.folder contains a null byte");
+  }
+  if (path.isAbsolute(folder) || /^[A-Za-z]:[\\/]/.test(folder)) {
+    throw new Error(`obsidian.folder must stay inside the vault (received absolute path ${folder})`);
+  }
+  const parts = path.normalize(folder).split(path.sep).filter((part) => part && part !== ".");
+  if (parts.length === 0 || parts.some((part) => part === "..")) {
+    throw new Error(`obsidian.folder escapes the vault: ${folder}`);
+  }
+  return parts.join(path.sep);
+}
+
+/**
+ * Resolve the vault directory. Relative paths are resolved from the repo root.
+ * The directory must already exist. The returned path is its realpath.
+ */
+export async function resolveVaultRoot(cfg, vault) {
+  if (typeof vault !== "string" || vault.trim() === "") {
+    throw new Error(
+      "obsidian.vault is required. Set it to your Obsidian vault path in .repolens.yml"
+    );
+  }
+  if (vault.includes("\0")) {
+    throw new Error("obsidian.vault contains a null byte");
+  }
+  const base = cfg.__repoRoot || process.cwd();
+  const lexical = path.resolve(base, vault);
+  let real;
+  try {
+    real = await fs.realpath(lexical);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`Obsidian vault does not exist: ${lexical}`);
+    }
+    throw err;
+  }
+  const stat = await fs.stat(real);
+  if (!stat.isDirectory()) {
+    throw new Error(`Obsidian vault is not a directory: ${lexical}`);
+  }
+  return real;
+}
+
+/**
+ * Resolve a folder inside the vault and create it.
+ * Symlinks that point outside the vault are rejected.
+ */
+export async function resolveVaultFolder(vaultRoot, folder) {
+  const relative = assertRelativeFolder(folder);
+  const lexical = path.resolve(vaultRoot, relative);
+  if (!isInsideRoot(vaultRoot, lexical)) {
+    throw new Error(`obsidian.folder escapes the vault: ${folder}`);
+  }
+
+  let current = vaultRoot;
+  for (const part of relative.split(path.sep)) {
+    current = path.join(current, part);
+    let listed;
+    try {
+      listed = await fs.lstat(current);
+    } catch (err) {
+      if (err.code === "ENOENT") break;
+      throw err;
+    }
+    if (listed.isSymbolicLink()) {
+      const real = await fs.realpath(current);
+      if (!isInsideRoot(vaultRoot, real)) {
+        throw new Error(`obsidian.folder escapes the vault through a symlink: ${folder}`);
+      }
+    } else if (!listed.isDirectory()) {
+      throw new Error(`obsidian.folder is not a directory: ${folder}`);
+    }
+  }
+
+  await fs.mkdir(lexical, { recursive: true });
+  const realFolder = await fs.realpath(lexical);
+  if (!isInsideRoot(vaultRoot, realFolder)) {
+    throw new Error(`obsidian.folder escapes the vault: ${folder}`);
+  }
+  return realFolder;
+}
+
+function containedFile(root, fileName) {
+  const base = safeFileName(fileName, "");
+  if (!base || base === MANIFEST_FILE) {
+    throw new Error(`Refusing to write an unsafe note name: ${fileName}`);
+  }
+  const resolved = path.resolve(root, base);
+  if (!isInsideRoot(root, resolved) || path.basename(resolved) !== base) {
+    throw new Error(`Note path escapes the vault folder: ${fileName}`);
+  }
+  return resolved;
+}
+
+async function writeIfChanged(filePath, content) {
+  let listed;
+  try {
+    listed = await fs.lstat(filePath);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (listed?.isSymbolicLink()) {
+    throw new Error(`Refusing to write through a symlink: ${filePath}`);
+  }
+  if (listed && !listed.isFile()) {
+    throw new Error(`Refusing to overwrite a non-file: ${filePath}`);
+  }
+  if (listed?.isFile()) {
+    const existing = await fs.readFile(filePath, "utf8");
+    if (existing === content) return false;
+  }
+  await fs.writeFile(filePath, content, "utf8");
+  return true;
+}
+
+async function readManifest(folder) {
+  const manifestPath = path.join(folder, MANIFEST_FILE);
+  try {
+    const raw = await fs.readFile(manifestPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.files) ? parsed.files.filter((item) => typeof item === "string") : [];
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      warn(`Ignoring unreadable Obsidian manifest: ${err.message}`);
+    }
+    return [];
+  }
+}
+
+function manifestPathFor(folder) {
+  const resolved = path.resolve(folder, MANIFEST_FILE);
+  if (!isInsideRoot(folder, resolved)) {
+    throw new Error("Obsidian manifest path escapes the vault folder");
+  }
+  return resolved;
+}
+
+function removableManagedFile(folder, rel) {
+  if (typeof rel !== "string" || rel.includes("\0") || path.isAbsolute(rel)) return null;
+  const parts = rel.split(/[\\/]/).filter(Boolean);
+  if (parts.length !== 1 || parts[0] === "." || parts[0] === ".." || parts[0] === MANIFEST_FILE) {
+    return null;
+  }
+  const resolved = path.resolve(folder, parts[0]);
+  if (!isInsideRoot(folder, resolved)) return null;
+  return resolved;
+}
+
+async function syncManifest(vaultRoot, folder, fileNames) {
+  const previous = await readManifest(folder);
+  const next = new Set(fileNames);
+  let removed = 0;
+  for (const rel of previous) {
+    if (next.has(rel)) continue;
+    const target = removableManagedFile(folder, rel);
+    if (!target || !isInsideRoot(vaultRoot, target)) continue;
+    let listed;
+    try {
+      listed = await fs.lstat(target);
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+    if (listed.isSymbolicLink() || !listed.isFile()) continue;
+    await fs.unlink(target);
+    removed += 1;
+  }
+
+  const body = `${JSON.stringify({ version: 1, files: [...fileNames].sort() }, null, 2)}\n`;
+  await writeIfChanged(manifestPathFor(folder), body);
+  return removed;
+}
+
+function renderPage(note, markdown, options) {
+  const body = options.useWikilinks
+    ? rewriteMarkdownToWikilinks(markdown, options.linkMap)
+    : String(markdown);
+  const backlink = options.useIndex
+    ? (options.useWikilinks ? `← [[${INDEX_NOTE}|Index]]` : `← [Index](${INDEX_NOTE}.md)`)
+    : "";
+  const parts = [];
+  if (options.useFrontmatter) {
+    const aliases = [note.key];
+    const title = displayTitle(note.key);
+    if (title !== note.name) aliases.push(title);
+    parts.push(buildFrontmatter({
+      title: note.name,
+      aliases,
+      tags: ["repolens", PAGE_TAGS[note.key]].filter(Boolean),
+      type: note.key,
+      project: options.projectName,
+      branch: options.branch,
+      publisher: "repolens",
+    }));
+  }
+  if (backlink) parts.push(`${backlink}\n`);
+  parts.push(body.trimEnd());
+  return ensureTrailingNewline(parts.join("\n"));
+}
+
+function renderIndex(notes, options) {
+  const byKey = new Map(notes.map((note) => [note.key, note]));
+  const listed = new Set();
+  const sections = [];
+
+  for (const group of AUDIENCE_GROUPS) {
+    const items = group.keys.filter((key) => byKey.has(key));
+    if (items.length === 0) continue;
+    sections.push(`## ${group.title}`, "");
+    for (const key of items) {
+      listed.add(key);
+      sections.push(indexItem(byKey.get(key), options.useWikilinks));
+    }
+    sections.push("");
+  }
+
+  const custom = notes.filter((note) => !listed.has(note.key));
+  if (custom.length > 0) {
+    sections.push("## Custom", "");
+    for (const note of custom) sections.push(indexItem(note, options.useWikilinks));
+    sections.push("");
+  }
+
+  const intro = [
+    `# ${options.projectName}`,
+    "",
+    "Architecture notes published by RepoLens into this Obsidian vault.",
+    "Re-running publish updates these notes in place.",
+    "",
+  ];
+
+  const parts = [];
+  if (options.useFrontmatter) {
+    const aliases = options.projectName && options.projectName !== INDEX_NOTE
+      ? [options.projectName]
+      : [];
+    parts.push(buildFrontmatter({
+      title: INDEX_NOTE,
+      aliases,
+      tags: ["repolens", "index"],
+      type: "index",
+      project: options.projectName,
+      branch: options.branch,
+      publisher: "repolens",
+    }));
+  }
+  parts.push([...intro, ...sections].join("\n").trimEnd());
+  return ensureTrailingNewline(parts.join("\n"));
+}
+
+function indexItem(note, useWikilinks) {
+  const description = PAGE_DESCRIPTIONS[note.key] || "Generated by RepoLens.";
+  const link = useWikilinks ? `[[${note.name}]]` : `[${note.name}](${note.fileName})`;
+  return `- ${link} — ${description}`;
+}
+
+function orderedKeys(renderedPages) {
+  const present = Object.entries(renderedPages)
+    .filter(([, markdown]) => typeof markdown === "string" && markdown.trim() !== "")
+    .map(([key]) => key);
+  const known = PAGE_ORDER.filter((key) => present.includes(key));
+  const custom = present.filter((key) => !PAGE_ORDER.includes(key));
+  return [...known, ...custom];
+}
+
+/**
+ * Publish rendered pages into an Obsidian vault folder.
+ * @returns {Promise<{ folder: string, files: string[], removed: number, changed: number }>}
+ */
+export async function publishToObsidian(cfg, renderedPages) {
+  const obsidian = cfg.obsidian || {};
+  const vaultRoot = await resolveVaultRoot(cfg, obsidian.vault);
+  const folderRel = obsidian.folder == null || obsidian.folder === ""
+    ? defaultFolder(cfg)
+    : obsidian.folder;
+  const folder = await resolveVaultFolder(vaultRoot, folderRel);
+
+  const useFrontmatter = obsidian.frontmatter !== false;
+  const useWikilinks = obsidian.wikilinks !== false;
+  const useIndex = obsidian.index !== false;
+  const projectName = cfg.project?.name || "RepoLens";
+  const branch = getCurrentBranch();
+
+  const notes = allocateNotes(orderedKeys(renderedPages || {}), useWikilinks);
+  const linkMap = buildLinkMap(notes);
+  const fileNames = [];
+  let changed = 0;
+
+  for (const note of notes) {
+    const filePath = containedFile(folder, note.fileName);
+    const content = renderPage(note, renderedPages[note.key], {
+      useFrontmatter,
+      useWikilinks,
+      useIndex,
+      linkMap,
+      projectName,
+      branch,
+    });
+    if (await writeIfChanged(filePath, content)) changed += 1;
+    fileNames.push(note.fileName);
+  }
+
+  if (useIndex) {
+    const indexPath = containedFile(folder, `${INDEX_NOTE}.md`);
+    const content = renderIndex(notes, { useFrontmatter, useWikilinks, projectName, branch });
+    if (await writeIfChanged(indexPath, content)) changed += 1;
+    fileNames.push(`${INDEX_NOTE}.md`);
+  }
+
+  const removed = await syncManifest(vaultRoot, folder, fileNames);
+  info(`obsidian notes written to ${folder} (${fileNames.length} notes, ${changed} updated, ${removed} removed)`);
+  return { folder, files: fileNames, removed, changed };
+}

package/src/utils/branch.js

@@ -118,6 +118,22 @@ export function shouldPublishToGitHubWiki(config, currentBranch = getCurrentBran
   return matchesAnyBranch(config.github_wiki.branches, currentBranch);
 }
 
+/**
+ * Check if current branch should publish to an Obsidian vault.
+ * Based on config.obsidian.branches setting.
+ */
+export function shouldPublishToObsidian(config, currentBranch = getCurrentBranch()) {
+  if (!config.obsidian) {
+    return true;
+  }
+
+  if (!config.obsidian.branches || config.obsidian.branches.length === 0) {
+    return true;
+  }
+
+  return matchesAnyBranch(config.obsidian.branches, currentBranch);
+}
+
 /**
  * Get branch-qualified page title
  */

package/src/utils/validate.js

@@ -49,6 +49,12 @@ export function validateConfig(config) {
     warnings.push(...notionWarnings);
   }
   
+  // Validate Obsidian configuration (local vault path; no credentials)
+  if (config.obsidian) {
+    const obsidianErrors = validateObsidianConfig(config.obsidian);
+    errors.push(...obsidianErrors);
+  }
+
   // Validate domains (if present)
   if (config.domains) {
     const domainErrors = validateDomains(config.domains);
@@ -142,7 +148,7 @@ function validatePublishers(publishers) {
     return errors;
   }
   
-  const validPublishers = ["notion", "markdown", "confluence", "github_wiki"];
+  const validPublishers = ["notion", "markdown", "confluence", "github_wiki", "obsidian"];
   
   if (Array.isArray(publishers)) {
     for (const pub of publishers) {
@@ -196,6 +202,62 @@ function validateNotionConfig(notion) {
   return errors;
 }
 
+/**
+ * Validate Obsidian vault configuration.
+ * The vault may be absolute (it lives outside the repo). The folder must
+ * stay inside that vault.
+ */
+function validateObsidianConfig(obsidian) {
+  const errors = [];
+
+  if (typeof obsidian !== "object" || Array.isArray(obsidian)) {
+    errors.push("obsidian must be an object");
+    return errors;
+  }
+
+  if (obsidian.vault !== undefined) {
+    if (typeof obsidian.vault !== "string" || obsidian.vault.trim() === "") {
+      errors.push("obsidian.vault must be a non-empty string");
+    } else if (obsidian.vault.includes("\0")) {
+      errors.push("obsidian.vault contains a null byte");
+    }
+  }
+
+  if (obsidian.folder !== undefined) {
+    if (typeof obsidian.folder !== "string" || obsidian.folder.trim() === "") {
+      errors.push("obsidian.folder must be a non-empty string");
+    } else if (obsidian.folder.includes("\0")) {
+      errors.push("obsidian.folder contains a null byte");
+    } else if (
+      path.isAbsolute(obsidian.folder) ||
+      /^[A-Za-z]:[\\/]/.test(obsidian.folder) ||
+      obsidian.folder.split(/[\\/]/).some((part) => part === "..")
+    ) {
+      errors.push("obsidian.folder must be a relative path inside the vault");
+    }
+  }
+
+  if (obsidian.branches !== undefined) {
+    if (!Array.isArray(obsidian.branches)) {
+      errors.push("obsidian.branches must be an array");
+    } else {
+      for (const branch of obsidian.branches) {
+        if (typeof branch !== "string") {
+          errors.push(`Invalid branch name: ${branch} (must be string)`);
+        }
+      }
+    }
+  }
+
+  for (const flag of ["index", "frontmatter", "wikilinks"]) {
+    if (obsidian[flag] !== undefined && typeof obsidian[flag] !== "boolean") {
+      errors.push(`obsidian.${flag} must be a boolean`);
+    }
+  }
+
+  return errors;
+}
+
 /**
  * Check for Notion configuration warnings
  */