Link Curator Dashboard Maintainer

Link Curator Dashboard — Maintenance Skill

Service overview

The link-curator dashboard is a FastAPI app running on port 8090, separate from the official Hermes dashboard (hermes dashboard, default port 9119). It reads from the vault at <profile-dir>/vault/ and exposes a read-only web UI.

Process inventory

# Find all dashboard processes
lsof -nP -iTCP:8090 -sTCP:LISTEN

# Check the command
ps -p <pid> -o pid,command

# Check working directory (macOS)
lsof -a -p <pid> -d cwd

# Check working directory (Linux)
readlink /proc/<pid>/cwd

Current layout (verify with ps aux | grep "8090"):

• The dashboard process typically runs uvicorn main:app --port 8090 from <profile-dir>/dashboard/
• The process working directory is authoritative — do not assume the path matches the skill's description if multiple dashboard instances exist
• This dashboard is a separate process from the official Hermes dashboard (the hermes dashboard command, default port 9119). They are independent and can run side-by-side.

Key paths

Endpoints

Caching — automatic

archive.py uses mtime-based invalidation — no lru_cache, no manual invalidation needed:

1. On every request, get_all_entries() checks the mtime of INDEX.md
2. If the file hasn't changed → returns cached entries (fast)
3. If the file was modified (new entries saved) → silently re-reads and rebuilds the cache

This means the dashboard always reflects the current vault state without any manual intervention. The only time you need to act is when the file can't be read (permissions, disk error) — in that case the last valid cache is served and a warning is logged.

/reload-cache still exists for edge cases (corrupted mtime, network mounts with broken stat) — it's a manual force-refresh that clears the cache and re-reads immediately.

Dashboard went offline — restart procedure

The dashboard has no watchdog and dies silently (e.g. after a system reboot). Unlike the official Hermes dashboard which can be supervised by hermes gateway install, the link-curator dashboard must be manually restarted when the process exits. See "Dashboard went offline — restart procedure" below.

cd <profile-dir>/dashboard
./start.sh 8090

For a background process:

cd <profile-dir>/dashboard
mkdir -p ../logs
nohup ./start.sh 8090 > ../logs/dashboard.log 2>&1 &

After starting, verify readiness:

sleep 2 && curl -s --max-time 3 http://localhost:8090/health

Expected: {"status":"healthy","total_entries":N,...}

If health fails, check the background process output:

tail -50 <profile-dir>/logs/dashboard.log

Validate

cd <profile-dir>/dashboard && python3 validate.py

Pitfall: The profile root at <profile-dir>/ also has a validate.py — it is a DIFFERENT file. Running python3 validate.py from the wrong directory gives wrong results or errors. See references/validate-path.md for the correct path, common wrong paths, and exit code meanings.

Double---- separator trap

When removing a malformed entry from INDEX.md (e.g. one with a wrong header level like # Index instead of ### Title), you may leave behind a dangling --- separator. Combined with the next entry's ---, this creates a double separator pattern (---\n\n---) which produces an empty entry chunk. The validator reports it as ERROR: Missing or malformed ### title line at chunk N.

Fix: After removing a bad entry, check the surrounding context in both INDEX.md and the relevant daily note file (e.g. vault/2026-MM-DD.md). Ensure only ONE --- separates entries, not two. The validator will catch this (Has errors: 1, ERROR: Missing or malformed ### title line) — re-check and patch the orphaned separator.

Why patch misses it: The malformed entry sits in a section of the file where many entries share identical string patterns (e.g. - **Summary**: ... lines). patch reports Found N matches for old_string and refuses to guess. Use Python direct file manipulation instead:

python3 - <<'EOF'
path = "<profile-dir>/vault/INDEX.md"
with open(path) as f:
    lines = f.readlines()
# Find the target line and insert/delete as needed
for i, line in enumerate(lines):
    if line.startswith("### TARGET ENTRY"):
        # remove: del lines[i-1:i+6]  (separator + entry)
        # insert: lines.insert(i, new_entry_text)
        break
with open(path, "w") as f:
    f.writelines(lines)
EOF

Diagnostic checklist — "dashboard shows fewer entries than expected"

Use this sequence before assuming server-side problems:

1. curl http://localhost:8090/health — get total_entries count
2. curl http://localhost:8090/day-json/YYYY-MM-DD — check specific days; returns JSON array of entries
3. curl http://localhost:8090/ | grep 'entry-card'` — count entry cards in raw HTML
4. If API returns correct count but browser UI doesn't → browser cache, try Ctrl+Shift+R or incognito window
5. If health count is fine but dashboard still shows fewer entries → possible INDEX.md chunk corruption. See obsidian skill → INDEX.md Health Check section for the Python chunk analysis one-liner that catches merged entries and double---- separators in seconds.

Quick health check (always run after INDEX.md edits):

cd <profile-dir>/dashboard && python3 validate.py

Expected: Has errors: 0, Fully valid: N matching vault entry count.

Key signal: total_entries from /health matches vault count → server is fine, client cache is the issue.