Enforce unique doc filenames and simple wiki-links

Rename section index files to match their titles (tutorials.md,
reference.md, how-to.md, explanation.md) so all filenames are unique.
Convert all path-based wiki-links to simple filename format for better
obsidian.nvim compatibility.

Update doc-filenames task to no longer skip index.md files.
Update doc-links task to reject path-based links containing '/'.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/changelog.d/unique-doc-filenames.doc.md

@@ -0,0 +1 @@
+Enforce unique filenames and simple wiki-links across all documentation for better obsidian.nvim compatibility

docs/explanation/why-gitops.md

@@ -44,8 +44,8 @@ BlumeOps uses layered GitOps:
 
 | Layer | Tool | What it manages |
 |-------|------|-----------------|
-| **Tailnet** | [[reference/infrastructure/tailscale|Pulumi]] | ACLs, tags, DNS |
-| **Host config** | [[reference/ansible/roles|Ansible]] | Services on [[indri]] |
+| **Tailnet** | [[tailscale|Pulumi]] | ACLs, tags, DNS |
+| **Host config** | [[roles|Ansible]] | Services on [[indri]] |
 | **Kubernetes** | [[argocd|ArgoCD]] | Containerized workloads |
 
 Each layer has its own reconciliation loop:
@@ -67,4 +67,4 @@ But for BlumeOps, the trade-off is worth it. The infrastructure is complex enoug
 
 - [[architecture]] - How the pieces fit together
 - [[argocd]] - Kubernetes GitOps
-- [[reference/ansible/roles|Ansible roles]] - Host configuration
+- [[roles|Ansible roles]] - Host configuration

docs/how-to/add-ansible-role.md

@@ -136,6 +136,6 @@ See [[alloy]] for how metrics are collected from textfiles.
 
 ## Related
 
-- [[reference/ansible/roles|Roles]] - Available roles reference
+- [[roles|Roles]] - Available roles reference
 - [[indri]] - Target host
 - [[observability]] - Metrics collection

docs/how-to/how-to.md

@@ -6,7 +6,7 @@ tags:
 
 # How-To Guides
 
-Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials/index|Tutorials]] if you're learning.
+Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials|Tutorials]] if you're learning.
 
 ## Deployment
 

docs/index.md

@@ -8,8 +8,8 @@ Welcome to the BlumeOps documentation.
 
 ## Sections
 
-- [[tutorials/index | Tutorials]] - Learning-oriented guides for getting started
-- [[reference/index | Reference]] - Technical specifications and service details
-- [[how-to/index | How-to]] - Task-oriented instructions for common operations
-- [[explanation/index | Explanation]] - Understanding the "why" behind BlumeOps
+- [[tutorials|Tutorials]] - Learning-oriented guides for getting started
+- [[reference|Reference]] - Technical specifications and service details
+- [[how-to|How-to]] - Task-oriented instructions for common operations
+- [[explanation|Explanation]] - Understanding the "why" behind BlumeOps
 - [[CHANGELOG]] - Release history and changes

docs/reference/reference.md

@@ -59,7 +59,7 @@ Cluster configuration and application registry.
 
 Configuration management for [[indri]]-hosted services.
 
-- [[reference/ansible/roles | Roles]] - Available ansible roles
+- [[roles]] - Available ansible roles
 
 ## Storage
 

docs/reference/services/devpi.md

@@ -32,6 +32,6 @@ Root password stored in 1Password (blumeops vault), injected via ExternalSecret.
 
 ## Related
 
-- [[how-to/use-pypi-proxy]] - Client configuration and package uploads
+- [[use-pypi-proxy]] - Client configuration and package uploads
 - [[argocd]] - Deployment
 - [[1password]] - Secrets management

docs/tutorials/ai-assistance-guide.md

@@ -108,7 +108,7 @@ For ArgoCD operations, use the `argocd` CLI directly:
 
 For AI agents building context:
 
-- [[reference/index|Reference Index]] - Entry point for technical details
+- [[reference|Reference]] - Entry point for technical details
 - [[hosts|Host Inventory]] - What hardware exists
 - [[apps|ArgoCD Apps]] - What's deployed in Kubernetes
 - [[routing|Routing]] - How services are exposed

docs/tutorials/exploring-the-docs.md

@@ -17,18 +17,18 @@ The docs follow the [Diataxis](https://diataxis.fr/) framework:
 
 | Section | Purpose | When to Use |
 |---------|---------|-------------|
-| **[[tutorials/index | Tutorials]]** | Learning-oriented | "I'm new and want to understand" |
-| **[[reference/index | Reference]]** | Information-oriented | "I need specific technical details" |
-| **[[how-to/index | How-to]]** | Task-oriented | "I need to do X" |
-| **[[explanation/index | Explanation]]** | Understanding-oriented | "I want to understand why" |
+| **[[tutorials|Tutorials]]** | Learning-oriented | "I'm new and want to understand" |
+| **[[reference|Reference]]** | Information-oriented | "I need specific technical details" |
+| **[[how-to|How-to]]** | Task-oriented | "I need to do X" |
+| **[[explanation|Explanation]]** | Understanding-oriented | "I want to understand why" |
 
 ## Quick Paths by Audience
 
 ### For Erich (Owner)
 
 You probably want quick access to operational details:
-- [[how-to/index|How-to guides]] for common operations (deploy, troubleshoot, update ACLs)
-- [[reference/index|Reference]] has service URLs, commands, and config locations
+- [[how-to|How-to guides]] for common operations (deploy, troubleshoot, update ACLs)
+- [[reference|Reference]] has service URLs, commands, and config locations
 - [[ai-assistance-guide]] explains how to work effectively with Claude
 - Run `mise run zk-docs` to prime AI context with key documentation
 
@@ -36,29 +36,29 @@ You probably want quick access to operational details:
 
 Context for effective assistance:
 - Read [[ai-assistance-guide]] for operational conventions
-- [[reference/index|Reference]] has the technical specifics you'll need
+- [[reference|Reference]] has the technical specifics you'll need
 - The repo's `CLAUDE.md` has critical rules (especially the kubectl context requirement)
 
 ### For External Readers
 
 Understanding what this is:
-- [[explanation/index|Explanation]] covers the "why" behind design decisions
-- [[reference/index|Reference]] shows what's actually running
+- [[explanation|Explanation]] covers the "why" behind design decisions
+- [[reference|Reference]] shows what's actually running
 - Browse service pages to see specific implementations
 
 ### For Contributors
 
 Getting started with changes:
 - [[contributing]] walks through the workflow
-- [[how-to/index|How-to guides]] for specific tasks (deploy services, add roles)
-- [[reference/index|Reference]] tells you where things live
+- [[how-to|How-to guides]] for specific tasks (deploy services, add roles)
+- [[reference|Reference]] tells you where things live
 
 ### For Replicators
 
 Replicators are people who want to build their own similar homelab GitOps setup, using BlumeOps as inspiration.
 
 - [[replicating-blumeops]] provides the overview
-- [[explanation/index|Explanation]] covers architecture and design rationale
+- [[explanation|Explanation]] covers architecture and design rationale
 - The `replication/` tutorials go deep on components
 - Reference pages show specific configuration choices
 
@@ -66,8 +66,7 @@ Replicators are people who want to build their own similar homelab GitOps setup,
 
 Documentation uses `[[wiki-links]]` for cross-references:
 - `[[service-name]]` links to a reference page
-- `[[folder/page]]` links to nested pages
-- `[[page | Display Text]]` customizes the link text
+- `[[page|Display Text]]` customizes the link text
 
 When reading on the web (docs.ops.eblu.me), these render as clickable links. The backlinks panel shows what references each page.
 

docs/tutorials/replicating-blumeops.md

@@ -38,7 +38,7 @@ You can start with a single machine and add storage later.
 
 Before deploying services, establish secure connectivity.
 
-**[[tutorials/replication/tailscale-setup|Setting Up Tailscale]]**
+**[[tailscale-setup|Setting Up Tailscale]]**
 - Create a tailnet and connect your devices
 - Configure ACLs for service access
 - Set up MagicDNS for convenient naming
@@ -49,7 +49,7 @@ This replaces: traditional VPNs, port forwarding, dynamic DNS
 
 Bootstrap the essential services that everything else depends on.
 
-**[[tutorials/replication/core-services | Core Services Setup]]**
+**[[core-services|Core Services Setup]]**
 - Set up [[forgejo]] for git hosting and CI/CD
 - Optionally set up [[zot]] container registry
 - Configure SSH access and deploy keys
@@ -60,7 +60,7 @@ Forgejo is central to GitOps - it's where your infrastructure definitions live a
 
 A cluster for running containerized workloads.
 
-**[[tutorials/replication/kubernetes-bootstrap|Bootstrapping Kubernetes]]**
+**[[kubernetes-bootstrap|Bootstrapping Kubernetes]]**
 - Install minikube (or k3s, kind, etc.)
 - Configure persistent storage
 - Expose the API securely via Tailscale
@@ -71,7 +71,7 @@ BlumeOps uses minikube for simplicity, but the patterns apply to any distributio
 
 Declarative, git-driven deployments.
 
-**[[tutorials/replication/argocd-config|Configuring ArgoCD]]**
+**[[argocd-config|Configuring ArgoCD]]**
 - Install ArgoCD in your cluster
 - Connect to your git repository
 - Deploy your first application
@@ -83,7 +83,7 @@ This is the heart of GitOps - changes in git automatically sync to your cluster.
 
 Know what's happening in your infrastructure.
 
-**[[tutorials/replication/observability-stack|Building the Observability Stack]]**
+**[[observability-stack|Building the Observability Stack]]**
 - Deploy Prometheus for metrics
 - Deploy Loki for logs
 - Deploy Grafana for dashboards
@@ -131,9 +131,9 @@ The principles (GitOps, IaC, observability) matter more than specific tools.
 
 ## Getting Started
 
-Begin with [[tutorials/replication/tailscale-setup]] - networking is the foundation everything else builds on.
+Begin with [[tailscale-setup]] - networking is the foundation everything else builds on.
 
 ## Related
 
-- [[reference/index]] - See BlumeOps' specific configurations
+- [[reference]] - See BlumeOps' specific configurations
 - [[contributing]] - Help improve BlumeOps instead

docs/tutorials/replication/argocd-config.md

@@ -198,7 +198,7 @@ BlumeOps uses manual sync for workloads, auto sync only for the `apps` Applicati
 
 ## Next Steps
 
-- [[tutorials/replication/observability-stack | Build observability]] - Monitor your deployments
+- [[observability-stack|Build observability]] - Monitor your deployments
 - Add more applications to your repo
 - Set up notifications for sync failures
 

docs/tutorials/replication/core-services.md

@@ -10,7 +10,7 @@ tags:
 
 > **Audiences:** Replicator
 >
-> **Prerequisites:** [[tutorials/replication/tailscale-setup | Tailscale Setup]]
+> **Prerequisites:** [[tailscale-setup|Tailscale Setup]]
 
 This tutorial walks through setting up the foundational services that your GitOps infrastructure depends on: a git forge and optionally a container registry.
 
@@ -29,7 +29,7 @@ Forgejo runs directly on your server (not in Kubernetes) because Kubernetes depe
 
 ### Using Ansible (BlumeOps Approach)
 
-BlumeOps manages Forgejo via an Ansible role. See [[reference/ansible/roles | Ansible Roles]].
+BlumeOps manages Forgejo via an Ansible role. See [[roles|Ansible Roles]].
 
 ### Manual Installation
 
@@ -101,7 +101,7 @@ For getting started, you can skip this and use public registries.
 
 ## Next Steps
 
-- [[tutorials/replication/kubernetes-bootstrap | Bootstrap Kubernetes]] - Now that you have a git repo, set up your cluster
+- [[kubernetes-bootstrap|Bootstrap Kubernetes]] - Now that you have a git repo, set up your cluster
 - Configure Forgejo webhooks for ArgoCD (after ArgoCD is running)
 
 ## BlumeOps Specifics

docs/tutorials/replication/kubernetes-bootstrap.md

@@ -148,7 +148,7 @@ spec:
 
 ## Next Steps
 
-- [[tutorials/replication/argocd-config | Configure ArgoCD]] - GitOps deployments
+- [[argocd-config|Configure ArgoCD]] - GitOps deployments
 - Install essential addons (ingress controller, cert-manager)
 
 ## BluemeOps Specifics

docs/tutorials/replication/observability-stack.md

@@ -177,7 +177,7 @@ spec:
     namespace: monitoring
 ```
 
-BluemeOps uses Alloy on both [[indri]] (for host metrics, via [[reference/ansible/roles | Ansible role]]) and in the [[cluster]] (for pod logs and service probes).
+BluemeOps uses Alloy on both [[indri]] (for host metrics, via [[roles|Ansible role]]) and in the [[cluster]] (for pod logs and service probes).
 
 ## What You Now Have
 

docs/tutorials/replication/tailscale-setup.md

@@ -112,8 +112,8 @@ Tags must be defined in ACLs before use.
 ## Next Steps
 
 With networking established:
-- [[tutorials/replication/core-services | Set Up Core Services]] - Install Forgejo and optionally a container registry
-- [[tutorials/replication/kubernetes-bootstrap | Bootstrap Kubernetes]] - Your cluster will join the tailnet
+- [[core-services|Set Up Core Services]] - Install Forgejo and optionally a container registry
+- [[kubernetes-bootstrap|Bootstrap Kubernetes]] - Your cluster will join the tailnet
 
 ## BlumeOps Specifics
 

docs/tutorials/tutorials.md

@@ -41,8 +41,8 @@ For those building their own homelab GitOps setup.
 | Tutorial | Audiences | Description |
 |----------|-----------|-------------|
 | [[replicating-blumeops]] | Replicator | Overview: building a similar environment |
-| [[tutorials/replication/tailscale-setup | Tailscale Setup]] | Replicator | Setting up Tailscale networking |
-| [[tutorials/replication/core-services | Core Services]] | Replicator | Forgejo and container registry |
-| [[tutorials/replication/kubernetes-bootstrap | Kubernetes Bootstrap]] | Replicator | Bootstrapping a Kubernetes cluster |
-| [[tutorials/replication/argocd-config | ArgoCD Config]] | Replicator | Configuring GitOps with ArgoCD |
-| [[tutorials/replication/observability-stack | Observability Stack]] | Replicator | Metrics, logs, and dashboards |
+| [[tailscale-setup|Tailscale Setup]] | Replicator | Setting up Tailscale networking |
+| [[core-services|Core Services]] | Replicator | Forgejo and container registry |
+| [[kubernetes-bootstrap|Kubernetes Bootstrap]] | Replicator | Bootstrapping a Kubernetes cluster |
+| [[argocd-config|ArgoCD Config]] | Replicator | Configuring GitOps with ArgoCD |
+| [[observability-stack|Observability Stack]] | Replicator | Metrics, logs, and dashboards |

mise-tasks/doc-filenames

@@ -33,13 +33,10 @@ def main() -> int:
     # Key: filename (without .md), Value: list of file paths
     filenames: dict[str, list[str]] = defaultdict(list)
 
-    # Scan all markdown files (excluding zk/, changelog.d/, and index.md files)
+    # Scan all markdown files (excluding zk/ and changelog.d/)
     for md_file in sorted(DOCS_DIR.rglob("*.md")):
         if "changelog.d" in md_file.parts or "zk" in md_file.parts:
             continue
-        # Skip index.md files - they're expected to exist in multiple directories
-        if md_file.name == "index.md":
-            continue
 
         rel_path = str(md_file.relative_to(DOCS_DIR))
         filename = md_file.stem  # filename without .md

mise-tasks/doc-links

@@ -8,12 +8,14 @@
 
 This script scans all markdown files in the docs/ directory (excluding
 changelog.d/), extracts wiki-links, and verifies each link target
-exists as a filename or path in the documentation.
+exists as a unique filename in the documentation.
 
 Wiki-link formats supported:
-- [[filename]] - links to filename.md (must be unique)
-- [[path/to/file]] - links to path/to/file.md (for ambiguous filenames like index)
-- [[target | Display Text]] - either format with display text
+- [[filename]] - links to filename.md (must be unique across all docs)
+- [[target|Display Text]] - filename with display text
+
+Path-based links (containing '/') are NOT supported to ensure all
+filenames are unique and links work correctly in obsidian.nvim.
 
 Usage: mise run doc-links
 """
@@ -90,9 +92,10 @@ def main() -> int:
         if (REPO_ROOT / filename).exists():
             valid_targets.add(Path(filename).stem)
 
-    # Collect all broken and ambiguous links
+    # Collect all broken, ambiguous, and path-based links
     broken_links: list[tuple[str, int, str]] = []
     ambiguous_links: list[tuple[str, int, str, list[str]]] = []
+    path_links: list[tuple[str, int, str]] = []
 
     # Scan all markdown files for wiki-links (excluding changelog.d/)
     for md_file in sorted(DOCS_DIR.rglob("*.md")):
@@ -103,8 +106,11 @@ def main() -> int:
         links = extract_wikilinks(md_file)
 
         for target, line_num in links:
-            if target in ambiguous_filenames:
-                # Link uses an ambiguous filename - needs to use full path
+            if "/" in target:
+                # Path-based links are not allowed - use simple filenames only
+                path_links.append((rel_path, line_num, target))
+            elif target in ambiguous_filenames:
+                # Link uses an ambiguous filename - needs to be renamed
                 ambiguous_links.append((rel_path, line_num, target, filename_counts[target]))
             elif target not in valid_targets:
                 broken_links.append((rel_path, line_num, target))
@@ -117,11 +123,28 @@ def main() -> int:
 
     has_errors = False
 
+    if path_links:
+        has_errors = True
+        console.print("[bold red]Path-Based Wiki-Links Found[/bold red]")
+        console.print("Wiki-links must use simple filenames only (no '/' paths).")
+        console.print("Rename files to be unique, then use [[filename]] format.")
+        console.print()
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("File")
+        table.add_column("Line", justify="right")
+        table.add_column("Target")
+
+        for file_path, line_num, target in path_links:
+            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))
+
+        console.print(table)
+        console.print()
+
     if ambiguous_links:
         has_errors = True
         console.print("[bold red]Ambiguous Wiki-Links Found[/bold red]")
         console.print("These links use filenames that exist in multiple locations.")
-        console.print("Use the full path instead (e.g., [[reference/index]] not [[index]]).")
+        console.print("Rename files to be unique across all documentation.")
         console.print()
         table = Table(show_header=True, header_style="bold")
         table.add_column("File")