Mirror repo layout in cloud storage for symlink correctness

.env.template

@@ -8,8 +8,8 @@
 #   # Edit .env and set LIBRARY_BASE
 
 # LIBRARY_BASE — absolute path to the root of your cloud-synced library storage.
-# This is the directory that contains your collection PDF directories and
-# library-indexed/ output. Used by init-symlinks.sh to create local symlinks.
+# This directory will be structured to mirror the repo layout (findings/ and
+# collections/NAME/{pdfs,indexed}/). Used by init-symlinks.sh to create local symlinks.
 #
 # Examples:
 #   LIBRARY_BASE="${HOME}/Dropbox/my-library"

README.md

@@ -180,20 +180,22 @@ to cloud folders work seamlessly with version control.
 
 ### Recommended cloud folder layout
 
-A clean convention is to store each collection's PDFs in a named folder, and use `library-` prefixed
-folders for the derived library assets (indexed output and findings). For example, using Dropbox:
+The cloud storage layout mirrors the repo structure exactly. For example, using Dropbox:
 
 ```text
 ~/Dropbox/my-library/
-├── collection-a/          ← PDFs for collection A
-├── collection-b/          ← PDFs for collection B
-├── library-findings/      ← research findings (symlinked to findings/)
-└── library-indexed/       ← converted indexed output
-    ├── collection-a/      (symlinked to collections/collection-a/indexed)
-    └── collection-b/      (symlinked to collections/collection-b/indexed)
+├── findings/              ← research findings (symlinked to findings/)
+└── collections/
+    ├── collection-a/
+    │   ├── pdfs/          ← PDFs for collection A (symlinked to collections/collection-a/pdfs)
+    │   └── indexed/       ← converted output (symlinked to collections/collection-a/indexed)
+    └── collection-b/
+        ├── pdfs/
+        └── indexed/
 ```
 
-The `library-` prefix distinguishes library infrastructure from per-collection PDF archives at a glance.
+Mirroring the repo layout means relative links in `findings/*.md` resolve correctly when
+apps resolve symlinks to their real filesystem path.
 
 ### One-command reconstruction with bootstrap.sh
 
@@ -220,9 +222,9 @@ array in `.env`:
 ```bash
 # .env
 LINKS=(
-    "findings:${LIBRARY_BASE}/library-findings"
-    "collections/collection-a/pdfs:${LIBRARY_BASE}/collection-a"
-    "collections/collection-a/indexed:${LIBRARY_BASE}/library-indexed/collection-a"
+    "findings:${LIBRARY_BASE}/findings"
+    "collections/collection-a/pdfs:${LIBRARY_BASE}/collections/collection-a/pdfs"
+    "collections/collection-a/indexed:${LIBRARY_BASE}/collections/collection-a/indexed"
 )
 ```
 

bootstrap.sh

@@ -90,16 +90,16 @@ parse_source_url() {
 pfb heading "Creating cloud-storage directories" "☁️"
 echo
 
-mkdir -p "${LIBRARY_BASE}/library-findings"
-pfb success "READY  ${LIBRARY_BASE}/library-findings"
+mkdir -p "${LIBRARY_BASE}/findings"
+pfb success "READY  ${LIBRARY_BASE}/findings"
 
 for col_dir in "${SCRIPT_DIR}/collections"/*/; do
     [[ -d "${col_dir}" ]] || continue
     name="$(basename "${col_dir}")"
-    mkdir -p "${LIBRARY_BASE}/${name}"
-    pfb success "READY  ${LIBRARY_BASE}/${name}"
-    mkdir -p "${LIBRARY_BASE}/library-indexed/${name}"
-    pfb success "READY  ${LIBRARY_BASE}/library-indexed/${name}"
+    mkdir -p "${LIBRARY_BASE}/collections/${name}/pdfs"
+    pfb success "READY  ${LIBRARY_BASE}/collections/${name}/pdfs"
+    mkdir -p "${LIBRARY_BASE}/collections/${name}/indexed"
+    pfb success "READY  ${LIBRARY_BASE}/collections/${name}/indexed"
 done
 
 echo

init-symlinks.sh

@@ -17,15 +17,15 @@
 #                 See .env.template for examples.
 #
 # LINKS are auto-derived from collections/*/ using the naming convention:
-#   collections/NAME/pdfs    → ${LIBRARY_BASE}/NAME
-#   collections/NAME/indexed → ${LIBRARY_BASE}/library-indexed/NAME
-#   findings                 → ${LIBRARY_BASE}/library-findings
+#   collections/NAME/pdfs    → ${LIBRARY_BASE}/collections/NAME/pdfs
+#   collections/NAME/indexed → ${LIBRARY_BASE}/collections/NAME/indexed
+#   findings                 → ${LIBRARY_BASE}/findings
 #
 # To override, define a LINKS array in .env before running:
 #   LINKS=(
-#     "findings:${LIBRARY_BASE}/library-findings"
-#     "collections/NAME/pdfs:${LIBRARY_BASE}/NAME"
-#     "collections/NAME/indexed:${LIBRARY_BASE}/library-indexed/NAME"
+#     "findings:${LIBRARY_BASE}/findings"
+#     "collections/NAME/pdfs:${LIBRARY_BASE}/collections/NAME/pdfs"
+#     "collections/NAME/indexed:${LIBRARY_BASE}/collections/NAME/indexed"
 #   )
 
 set -euo pipefail
@@ -75,12 +75,12 @@ fi
 # @side_effects Populates the global LINKS array.
 build_links() {
     LINKS=()
-    LINKS+=("findings:${LIBRARY_BASE}/library-findings")
+    LINKS+=("findings:${LIBRARY_BASE}/findings")
     for col_dir in "${SCRIPT_DIR}/collections"/*/; do
         [[ -d "${col_dir}" ]] || continue
         name="$(basename "${col_dir}")"
-        LINKS+=("collections/${name}/pdfs:${LIBRARY_BASE}/${name}")
-        LINKS+=("collections/${name}/indexed:${LIBRARY_BASE}/library-indexed/${name}")
+        LINKS+=("collections/${name}/pdfs:${LIBRARY_BASE}/collections/${name}/pdfs")
+        LINKS+=("collections/${name}/indexed:${LIBRARY_BASE}/collections/${name}/indexed")
     done
 }