@brainpilot/skills 0.0.6 → 0.0.8

package/skills/16_Animal_Behavior/deeplabcut/references/modelzoo.md

@@ -0,0 +1,98 @@
+# SuperAnimal & Model Zoo Reference
+
+## Table of Contents
+1. [SuperAnimal Overview](#superanimal-overview)
+2. [Zero-Shot Inference](#zero-shot-inference)
+3. [Fine-Tuning a SuperAnimal Model](#fine-tuning-a-superanimal-model)
+4. [Available Models](#available-models)
+
+## SuperAnimal Overview
+
+SuperAnimal models are pretrained across diverse datasets and can perform pose estimation on new animals without any additional training data. They support:
+- Top-view mice (various strains, fur colors)
+- Quadrupeds (dogs, horses, sheep, pigs, cheetahs, etc.)
+- Primate/human faces
+
+## Zero-Shot Inference
+
+Use `video_inference_superanimal` for out-of-the-box inference without any labeled data:
+
+```python
+import deeplabcut as dlc
+
+# Single video inference
+dlc.video_inference_superanimal(
+    videos=["/path/to/video.mp4"],
+    superanimal_name="superanimal_topviewmouse",
+    model_name="hrnet_w32",
+    detector_name="fasterrcnn_resnet50_fpn_v2",
+    scale_list=[200, 300, 400],
+    videotype=".mp4",
+)
+```
+
+**Key parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `videos` | List of video paths |
+| `superanimal_name` | Which pretrained model to use |
+| `model_name` | Pose model: `hrnet_w32`, `hrnet_w48` |
+| `detector_name` | Detector: `fasterrcnn_resnet50_fpn_v2` |
+| `scale_list` | Scales to try for detection; `[200, 300, 400]` is a good default. Larger animals → lower values (e.g. `[100, 200]`), smaller → higher (e.g. `[400, 600]`) |
+
+## Fine-Tuning a SuperAnimal Model
+
+When you have some labeled data, fine-tune for better accuracy:
+
+```python
+# Create a project from a SuperAnimal model
+config_path = dlc.create_pretrained_project(
+    path="my-superanimal-project",
+    task="my_task",
+    videos=["/path/to/video.mp4"],
+    superanimal_name="superanimal_topviewmouse",
+    model_name="hrnet_w32",
+    detector_name="fasterrcnn_resnet50_fpn_v2",
+    working_directory="/path/to/projects",
+    copy_videos=False,
+)
+
+# Now use the standard pipeline:
+# 1. extract_frames -> 2. label_frames -> 3. create_training_dataset -> 4. train_network
+# The pretrained weights give a huge head start; often 5K-20K iterations suffice.
+```
+
+## Available Models
+
+### Pose Models (`model_name`)
+
+| Model | Description |
+|-------|-------------|
+| `hrnet_w32` | Default, good balance of speed/accuracy |
+| `hrnet_w48` | Higher accuracy, more parameters |
+| `resnet_50` | ResNet-50 backbone |
+| `resnet_101` | ResNet-101 backbone |
+
+### Detectors (`detector_name`)
+
+| Detector | Description |
+|----------|-------------|
+| `fasterrcnn_resnet50_fpn_v2` | Default, good for multi-animal |
+| `fasterrcnn_mobilenet_v3_large_fpn` | Lighter, faster |
+
+### SuperAnimal Species
+
+| `superanimal_name` | Species | Keypoints |
+|---------------------|---------|-----------|
+| `superanimal_topviewmouse` | Top-view mice | 21 (nose, ears, limbs, tail base) |
+| `superanimal_quadruped` | Dogs, horses, sheep, pigs, etc. | 39 |
+| `superanimal_face` | Primate/human faces | 54 |
+| `superanimal_full` | Combined topview mouse + quadruped | Combined |
+
+## Tips
+
+- **Scale is critical**: If detections are poor, tune `scale_list`. Each value represents a different box size. Start with `[200, 300, 400]` and expand the range if needed.
+- **GPU required**: SuperAnimal models require a GPU for practical use.
+- **`create_pretrained_project` uses symbolic links**: the model weights are linked, not copied, so don't delete the original.
+- **dlclibrary**: Models are downloaded via `dlclibrary` from HuggingFace on first use.

package/skills/16_Animal_Behavior/deeplabcut/references/standard-pipeline.md

@@ -0,0 +1,165 @@
+# Standard Pipeline Reference
+
+## Table of Contents
+1. [Create a Project](#create-a-project)
+2. [Extract & Label Frames](#extract-label-frames)
+3. [Create Training Dataset](#create-training-dataset)
+4. [Train & Evaluate](#train-evaluate)
+5. [Analyze Videos](#analyze-videos)
+6. [Export Results](#export-results)
+
+## Create a Project
+
+```python
+import deeplabcut as dlc
+
+config_path = dlc.create_new_project(
+    "ProjectName",       # project name
+    "ExperimenterName",  # your name
+    ["/path/to/video.mp4"],      # video(s) to add
+    working_directory="/path/to/projects",
+    copy_videos=False,   # True = copy, False = symlink
+    multianimal=False,   # True for maDLC
+)
+```
+
+A `config.yaml` is created. Edit it to adjust bodyparts, skeleton, etc. Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `bodyparts` | List of body part names to track |
+| `skeleton` | Pairs of bodyparts for skeleton lines in visualization |
+| `numframes2pick` | How many frames to extract for labeling (~20 recommended) |
+| `TrainingFraction` | Fraction of data used for training (e.g. `[0.95]`) |
+| `iteration` | Training iteration identifier |
+
+## Extract & Label Frames
+
+```python
+# Extract frames for manual labeling
+dlc.extract_frames(
+    config_path,
+    mode="automatic",    # or "manual"
+    algo="kmeans",       # clustering method: kmeans, uniform
+    crop=True,           # crop around animal for better labeling
+    userfeedback_percentage=20,
+)
+
+# User labels frames using the GUI
+# dlc.label_frames(config_path)  # opens labeling GUI
+
+# After labeling, check labels for completeness
+dlc.check_labels(config_path, display_suggestions=True)
+```
+
+**Labeling tips:**
+- Label ~20-50 frames for good initial results
+- Use `kmeans` algorithm for diverse frame selection
+- Set `crop=True` to zoom in on animals for precise labeling
+
+## Create Training Dataset
+
+```python
+dlc.create_training_dataset(
+    config_path,
+    net_type="resnet_50",     # see net types below
+    augmenter_type="imgaug",   # or "tensorpack", "default"
+    num_shuffles=1,
+)
+```
+
+Available architectures:
+
+| `net_type` | Best for |
+|-----------|----------|
+| `resnet_50` | Default, good accuracy-speed balance |
+| `resnet_101` | Higher accuracy, slower|
+| `resnet_152` | Maximum accuracy |
+| `mobilenet_v2_1.0` | Lightweight, faster inference |
+| `efficientnet-b0` | Efficient, good for deployment |
+| `dlcrnet_ms5` | Multi-scale, good for small body parts |
+
+## Train & Evaluate
+
+```python
+# Train
+dlc.train_network(
+    config_path,
+    maxiters=100000,     # more iters = more training
+    saveiters=5000,      # checkpoint interval
+    displayiters=500,    # console update interval
+    max_snapshots_to_keep=5,
+)
+
+# Evaluate on test set
+dlc.evaluate_network(
+    config_path,
+    Shuffles=[1],
+    plotting=True,
+    show_errors=True,
+)
+
+# Evaluate returns: train_error, test_error, p_cutoff
+# p_cutoff: probability threshold for good predictions
+```
+
+**Key metrics:**
+- RMSE < 5 pixels is usually "good enough"
+- Use `p_cutoff` from evaluation to filter predictions later
+- If accuracy is low: label more frames, use deeper network, increase `maxiters`
+
+## Analyze Videos
+
+```python
+# Predict poses for all frames
+dlc.analyze_videos(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    save_as_csv=True,
+    batchsize=8,
+)
+
+# Create labeled video with predictions overlaid
+dlc.create_labeled_video(
+    config_path,
+    ["/path/to/video.mp4"],
+    filtered=True,      # apply ARIMA filtering
+    trailpoints=10,     # trail length for visualization
+)
+
+# Filter predictions (removes jitter)
+dlc.filterpredictions(
+    config_path,
+    ["/path/to/video.mp4"],
+    filtertype="arima",   # or "median"
+    ARdegree=3,
+    MAdegree=1,
+)
+```
+
+## Export Results
+
+H5 files are in the video directory. Export to CSV:
+
+```python
+# Export to CSV
+dlc.analyze_videos_converth5_to_csv(
+    "/path/to/videoDLC_resnet50_ProjectNameJul9",
+    videotype=".mp4",
+)
+
+# Convert to NWB (Neurodata Without Borders)
+dlc.analyze_videos_converth5_to_nwb(
+    "/path/to/videoDLC_resnet50_ProjectNameJul9",
+    scorer="YourName",
+)
+
+# Plot trajectories
+dlc.plot_trajectories(
+    config_path,
+    ["/path/to/video.mp4"],
+    filtered=True,
+    showfigure=True,
+)
+```

package/skills/16_Animal_Behavior/deeplabcut/references/utilities.md

@@ -0,0 +1,146 @@
+# Video & Data Utilities Reference
+
+## Table of Contents
+1. [Video Preprocessing](#video-preprocessing)
+2. [Post-Processing Predictions](#post-processing-predictions)
+3. [Data Export & Conversion](#data-export-conversion)
+4. [Skeleton Analysis](#skeleton-analysis)
+5. [Outlier Detection](#outlier-detection)
+
+## Video Preprocessing
+
+```python
+import deeplabcut as dlc
+
+# Collect all videos in a directory
+videos = dlc.collect_video_paths("/path/to/video_dir", videotype=[".mp4", ".avi"])
+
+# Check video integrity
+dlc.check_video_integrity(videos)
+
+# Crop video
+dlc.CropVideo("/path/to/video.mp4", start=100, end=5000, output_path="cropped.mp4")
+
+# Downsample (reduce frame rate)
+dlc.DownSampleVideo("/path/to/video.mp4", factor=2, output_path="downsampled.mp4")
+
+# Shorten video
+dlc.ShortenVideo("/path/to/video.mp4", start="00:00:05", stop="00:05:00", output_path="short.mp4")
+```
+
+## Post-Processing Predictions
+
+```python
+# Filter jittery predictions
+dlc.filterpredictions(
+    config_path,
+    ["/path/to/video.mp4"],
+    filtertype="arima",    # or "median"
+    ARdegree=3,
+    MAdegree=1,
+    p_bound=0.5,           # min probability to keep
+)
+
+# Create video with all raw detections (before filtering)
+dlc.create_video_with_all_detections(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+)
+```
+
+**Filter tips:**
+- `arima`: Better for smooth tracking, uses temporal context
+- `median`: Simple, fast, good for quick cleanup
+- Low `p_bound` (0.1) keeps more predictions; high (0.9) is more conservative
+
+## Data Export & Conversion
+
+```python
+# Convert H5 to CSV
+dlc.analyze_videos_converth5_to_csv(
+    "/path/to/output_folder",
+    videotype=".mp4",
+    scorer="YourName",
+)
+
+# Convert CSV to H5
+dlc.convertcsv2h5("config.yaml", "user_specified")
+
+# Convert single-animal project to maDLC format
+dlc.convert2_maDLC(config_path, num_bodyparts=6)
+
+# Export to NWB (supports NWB 2.0)
+dlc.analyze_videos_converth5_to_nwb(
+    "/path/to/output_folder",
+    scorer="YourName",
+    videotype=".mp4",
+    individual_name="mouse1",
+)
+```
+
+## Skeleton Analysis
+
+Compute bone lengths and joint angles from predictions:
+
+```python
+dlc.analyzeskeleton(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    save_as_csv=True,
+    filtered=True,
+)
+```
+
+## Outlier Detection
+
+Find and relabel problematic frames:
+
+```python
+# Find outliers in raw predictions
+dlc.find_outliers_in_raw_data(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+)
+
+# Extract outlier frames for relabeling
+dlc.extract_outlier_frames(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    extractionalgorithm="jump",  # or "uncertain", "manual"
+    p_bound=0.5,
+)
+```
+
+**Extraction algorithms:**
+- `"jump"`: Find frames where body parts jump more than expected
+- `"uncertain"`: Find frames with low prediction confidence
+- `"manual"`: Use outlier data from `find_outliers_in_raw_data`
+
+## Merge Datasets
+
+Combine training data from multiple projects:
+
+```python
+# Merge two labeled datasets
+dlc.merge_datasets(
+    config_path,
+    [project_config1_path, project_config2_path],
+)
+```
+
+## Trajectory Plotting
+
+```python
+dlc.plot_trajectories(
+    config_path,
+    ["/path/to/video.mp4"],
+    videotype=".mp4",
+    filtered=True,
+    displayedbodyparts=["nose", "tailbase"],
+    showfigure=True,
+)
+```

package/skills/16_Animal_Behavior/ethoclaw-analysis-report/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: ethoclaw-analysis-report
+description: Used to generate a structured analysis report based on existing skeleton data, behavioral data, statistical tables, and result figures under a single project path (project_path). First generates manifest.json, then the agent directly fills in the section bodies in the manifest, and finally renders a structured analysis report. Applicable to scenarios such as heatmaps, trajectory plots, radar plots, violin plots, cluster plots, and statistical result summaries. Default output is a single-file HTML report. Users may trigger this with English requests like "generate a report based on this project folder", "organize these results into an HTML report", "generate an analysis summary based on existing charts", or "help me check the groupings and produce a report".
+---
+
+# Ethoclaw Analysis Report
+
+Generate a structured analysis report based on existing data and figures under a single `project_path`. The main workflow is fixed as follows:
+
+1. Use `build_report_manifest.py` to generate `manifest.json`
+2. The agent only reads `manifest.json` and directly fills in `manifest["section_bodies"][...]["body"]`
+3. Use `render_report.py --manifest manifest.json` to render `report.md` and single-file `report.html`
+
+Do not create `sections.json`. Do not write the main text to other intermediate files. `manifest.json` is the only intermediate product.
+
+## Environment Requirements
+
+- Python `>=3.10`
+  - The current scripts use modern type annotation syntax like `str | None`, `list[...]`, which cannot be run directly on interpreters below 3.10
+- Required dependency: `Pillow`
+  - `report_utils.py` directly depends on `PIL.Image`
+  - Used to compress and embed `.png` / `.jpg` / `.jpeg` images when rendering HTML
+- File encoding: Must read/write `manifest.json`, `report.md`, `report.html` in `UTF-8`
+- Shell/platform notes:
+  - Under Windows PowerShell, long Chinese text passed through command line arguments, pipes, here-strings, environment variables, or `python -c` / `python -` injection can easily be replaced with `?` or produce garbled text
+  - Therefore, text filling must directly edit the `manifest.json` file itself, not through shell text channels
+
+## Core Scope
+
+Process only one project directory. The user must provide `project_path`, and only files under that path can be read.
+
+Allowed inputs include but are not limited to:
+
+- Skeleton or trajectory data: `.h5`, `.csv`, keypoint coordinate tables
+- Behavioral or statistical data: summary tables, event tables, significance test tables, parameter tables, single-sample statistical JSON
+- Image results: heatmaps, trajectory plots, radar plots, violin plots, cluster plots, atlas, time-series plots
+- Project metadata: description text, same-directory notes files, experimental information supplemented by the user in conversation
+
+Do not assume the project must have groupings, nor that all charts must be complete.
+
+## Script Responsibilities
+
+- `scripts/build_report_manifest.py`
+  - Input: `project_path`
+  - Output: `manifest.json`
+  - Responsible for scanning the project, summarizing facts, determining report mode, and generating fillable `section_bodies`
+
+- Agent
+  - Input: `manifest.json`
+  - Responsible for reading instructions in `facts`, `galleries`, and `section_bodies`
+  - Directly fills in `manifest["section_bodies"][body_key]["body"]`
+
+- `scripts/render_report.py`
+  - Input: `manifest.json` with filled body text
+  - Output: `report.md`, single-file `report.html`
+  - HTML embeds images as compressed data URIs by default, not relying on external image files
+  - Only responsible for rendering, not for automatically filling in body text
+
+## Language Detection
+
+Before starting any report generation, determine the report language based on the following priority:
+default to English
+
+## Standard Workflow
+
+Execute in the following order:
+
+0. **Detect report language**: Apply the language detection rules above to determine whether to generate report
+1. Confirm the user has provided `project_path`
+2. Run `build_report_manifest.py --project-path <project_path> --output <manifest.json>`
+3. Read `manifest.json`
+4. Check `facts.unconfirmed_items` and `facts.sample_check`
+5. If there are key metadata missing, first ask the user questions
+6. Fill in each `manifest["section_bodies"][body_key]["body"]`
+7. Save back to the same `manifest.json`
+8. Re-read the just-written `manifest.json` in UTF-8, check each filled `body` to ensure it is still normal text, not `?`, `\uFFFD`, garbled text, or truncated text
+9. Only after confirming step 8 is correct, run `render_report.py --manifest <manifest.json> --output-dir <report_output>`
+
+Do not render an empty report first and then fill it in.
+When filling in body text, directly edit the existing `manifest.json` file, not through shell inline text, command arguments, redirection, or pipes to write large text into JSON.
+Also do not first assemble body text into `python -c`, `python -`, `node -e`, PowerShell here-string, `jq` filters, environment variables, or any command line string, and then have the script write it back to `manifest.json`; these are text injection, not "direct file editing".
+
+## Confirm project_path First
+
+You must confirm the user has provided `project_path` before starting work.
+
+If not provided:
+
+- First ask the user for `project_path`
+- Before getting the path, do not assume default directories, do not search across directories for materials
+
+If the user provides a path:
+
+- Only read files under that path
+- Do not fetch images and data from sibling directories, parent directories, or other project directories
+- If the path materials are insufficient, only report the insufficiency and ask questions, do not change to read other directories
+
+## When Questions Must Be Asked
+
+The following information, if cannot be confirmed within the project path, must be asked to the user first before continuing to generate a complete report:
+
+- Whether there are groupings; if file name prefixes already clearly show labels like `control`, `model`, `sham`, `vehicle`, they can be treated as candidate groupings first
+- Meaning of each group label, e.g., what do opaque abbreviations like `Y`, `con`, `k` represent
+- Which group is the control group, or if there is no control group at all
+- Experimental paradigm, experimental scenario, or task type
+- Report purpose: internal reporting, experimental records, manuscript draft, figure organization, etc.
+- Whether explanatory conclusions are allowed, or only result organization
+- If there are multiple result directories, which is the main result for this report
+
+Before confirming these key items:
+
+- Material inventory and result description based on current evidence can be completed
+- Section bodies that do not depend on background explanation can be filled in
+- Do not output a complete report with strong conclusions
+- Do not automatically interpret unclear abbreviations as experimental group meanings; only make candidate grouping judgments for obvious labels like `control`, `model`
+
+## manifest.json Contract
+
+`manifest.json` must contain at least these top-level fields:
+
+- `project_path`
+- `project_name`
+- `report_title`
+- `report_goal`
+- `scan`
+- `report_mode`
+- `report_mode_reason`
+- `facts`
+- `galleries`
+- `section_bodies`
+
+Where `section_bodies` is the only location for body text filling. Structure:
+
+```json
+{
+  "overview_body": {
+    "section_id": "overview",
+    "title": "Project Overview",
+    "purpose": "Provide a brief overview at the project level.",
+    "write_when": "Usually filled in; if even the basic project purpose cannot be confirmed, outline as result organization.",
+    "source_fields": ["facts.overview", "report_mode", "facts.unconfirmed_items"],
+    "rules": [
+      "Explain project name, report purpose, experimental paradigm or its absence.",
+      "Overview can cover core figure types or analysis scope."
+    ],
+    "body": ""
+  }
+}
+```
+
+The agent only needs to change `body`. Do not change the meaning of `section_id`, `title`, `purpose`, `write_when`, `source_fields`, `rules`.
+If batch modifying multiple bodies is needed, also directly edit this UTF-8 `manifest.json` file itself, not assembling a shell command containing the body text to overwrite it.
+After writing, must re-read this `manifest.json` from disk to confirm each filled `body` can display as normal UTF-8 text; only after confirming the body text is correct in the file can the rendering step proceed.
+
+## What to Write for Each Body
+
+### `project_summary_body`
+
+- Purpose: Compress project path, material scope, current mode, and key gaps into a short section
+- Required content: Scan scope, core materials, most suitable writing approach, most critical gaps
+- Should not include: File-by-file lists, materials outside the path, long disclaimers
+
+### `overview_body`
+
+- Purpose: Provide high-level overview at the project level and first point out the most obvious result characteristics
+- Required content: Project name, experimental paradigm, current report purpose, what this experiment typically evaluates and basic workflow, 1-2 most notable conclusions from current data
+- Should not write: Turn the entire section into method description
+
+### `sample_check_body`
+
+- Purpose: Verify samples and groupings
+- Required content: Sample count, sample IDs, candidate group labels, whether group names are confirmed, control group status, items to be confirmed
+- Should not write: Force interpretation of unclear abbreviations
+- Additional requirement: If file name prefixes already clearly show labels like `control`, `model`, `sham`, `vehicle`, they can be directly treated as candidate groupings
+
+### `raw_trajectory_body`
+
+- Purpose: When only raw skeleton or trajectory data exists, provide simple result summary based on coordinate distribution and path length
+- Required content: Which raw trajectory files were used, most obvious activity areas or principal axis distribution, intuitive differences in movement range or path length
+- Should not write: Hard map horizontal/vertical axes to confirmed open arm/closed arm without device mapping
+- Enable by default: As long as raw trajectory summary can be extracted from the project, whether single-sample or multi-sample, it should be filled in
+
+### `heatmap_body`
+
+- Purpose: Summarize spatial distribution or movement patterns shown in heatmaps, trajectory plots, atlas, time-series plots
+- Required content: Which figures were referenced, main phenomena observed on the figures
+- Should not write: Statistical significance or mechanistic conclusions
+
+### `radar_body`
+
+- Purpose: Summarize multi-parameter profiles in radar plots
+- Required content: What the figure represents, profile relative highs and lows, main difference points
+- Should not write: Unconfirmed indicator meanings, unconfirmed inter-group comparisons
+
+### `stats_body`
+
+- Purpose: Summarize comparison results supported by statistical tables or statistical figures
+- Required content: Which statistical tables/figures were referenced, and comparison results that can be supported by these materials
+- Should not write: Significance conclusions when there are no statistical tables
+- Additional requirement: Even if formal grouping definitions are incomplete, if group names are very obvious, raw difference directions can be summarized, but do not write mechanistic conclusions
+
+### `cluster_body`
+
+- Purpose: Describe the pattern structure presented in cluster plots
+- Required content: Clustering targets, relative proximity or separation trends
+- Should not write: Turn visual separation into statistical significance
+
+### `single_subject_body`
+
+- Purpose: Summarize core results for a single individual or single record in single-sample mode
+- Required content: Total duration, effective detection duration, distance, core indicators like area residence/entry; if only raw skeleton data exists, also write main activity areas based on trajectory distribution
+- Should not write: Group-level patterns
+
+### `integrated_interpretation_body`
+
+- Purpose: Integrate multiple result sources across figure types
+- Required content: Which figure types or statistical sources were integrated, which are facts and which are interpretations based on current experimental paradigm
+- Should not write: Unapproved mechanistic or causal summaries
+
+## Report Modes
+
+Prioritize selecting the most appropriate one from the following modes:
+
+- `single-subject`
+- `multi-sample-no-groups`
+- `grouped-raw-summary`
+- `grouped-comparison`
+- `raw-trajectory-summary`
+- `figure-only-summary`
+- `data-inventory-only`
+
+If multiple modes could all apply, prioritize the one that best matches the existing evidence; if there are still key ambiguities, confirm with the user.
+
+## Reference Navigation
+
+Read the following files as needed based on task phase, do not load all at once:
+
+- When needing to determine what material types are in the current directory: read `references/input-types.md`
+- When needing to determine which items must be confirmed with the user: read `references/metadata-schema.md`
+- When needing to determine what sections exist for this report and body responsibilities: read `references/report-sections.md`
+- When needing to select report mode and sections based on materials: read `references/section-selection-rules.md`
+- When needing to constrain interpretation scope and avoid out-of-bounds conclusions: read `references/interpretation-guardrails.md`
+- If `facts.overview.experiment_type` or other project materials explicitly point to a specific animal behavior paradigm, read the corresponding file before writing `overview_body`, `raw_trajectory_body`, `heatmap_body`, `stats_body`, `single_subject_body`, `integrated_interpretation_body`:
+  - `TCST`: `references/experiment-types/tcst.md`
+  - `OFT`: `references/experiment-types/oft.md`
+  - `TST`: `references/experiment-types/tst.md`
+  - `EPM`: `references/experiment-types/epm.md`
+  - `FST`: `references/experiment-types/fst.md`
+  - `NOR`: `references/experiment-types/nor.md`
+- When needing to view display templates: read `assets/report_template_en.md` and related `assets/section_templates/*.md`
+
+## Expression Requirements
+
+- The default language of body should match the current user's conversation language; write in English if the user communicates in English; if the user explicitly specifies the report language, prioritize the user's specification.
+- When terms first appear, prioritize using "English" format, especially for statistical methods, figure types, ethology metrics, and experimental paradigm names; subsequent text can keep one writing style as long as it doesn't cause ambiguity.
+- File names, group labels, column names, and original metric names that come from project files can retain original English, do not forcibly translate and then rewrite the original values.
+- Prioritize giving the most direct and informative summary based on current data, do not avoid obvious result characteristics just because of lacking complete background.
+- If limitations need to be stated, concentrate them in `project_summary_body`, `overview_body`, or `integrated_interpretation_body` briefly once, do not repeat disclaimers in every section.
+- When the experimental paradigm is already clear, concise conclusions can be made about area preference, exploration direction, activity pattern, or coping style by combining with the paradigm's readout meaning.
+- First explain which files and figures are based on, then write interpretations
+- Separate "observed facts" from "inferences based on context"
+- When figures or tables are missing, skip the corresponding body and keep empty string
+- When there are no groupings, do not write inter-group comparisons
+- When there are no statistical tables, do not write significance conclusions
+- When there are only figures without reliable table support, summarize the most obvious image patterns, but do not write as statistical significance or mechanistic conclusions
+- Do not render prompt text, writing instructions, or reasoning rules into the final HTML
+
+## Quality Constraints
+
+- Do not read materials outside `project_path`
+- Do not fabricate group meanings, sample sizes, experimental backgrounds, statistical methods, or result conclusions
+- Do not directly write clustering, heatmaps, or visual separations as significant differences
+- Do not exaggerate single-sample phenomena into group-level patterns
+- If the user doesn't provide report purpose, ask first; if the answer cannot be obtained temporarily, write as "result organization" first