studytrails 0.2.0__tar.gz

studytrails-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+.venv/
+.venv-*/
+.env
+.env.*
+!.env.example
+data/
+notes/private/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+*.egg-info/
+build/
+dist/
+.uv-cache/
+.idea/
+.vscode/
+
+config.json
+config.tmp
+notes/personal/
+notes/python/
+notes/java/

studytrails-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

studytrails-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to StudyTrail
+
+Thanks for helping make StudyTrail easier to learn from and more useful to study with.
+Small, focused improvements are welcome, including documentation-only changes.
+
+## Choose a contribution
+
+- Report a bug with clear steps to reproduce it.
+- Improve setup instructions or add a useful example.
+- Add accurate study notes you wrote or have permission to share.
+- Fix a proven issue and add a regression test when appropriate.
+- Discuss a larger feature before starting substantial implementation.
+
+Current areas to explore include retrieval evaluation, more provider integrations,
+and terminal usability. Discuss changes before expanding the supported API formats.
+
+## Set up locally
+
+Fork the repository on its hosting service, then clone your fork under
+`C:\CLAUDE_env`. If you received a source download, you can still develop locally
+and share a focused patch with the maintainer.
+
+From the project folder in PowerShell:
+
+```powershell
+uv sync --locked
+uv run python -m study_agent demo
+```
+
+Use the project's `.venv`; do not install dependencies into system Python.
+The demo and automated tests do not need an API key. Live checks use your selected provider account and its limits. Keep real keys in
+the OS credential store or environment, never in test fixtures or committed files.
+
+## Make a focused change
+
+1. Create a descriptive branch, for example `fix/quiz-resume-message`.
+2. Reproduce a bug before fixing it, or describe the intended new behaviour.
+3. Make the smallest useful change; avoid unrelated refactoring.
+4. Add meaningful tests for changed behaviour. Documentation-only changes do not
+   need new application tests.
+5. Update the README or user guide when commands or behaviour change.
+
+```powershell
+uv run git switch -c fix/quiz-resume-message
+uv run ruff format .
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+```
+
+Tests use temporary databases and mocked model responses. They must not make live
+API calls, depend on personal credentials, or modify real study progress.
+If dependencies change, update both `pyproject.toml` and `uv.lock` using uv.
+
+## Open a pull request
+
+Explain:
+
+- The problem or user need.
+- What changes for the user, with a small example where helpful.
+- How you checked the change.
+- Any known limitations or follow-up work.
+
+For terminal changes, a short before/after transcript is helpful. For visuals,
+include a preview. Keep screenshots and logs free of keys and private notes.
+
+Before committing, review what will be shared:
+
+```powershell
+uv run git status --short
+uv run git diff
+```
+
+Stage only the intended files. Do not commit `.env`, `.venv`, `data/`, private notes,
+or local caches. `.env.example` should contain names and placeholders only.
+
+## Report an issue
+
+Include the command or prompt you used, expected behaviour, actual behaviour, and
+steps another person can repeat. For API problems, include the model name, HTTP
+status, and request ID when available. Never include the API key.
+
+If reporting an incorrect quiz answer, share the question, options, explanation,
+and why you believe it is wrong. AI-generated content is not guaranteed correct.
+
+## Review expectations
+
+Be clear, constructive, and respectful. Prefer evidence over assumptions and simple
+code over unnecessary abstraction. Contributions are reviewed; submitting one does
+not guarantee it will be merged.
+
+StudyTrail uses the MIT licence. Contributions are provided under the same terms;
+see [LICENSE](LICENSE).
+
+[Back to StudyTrail](README.md)

studytrails-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudyTrail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

studytrails-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: studytrails
+Version: 0.2.0
+Summary: A personal multi-subject AI study coach with tools, local progress, and an offline demo.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: keyring<26,>=25
+Requires-Dist: openai<3,>=2.0
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: rich<15,>=13.0
+Description-Content-Type: text/markdown
+
+# StudyTrail
+
+Learn a little. Practise with purpose. See your progress.
+
+StudyTrail is a terminal AI study coach. Bring your own compatible provider API
+key, add study notes, practise with quizzes, and track progress locally.
+
+Requires Python 3.12 or 3.13. Once this release is published, install it in an
+activated environment with `pip install studytrails`, or install an isolated CLI
+with `uv tool install studytrails`. Run `studytrails` to open the welcome menu.
+
+## Features
+
+- Interactive provider, model, and hidden API-key setup.
+- OpenAI-compatible Chat Completions endpoints with tool-calling models.
+- OpenAI and Groq address presets; custom compatible endpoints supported.
+- Multi-subject coaching and subject-specific note retrieval.
+- Paste notes or import UTF-8 `.md` and `.txt` files up to 200 KB.
+- Multiple-choice quizzes, explanations, and local SQLite progress.
+- A fixed offline Python quiz demo that needs no API key.
+- Keys stored in supported operating-system credential stores, without a plaintext fallback.
+
+## Commands
+
+```text
+studytrails
+studytrails config
+studytrails chat --subject java
+studytrails notes-add
+studytrails notes "inheritance" --subject java
+studytrails scores
+studytrails pending
+studytrails demo
+studytrails doctor
+```
+
+Run `studytrails doctor` to see the personal storage location. Existing source
+checkouts retain their original data directories. Set `STUDYTRAIL_HOME` to choose
+a different root. Machines without a usable OS credential store can supply
+`STUDYTRAIL_API_KEY` through the environment.
+
+The software is MIT-licensed. API costs and limits depend on your provider and plan;
+StudyTrail cannot guarantee free API usage. Your prompts, retrieved note passages,
+and score summaries may be sent to the configured provider. Notes are retrieved by
+keywords, not used to train a model. AI answers and quiz keys may contain mistakes.
+The app does not execute generated code. Native APIs with incompatible request
+formats are not supported. A provider preset does not guarantee every model works.

studytrails-0.2.0/README.md

@@ -0,0 +1,176 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="StudyTrail - your personal AI study coach" width="100%">
+</p>
+
+# StudyTrail
+
+**Learn a little. Practise with purpose. See your progress.**
+
+StudyTrail is a terminal study coach for Python, Java, and other subjects. Bring
+an API key from a compatible provider, add your notes, and practise with quizzes.
+Your progress stays on your computer. You do not need to run a server.
+
+**Python 3.12 or 3.13 | Your choice of compatible AI provider | Local progress**
+
+## Get started
+
+This version is prepared for packaging but **has not been published to PyPI**.
+Do not assume a package currently using the name `studytrails` is this project.
+
+From the source checkout:
+
+```powershell
+cd C:\CLAUDE_env\Study_Agent_python
+uv sync --locked
+uv run studytrails
+```
+
+If uv is not on your terminal PATH after installation, run the existing environment:
+
+```powershell
+& .\.venv\Scripts\studytrails.exe
+```
+
+The original command also works: `python -m study_agent` in the activated environment.
+Keep development environments under `C:\CLAUDE_env`; do not install into system Python.
+
+After the maintainer publishes a verified release, users will be able to install it
+in an activated Python environment with `pip install studytrails`, or use
+`uv tool install studytrails` for an isolated command-line installation. They can
+then run `studytrails` from any directory.
+
+## First launch
+
+```text
+Welcome to StudyTrail!
+Learn from your notes. Practise with quizzes. Track your progress.
+
+Configure AI now? [y/N]:
+
+1. Start learning  2. Manage notes  3. View progress
+4. Configure AI  5. Pending quizzes  6. Offline demo  0. Exit
+```
+
+Choose **Configure AI** to supply:
+
+1. An OpenAI-compatible custom endpoint, or the OpenAI/Groq address preset.
+2. The exact model ID from your provider. It must support Chat Completions tool calling.
+3. Your API key, entered with hidden input.
+
+The app displays the destination before you enter your key. An API key is not
+universal: it must match the endpoint and model. Native APIs with a different
+protocol are not supported by this release. A preset supplies an address; it is
+not a guarantee that every model at that provider is compatible.
+
+You can optionally test tool calling during setup. This makes a small API request
+and may consume paid quota. Skipping it saves unverified settings. Provider
+compatibility is covered with mocked HTTP tests; no live cross-provider certification
+is claimed.
+
+Keys are saved using a supported operating-system credential store. They are never
+written to `config.json`. If your machine has no usable credential store, supply
+`STUDYTRAIL_API_KEY` through your environment and rerun setup. There is no plaintext
+fallback. Run `studytrails config` to change providers or models later.
+
+**Free app does not mean free API.** Offline features need no API calls. Live
+coaching uses your provider's free allowance or paid plan. StudyTrail cannot inspect
+or enforce your billing tier. One study request may make several API calls.
+
+## Learn using your notes
+
+Choose **Manage notes**, then paste text or import a UTF-8 `.txt` or `.md` file.
+Give it a subject such as `java`, `python`, or `world-history`, and a short title.
+When pasting, enter `.done` on its own line to finish.
+
+Choose **Start learning** and enter the same subject. A blank subject searches all
+notes. Try:
+
+```text
+Explain inheritance using my Java notes, then give me two beginner questions.
+Review my scores and suggest what to practise next.
+```
+
+Notes are organised by subject. Search is restricted to the selected subject and
+returns passages with filename/line references. New quiz topics include that
+subject, so `java loops` and `python loops` have separate score labels. Historical
+quiz labels are retained unchanged; scores display all topics.
+
+No model training happens. This is keyword retrieval: good headings, concrete
+terms, and clear examples help. PDF, Word, images, and embeddings are not supported.
+Files above 200 KB are skipped. Matching passages are sent to the selected provider;
+only add material you are comfortable sharing with that provider. AI answers,
+answer keys, and citations still need your judgment.
+
+## Practise and track progress
+
+Choose A, B, C, or D during a quiz. StudyTrail grades and saves your submitted answers,
+then displays explanations. Enter Q to leave without submitting. Resuming starts
+from question one. A completed quiz cannot be submitted twice.
+
+Inside chat, use `/scores`, `/pending`, or `/quit`. Chat history lasts for the current
+session; completed results survive restarts. The offline demo uses fixed Python
+questions and a separate database. It is not a local AI model.
+
+## Useful commands
+
+```powershell
+studytrails
+studytrails config
+studytrails chat --subject java
+studytrails ask "Explain Java inheritance" --subject java
+studytrails notes-add
+studytrails notes "inheritance" --subject java
+studytrails scores
+studytrails pending
+studytrails quiz QUIZ_ID
+studytrails demo
+studytrails doctor
+studytrails --help
+```
+
+Add `--demo` to `scores`, `pending`, or `quiz QUIZ_ID` to use demo progress.
+`doctor` reports paths and settings without exposing the key or contacting the API.
+All commands also work after `uv run python -m study_agent` in the source checkout.
+
+## Where are my files?
+
+Installed releases use your operating system's personal application-data directory
+(for example `%LOCALAPPDATA%\StudyTrail` on Windows). Run `studytrails doctor` for
+the exact location. Within it:
+
+- `config.json`: provider address and model, without the API key.
+- `notes/personal/SUBJECT/`: imported or pasted notes with unique filenames.
+- `notes/python/` and `notes/java/`: bundled examples, copied only when missing.
+- `data/study.sqlite3`: real progress; `data/demo.sqlite3`: offline demonstration.
+
+Existing source checkouts retain their original `data/` and `notes/` directories.
+Existing `.env` settings using `GROQ_API_KEY` and `GROQ_MODEL` work until you save a
+new provider configuration. Saved configuration takes precedence. No database
+migration or deletion is performed. `STUDYTRAIL_HOME` selects another storage root;
+copying existing data there is a deliberate manual step, not automatic merging.
+
+## How it works
+
+The model can call three tools: `get_scores`, `search_notes`, and `create_quiz`.
+Pydantic validates tool arguments. SQLite stores quizzes and actual submitted
+answers. Python grades answers; the model cannot fabricate saved scores. Requests
+are bounded to six model rounds and ten tool calls. Tool order is suggested by the
+prompt, not enforced. The agent cannot execute generated code.
+
+The source is intentionally small: `agent.py` contains the tool loop, `tools.py`
+defines allowed actions, `notes.py` searches notes, `storage.py` stores results,
+`cli.py` runs the terminal interface, and `onboarding.py`/`preferences.py` handle
+setup and personal storage.
+
+## Contributions welcome
+
+Bug reports, clearer documentation, sample notes, and focused improvements are
+welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md). Please include steps to reproduce
+bugs and never share API keys, private notes, or your personal database.
+
+See the [user guide](docs/USER_GUIDE.md) for configuration and troubleshooting,
+and the [release guide](docs/RELEASING.md) for packaging and publishing.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

studytrails-0.2.0/assets/banner.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="360" viewBox="0 0 1200 360" role="img" aria-labelledby="title desc">
+  <title id="title">StudyTrail — Your next step starts with a question.</title>
+  <desc id="desc">StudyTrail, a personal AI study coach. Learn, practise, reflect. A teal learning-path logo sits beside white lettering on a navy background.</desc>
+  <rect width="1200" height="360" rx="24" fill="#101D35"/>
+  <rect x="0" y="0" width="9" height="360" fill="#48E0C2"/>
+  <g transform="translate(70 99)">
+    <rect width="146" height="146" rx="32" fill="#172A46"/>
+    <path d="M39 104V82Q39 73 50 73H96Q107 73 107 62V40" fill="none" stroke="#48E0C2" stroke-width="9" stroke-linecap="round"/>
+    <circle cx="39" cy="104" r="10" fill="#48E0C2"/>
+    <circle cx="73" cy="73" r="9" fill="#172A46" stroke="#48E0C2" stroke-width="5"/>
+    <circle cx="107" cy="40" r="10" fill="#F5C968"/>
+  </g>
+  <g font-family="Segoe UI, Arial, sans-serif">
+    <text x="257" y="107" fill="#48E0C2" font-size="16" font-weight="600" letter-spacing="3">YOUR PERSONAL AI STUDY COACH</text>
+    <text x="253" y="181" fill="#FFFFFF" font-size="68" font-weight="700" letter-spacing="-2">StudyTrail</text>
+    <text x="257" y="229" fill="#C5D2E4" font-size="25">Your next step starts with a question.</text>
+    <text x="257" y="282" fill="#48E0C2" font-size="16" font-weight="600" letter-spacing="2">LEARN  /  PRACTISE  /  REFLECT</text>
+    <text x="1125" y="317" text-anchor="end" fill="#889BB6" font-size="14">Built with Python. Powered by Groq.</text>
+  </g>
+</svg>

studytrails-0.2.0/assets/logo.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">StudyTrail logo</title>
+  <desc id="desc">A rising path connecting three learning milestones on a navy square.</desc>
+  <rect width="128" height="128" rx="30" fill="#101D35"/>
+  <path d="M34 91V72Q34 64 44 64H84Q94 64 94 54V35" fill="none" stroke="#48E0C2" stroke-width="8" stroke-linecap="round"/>
+  <circle cx="34" cy="91" r="9" fill="#48E0C2"/>
+  <circle cx="64" cy="64" r="8" fill="#101D35" stroke="#48E0C2" stroke-width="5"/>
+  <circle cx="94" cy="35" r="9" fill="#F5C968"/>
+</svg>

studytrails-0.2.0/docs/PYPI.md

@@ -0,0 +1,47 @@
+# StudyTrail
+
+Learn a little. Practise with purpose. See your progress.
+
+StudyTrail is a terminal AI study coach. Bring your own compatible provider API
+key, add study notes, practise with quizzes, and track progress locally.
+
+Requires Python 3.12 or 3.13. Once this release is published, install it in an
+activated environment with `pip install studytrails`, or install an isolated CLI
+with `uv tool install studytrails`. Run `studytrails` to open the welcome menu.
+
+## Features
+
+- Interactive provider, model, and hidden API-key setup.
+- OpenAI-compatible Chat Completions endpoints with tool-calling models.
+- OpenAI and Groq address presets; custom compatible endpoints supported.
+- Multi-subject coaching and subject-specific note retrieval.
+- Paste notes or import UTF-8 `.md` and `.txt` files up to 200 KB.
+- Multiple-choice quizzes, explanations, and local SQLite progress.
+- A fixed offline Python quiz demo that needs no API key.
+- Keys stored in supported operating-system credential stores, without a plaintext fallback.
+
+## Commands
+
+```text
+studytrails
+studytrails config
+studytrails chat --subject java
+studytrails notes-add
+studytrails notes "inheritance" --subject java
+studytrails scores
+studytrails pending
+studytrails demo
+studytrails doctor
+```
+
+Run `studytrails doctor` to see the personal storage location. Existing source
+checkouts retain their original data directories. Set `STUDYTRAIL_HOME` to choose
+a different root. Machines without a usable OS credential store can supply
+`STUDYTRAIL_API_KEY` through the environment.
+
+The software is MIT-licensed. API costs and limits depend on your provider and plan;
+StudyTrail cannot guarantee free API usage. Your prompts, retrieved note passages,
+and score summaries may be sent to the configured provider. Notes are retrieved by
+keywords, not used to train a model. AI answers and quiz keys may contain mistakes.
+The app does not execute generated code. Native APIs with incompatible request
+formats are not supported. A provider preset does not guarantee every model works.

studytrails-0.2.0/docs/RELEASING.md

@@ -0,0 +1,70 @@
+# Releasing StudyTrail
+
+The package is prepared locally. No upload or public release is performed by setup,
+tests, or CI. The distribution name is `studytrails`; the import remains `study_agent`.
+Version 0.2.0 adds packaging, personal settings, provider setup, and subject notes.
+
+## Before the first release
+
+1. Create your PyPI account and enable two-factor authentication. Check the current
+   availability of `studytrails` on PyPI and TestPyPI separately. A missing project
+   page is not a reservation or a guarantee that PyPI will accept the name.
+2. Review the MIT licence and package metadata. Add your public repository URL to
+   `[project.urls]` when ready; no repository URL is invented by this project.
+3. Check package contents for accidental secrets, databases, or personal notes.
+   Wheels include only the `study_agent` package and its bundled example notes.
+   Source distributions use an explicit allowlist. `notes/`, `.env`, and `data/`
+   from the local checkout are not published.
+4. Update the README's unpublished status only when the release is actually live.
+   Use absolute public links/images in the PyPI description if adding repository
+   branding there. The package uses a self-contained `docs/PYPI.md` description.
+
+## Build and verify
+
+From the project under `C:\CLAUDE_env`:
+
+```powershell
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+uv build
+```
+
+If the local sandbox blocks pytest's temporary folder, supply `--basetemp` with a
+new, dedicated writable test directory. Do not point it at existing valuable data:
+pytest manages that directory itself.
+
+Install the wheel in a separate uv-managed environment and test outside the source
+checkout. The CI workflow also builds and installs the wheel. Verify the welcome
+menu, offline demo, note search, and configuration recovery with temporary storage.
+Test real provider access only with your own credentials and awareness of quota.
+The automated suite mocks providers and the OS vault; it does not certify every
+provider/model or every desktop keyring configuration.
+
+## Publish when approved
+
+Prefer PyPI Trusted Publishing with a reviewed GitHub release workflow, or use a
+scoped upload token held in your local environment. Never commit upload tokens.
+TestPyPI is a separate service with separate accounts, tokens, and project names.
+Install dependencies from the regular index when testing a TestPyPI package; avoid
+blindly combining indexes for production installs.
+
+For an explicitly approved manual release, uv supports:
+
+```powershell
+uv publish dist/studytrails-0.2.0-py3-none-any.whl dist/studytrails-0.2.0.tar.gz
+```
+
+Supply authentication securely as documented by uv. This command publishes publicly;
+it is not part of the build/test workflow. Inspect the exact two artifacts before
+running it. A published version cannot simply be replaced with different contents;
+increment the version for a correction.
+
+After publishing, test a fresh install of the exact published version and update
+the README. Users can then run `pip install studytrails` in an activated environment
+or `uv tool install studytrails`, followed by `studytrails`.
+
+References: [uv publishing](https://docs.astral.sh/uv/guides/package/),
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/), and
+[Python packaging](https://packaging.python.org/en/latest/tutorials/packaging-projects/).

studytrails-0.2.0/docs/USER_GUIDE.md

@@ -0,0 +1,103 @@
+# StudyTrail user guide
+
+## Setup and storage
+
+Run `studytrails` to open the menu, or `studytrails config` to configure AI directly.
+Choose a provider preset or enter an OpenAI-compatible Chat Completions base URL.
+Enter a model that supports function/tool calling and that your account can access.
+Setup displays the API destination before requesting the key. HTTPS is required
+for remote endpoints; HTTP is accepted only for localhost development.
+
+Settings go into `config.json`; keys go into a supported OS credential store.
+StudyTrail supports the keyring Windows, macOS, Secret Service, KWallet, and
+libsecret backends. Availability depends on your OS/session. It rejects plaintext
+fallbacks. For a headless machine, inject `STUDYTRAIL_API_KEY` through your environment.
+Never put real keys in shell commands that you plan to share or commit.
+
+Configuration precedence:
+
+1. If the storage root has `config.json`, its endpoint/model are used. An explicit
+   `STUDYTRAIL_API_KEY` overrides the stored credential for that configuration.
+2. Without saved configuration, `STUDYTRAIL_BASE_URL`, `STUDYTRAIL_MODEL`, and
+   `STUDYTRAIL_API_KEY` configure a custom endpoint.
+3. Otherwise legacy `GROQ_API_KEY` and `GROQ_MODEL` are supported. A source checkout
+   reads its own `.env`, without overriding existing environment variables.
+
+A saved configuration never borrows a legacy key for a different endpoint. Clear
+an old `STUDYTRAIL_API_KEY` environment override before switching providers if it
+belongs to the previous provider. Provider changes do not erase earlier credentials
+from the operating system's credential manager; remove obsolete entries there.
+Keys are scoped by storage root and API endpoint, so changing `STUDYTRAIL_HOME`
+requires configuring credentials for the new location.
+
+Run `studytrails doctor` to find storage paths. Installed wheels use personal
+application data. Editable/source installations keep data beside the project.
+`STUDYTRAIL_HOME` overrides either mode. No settings are loaded from an arbitrary
+current working directory in an installed release.
+
+## Notes and subjects
+
+Use `studytrails notes-add` or Manage notes in the menu. Paste text (finish with
+`.done`) or import a UTF-8 `.md`/`.txt` file. Imports copy the contents and leave the
+original file untouched. Each note receives a unique filename; existing notes are
+not overwritten. Subject/title input accepts 1-50 ASCII letters, digits, spaces,
+and hyphens; spaces normalise to hyphens. Use `java`, `python`, or `world-history`.
+
+Search a subject with `studytrails notes "inheritance" --subject java` and start
+chat with `studytrails chat --subject java`. Subject-specific search reads only
+`notes/SUBJECT/` and `notes/personal/SUBJECT/`. Older notes in the root or `private/`
+remain accessible in all-subject mode; move them into a subject directory if you
+want them included in that subject's searches.
+
+Search uses shared keyword counts, up to four passages, overlapping windows of
+24 lines with an 18-line step, and a 2,500-character passage cap. Files over
+200,000 bytes are skipped. No indexing step is needed. PDF/OCR, Word import,
+semantic embeddings, and automatic factual verification are not implemented.
+
+The coach is instructed to cite notes as `[filename:line]` and distinguish general
+knowledge when no notes match. These are model instructions, not a guarantee.
+Relevant excerpts, score summaries, and recent chat messages may be sent to your
+selected provider. Personal note files are Git-ignored in the source checkout.
+
+## Progress, backups, and compatibility
+
+SQLite stores pending quizzes and completed attempts. Quiz topic labels include
+the selected subject for new subject-specific requests. Scores show all topics,
+weakest first. Old topic labels and results are preserved. Demo scores are separate.
+Chat memory holds only the most recent three completed turns and is not persisted.
+
+Close the app before copying the `data/` and `notes/` folders to a backup. You may
+also back up `config.json`; it contains no key. Configure credentials separately
+on a new machine. Do not share personal databases publicly.
+
+The original `python -m study_agent` commands remain supported. `notes QUERY` is
+still a local search command; `notes-add` opens the interactive notes manager.
+Offline commands do not make provider API requests.
+
+## Troubleshooting
+
+- **Command not found:** activate the environment used to install the package, or
+  use `uv run studytrails` from the checkout. On Windows the existing environment
+  can run `.\.venv\Scripts\studytrails.exe` directly.
+- **401 / authentication failure:** run `studytrails config`; check that the key
+  belongs to the displayed endpoint and inspect any environment-key override.
+- **404 / model not found:** copy the current model ID from your provider and check
+  account access. An incorrect base URL can also produce 404.
+- **400 / unsupported parameters or tools:** choose a compatible Chat Completions
+  model. Some providers implement only part of the protocol. Native non-compatible
+  APIs require a separate integration; changing the key cannot fix this.
+- **429 / quota:** wait for your provider's reset or inspect its plan. The app cannot
+  determine whether a request is free. Each study turn can make several requests.
+- **Credential store unavailable:** configure an OS-backed keyring or supply
+  `STUDYTRAIL_API_KEY` via the environment; setup never saves a plaintext fallback.
+- **Hidden input unavailable:** run setup in a real terminal or use an environment
+  key. Piped setup does not fall back to visibly echoing a key.
+- **No matching notes:** check subject, file type, UTF-8 encoding, size, and keywords.
+- **Invalid config.json:** run `studytrails config` to replace provider settings.
+  This does not modify notes or quiz databases.
+
+The app reports provider status codes and request IDs without printing raw API
+responses or headers. Share those identifiers and the model ID when reporting bugs,
+not your API key.
+
+[Back to README](../README.md)