Files
Dashboard_Projects_Management/docs/knowledge-library.md
T
2026-10-21 15:25:33 +02:00

5.6 KiB

Knowledge Library

Knowledge Library is a separate Django app under /knowledge/, with its own models, routes and menu entry. It does not create or modify Project Manager cards. See Pocket source review and schema rationale.

Capture

Run migrations, sign in, and open Knowledge Library → Capture tokens. The token is displayed only when created and can be revoked there. An Apple Shortcut can send a JSON POST to /api/bookmarks/ with Authorization: Bearer <token> and Content-Type: application/json:

{"url":"https://example.org/article","title":"Optional title","saved_reason":"Why this matters"}

The endpoint returns 201 for a new item or 200 with duplicate: true for an existing URL. URLs are normalized conservatively: scheme/host case and fragment are ignored, while path and query are preserved. Capture is owner-scoped and limited to 30 posts per token per minute. Token values are stored only as SHA-256 hashes. Browser forms use Django session authentication and CSRF; bearer tokens are accepted only at the capture endpoint. A saved link remains available when metadata has not been fetched.

New items show pending until .venv/bin/python manage.py fetch_knowledge_metadata --limit 20 runs. A one-minute user-systemd timer is supplied in deploy/systemd/common-ground-knowledge-metadata.{service,timer}; link and enable it after the application and migration are deployed. The timer processes at most five links per run. The page polls pending cards for two minutes and replaces them when the worker completes. On this host, link both files from deploy/systemd/ into ~/.config/systemd/user/, run systemctl --user daemon-reload, then systemctl --user enable --now common-ground-knowledge-metadata.timer after migrations. Use flatpak-spawn --host before systemctl when running inside the Codex Flatpak shell. It checks every DNS answer and redirect target, pins the outbound connection to a validated public IP, restricts ports, limits redirects, total time and response bytes, and extracts Open Graph metadata first, then Twitter Card metadata, then HTML title/description and favicon. It stores no page HTML. YouTube URLs use the fixed YouTube oEmbed JSON endpoint; returned embed HTML is ignored. Failed fetches show error and use exponential retry, capped at five attempts. No arbitrary URL is fetched during the save request. Fetched HTML is never rendered or stored as article content.

MCP discovery

Authorize the MCP client with knowledge:read to expose find_relevant_saved_interests(context). It returns at most three links belonging to the OAuth user. The current matching is intentionally simple and deterministic; it searches saved titles, descriptions, reasons and tags, and can return no matches. It does not inspect conversations on its own. Clients must choose to call it, so automatic invocation cannot be guaranteed. Existing projects:read scope does not grant library access.

ntfy prototype

TasksNest's planner/services/notifications.py at commit 743785c2e0e41514c8dd18c035b7ea21716d87de uses a UTF-8 HTTP POST with a Title header; this app follows that transport convention. Configure the server environment, outside Git:

KNOWLEDGE_NTFY_ENABLED=1
KNOWLEDGE_NTFY_URL=https://your-ntfy-host/private-topic
KNOWLEDGE_NTFY_USER_ID=<owner database ID>
KNOWLEDGE_NTFY_MODE=forgotten
KNOWLEDGE_NTFY_WEEKLY_LIMIT=2
KNOWLEDGE_NTFY_QUIET_START=22
KNOWLEDGE_NTFY_QUIET_END=8

The feature is off by default. Run .venv/bin/python manage.py rediscover_knowledge from a scheduled service (for example, once daily); no timer is installed by the app. Modes are forgotten, random, and timely (recent saved item, not a claim that its price or availability changed). Items must be at least two days old, are cooled down for 14 days after delivery, and the weekly limit defaults to two. Quiet hours use Django's configured local timezone. The notification includes the original source URL and saved reason. Delivery events are recorded after success; failed sends do not consume a slot. Snooze and dismissal controls are future work.

Current limits

This checkout uses SQLite. Search is scoped by owner but does not yet use PostgreSQL full-text search or semantic matching. The browser page supports save, search, edit of user title/description, preview/plain/embed modes, manual refresh and archive. Publisher metadata remains separate from user edits, so refresh preserves overrides. YouTube playback is opt-in and uses only a constructed youtube-nocookie.com URL after a click; no provider HTML or iframe loads automatically. Preview images load directly from their publisher with no referrer; broken images fall back to text. Editing tags, reasons, and snooze needs a later UI pass. No article body is stored. No project conversion happens automatically.

Preview implementation choices

The current project uses SQLite, so preview metadata is cached on the owner-scoped SavedItem row rather than in PostgreSQL. A later PostgreSQL deployment can use the same migration fields and add a full-text index. micawber offers general oEmbed provider discovery, Beautiful Soup offers broader HTML parsing, and httpx offers a higher-level HTTP client. This feature needs only one allowlisted oEmbed provider and a narrow set of head tags. The standard-library parser and DNS-pinned connection avoid extra dependencies and make SSRF checks explicit. Open Graph image alt and site name and the YouTube oEmbed endpoint informed field mapping; YouTube Help documents the privacy-enhanced embed domain.