satori

Imported from yuxino/satori (AGENTS.md). Install upstream with npx skills add yuxino/satori. Copyright stays with the author.

Satori project guidance

Product intent

Satori is a local-first macOS and Windows learning workspace. Its primary job is to help a learner understand PDF-based material. It is not a note-taking product first.

Persistent project memory

• Read docs/brief.md, docs/status.md, and relevant files in docs/decisions/ before significant work.
• Update docs/status.md at the end of each meaningful implementation session.
• Record durable architectural choices in a numbered file under docs/decisions/.
• Keep docs/plans/ only for unfinished work. After implementation, move durable constraints into the brief, status, or an ADR and delete the plan; Git remains the history.
• Keep this file short and limited to stable working rules.

Scope and privacy

• Build for macOS 14+ and Windows 11. Treat Linux, mobile, and browser clients as out of scope unless the user explicitly expands it.
• Keep study files, reading position, project structure, and learning history local by default.
• Do not add source PDFs to Git. Store file bookmarks or local references instead.
• Treat configured AI services as on-demand page-understanding providers, not as file hosting.
• Support multiple local provider profiles. Keep non-secret endpoints and model IDs in local JSON, but store every user-supplied API key only in macOS Keychain or the current Windows user's Credential Manager. Never write a key into the repository, local JSON, logs, screenshots, environment variables, or persisted WebView state.
• Keep the active profile and model configurable and persisted locally. A configured model must support scanned-page image input; never silently fall back to another provider.
• Treat user-selected question images as ephemeral request context: resize locally, send only on submission, and do not persist them without an explicit product decision.
• Keep per-document learning sessions in the platform-local application data directory; send only bounded recent text turns for follow-ups and keep provider response storage disabled.

Engineering rules

• Follow the Satori 3.0 stack: Tauri 2, TypeScript/Vite, PDF.js, Rust, and local JSON persistence. Keep dependencies small and justify new ones.
• The legacy Swift app exists only in tag legacy-swift; do not restore its source or packaging resources to the working tree.
• Run frontend builds before Rust checks because Vite rebuilds assets embedded by Tauri.
• Add tests for new persistence and parsing behavior; visually check material UI changes.
• Make small, focused commits. Do not stage unrelated files.