Starlog

Starlog is a single-user study, notes, planning, and assistant system.

The default browser entry point is Today: manual card creation, due review, and daily morning/evening notes. Assistant, Library, Planner, and Review remain the official surfaces, with Assistant secondary to the focused study workflow for now.

What You Use

• Today: focused daily entry point for cards, due review, and daily notes
• Assistant: the primary thread for commands, follow-up questions, confirmations, and returned cards
• Library: notes, captures, saved artifacts, and source history
• Planner: tasks, schedule, briefings, and time blocks
• Review: flashcards and recall sessions
• Desktop helper: a capture companion for clipboard and screenshot intake on laptop

First-Time Use

For a first-time user, the normal path is:

1. Open the web app at /today.
2. If this is a new Starlog instance, choose Set Up Starlog and create a passphrase with at least 12 characters.
3. Sign in with that same passphrase.
4. Add cards manually, review due cards, and save the daily morning plan/evening reflection.
5. Open Assistant, Library, Planner, or the full Review surface only when needed.

Important:

• Starlog is single-user today.
• Do not commit passphrases, bearer tokens, API keys, or bridge tokens into this repo.

User docs:

• docs/CURRENT_STATE.md
• docs/USER_GUIDE.md
• docs/MORNING_BRIEFING_AND_VOICE.md
• docs/CODEX_PHONE_PWA_CONNECTION.md

Everyday Workflow

The intended flow is simple:

1. Start at /today.
2. Write or update the daily note.
3. Create cards manually from what you are studying.
4. Review due cards.
5. Open a support view only when needed: Library for notes/artifacts, Planner for scheduling, Review for full deck work, and Assistant for command-style help.

Native Mobile

The native mobile app is the first-class mobile client.

Tabs:

• Assistant
• Library
• Planner
• Review

Use mobile for:

• quick capture
• voice input
• in-thread Assistant actions
• review on the go
• alarm and briefing playback

Self-Host Starlog

Starlog is designed so the web app and API can be self-hosted together.

The PWA talks to the API you run. The native mobile app and desktop helper can then point at that same deployment, whether you host it locally, on Railway, or somewhere else.

Prerequisites

• Node.js + pnpm
• Python 3.12+
• uv

Start The Full Local Stack In One Command

From repo root:

./scripts/dev_stack.sh

This command:

• installs or refreshes workspace dependencies with pnpm install
• syncs the API environment with uv sync --project services/api --extra dev
• starts the API on http://0.0.0.0:8000
• starts the PWA on http://localhost:3000

For phone or LAN testing, use:

./scripts/dev_stack.sh --lan

That keeps the API on http://0.0.0.0:8000 and exposes the PWA on http://0.0.0.0:3000.

Press Ctrl-C once to stop both services.

If you prefer aliases, make dev-stack, make dev-stack-lan, pnpm dev:stack, and pnpm dev:stack:lan point to the same flow.

Manual Start Commands

If you prefer to run each service yourself:

Install dependencies:

pnpm install
uv sync --project services/api --extra dev

Run the API:

uv run --project services/api uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 --app-dir services/api

Run the PWA:

pnpm --filter web dev

For LAN access to the PWA, use:

pnpm --filter web dev -- --hostname 0.0.0.0 --port 3000

Production-Style Web Hosting

Build:

pnpm --filter web build

Run:

pnpm --filter web start

The production web server uses the Next.js app in apps/web.

The API can be hosted anywhere that can run the FastAPI service in services/api.

First Sign-In On A Self-Hosted Instance

1. Open the web app.
2. Set API base to your API URL, for example http://localhost:8000.
3. Click Set Up Starlog if this is a new instance.
4. Sign in with the passphrase you just created.
5. Go to /assistant and start using the thread.

Mobile And Phone Testing

For LAN testing from your phone, use:

• web app: http://<YOUR_LAN_IP>:3000
• API: http://<YOUR_LAN_IP>:8000

Detailed setup:

• docs/PHONE_SETUP.md
• docs/ANDROID_DEV_BUILD.md

Desktop Helper

The desktop helper is a capture-first companion, not a second full client.

Use it for:

• clipboard capture
• screenshot capture
• recent capture review
• Open in Library
• Ask Assistant

Setup and release docs:

• docs/DESKTOP_HELPER_MAIN_LAPTOP_SETUP.md
• tools/desktop-helper/README.md

Repo Entry Points

• product direction: PLAN.md
• current state: docs/CURRENT_STATE.md
• repo rules: AGENTS.md
• assistant UI/backend reset: starlog_assistant_ui_repo_execution_checklist.md
• user guide: docs/USER_GUIDE.md