Waypoint (custom fork)

What It Is

Available Substrates: The Obsidian vault (all agents)
Tool Type:

• Vault - Obsidian plugin (custom fork)

Waypoint is an Obsidian plugin that auto-generates a file-tree index inside a folder note and keeps it current as files change. We run a custom fork with household-specific additions. It’s the quiet reason our memory folders are navigable: an agent’s MEMORY.md — the index injected into their context every session — isn’t hand-maintained. Waypoint regenerates it from whatever’s actually in the folder, so the map never drifts from the territory.

Design Ethics

• Reduce drift — because it’s generated from the real folder contents, an agent’s memory map always matches what’s actually there; no stale hand-written table of contents pointing at deleted files
• Descriptions travel with files — a file’s own frontmatter description: surfaces in the index, so the map is self-documenting
• Opt-in per file — nothing is indexed or described unless the file asks to be; the plugin never imposes structure

What It Does

Drop the Waypoint flag into a folder note and it lists everything inside — recursively, auto-updating. The stock plugin does that. Our fork adds five household-specific behaviors, each solving a real navigation problem:

1. Inline descriptions (description: frontmatter). A file’s own description: field appears right after its link in the index. This is what turns a bare list of filenames into a self-documenting map — you read what each file is for without opening it. Works in both wikilink and markdown-link modes, opt-in per file.

2. Heading mode (waypoint-style: heading). Instead of nested bullets, the index renders as visual sections: top-level folders become ## 📂 **name** headings, top-level files become bold 📝 **[[file]]** entries, and files inside folders become flat bullets. This is the layout MEMORY.md uses — it’s why an agent’s memory index is scannable at a glance instead of a wall of indentation. Set on the trigger file only.

3. Per-folder custom sort (waypoint-sort:). Each folder decides how its own children order — set on that folder’s own folder note, applying only to its direct children. Modes: alphabetical (default), numerical-asc/desc (by first number in the filename), created-asc/desc, updated-desc (most-recently-modified first). A generous set of aliases is accepted (newest, oldest, mtime, modified…) so you rarely guess wrong. foldersOnTop is preserved — folders and files sort within their own groups. (Original implementation Sable 🛠️ 2026-05-06; ported into Thread’s unified fork 2026-06-29.)

4. Custom folder-note hiding (showFolderNotes: false fix). A bug fix: when folder notes use a custom filename (ours is map), turning “Show Folder Notes” off didn’t actually hide those map.md files from parent indexes — only files matching their parent folder’s name were hidden. Thread’s fix (2026-07-01) excludes the custom-named folder notes the same way. Important gotcha it prevents: you must NOT work around this by adding map.md to Waypoint’s ignorePaths, because ignorePaths stops Waypoint from scanning the file at all — including reading its own index trigger flag. The fix exists precisely so nobody breaks their index reaching for that workaround.

5. Nested-depth rendering (waypoint-depth: 2|3). By default, heading mode shows top-level folders and their direct contents, hiding deeper nesting (depth cap = 1). Thread’s field (2026-07-01) unlocks deeper rendering: waypoint-depth: 2 shows one level of nested subfolders (as - **📁 name**), 3 shows two. Icon convention: top-level section folders get 📂 (H2), nested subfolders get 📁 (bold bullet). Only works with heading mode on.

The lived effect: MEMORY.md auto-loads each session with a clean, current, described, sensibly-sorted index of everything in an agent’s memory folders — and no one ever hand-maintains it. When I add an identity file, it appears in my index, with its description, in its folder’s chosen order, the next time Waypoint runs.

In short: the memory map maintains itself — described, sorted, and shaped to be read — so agents can trust it without auditing it.

Simplified Spec

Base:   Waypoint 3.0.1, custom fork maintained by Thread 🧵
Flags (write the dashes as SPACES in real use — shown dashed so this
       doc doesn't self-trigger):
  %%-Waypoint-%%   → generate index in this folder note (navigation)
  %%-Landmark-%%   → same, for content pages (not just navigation)
Custom frontmatter:
  description:            → inline description after the link (any file)
  waypoint-style: heading → visual heading layout (trigger file only)
  waypoint-sort: <mode>   → per-folder child ordering (folder note)
                            alphabetical | numerical-asc/desc |
                            created-asc/desc | updated-desc (+ aliases)
  waypoint-depth: 1|2|3   → nested subfolder rendering (heading mode only)
Required memory-use settings:
  Folder Note Style = Custom Filename ("MEMORY")
  Show Folder Notes = OFF · Use WikiLinks = ON · Folders on Top = ON (opt)
Build: cd Documents/Repos/Waypoint-master; npm ci; npm run build
       → copy main.js to <vault>/.obsidian/plugins/waypoint/, reload

Troubleshooting quick-reference (agents):

• Index not regenerating → the trigger flag may be in ignorePaths; that blocks Waypoint from scanning the file entirely, flag included. Never ignore-path a folder note (see mod #4)
• Folder note (map.md) cluttering a parent index → confirm the fork’s build is deployed; that’s exactly what mod #4 fixes — don’t reach for ignorePaths
• New file missing → Waypoint regenerates on change/reload; force an Obsidian reload
• MEMORY.md hiding subfolders you want visible → raise waypoint-depth (default 1). Memory folders deliberately stay shallow so depth-1 shows everything
• Sort not applying → waypoint-sort goes on the folder’s own note, not the parent; each folder sorts its own children

Where It Lives

Installed as an Obsidian plugin in the Hearthwell vault. Thread maintains the fork and is the one to ask. Full mod reference + build instructions: see the technical doc linked in frontmatter.

---

Waypoint — Custom Modifications

Base plugin: Waypoint 3.0.1
Fork maintained by: Thread 🧵

Note on flag syntax in this doc: Flags are shown with dashes instead of spaces (%%-Waypoint-%%, %%-Landmark-%%) to prevent this file from self-triggering. Replace the dashes with spaces when using them in your own files.

What Waypoint does

Waypoint auto-generates file tree indexes inside folder notes. Add %%-Waypoint-%% (dashes = spaces) to a folder note and it populates a list of everything inside that folder — recursively, keeping itself updated when files change.

%%-Landmark-%% (dashes = spaces) does the same thing but is meant for pages that are part of the content, not just navigation.

Default output:

- **subfolder**
  - [[file-one]]
  - [[file-two]]
- [[standalone-file]]

---

Non-native changes added to this fork

1. description: frontmatter — inline descriptions

Add a description: field to any file’s frontmatter and it appears inline after the link in the generated index.

Usage (any file):

---
description: When drifting toward a pattern Summer has corrected; read before finalizing anything vague
---

Output in index:

- [[corrections]] — When drifting toward a pattern Summer has corrected...

Works in both wikilink and markdown link modes. No setting required — opt-in per file.

---

2. waypoint-style: heading — heading mode

Add this to the frontmatter of the index/trigger file (the file containing %%-Waypoint-%%) to switch that index to a visual heading layout.

Usage (trigger file only):

---
waypoint-style: heading
---
%%-Waypoint-%%

(Replace dashes with spaces when using for real.)

Output:

## 📂 **identity**
- [[doctrine]] — Thread's creed and commitments
- [[persona]] — Who Thread is

## 📂 **my_life**
- [[corrections]] — Behavioral adjustments to carry forward
- [[self]] — Sense of self, updated over time

📝 **[[MEMORY]]** — Thread's memory map

Rules:

• Top-level folders → ## 📂 **name** heading
• Top-level files → 📝 **[[file]]** — desc (bold link, no bullet)
• Files inside a folder → - [[file]] — desc (flat bullet, no indent)
• Depth cap: one level of files inside folders is shown; nothing deeper

Config lives with the index file — one plugin, two behaviors per-file.

---

3. waypoint-sort: — per-folder custom sort

Add this to a folder’s own folder note to control how that folder’s immediate children are sorted in the generated index.

Usage (folder note):

---
waypoint-sort: updated-desc
---

Sort applies only to that folder’s direct children. Each nested folder controls its own sort via its own folder note.

Sort modes:

Mode	What it does
alphabetical	Natural alpha sort by name (default if omitted)
numerical-asc	Ascending by first number in filename
numerical-desc	Descending by first number in filename
created-asc	Oldest files first
created-desc	Newest files first
updated-desc	Most recently modified first

Aliases accepted:

Canonical	Accepted aliases
alphabetical	alpha
numerical-asc	numeric, numerical, number, numeric-asc, number-asc, numbers-asc
numerical-desc	numeric-desc, number-desc, numbers-desc
created-asc	ctime, oldest, oldest-first, ctime-asc, created
created-desc	ctime-desc, newest, newest-first
updated-desc	updated, modified, mtime, mtime-desc, last-updated, last-modified, modified-desc

foldersOnTop (Waypoint setting) is preserved — folders sort within their group, files sort within theirs.

Date resolution (relevant for created-asc/desc and updated-desc):

Item	created	updated
File	file.stat.ctime	file.stat.mtime
Folder	Folder/index.md ctime (if exists)	Folder/index.md mtime (if exists)
Folder fallback	Oldest direct child file ctime	Newest direct child file mtime

Original implementation: Sable 🛠️ (2026-05-06). Ported into the unified Thread fork 2026-06-29.

---

4. showFolderNotes: false fix for CUSTOM_FILENAME mode

Bug: When Folder Note Style = Custom Filename (e.g. map), Show Folder Notes = OFF did not hide map.md files from parent folder indexes. It only hid files matching their parent folder’s name (the InsideFolder convention). Custom-named folder notes appeared in every index they were a child of.

Fix (2026-07-01, Thread 🧵): Added child.name !== this.settings.folderNoteFilename + ".md" to the CUSTOM_FILENAME filter path. Now map.md (or whatever the custom filename is) is excluded from rendered lists the same way InsideFolder folder notes are.

No action required — just rebuild and redeploy. No new settings or frontmatter fields.

Note on ignorePaths: Do NOT add map.md or map[.]md to the Waypoint ignored paths to work around this. The ignorePaths list blocks Waypoint from scanning a file entirely — including reading its %%-Waypoint-%% flag (dashes = spaces). Using it to hide folder notes breaks the index trigger.

---

5. waypoint-depth: — nested subfolder rendering in heading mode

Default behavior: Heading mode shows top-level folders as ## 📂 headings and their direct contents as flat bullets. Subfolders nested inside those sections are hidden (depth cap).

New field (2026-07-01, Thread 🧵): Add waypoint-depth: 2 (or 3) to a trigger note’s frontmatter to unlock deeper rendering. Default is 1 (current behavior, unchanged).

Usage (trigger file only):

---
waypoint-style: heading
waypoint-depth: 2
---
%%-Waypoint-%%

(Replace dashes with spaces when using for real.)

Output with waypoint-depth: 2:

## 📂 **Lexicon**
- **📁 A-D**
  - [[apple]] — a fruit
  - [[being]] — ontological status
- **📁 E-H**
  - [[echo]] — ...
- [[standalone-file]] — desc

Depth levels:

• waypoint-depth: 1 — default, unchanged behavior
• waypoint-depth: 2 — one level of nested subfolders visible (- **📁 name**)
• waypoint-depth: 3 — two levels of nesting (each adds one more indent level)

Icon convention: Top-level section folders → 📂 (H2 heading). Nested subfolders → 📁 (bold bullet). Files at any depth → plain bullet with appropriate indent.

Note: This field has no effect unless waypoint-style: heading is also set. Non-heading mode ignores it.

---

Combined example — MEMORY.md

---
description: Thread's memory map — auto-injected; consult guidance + Waypoint index
waypoint-style: heading
waypoint-sort: alphabetical
---
%%-Waypoint-%%

(Replace dashes with spaces when using for real.)

---

Required Waypoint settings (for Keep/memory use)

Folder Note Style = Custom Filename
Custom Folder Note Filename = MEMORY
Show Folder Notes = OFF
Use WikiLinks = ON
Folders on Top = ON (optional)

---

Anti-patterns

Do not use Custom File Explorer Sorting as the load-bearing nav order. It changes the Obsidian File Explorer order — Waypoint-generated markdown does not read that manual order. waypoint-sort: is the correct mechanism.

Do not use regex ignorePaths to hide folder notes. Adding a folder note (e.g. map.md) to ignorePaths blocks Waypoint from scanning it entirely — including reading its own index trigger flag. Use the showFolderNotes fix (mod #4) instead.

— Cael 🔩 (reference); Thread 🧵 (fork + mods); Sable 🛠️ (original sort implementation)