Update README with user manual information and align structure

- Add comprehensive setup instructions from user manual
- Include pricing information for all models
- Add Part 1-5 structure for better organization
- Include terms CSV creation guide
- Add customization section details
- Add best practices section
- Include full citation format
- Reference user manual PDF (stored separately due to Hugging Face binary file restrictions)

README.md

@@ -18,17 +18,27 @@ Schema Study is a free, no-code, open-source web application that turns a spread
 **Key Pedagogical Approach:** Schema Study uses a Socratic questioning method that (1) withholds direct solutions while providing brief, targeted feedback, (2) poses exactly one scenario-grounded follow-up question per turn, and (3) presses for mechanistic reasoning, justification, and connections between concepts. The tool provides formative practice through question-led dialogue; independent performance is evaluated in secure assessments outside the app.
 
 ## Features
+
 - **No-Code Setup:** Upload course terms via a single CSV spreadsheet - no programming required
 - **Password Protection:** Secure access for your class or group
 - **Customizable Terms:** Use your own CSV file of terms and definitions
 - **Evidence-Based Pedagogy:** Implements Socratic questioning and formative feedback strategies
-- **Prompt Templates:** Engage with the material using creative, research-based prompts including midterm review
+- **Prompt Templates:** Five customizable conversation starters (Misconception Check, Two Truths & a Lie, Connect Terms, Schema Map, Create Study Plan)
 - **AI-Enhanced Feedback:** Get instant, formative feedback and guidance using GPT-5.2 (default), GPT-5.1, or GPT-4.1
 - **Web Search Support:** Optional web search functionality for current information and citations (configurable in `config.py`)
 - **Real-Time Streaming:** Live token-by-token response streaming with visual typing indicator
 - **Professional, Accessible UI:** Clean, modern design with a color palette for clarity and focus
 - **Open-Source & Free:** Fully open-source under GNU GPL-3 License, no paywalls or proprietary services required
 
+## Evaluation Versions
+
+Before creating your own copy, explore the evaluation versions:
+
+- **Version 1** (Winter 2025): [https://huggingface.co/spaces/keefereuther/Schema_Study_v1](https://huggingface.co/spaces/keefereuther/Schema_Study_v1)
+- **Version 2** (Current Preview): [https://huggingface.co/spaces/keefereuther/Schema_Study_Preview](https://huggingface.co/spaces/keefereuther/Schema_Study_Preview)
+
+**Note:** These are evaluation versions for testing. You'll need your OpenAI API key to interact with the chatbot on these evaluation versions. The production version can be found at [https://huggingface.co/spaces/keefereuther/Schema_Study](https://huggingface.co/spaces/keefereuther/Schema_Study).
+
 ## How to Use (Students)
 1. **Access the App:** Go to your Hugging Face Space URL. Enter the password provided by your instructor.
 2. **Select a Term:** Use the dropdown to pick a course term.
@@ -37,39 +47,80 @@ Schema Study is a free, no-code, open-source web application that turns a spread
 
 ## How to Use (Instructors)
 
-### Best Practices for Integration
+### Prerequisites
 
-Based on classroom testing and iterative refinement, here are recommended best practices for integrating Schema Study:
+Before starting, you'll need:
 
-- **Clear Structured Messaging:** Provide students with clear instructions on how to use Schema Study and its role in your course
-- **AI Literacy Training:** Include brief training on AI literacy and appropriate use of AI tools in educational settings
-- **Curricular Alignment:** Ensure your terms and context align with your learning objectives - update content regularly as you progress through the course
-- **Scaffolded Active Learning:** Embed Schema Study within structured assignments rather than as an optional tool
-- **Formative vs. Summative:** Use Schema Study for formative practice and feedback; evaluate independent performance in secure assessments outside the app
+- A web browser (Chrome, Firefox, or Safari)
+- An email address
+- A credit card to purchase $5-10 of credits for OpenAI API usage
+- Your course syllabus or a list of course learning objectives
+- About 1-2 hours to create your customized copy of Schema Study
 
-### Setup
-1. **Clone or Fork the Space:**
-   ```bash
-   git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
-   cd <your-space-name>
-   ```
+### Part 1: Setting Up Accounts
+
+#### 1. Create a Hugging Face Account
+
+Your chatbot will run inside a Hugging Face Space. Sign-up is browser-based and takes approximately 2 minutes.
+
+1. Go to [huggingface.co](https://huggingface.co) → Sign Up
+2. Verify your email before continuing
+
+#### 2. Open an OpenAI Platform Account
+
+**NOTE: This is different from a ChatGPT account.** An API (Application Programming Interface) is a way for your application to talk to OpenAI's systems. An API Key is like a special password that gives you permission to use OpenAI's services and keeps track of how much you're using.
+
+**Pricing Information:**
+- **GPT-4.1:** ~$2 per million input tokens, ~$8 per million output tokens
+- **GPT-5.1:** ~$1.25 per million input tokens, ~$10 per million output tokens
+- **GPT-5.2:** ~$1.75 per million input tokens, ~$14 per million output tokens
+
+*Note: One million tokens ≈ 750,000 words. Prices may vary by deployment tier.*
+
+1. Visit [platform.openai.com](https://platform.openai.com)
+2. Follow the [walkthrough video](https://www.youtube.com/watch?v=QiJ6cWm9Dx4) to generate an API key
+3. Preload $5-10 in API credits
+4. **Important:** Copy and save your API key in a secure place. You will need it later.
+
+### Part 2: Creating Your Terms CSV File
+
+1. **Download the template:** Use the `terms.csv` file as a starting point
+2. **Refine your TERM entries:**
+   - Do not alter column headers (TERM and CONTEXT)
+   - Edit the TERM column to contain terms and phrases relevant to your course learning objectives
+   - Terms can include concepts, case studies, people, course policies, mathematical/computing functions, or anything else you want students to learn deeply
+   - Add as many rows as you like
+3. **Tip:** Feed your syllabus to a generative AI chatbot (ChatGPT, Gemini, Claude) to generate a first draft of terms, then curate manually
+
+**CSV Format:**
+- First column: TERM (the term or concept name)
+- Second column: CONTEXT (definition, explanation, or course-specific context)
+
+### Part 3: Setting Up Your Hugging Face Space
+
+1. **Fork or Duplicate the Space:**
+   - Go to [https://huggingface.co/spaces/keefereuther/Schema_Study](https://huggingface.co/spaces/keefereuther/Schema_Study)
+   - Click "Duplicate this Space" to create your own copy
+   - Or clone via git:
+     ```bash
+     git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
+     cd <your-space-name>
+     ```
 
 2. **Edit Configuration:**
-   - Update `config.py` for your course (title, instructions, prompt templates, etc).
+   - Update `config.py` for your course (title, instructions, prompt templates, etc.)
    - Configure AI model settings:
      - `ai_model`: Choose "gpt-5.2" (default), "gpt-5.1", or "gpt-4.1"
      - `reasoning_effort`: For GPT-5.2 and GPT-5.1, set to "none" (fastest), "minimal", "low", or "medium"
      - `enable_web_search`: Set to `True` or `False` (default: True)
-   - Place your terms CSV (e.g., `terms.csv`) in the root directory. Format: first column = term, second column = context/definition.
+   - Place your terms CSV (e.g., `terms.csv`) in the root directory
 
 3. **Set Secrets:**
-   - Create `.streamlit/secrets.toml` file locally or use Hugging Face Space secrets:
-     ```toml
-     username = "your_username"
-     password = "your_password"
-     OPENAI_API_KEY = "your_openai_api_key"
-     ```
-   - For Hugging Face Spaces, go to **Settings > Repository secrets** and add the same keys.
+   - In your Hugging Face Space, go to **Settings > Repository secrets**
+   - Add the following secrets:
+     - `username`: Your desired username for app access
+     - `password`: Your desired password for app access
+     - `OPENAI_API_KEY`: Your OpenAI API key
 
 4. **Push Changes:**
    ```bash
@@ -78,7 +129,27 @@ Based on classroom testing and iterative refinement, here are recommended best p
    git push
    ```
 
+### Part 4: Customizing Schema Study
+
+All customization is done through `config.py`. Key sections include:
+
+- **A. Basic App Settings:** App title, terms CSV file, warning messages
+- **B. AI Model Settings:** Model selection, reasoning effort, temperature, web search
+- **C. Student Instructions:** Instructions displayed in the expander
+- **D. Prompt Template Buttons:** Five customizable conversation starters
+- **E. Attribution & License:** Sidebar footer information
+- **F. Resources List:** Sidebar links and downloadable files
+- **G. AI System Prompt:** Advanced customization of the tutor's behavior
+
+See the user manual (S2_user_manual_v3.pdf) for detailed configuration instructions.
+
+### Part 5: Sharing and Embedding
+
+1. **Share via Direct Link:** Copy your Space URL and share with students along with the username & password
+2. **Embed in LMS:** In the Space header, select "Embed this Space" and copy the `<iframe>` snippet. Post or embed inside your LMS (e.g., Canvas) along with the username & password. Students can authenticate seamlessly within your course platform.
+
 ### Model Selection Guide
+
 - **GPT-5.2** (default): Latest reasoning model, fastest with reasoning="none", supports web search
 - **GPT-5.1**: Reasoning model with reasoning="none" default for faster responses, supports web search
 - **GPT-4.1**: Use if you need temperature control or prefer non-reasoning model, excellent web search support
@@ -86,16 +157,28 @@ Based on classroom testing and iterative refinement, here are recommended best p
 ## Configuration
 
 ### AI Model Settings (`config.py`)
+
 - **Default Model:** GPT-5.2 with reasoning="none" for faster responses
 - **Alternative Models:** GPT-5.1 (reasoning model) or GPT-4.1 (non-reasoning model with temperature control)
 - **Web Search:** Configurable via `enable_web_search` (default: True)
 - **Reasoning Effort:** Configurable for GPT-5.2 and GPT-5.1 (options: "none", "minimal", "low", "medium")
 - **Temperature:** Configurable for GPT-4.1 (0.0-2.0)
 
+### Pacing and Question Control
+
+Schema Study enforces structured pacing to prevent cognitive overload. The system prompt enforces **one focused question plus one short, realistic application example per turn** to reduce confusion from multiple simultaneous follow-ups.
+
+**Universal Design for Learning (UDL) Adjustments:**
+- **For additional scaffolding:** Modify `term_prompt` to allow brief clarifying questions
+- **For advanced students:** Add instructions to keep responses focused and move efficiently toward connections
+
+The five prompt templates provide structured entry points for students who need additional support initiating conversations.
+
 ### Other Settings
-- All settings are in `config.py` (title, instructions, prompt templates, resources, AI model parameters, etc).
-- Theming is managed via `.streamlit/config.toml` and custom CSS in `app.py`.
-- Dependencies are listed in `requirements.txt`.
+
+- All settings are in `config.py` (title, instructions, prompt templates, resources, AI model parameters, etc.)
+- Theming is managed via `.streamlit/config.toml` and custom CSS in `app.py`
+- Dependencies are listed in `requirements.txt`
 
 ## Technical Details
 
@@ -106,6 +189,7 @@ Based on classroom testing and iterative refinement, here are recommended best p
 - **Inactivity Guard:** Streaming stops after 60s of no server deltas
 
 ### File Structure
+
 - `app.py` — Main Streamlit app with Responses API integration
 - `config.py` — All app settings and customization (model selection, web search, prompt templates, system prompt)
 - `.streamlit/secrets.toml` — Authentication credentials and API key (not tracked in git)
@@ -113,17 +197,34 @@ Based on classroom testing and iterative refinement, here are recommended best p
 - `terms.csv` — Your course terms and definitions (CSV format: term, context)
 - `example_syllabus.pdf` — Example resource file (replace with your own syllabus)
 - `LICENSE` — GNU GPL-3 License file
+- `S2_user_manual_v3.pdf` — Comprehensive user manual with detailed setup and configuration instructions
 
 ## License
 This project is licensed under the GNU GPL-3 License. See the [LICENSE](LICENSE) file for details.
 
+## Best Practices for Integration
+
+Based on classroom testing and iterative refinement, here are recommended best practices:
+
+- **Clear Structured Messaging:** Provide students with clear instructions on how to use Schema Study and its role in your course
+- **AI Literacy Training:** Include brief training on AI literacy and appropriate use of AI tools in educational settings
+- **Curricular Alignment:** Ensure your terms and context align with your learning objectives - update content regularly as you progress through the course
+- **Scaffolded Active Learning:** Embed Schema Study within structured assignments rather than as an optional tool
+- **Formative vs. Summative:** Use Schema Study for formative practice and feedback; evaluate independent performance in secure assessments outside the app
+
 ## Research & Citation
 
-This app, its corresponding CourseSource manuscript, and all documentation was authored, edited, and tested by Keefe Reuther, Dr. Liam O Mueller, Grace Constantian, Albert Nguyen, and the members of the Reuther Lab.
+This app, its corresponding manuscript, and all documentation was authored, edited, and tested by Keefe Reuther, [Liam O Mueller](https://biology.ucsd.edu/research/faculty/lomueller), Grace Constantian, Albert Nguyen, and the members of the Reuther Lab.
+
+Schema Study was developed to address critical challenges in undergraduate biology education: providing immediate, personalized formative feedback to increasingly large, diverse classes. The app uses evidence-based teaching practices and Socratic questioning to deepen understanding, correct misconceptions, and encourage students to find connections among course concepts.
 
 **Research Evidence:** During Winter 2025, Schema Study was integrated into an introductory biology course with 225 students. Pre- and post-surveys indicated strong student satisfaction, with 72% of students reporting they would reuse Schema Study in future biology courses. Each additional day per week students used Schema Study more than doubled the likelihood they would recommend it. Schema Study enhanced students' AI self-efficacy and their belief that AI is relevant to their education and careers.
 
-If you use this app in your research or teaching, please cite the associated CourseSource manuscript and acknowledge the developers.
+If you use this app in your research or teaching, please cite the associated manuscript:
+
+**Reuther, K., Mueller, L. O., Constantian, G., & Nguyen, A. (2025). Schema Study: A Large Language Model (LLM) Application for Asynchronous Student Learning and Inquiry. *CourseSource Teaching Tools and Strategies*.**
+
+The production version of this app can be found at [https://huggingface.co/spaces/keefereuther/Schema_Study](https://huggingface.co/spaces/keefereuther/Schema_Study).
 
 ## Acknowledgments
 
@@ -131,4 +232,6 @@ Developed by Keefe Reuther, Assistant Teaching Professor in the UC San Diego Sch
 
 This work was supported by University of California, San Diego intramural grants TG114333 and RG113974.
 
+## Support
+
 For questions about creating your own version of this application for use in your classroom, please email kdreuther@ucsd.edu.