diff --git a/docs/changelog.d/unique-doc-filenames.doc.md b/docs/changelog.d/unique-doc-filenames.doc.md
new file mode 100644
index 0000000..5949a60
--- /dev/null
+++ b/docs/changelog.d/unique-doc-filenames.doc.md
@@ -0,0 +1 @@
+Enforce unique filenames, simple wiki-links (no paths), and no spaces in wiki-link targets for obsidian.nvim compatibility
diff --git a/docs/explanation/index.md b/docs/explanation/explanation.md
similarity index 100%
rename from docs/explanation/index.md
rename to docs/explanation/explanation.md
diff --git a/docs/explanation/why-gitops.md b/docs/explanation/why-gitops.md
index 6a98d24..126212c 100644
--- a/docs/explanation/why-gitops.md
+++ b/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
diff --git a/docs/how-to/add-ansible-role.md b/docs/how-to/add-ansible-role.md
index a8ab8d5..e30a562 100644
--- a/docs/how-to/add-ansible-role.md
+++ b/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
diff --git a/docs/how-to/index.md b/docs/how-to/how-to.md
similarity index 95%
rename from docs/how-to/index.md
rename to docs/how-to/how-to.md
index a6fe23f..e4582c4 100644
--- a/docs/how-to/index.md
+++ b/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
 
diff --git a/docs/index.md b/docs/index.md
index 2a2bec1..3fa7a3d 100644
--- a/docs/index.md
+++ b/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
diff --git a/docs/reference/infrastructure/gilbert.md b/docs/reference/infrastructure/gilbert.md
index b4ed983..72e04cb 100644
--- a/docs/reference/infrastructure/gilbert.md
+++ b/docs/reference/infrastructure/gilbert.md
@@ -24,4 +24,4 @@ Managed via `Brewfile` and `mise.toml` in the blumeops repo.
 ## Related
 
 - [[indri]] - Server accessed from gilbert
-- [[cluster | Cluster]] - Remote k8s access
+- [[cluster|Cluster]] - Remote k8s access
diff --git a/docs/reference/infrastructure/hosts.md b/docs/reference/infrastructure/hosts.md
index a4a4d86..b66b76b 100644
--- a/docs/reference/infrastructure/hosts.md
+++ b/docs/reference/infrastructure/hosts.md
@@ -12,9 +12,9 @@ All devices connected via [Tailscale](https://login.tailscale.com/) tailnet `tai
 
 | Host | Description | Card |
 |------|-------------|------|
-| **Indri** | Mac Mini M1, 2020 - Primary server | [[indri | Details]] |
-| **Gilbert** | MacBook Air M4, 2025 - Workstation | [[gilbert | Details]] |
-| **[[sifaka | Sifaka]]** | Synology NAS - Storage & backups | [[sifaka | Details]] |
+| **Indri** | Mac Mini M1, 2020 - Primary server | [[indri|Details]] |
+| **Gilbert** | MacBook Air M4, 2025 - Workstation | [[gilbert|Details]] |
+| **[[sifaka|Sifaka]]** | Synology NAS - Storage & backups | [[sifaka|Details]] |
 | **Mouse** | MacBook Air M2 - Allison's laptop | - |
 | **UniFi** | UniFi Express 7 - Home WiFi | - |
 | **Dwarf** | iPad Air - Employer-provided, off tailnet | - |
@@ -22,4 +22,4 @@ All devices connected via [Tailscale](https://login.tailscale.com/) tailnet `tai
 ## Related
 
 - [[tailscale]] - Network configuration
-- [[routing | Routing]] - Service URLs
+- [[routing|Routing]] - Service URLs
diff --git a/docs/reference/infrastructure/indri.md b/docs/reference/infrastructure/indri.md
index 443129f..00206b9 100644
--- a/docs/reference/infrastructure/indri.md
+++ b/docs/reference/infrastructure/indri.md
@@ -26,11 +26,11 @@ Primary BlumeOps server. Mac Mini M1 (2020).
 - [[zot]] - Container registry
 - [[jellyfin]] - Media server
 - [[borgmatic]] - Backup system
-- [[alloy | Alloy]] - Metrics/logs collector
+- [[alloy|Alloy]] - Metrics/logs collector
 - [[caddy]] - Reverse proxy for `*.ops.eblu.me`
 
 **Kubernetes (via minikube):**
-- [[apps | All k8s applications]]
+- [[apps|All k8s applications]]
 
 **GUI Applications (manual start required):**
 - Docker Desktop - Container runtime for minikube
diff --git a/docs/reference/infrastructure/routing.md b/docs/reference/infrastructure/routing.md
index 09abf8b..1b687ae 100644
--- a/docs/reference/infrastructure/routing.md
+++ b/docs/reference/infrastructure/routing.md
@@ -38,7 +38,7 @@ DNS points to indri's Tailscale IP (100.98.163.89). TLS via Let's Encrypt (ACME
 | [[navidrome]] | https://dj.ops.eblu.me | Music streaming |
 | [[jellyfin]] | https://jellyfin.ops.eblu.me | Media server |
 | [[postgresql]] | pg.ops.eblu.me:5432 | Database |
-| [[sifaka | Sifaka]] | https://nas.ops.eblu.me | NAS dashboard |
+| [[sifaka|Sifaka]] | https://nas.ops.eblu.me | NAS dashboard |
 
 ## Tailscale-Only Services
 
diff --git a/docs/reference/infrastructure/tailscale.md b/docs/reference/infrastructure/tailscale.md
index 423734c..e70e406 100644
--- a/docs/reference/infrastructure/tailscale.md
+++ b/docs/reference/infrastructure/tailscale.md
@@ -58,5 +58,5 @@ Pulumi uses OAuth client from 1Password (blumeops vault):
 
 ## Related
 
-- [[routing | Routing]] - Service URLs
-- [[hosts | Hosts]] - Device inventory
+- [[routing|Routing]] - Service URLs
+- [[hosts|Hosts]] - Device inventory
diff --git a/docs/reference/kubernetes/apps.md b/docs/reference/kubernetes/apps.md
index 298aafc..715c6ba 100644
--- a/docs/reference/kubernetes/apps.md
+++ b/docs/reference/kubernetes/apps.md
@@ -26,7 +26,7 @@ Registry of all applications deployed via [[argocd]].
 | `grafana` | monitoring | Helm chart (forge mirror) | [[grafana]] |
 | `grafana-config` | monitoring | `argocd/manifests/grafana-config/` | [[grafana]] |
 | `immich` | immich | Helm chart | [[immich]] |
-| `alloy-k8s` | alloy | `argocd/manifests/alloy-k8s/` | [[alloy | Alloy]] |
+| `alloy-k8s` | alloy | `argocd/manifests/alloy-k8s/` | [[alloy|Alloy]] |
 | `kube-state-metrics` | monitoring | `argocd/manifests/kube-state-metrics/` | K8s metrics |
 | `miniflux` | miniflux | `argocd/manifests/miniflux/` | [[miniflux]] |
 | `kiwix` | kiwix | `argocd/manifests/kiwix/` | [[kiwix]] |
@@ -45,4 +45,4 @@ Registry of all applications deployed via [[argocd]].
 ## Related
 
 - [[argocd]] - GitOps platform details
-- [[cluster | Cluster]] - Kubernetes infrastructure
+- [[cluster|Cluster]] - Kubernetes infrastructure
diff --git a/docs/reference/kubernetes/cluster.md b/docs/reference/kubernetes/cluster.md
index f22d274..72af96c 100644
--- a/docs/reference/kubernetes/cluster.md
+++ b/docs/reference/kubernetes/cluster.md
@@ -24,7 +24,7 @@ Single-node Minikube cluster running on [[indri]].
 
 ## Volume Mounting
 
-Pods mount NFS directly from [[sifaka | Sifaka]]. Docker NATs outbound traffic through indri's LAN IP (192.168.1.50), allowing access to Sifaka's NFS exports.
+Pods mount NFS directly from [[sifaka|Sifaka]]. Docker NATs outbound traffic through indri's LAN IP (192.168.1.50), allowing access to Sifaka's NFS exports.
 
 ## Registry Mirror
 
@@ -34,6 +34,6 @@ Mirrors configured: `registry.ops.eblu.me`, `docker.io`, `ghcr.io`, `quay.io`
 
 ## Related
 
-- [[apps | Apps]] - ArgoCD applications
+- [[apps|Apps]] - ArgoCD applications
 - [[argocd]] - GitOps deployment
 - [[zot]] - Registry mirror
diff --git a/docs/reference/kubernetes/tailscale-operator.md b/docs/reference/kubernetes/tailscale-operator.md
index 8df8df3..580f948 100644
--- a/docs/reference/kubernetes/tailscale-operator.md
+++ b/docs/reference/kubernetes/tailscale-operator.md
@@ -31,7 +31,7 @@ Services exposed via Tailscale Ingress are **not accessible** from:
 - Other Kubernetes pods (they're not Tailscale clients)
 - Docker containers on indri
 
-For pod-to-service communication, use [[routing | Caddy]] (`*.ops.eblu.me`) instead.
+For pod-to-service communication, use [[routing|Caddy]] (`*.ops.eblu.me`) instead.
 
 ## Related
 
diff --git a/docs/reference/operations/backup.md b/docs/reference/operations/backup.md
index fd3a31c..c84b164 100644
--- a/docs/reference/operations/backup.md
+++ b/docs/reference/operations/backup.md
@@ -11,5 +11,5 @@ Daily automated backups of BlumeOps data.
 ## Components
 
 - [[borgmatic]] - Backup orchestration
-- [[sifaka | Sifaka]] - Backup target (NAS)
-- [[backups | backup-policy]] - What gets backed up and retention
+- [[sifaka|Sifaka]] - Backup target (NAS)
+- [[backups|backup-policy]] - What gets backed up and retention
diff --git a/docs/reference/operations/disaster-recovery.md b/docs/reference/operations/disaster-recovery.md
index fbe19cd..6244fce 100644
--- a/docs/reference/operations/disaster-recovery.md
+++ b/docs/reference/operations/disaster-recovery.md
@@ -8,7 +8,7 @@ tags:
 
 TBD. Current state:
 
-- [[borgmatic]] provides daily backups to [[sifaka | Sifaka]]
+- [[borgmatic]] provides daily backups to [[sifaka|Sifaka]]
 - Infrastructure can be rebootstrapped using the blumeops repo
 - Detailed DR procedures not yet documented
 
diff --git a/docs/reference/operations/observability.md b/docs/reference/operations/observability.md
index 1673d25..f702235 100644
--- a/docs/reference/operations/observability.md
+++ b/docs/reference/operations/observability.md
@@ -12,5 +12,5 @@ Metrics, logs, and dashboards for BlumeOps infrastructure.
 
 - [[prometheus]] - Metrics storage and querying
 - [[loki]] - Log aggregation
-- [[alloy | Alloy]] - Metrics and log collection
+- [[alloy|Alloy]] - Metrics and log collection
 - [[grafana]] - Dashboards and visualization
diff --git a/docs/reference/index.md b/docs/reference/reference.md
similarity index 81%
rename from docs/reference/index.md
rename to docs/reference/reference.md
index c86d62e..49ac915 100644
--- a/docs/reference/index.md
+++ b/docs/reference/reference.md
@@ -14,7 +14,7 @@ Individual service reference cards with URLs and configuration details.
 
 | Service | Description | Location |
 |---------|-------------|----------|
-| [[alloy | Alloy]] | Observability collector (metrics & logs) | indri + k8s |
+| [[alloy|Alloy]] | Observability collector (metrics & logs) | indri + k8s |
 | [[argocd]] | GitOps continuous delivery | k8s |
 | [[borgmatic]] | Backup system | indri |
 | [[caddy]] | Reverse proxy & TLS termination | indri |
@@ -40,18 +40,18 @@ Individual service reference cards with URLs and configuration details.
 
 Host inventory and network configuration.
 
-- [[hosts | Hosts]] - Device inventory
+- [[hosts|Hosts]] - Device inventory
 - [[indri]] - Primary server
 - [[gilbert]] - Development workstation
 - [[tailscale]] - ACLs, groups, tags
-- [[routing | Routing]] - DNS domains, port mappings
+- [[routing|Routing]] - DNS domains, port mappings
 
 ## Kubernetes
 
 Cluster configuration and application registry.
 
-- [[cluster | Cluster]] - Minikube specs, storage, networking
-- [[apps | Apps]] - ArgoCD application registry
+- [[cluster|Cluster]] - Minikube specs, storage, networking
+- [[apps|Apps]] - ArgoCD application registry
 - [[tailscale-operator]] - Tailscale ingress for k8s services
 - [[external-secrets]] - Secrets management
 
@@ -59,15 +59,15 @@ Cluster configuration and application registry.
 
 Configuration management for [[indri]]-hosted services.
 
-- [[reference/ansible/roles | Roles]] - Available ansible roles
+- [[roles]] - Available ansible roles
 
 ## Storage
 
 Network storage and backup configuration.
 
-- [[sifaka | Sifaka]] - Synology NAS configuration
+- [[sifaka|Sifaka]] - Synology NAS configuration
 - [[postgresql-storage]] - Database cluster
-- [[backups | Backups]] - Backup policy and schedule
+- [[backups|Backups]] - Backup policy and schedule
 
 ## Operations
 
diff --git a/docs/reference/services/argocd.md b/docs/reference/services/argocd.md
index fb37539..ca49dc1 100644
--- a/docs/reference/services/argocd.md
+++ b/docs/reference/services/argocd.md
@@ -7,7 +7,7 @@ tags:
 
 # ArgoCD
 
-GitOps continuous delivery platform for the [[cluster | Kubernetes cluster]].
+GitOps continuous delivery platform for the [[cluster|Kubernetes cluster]].
 
 ## Quick Reference
 
@@ -33,5 +33,5 @@ GitOps continuous delivery platform for the [[cluster | Kubernetes cluster]].
 
 ## Related
 
-- [[apps | Apps]] - Full application registry
+- [[apps|Apps]] - Full application registry
 - [[forgejo]] - Git source
diff --git a/docs/reference/services/borgmatic.md b/docs/reference/services/borgmatic.md
index 2abf5c0..071a52f 100644
--- a/docs/reference/services/borgmatic.md
+++ b/docs/reference/services/borgmatic.md
@@ -16,7 +16,7 @@ Daily backup system using Borg backup, running on indri.
 | **Install** | mise (pipx) |
 | **Config** | `~/.config/borgmatic/config.yaml` |
 | **Schedule** | Daily at 2:00 AM |
-| **Repository** | `/Volumes/backups/borg/` on [[sifaka | Sifaka]] |
+| **Repository** | `/Volumes/backups/borg/` on [[sifaka|Sifaka]] |
 
 ## What Gets Backed Up
 
@@ -54,6 +54,6 @@ Dashboard: "Borgmatic Backups" in [[grafana]]
 
 ## Related
 
-- [[backups | Backups]] - Full backup policy
-- [[sifaka | Sifaka]] - Backup target
+- [[backups|Backups]] - Full backup policy
+- [[sifaka|Sifaka]] - Backup target
 - [[postgresql]] - Database backups
diff --git a/docs/reference/services/devpi.md b/docs/reference/services/devpi.md
index 9c20c32..085666d 100644
--- a/docs/reference/services/devpi.md
+++ b/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
diff --git a/docs/reference/services/grafana.md b/docs/reference/services/grafana.md
index 1810017..7e11397 100644
--- a/docs/reference/services/grafana.md
+++ b/docs/reference/services/grafana.md
@@ -47,4 +47,4 @@ Optional annotation: `grafana_folder: "FolderName"`
 
 - [[prometheus]] - Metrics datasource
 - [[loki]] - Logs datasource
-- [[alloy | Alloy]] - Data collector
+- [[alloy|Alloy]] - Data collector
diff --git a/docs/reference/services/immich.md b/docs/reference/services/immich.md
index d590be4..e31dfd4 100644
--- a/docs/reference/services/immich.md
+++ b/docs/reference/services/immich.md
@@ -17,10 +17,10 @@ Self-hosted photo and video management.
 | **Namespace** | `immich` |
 | **Deployment** | Helm chart (k8s) |
 | **Database** | [[postgresql]] (CNPG) |
-| **Storage** | [[sifaka | Sifaka]] photos volume |
+| **Storage** | [[sifaka|Sifaka]] photos volume |
 
 ## Related
 
 - [[postgresql]] - Database backend
-- [[sifaka | Sifaka]] - Photo storage
+- [[sifaka|Sifaka]] - Photo storage
 - [[jellyfin]] - Video streaming (separate service)
diff --git a/docs/reference/services/jellyfin.md b/docs/reference/services/jellyfin.md
index 067a93f..2673cac 100644
--- a/docs/reference/services/jellyfin.md
+++ b/docs/reference/services/jellyfin.md
@@ -42,10 +42,10 @@ Dashboard > Playback:
 ## Observability
 
 - Metrics: `jellyfin_metrics` ansible role
-- Logs: Forwarded via [[alloy | Alloy]]
+- Logs: Forwarded via [[alloy|Alloy]]
 - Dashboard: "Jellyfin Media Server" in [[grafana]]
 
 ## Related
 
 - [[navidrome]] - Music streaming
-- [[sifaka | Sifaka]] - Media storage
+- [[sifaka|Sifaka]] - Media storage
diff --git a/docs/reference/services/kiwix.md b/docs/reference/services/kiwix.md
index 368559b..8c0ffc2 100644
--- a/docs/reference/services/kiwix.md
+++ b/docs/reference/services/kiwix.md
@@ -17,7 +17,7 @@ Offline Wikipedia and ZIM archive server.
 | **Tailscale URL** | https://kiwix.tail8d86e.ts.net |
 | **Namespace** | `kiwix` |
 | **Image** | `ghcr.io/kiwix/kiwix-serve:3.8.1` |
-| **Storage** | NFS from [[sifaka | Sifaka]] (`/volume1/torrents`) |
+| **Storage** | NFS from [[sifaka|Sifaka]] (`/volume1/torrents`) |
 
 ## Architecture
 
@@ -49,4 +49,4 @@ Full list: `argocd/manifests/kiwix/configmap-zim-torrents.yaml`
 ## Related
 
 - [[transmission]] - Downloads ZIM files
-- [[sifaka | Sifaka]] - ZIM storage
+- [[sifaka|Sifaka]] - ZIM storage
diff --git a/docs/reference/services/loki.md b/docs/reference/services/loki.md
index 2013cc1..49f168e 100644
--- a/docs/reference/services/loki.md
+++ b/docs/reference/services/loki.md
@@ -24,7 +24,7 @@ Log aggregation system for BlumeOps infrastructure.
 
 - Single-node deployment with filesystem storage
 - TSDB index with 24h period
-- Logs collected by [[alloy | Alloy]] and pushed via Loki API
+- Logs collected by [[alloy|Alloy]] and pushed via Loki API
 - Queried via [[grafana]]
 
 ## Log Sources
@@ -46,6 +46,6 @@ Log aggregation system for BlumeOps infrastructure.
 
 ## Related
 
-- [[alloy | Alloy]] - Log collector
+- [[alloy|Alloy]] - Log collector
 - [[grafana]] - Log visualization
 - [[prometheus]] - Metrics counterpart
diff --git a/docs/reference/services/navidrome.md b/docs/reference/services/navidrome.md
index 20e5b1e..6044fe8 100644
--- a/docs/reference/services/navidrome.md
+++ b/docs/reference/services/navidrome.md
@@ -39,4 +39,4 @@ The `/data` directory contains SQLite database, configuration, and cache.
 ## Related
 
 - [[jellyfin]] - Video streaming
-- [[sifaka | Sifaka]] - Music storage
+- [[sifaka|Sifaka]] - Music storage
diff --git a/docs/reference/services/postgresql.md b/docs/reference/services/postgresql.md
index c09ed7c..27f8b3d 100644
--- a/docs/reference/services/postgresql.md
+++ b/docs/reference/services/postgresql.md
@@ -34,7 +34,7 @@ Database cluster via CloudNativePG operator.
 | miniflux | app owner | Owns miniflux database |
 | teslamate | superuser | TeslaMate (needs extensions) |
 | eblume | superuser | Admin access |
-| borgmatic | pg_read_all_data | [[borgmatic | Backup]] access |
+| borgmatic | pg_read_all_data | [[borgmatic|Backup]] access |
 
 ## Backup
 
diff --git a/docs/reference/services/prometheus.md b/docs/reference/services/prometheus.md
index fd76b81..2eacd0e 100644
--- a/docs/reference/services/prometheus.md
+++ b/docs/reference/services/prometheus.md
@@ -23,19 +23,19 @@ Metrics storage and querying for BlumeOps infrastructure.
 ## Data Sources
 
 ### Remote Write (from Alloy)
-- Indri system metrics via [[alloy | Alloy]] remote_write
+- Indri system metrics via [[alloy|Alloy]] remote_write
 - Textfile metrics: minikube, borgmatic, zot, jellyfin
 
 ### Scrape Targets
 
 | Target | Metrics |
 |--------|---------|
-| `sifaka:9100` | [[sifaka | Sifaka]] NAS (node_exporter) |
-| `cnpg-metrics.tail8d86e.ts.net:9187` | [[postgresql | CloudNativePG]] metrics |
+| `sifaka:9100` | [[sifaka|Sifaka]] NAS (node_exporter) |
+| `cnpg-metrics.tail8d86e.ts.net:9187` | [[postgresql|CloudNativePG]] metrics |
 | `kube-state-metrics.monitoring.svc:8080` | Kubernetes resource metrics |
 
 ## Related
 
-- [[alloy | Alloy]] - Metrics collector
+- [[alloy|Alloy]] - Metrics collector
 - [[grafana]] - Visualization
 - [[loki]] - Logs counterpart
diff --git a/docs/reference/services/transmission.md b/docs/reference/services/transmission.md
index 7f22af3..d34302c 100644
--- a/docs/reference/services/transmission.md
+++ b/docs/reference/services/transmission.md
@@ -17,7 +17,7 @@ BitTorrent daemon, primarily for downloading ZIM archives for [[kiwix]].
 | **Tailscale URL** | https://torrent.tail8d86e.ts.net |
 | **Namespace** | `torrent` |
 | **Image** | `lscr.io/linuxserver/transmission:latest` |
-| **Storage** | NFS PVC from [[sifaka | Sifaka]] |
+| **Storage** | NFS PVC from [[sifaka|Sifaka]] |
 
 ## Storage Layout
 
@@ -43,11 +43,11 @@ When downloads complete, the zim-watcher CronJob detects new ZIMs and restarts K
 
 ## Monitoring
 
-Basic uptime via blackbox probe in [[alloy | Alloy]] k8s (Services Health dashboard).
+Basic uptime via blackbox probe in [[alloy|Alloy]] k8s (Services Health dashboard).
 
 Web UI shows: active/seeding/paused counts, speeds, disk usage.
 
 ## Related
 
 - [[kiwix]] - ZIM archive consumer
-- [[sifaka | Sifaka]] - Download storage
+- [[sifaka|Sifaka]] - Download storage
diff --git a/docs/reference/services/zot.md b/docs/reference/services/zot.md
index c506f31..71a9e21 100644
--- a/docs/reference/services/zot.md
+++ b/docs/reference/services/zot.md
@@ -30,7 +30,7 @@ OCI-native container registry providing pull-through cache and private image sto
 
 ## Pull-Through Cache
 
-When [[cluster | minikube]] pulls an image, containerd checks zot first. If cached, returns immediately. If not, zot fetches from upstream, caches it, then returns.
+When [[cluster|minikube]] pulls an image, containerd checks zot first. If cached, returns immediately. If not, zot fetches from upstream, caches it, then returns.
 
 ## Security Model
 
@@ -39,4 +39,4 @@ Network access only (no authentication). Defense is the Tailscale ACL boundary.
 ## Related
 
 - [[forgejo]] - Container build CI
-- [[cluster | Cluster]] - Registry consumer
+- [[cluster|Cluster]] - Registry consumer
diff --git a/docs/reference/storage/backups.md b/docs/reference/storage/backups.md
index 44cb7cc..9418eac 100644
--- a/docs/reference/storage/backups.md
+++ b/docs/reference/storage/backups.md
@@ -7,7 +7,7 @@ tags:
 
 # Backup Policy
 
-Daily automated backups from [[indri]] to [[sifaka | Sifaka]] NAS.
+Daily automated backups from [[indri]] to [[sifaka|Sifaka]] NAS.
 
 ## Schedule
 
@@ -30,8 +30,8 @@ Daily automated backups from [[indri]] to [[sifaka | Sifaka]] NAS.
 
 | Database | Host | Method |
 |----------|------|--------|
-| miniflux | [[postgresql | pg.ops.eblu.me]] | pg_dump stream |
-| teslamate | [[postgresql | pg.ops.eblu.me]] | pg_dump stream |
+| miniflux | [[postgresql|pg.ops.eblu.me]] | pg_dump stream |
+| teslamate | [[postgresql|pg.ops.eblu.me]] | pg_dump stream |
 
 ## Sifaka-Native Data
 
@@ -56,7 +56,7 @@ Some data lives directly on [[sifaka]] rather than being backed up to it (photos
 
 ## Backup Target
 
-Repository: `/Volumes/backups/borg/` on [[sifaka | Sifaka]]
+Repository: `/Volumes/backups/borg/` on [[sifaka|Sifaka]]
 
 ## Monitoring
 
@@ -70,5 +70,5 @@ Dashboard: "Borgmatic Backups" in [[grafana]]
 ## Related
 
 - [[borgmatic]] - Backup system details
-- [[sifaka | Sifaka]] - Backup storage
+- [[sifaka|Sifaka]] - Backup storage
 - [[postgresql]] - Database backups
diff --git a/docs/reference/storage/sifaka.md b/docs/reference/storage/sifaka.md
index 81e6391..c6c961f 100644
--- a/docs/reference/storage/sifaka.md
+++ b/docs/reference/storage/sifaka.md
@@ -46,13 +46,13 @@ Node exporter running in Docker container, scraped by [[prometheus]] at `sifaka:
 
 ## Backup
 
-Sifaka is the **target** for [[backup | backups]], not a backup source. [[borgmatic]] sends backups TO sifaka, not OF sifaka.
+Sifaka is the **target** for [[backup|backups]], not a backup source. [[borgmatic]] sends backups TO sifaka, not OF sifaka.
 
 Data protection for sifaka itself currently relies on the Synology RAID 5 configuration, which provides single-disk fault tolerance. Future plans include offsite duplication for additional resiliency.
 
 ## Related
 
-- [[backups | Backups]] - Backup policy
+- [[backups|Backups]] - Backup policy
 - [[borgmatic]] - Backup system
 - [[immich]] - Photo consumer
 - [[jellyfin]] - Media consumer
diff --git a/docs/tutorials/adding-a-service.md b/docs/tutorials/adding-a-service.md
index b61c2dc..aba61d4 100644
--- a/docs/tutorials/adding-a-service.md
+++ b/docs/tutorials/adding-a-service.md
@@ -14,7 +14,7 @@ This tutorial walks through deploying a new service to BlumeOps via ArgoCD, incl
 
 ## Prerequisites
 
-- Access to the [[tailscale | Tailscale]] network
+- Access to the [[tailscale|Tailscale]] network
 - `kubectl` configured with `minikube-indri` context
 - `argocd` CLI installed (via Brewfile: `brew bundle`)
 
diff --git a/docs/tutorials/ai-assistance-guide.md b/docs/tutorials/ai-assistance-guide.md
index c553dec..0b62620 100644
--- a/docs/tutorials/ai-assistance-guide.md
+++ b/docs/tutorials/ai-assistance-guide.md
@@ -62,9 +62,9 @@ Types (file suffix): `.feature`, `.bugfix`, `.infra`, `.doc`, `.ai`, `.misc`
 ### Wiki-Link Formatting
 
 Use simple wiki-links without alternate text or extra spaces:
-- Prefer `[[borgmatic]]` over `[[borgmatic | Borgmatic]]`
+- Prefer `[[borgmatic]]` over `[[borgmatic|Borgmatic]]`
 - Only use alternate text when grammatically warranted (e.g., `[[cluster|Kubernetes]]` reads better than `[[cluster]]`)
-- No spaces around the pipe: `[[path|Text]]` not `[[ path | Text ]]`
+- No spaces around the pipe: `[[path|Text]]` not `[[ path|Text ]]`
 
 When editing documentation, rewrite links to follow this convention as you encounter them.
 
@@ -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
diff --git a/docs/tutorials/exploring-the-docs.md b/docs/tutorials/exploring-the-docs.md
index 1e356ec..8cf09e1 100644
--- a/docs/tutorials/exploring-the-docs.md
+++ b/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.
 
diff --git a/docs/tutorials/replicating-blumeops.md b/docs/tutorials/replicating-blumeops.md
index 6ddb5c5..b58e425 100644
--- a/docs/tutorials/replicating-blumeops.md
+++ b/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
diff --git a/docs/tutorials/replication/argocd-config.md b/docs/tutorials/replication/argocd-config.md
index 2dcbe85..91e5637 100644
--- a/docs/tutorials/replication/argocd-config.md
+++ b/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
 
diff --git a/docs/tutorials/replication/core-services.md b/docs/tutorials/replication/core-services.md
index 100598e..85af3ac 100644
--- a/docs/tutorials/replication/core-services.md
+++ b/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
diff --git a/docs/tutorials/replication/kubernetes-bootstrap.md b/docs/tutorials/replication/kubernetes-bootstrap.md
index b92c025..7ffc9fa 100644
--- a/docs/tutorials/replication/kubernetes-bootstrap.md
+++ b/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
diff --git a/docs/tutorials/replication/observability-stack.md b/docs/tutorials/replication/observability-stack.md
index 4c3adb2..67c356c 100644
--- a/docs/tutorials/replication/observability-stack.md
+++ b/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
 
diff --git a/docs/tutorials/replication/tailscale-setup.md b/docs/tutorials/replication/tailscale-setup.md
index 23b9ea2..07a2217 100644
--- a/docs/tutorials/replication/tailscale-setup.md
+++ b/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
 
diff --git a/docs/tutorials/index.md b/docs/tutorials/tutorials.md
similarity index 70%
rename from docs/tutorials/index.md
rename to docs/tutorials/tutorials.md
index 776e42b..013ccdf 100644
--- a/docs/tutorials/index.md
+++ b/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 |
diff --git a/mise-tasks/doc-filenames b/mise-tasks/doc-filenames
index 912effc..fe626f0 100755
--- a/mise-tasks/doc-filenames
+++ b/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
diff --git a/mise-tasks/doc-links b/mise-tasks/doc-links
index bdc0f2b..460be11 100755
--- a/mise-tasks/doc-links
+++ b/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
 """
@@ -28,16 +30,20 @@ from rich.table import Table
 
 DOCS_DIR = Path(__file__).parent.parent / "docs"
 
-# Regex to match wiki-links: [[Target]] or [[Target | Display]]
-WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(?:\s*\|\s*[^\]]+)?\]\]")
+# Regex to match wiki-links: [[Target]] or [[Target|Display]]
+# Captures: group(1) = target (may have spaces), group(2) = full "|Display" part if present
+WIKILINK_PATTERN = re.compile(r"\[\[([^\]|]+)(\|[^\]]+)?\]\]")
 
 # Regex to match inline code (backticks)
 INLINE_CODE_PATTERN = re.compile(r"`[^`]+`")
 
 
-def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
+def extract_wikilinks(file_path: Path) -> list[tuple[str, int, bool]]:
     """Extract all wiki-link targets from a markdown file with line numbers.
 
+    Returns list of (target, line_num, has_spaces) tuples.
+    has_spaces is True if the target or pipe separator had surrounding spaces.
+
     Ignores wiki-links inside inline code (backticks) as these are examples.
     """
     content = file_path.read_text()
@@ -47,8 +53,14 @@ def extract_wikilinks(file_path: Path) -> list[tuple[str, int]]:
         # Remove inline code before searching for wiki-links
         line_without_code = INLINE_CODE_PATTERN.sub("", line)
         for match in WIKILINK_PATTERN.finditer(line_without_code):
-            target = match.group(1).strip()
-            links.append((target, line_num))
+            raw_target = match.group(1)
+            target = raw_target.strip()
+            pipe_part = match.group(2)  # "|Display" or None
+            # Check for spaces: in target, or around the pipe
+            has_spaces = raw_target != target
+            if pipe_part and (raw_target.endswith(" ") or pipe_part.startswith("| ")):
+                has_spaces = True
+            links.append((target, line_num, has_spaces))
 
     return links
 
@@ -90,9 +102,11 @@ def main() -> int:
         if (REPO_ROOT / filename).exists():
             valid_targets.add(Path(filename).stem)
 
-    # Collect all broken and ambiguous links
+    # Collect all broken, ambiguous, path-based, and spaced links
     broken_links: list[tuple[str, int, str]] = []
     ambiguous_links: list[tuple[str, int, str, list[str]]] = []
+    path_links: list[tuple[str, int, str]] = []
+    spaced_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")):
@@ -102,9 +116,15 @@ def main() -> int:
         rel_path = str(md_file.relative_to(DOCS_DIR))
         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
+        for target, line_num, has_spaces in links:
+            if has_spaces:
+                # Links with spaces in target or around pipe are not allowed
+                spaced_links.append((rel_path, line_num, target))
+            elif "/" 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 +137,45 @@ def main() -> int:
 
     has_errors = False
 
+    if spaced_links:
+        has_errors = True
+        console.print("[bold red]Wiki-Links With Spaces Found[/bold red]")
+        console.print("Wiki-links must not have spaces in the target or around the pipe.")
+        console.print("Use [[target|Display Text]] not [[target | Display Text]].")
+        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 spaced_links:
+            table.add_row(file_path, str(line_num), escape(f"[[{target}]]"))
+
+        console.print(table)
+        console.print()
+
+    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")