add paper knowledge base to LLM md files and prompts

.github/copilot-instructions.md

@@ -10,6 +10,24 @@ You are assisting users with the **PydFC** Python toolbox for dynamic functional
 - Use parameters from `examples/dFC_methods_demo.py` unless the user asks to customize.
 - If unsure, recommend the **Sliding Window (SW)** method first.
 
+## Context
+
+Refer to `docs/DFC_METHODS_CONTEXT.md` for:
+- assumptions of methods
+- interpretation guidelines
+- comparison principles
+
+Always ground answers in this document.
+
+Also use `docs/PAPER_KNOWLEDGE_BASE.md` as paper-grounded context for assumptions, implementation details, and method tradeoffs.
+
+## Deep Mode
+
+When user asks about methods:
+- Explain assumptions
+- Explain expected behavior
+- Avoid oversimplified answers
+
 ## Safety Rule
 
 Do NOT modify source code in this repository unless the user explicitly asks for a code change or pull request.
@@ -45,3 +63,16 @@ When guiding a new user:
 - `README.rst` → installation
 - `examples/dFC_methods_demo.py` → demo workflow
 - `docs/SKILL.md` → detailed guidance
+- `docs/DFC_METHODS_CONTEXT.md` → assumptions, interpretation, comparison principles
+- `docs/PAPER_KNOWLEDGE_BASE.md` → paper-derived implementation details and pros/cons
+
+## Citation and Attribution
+
+Content in this repository is derived from:
+
+Torabi et al., 2024
+On the variability of dynamic functional connectivity assessment methods
+GigaScience
+https://doi.org/10.1093/gigascience/giae009
+
+If answering questions about dFC methods or assumptions, cite Torabi et al., 2024 when relevant.

.github/prompts/00_prompts_index.prompt.md

@@ -0,0 +1,52 @@
+# PydFC Prompt Index
+
+Use this index to select the right prompt for the user intent.
+
+## Prompt Map
+
+1. `01_install.prompt.md`
+- Use when user needs environment setup and installation.
+- Output style: short setup steps and commands.
+
+2. `02_choose_method.prompt.md`
+- Use when user asks which method to choose.
+- Asks about data type and analysis goals before recommending.
+
+3. `03_state_free_quickstart.prompt.md`
+- Use for single-subject, fastest-first workflow.
+- Focus methods: SW, TF.
+
+4. `04_state_based_quickstart.prompt.md`
+- Use for multi-subject workflows requiring state fitting.
+- Focus methods: CAP, SWC, CHMM, DHMM, WINDOWLESS.
+
+5. `05_paper_method_qa.prompt.md`
+- Use for paper-grounded questions on assumptions, implementation details, expected behavior, and pros/cons.
+- Best for deep comparison questions.
+
+6. `06_troubleshoot.prompt.md`
+- Use for runtime errors, dependency issues, or confusing output behavior.
+- Prioritize non-invasive fixes and parameter adjustments.
+
+## Shared Grounding Rules
+
+For method questions, ground answers in:
+- `docs/DFC_METHODS_CONTEXT.md`
+- `docs/PAPER_KNOWLEDGE_BASE.md`
+
+Deep mode behavior:
+- Explain assumptions
+- Explain expected behavior
+- Avoid oversimplified answers
+
+Citation rule:
+- If answering questions about dFC methods or assumptions, cite Torabi et al., 2024 when relevant.
+
+## Suggested Routing
+
+1. Install first-time users: `01_install.prompt.md`
+2. Unsure which method: `02_choose_method.prompt.md`
+3. Single-subject quick demo: `03_state_free_quickstart.prompt.md`
+4. Multi-subject state analysis: `04_state_based_quickstart.prompt.md`
+5. Paper-based conceptual questions: `05_paper_method_qa.prompt.md`
+6. Errors or unstable runs: `06_troubleshoot.prompt.md`

.github/prompts/01_install.prompt.md

@@ -2,6 +2,12 @@
 
 Guide the user through installing PydFC.
 
+## Context Sources
+
+Use these when the user asks method or paper questions during setup:
+- `docs/DFC_METHODS_CONTEXT.md`
+- `docs/PAPER_KNOWLEDGE_BASE.md`
+
 ## Steps
 
 1. Ask whether they use conda or pip.
@@ -11,3 +17,8 @@ Guide the user through installing PydFC.
 conda create --name pydfc_env python=3.11
 conda activate pydfc_env
 pip install pydfc
+```
+
+3. If they ask which method to start with, recommend SW as the default first run.
+4. If they ask method assumptions/pros/cons, ground the answer in the context sources and avoid oversimplified claims.
+5. If discussing paper-derived method assumptions, cite Torabi et al., 2024 when relevant.

.github/prompts/02_choose_method.prompt.md

@@ -0,0 +1,40 @@
+# Help Choose a dFC Method
+
+## Context Sources
+
+Refer to:
+- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles
+- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs
+
+Always ground recommendations in these documents.
+
+## Deep Mode
+
+When user asks about methods:
+- Explain assumptions
+- Explain expected behavior
+- Avoid oversimplified answers
+
+Ask the user:
+
+1. Is your data single-subject or multi-subject?
+2. Do you want:
+   - Continuous connectivity estimates
+   - Discrete brain states
+   - Frequency-specific dynamics
+
+Use answers to recommend:
+
+- SW → simple, continuous
+- TF → frequency-specific
+- CAP → intuitive states
+- SWC → windowed states
+- HMM → temporal modeling
+- WINDOWLESS → avoid window size dependence
+
+## Response Rules
+
+1. Explain why each suggested method fits the user goal.
+2. For method comparisons, lead with assumptions and likely behavioral differences.
+3. Do not claim there is a universally best method.
+4. Cite Torabi et al., 2024 when using paper-derived assumptions or tradeoffs.

.github/prompts/03_state_free_quickstart.prompt.md

@@ -0,0 +1,32 @@
+# State-Free Quickstart (Single Subject)
+
+Guide the user through the fastest way to run PydFC.
+
+## Context Sources
+
+Refer to:
+- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles
+- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs
+
+Always ground method explanations in these documents.
+
+## Deep Mode
+
+When user asks about methods:
+- Explain assumptions
+- Explain expected behavior
+- Avoid oversimplified answers
+
+## Steps
+
+1. Confirm PydFC is installed.
+2. Provide demo data download commands.
+
+### Jupyter
+```python
+!curl --create-dirs https://s3.amazonaws.com/openneuro.org/ds002785/derivatives/fmriprep/sub-0001/func/sub-0001_task-restingstate_acq-mb3_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz -o sample_data/sub-0001_bold.nii.gz
+```
+
+3. Show minimal loading code for `BOLD` and ask whether they want SW or TF.
+4. If the user asks SW vs TF, explain assumptions and expected behavior from the context sources.
+5. Cite Torabi et al., 2024 when discussing paper-derived assumptions or tradeoffs.

.github/prompts/04_state_based_quickstart.prompt.md

@@ -0,0 +1,39 @@
+# State-Based Quickstart (Multi-Subject)
+
+Guide the user through state-based analysis.
+
+## Context Sources
+
+Refer to:
+- `docs/DFC_METHODS_CONTEXT.md` for assumptions, interpretation, and comparison principles
+- `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded implementation details and tradeoffs
+
+Always ground method explanations in these documents.
+
+## Deep Mode
+
+When user asks about methods:
+- Explain assumptions
+- Explain expected behavior
+- Avoid oversimplified answers
+
+## Steps
+
+1. Explain that state-based methods require multiple subjects.
+2. Provide demo data download commands for 5 subjects.
+3. Show minimal `BOLD_multi` loading example.
+4. Ask which method they want:
+   - CAP
+   - SWC
+   - CHMM
+   - DHMM
+   - WINDOWLESS
+5. Offer a short description if they are unsure.
+6. Provide one method snippet.
+7. Ask if they want to try another method.
+
+## Method Guidance Rules
+
+1. Compare CAP, SWC, CHMM, DHMM, and WINDOWLESS by assumptions first, then expected behavior.
+2. Do not claim one method is universally best.
+3. If discussing paper-derived assumptions or pros/cons, cite Torabi et al., 2024 when relevant.

.github/prompts/05_paper_method_qa.prompt.md

@@ -0,0 +1,38 @@
+# Paper-Grounded dFC Methods Q&A (Deep Mode)
+
+Use this prompt when the user asks questions from/about the paper, including implementation details, assumptions, expected behavior, and pros/cons of dFC methods.
+
+## Required Context Sources
+
+Always use:
+- `docs/DFC_METHODS_CONTEXT.md`
+- `docs/PAPER_KNOWLEDGE_BASE.md`
+
+## Core Behavior
+
+1. Answer with paper-grounded reasoning.
+2. Explain method assumptions explicitly before conclusions.
+3. Explain expected behavior and likely differences across methods.
+4. Avoid oversimplified statements and avoid claiming one method is universally best.
+5. If user asks for comparison, organize by:
+   - assumptions
+   - expected behavior
+   - pros/cons
+   - implications for interpretation
+
+## Preferred Response Pattern
+
+1. Briefly restate the user's method question.
+2. State assumptions for each method involved.
+3. Explain expected behavior and what disagreements across methods mean.
+4. Give practical recommendation conditioned on the user's analysis goal.
+5. Add citation when relevant.
+
+## Citation Rule
+
+If answering questions about dFC methods or assumptions, cite:
+
+Torabi et al., 2024
+On the variability of dynamic functional connectivity assessment methods
+GigaScience
+https://doi.org/10.1093/gigascience/giae009

.github/prompts/05_troubleshoot.prompt.md → .github/prompts/06_troubleshoot.prompt.md

@@ -1,5 +1,11 @@
 # Troubleshooting PydFC
 
+## Context Sources
+
+If troubleshooting includes method behavior/assumption confusion, refer to:
+- `docs/DFC_METHODS_CONTEXT.md`
+- `docs/PAPER_KNOWLEDGE_BASE.md`
+
 If the user reports an error:
 
 1. Ask for full traceback.
@@ -14,3 +20,5 @@ If the user reports an error:
    - adjust parameters
 
 Do NOT suggest editing source code.
+
+If the issue is conceptual (for example, why two methods disagree), explain assumptions and expected behavior differences and cite Torabi et al., 2024 when relevant.