LumenTale

LumenTale is a local-first personal AI character chat platform. It starts as a clean multi-page workspace for chats, characters, worldbooks, assets, presets, and settings.

Run Locally

npm install
npm run dev

The frontend runs at http://localhost:5173 and the backend runs at http://localhost:8787.

Runtime data is stored outside the repository by default. Chats, imported content, uploaded files, provider configuration, and API keys are separated from source code and frontend build output.

• macOS: ~/Library/Application Support/LumenTale
• Linux: ~/.local/share/LumenTale
• Windows: %APPDATA%\\LumenTale

Set LUMENTALE_DATA_DIR to override the storage location explicitly.

To stop the background dev services started by Codex:

kill $(cat .lumentale-api.pid) $(cat .lumentale-web.pid)

One-off CharaVault Test

For a real-world import smoke test against 1-2 CharaVault cards, use the backend-only one-off script instead of wiring CharaVault into Explore.

1. Open CharaVault in your normal Chrome/Chromium profile and complete the Cloudflare challenge manually.
2. Start the backend:

npm run start -w backend

3. Run the one-off downloader/importer with 1-2 explicit detail URLs:

npm run charavault:test -w backend -- \
  --channel chrome \
  --user-data-dir "$HOME/.config/google-chrome" \
  --repeat-first \
  "https://charavault.net/cards/example/card-one" \
  "https://charavault.net/cards/example/card-two"

Artifacts are written to a temp directory by default:

• downloads/<slug>/original.png
• downloads/<slug>/meta.json
• downloads/index.json
• downloads/report.json

What the script validates:

• raw PNG card download succeeds
• current /api/import/character accepts the card
• imported character retains source metadata via source.name/url/license
• imported fields such as name, firstMessage, description, personality, and normalized tags are visible in local storage
• optional repeat import records current duplicate behavior without changing product logic

Useful flags:

• --skip-import: download only
• --outdir <path>: control artifact location
• --api-base-url <url>: point at a different backend
• --headless: run without visible browser
• --timeout-ms <number>: extend page timeout

First MVP Scope

• Multi-page React workspace
• Local Express API
• JSON-backed local data store
• Character and worldbook management screens
• OpenAI-compatible provider preset structure
• Basic chat flow with local fallback replies

Project Layout

backend/
  src/
    server.js
    store.js
    importers.js
frontend/
  src/
    components/
    pages/
    lib/

Docs

• 中文导入与探索说明：docs/import-and-explore-guide.zh-CN.md