# TODO

This file tracks larger Lumi work that cannot safely be completed in one pass. Keep pending work under the relevant category and move completed items to the Done section with a short note.

## OKF Knowledge System

- Add `knowledge/core`, `knowledge/plugins`, `knowledge/community`, and `knowledge/corrections` directories with documented ownership rules.
- Implement OKF Markdown/frontmatter parsing with stable IDs, scopes, status, priority, tags, generated/editable flags, and timestamps.
- Generate fixed core/plugin OKF from routes, commands, schemas, plugin metadata, README docs, and defaults.
- Add admin-editable community OKF for community names, owner/admin names, bot name, currency, items, roles, lore, links, moderation rules, command rules, and local terminology.
- Add corrections OKF files created only through admin review.
- Implement safe placeholder resolution for core/plugin OKF references such as `{{community.currency.primary_name}}`.
- Preserve source metadata for every retrieved OKF chunk: path, id, heading, score, and excerpt.

## OKF Retrieval and Indexing

- Implement or adapt an OKF indexer that chunks Markdown by heading.
- Re-index only changed OKF files when possible.
- Enforce retrieval priority: active corrections, community OKF, plugin OKF, core OKF.
- Add retrieval boosts for corrections.
- Ensure missing placeholders never crash context injection.

## Feedback Loop

- Add thumbs up/down controls to Lumi chat answers.
- Store feedback payloads with rating, prompt, response, retrieved context, optional comment, model/provider, timestamp, and review status.
- Show an optional comment field for thumbs down and keep thumbs up lightweight.
- Ensure feedback never directly modifies OKF.

## Admin Feedback Review

- Add an admin feedback review page or section.
- Show prompt, response, rating, comment, retrieved OKF sources, model/provider, and timestamp for each feedback item.
- Add review actions: reviewed/no action, good, bad retrieval, bad response, missing knowledge, archive/delete.
- Add correction creation UI with title, tags, affected topic/file, and Markdown body.
- Save approved corrections as OKF files and re-index after save.
- Add links from feedback rows to generated correction files.

## Storage and Preservation

- Store feedback queue, review status, source context snapshots, and correction links in SQLite or existing app storage.
- Keep community OKF, corrections OKF, feedback/review data, and source metadata preserved across updates.
- Ensure generated OKF is reproducible and not accidentally overwritten by admin edits.

## Homepage Hero Embed Requirements

- Continue improving service-specific "why unavailable" messages where external providers expose enough signal.

### Discord Server Widget Hero

- Add optional Discord invite-to-server-ID lookup support if Discord server IDs are not known.

### Twitch Stream Hero

- Support additional configured parent domains for alternate hostnames.
- Support stream-only and stream-with-chat layouts.
- Respect Twitch minimum player size requirements.
- If live-only mode is enabled, check live status or gracefully hide/fallback when offline.
- Show a clear admin warning when the Twitch embed fails due to missing or incorrect parent domain.
- Add admin helper text explaining that Twitch embeds require the site domain to be allowed as a parent domain.

### YouTube Live Hero

- Support YouTube live video URLs, raw video IDs, and optional channel-based live lookup.
- For static live heroes, extract and use the provided live video ID.
- For automatic channel live detection, require YouTube API configuration.
- Cache live lookup results to avoid excessive API calls.
- Support optional live-only mode.
- Support optional YouTube live chat only when a valid live video ID exists.
- Support autoplay and muted settings.
- If live-only mode is enabled and no active stream is found, skip the hero or show fallback content.
- Show fallback/error states for private, removed, age-restricted, embedding-disabled, unavailable, or not-yet-live videos.
- Add admin helper text explaining that YouTube Live requires either a live video link or API-based channel lookup.

### YouTube Video Hero

- Show fallback/error states for private, removed, age-restricted, unavailable, or embedding-disabled videos.
- Detect embedding-disabled videos before save when a YouTube API key or another reliable server-side signal is available.

### External Embedded Content Hero

- Support generic external iframe embeds only for sites that explicitly allow embedding.
- Detect or gracefully handle sites that block embedding through `X-Frame-Options` or CSP `frame-ancestors`.
- Show an admin warning when an external site refuses to be embedded.

### Hero Embed Admin UX

- Show “why unavailable” information in the admin UI when a hero cannot render.

## Update Page UX Improvements

- Add async in-place checks for the older `/admin` and `/admin/settings` update buttons, matching `/admin/updates`.
- Continue simplifying advanced update terminology without hiding recovery-critical detail.

## Homepage Hero System

- Improve handling of live-only Twitch heroes and live-state detection.
- Add explicit Discord invite-to-widget guidance or lookup support if Discord server IDs are not known.

## Homepage Hero UX Improvements

- Review all homepage builder forms for non-technical usability.
- Add tooltips and inline explanations where appropriate.

## UI Text and Button Language

- Review all button labels, field labels, headings, helper text, warnings, empty states, and confirmation dialogs across Lumi.
- Replace technical/internal wording with clearer user-facing wording where possible.
- Keep AI-related wording precise enough for admins to understand model, provider, context, retrieval, embeddings, feedback, corrections, and OKF behavior.
- Review the update pages and simplify labels such as `Check plugin`, `Apply safe target`, and `Disable for recovery`.
- Prefer clear action labels such as `Check for updates`, `Update plugin`, `Use recommended version`, `Disable temporarily`, and `Start recovery mode`.
- Add short helper text below advanced or risky update actions explaining what will happen.
- Replace implementation-focused wording with task-focused wording wherever practical.
- Avoid exposing Git, branch, commit, target, repository, cache, migration, or rollback terms unless the user needs them.
- When technical terms are unavoidable, add short tooltips or inline explanations.
- Standardize common action wording across all pages: save, update, check, review, restore, disable, enable, archive, delete, retry, import, export, cancel, and confirm.
- Ensure destructive or system-changing actions have clear confirmation text.
- Ensure error messages explain both what went wrong and what the admin can try next.
- Review plugin management, core settings, update pages, homepage management, OKF management, feedback review, and AI configuration for inconsistent wording.
- Split highly technical pages into simple and advanced sections where practical.
- Hide rarely needed expert controls behind expandable advanced sections.
- Add examples for fields that expect URLs, model names, provider names, paths, selectors, or structured values.
- Ensure labels and helper text are suitable for non-technical admins without removing important admin-level specificity.
- Review localization/translation keys if present so simplified wording remains consistent across languages.

## Done

- 2026-06-17: Fixed custom command Edit buttons and `/commands` Copy Link / expand buttons with delegated handlers, clipboard fallback, and v0.1.5 patch bump.
- 2026-06-17: Fixed repo-based core updates deleting `data/update-cache/repo` during apply, added a verification guard, and bumped core package version to v0.1.4.
- 2026-06-17: Bumped core package version to v0.1.3.
- 2026-06-17: Completed homepage hero embed pass for Discord widgets, YouTube video playback options, external embed fallback/sandbox controls, admin validation, platform-specific fields, and Test preview behavior.
- 2026-06-17: Fixed core update snapshots for large ZIP-origin installs by replacing the full-install ZIP backup with a filesystem snapshot directory, avoiding the 2 GiB ZIP limit for large preserved files such as local AI models.
- 2026-06-17: Completed `/admin/updates` UX pass: viewport-fixed dismissible notifications, auto-dismiss for non-critical results, async core/plugin check actions without page refresh or scroll jumps, in-place update-card data refresh, loading states, and collapsed advanced Manual ZIP fallback below repo update containers.
- 2026-06-17: Completed homepage hero reliability pass: server-side hero validation before save, admin-visible validation errors, home-page fallback message for broken legacy heroes, automatic YouTube/Twitch/Discord embed derivation, correct Twitch parent host at render time, and image/embed conflict handling.
- 2026-06-17: Completed homepage hero builder UX pass: friendlier labels, contextual help text, normal URL paste support, automatic embed filling, per-row readiness messages, and test preview support.
- 2026-06-17: Fixed homepage links to support local Lumi paths such as `/commands`, and made unavailable live-only heroes fall through to lower-priority heroes instead of blocking the homepage.
- 2026-06-17: Completed update-page wording cleanup for common actions such as check, update, restore previous version, disable temporarily, and ZIP rollback wording.
- 2026-06-17: Added permanent repo-update architecture for ZIP-origin installs using `data/update-cache/repo`, non-live-git metadata checks, snapshot-copy apply, update-state recording, and preservation of user-owned paths.
- 2026-06-17: Separated Lumi AI `tool_info.json` tools from normal plugin update rows and rendered tools under the `lumi_ai` plugin row.