trees_gene_families + trees_gene_groups: deep README+AI_GUIDE eval pass — bring to phylonames/genomesDB/trees_species parity

Completes the docs-cleanup sweep that started with phylonames (35eae52),
genomesDB (1130202/332e2f5), trees_species (3303916/7d14730), and
orthogroups (2798129). Both trees_gene_* subprojects now match those at
the same documentation depth.

trees_gene_families (single template, UNIT pattern, 76 frozen instances)
======================================================================

Filesystem changes:
- Moved research_notebook content to project-root sandbox per §1
  consolidation: README.md → research_notebook/research_user/subproject-trees_gene_families/README.md
  (git mv); rgs_from_before/ and species_keeper_list-species70.tsv plain-mv
  (gitignored sandbox content).
- Deleted per-subproject research_notebook/ (.gitkeep removed via git rm).

7 AI_GUIDE-*.md → AI_GUIDE.md renames in the template (per §3):
- AI_GUIDE-trees_gene_families.md
- gene_family_COPYME/STEP_{1,2,3}/AI_GUIDE-*.md
- gene_family_COPYME/STEP_{1,2,3}/workflow-COPYME-*/ai/AI_GUIDE-*.md

Bulk sed in template docs only (excluded 76 gene_family-<instance>/ dirs
per §47 + all workflow-RUN_*): cross-ref filename rewrites; no
RUN-workflow.sbatch references found (already on §29).

Doc enrichment to phylonames/genomesDB/trees_species depth:
- Subproject README + AI_GUIDE: AI-attribution HTML block, §42 Where-this-fits
  with parent/sibling links + reads-from / outputs-to / downstream-consumers,
  removed research_notebook/ from dir trees (replaced with note pointing at
  project-root sandbox), updated all paths to ../../research_notebook/research_user/subproject-trees_gene_families/,
  reconciled scale claim (subproject AI_GUIDE used to say "8 sono families"
  while README says "76"; harmonized to 76 with mechanosensitive subset
  listed separately).
- Subproject AI_GUIDE bug-fix: corrected stale cross-ref to
  ../trees_gene_groups/gene_groups_COPYME/... (underscore — doesn't exist)
  → ../trees_gene_groups/gene_groups-COPYME/... (HYPHEN — correct).
- 3 STEP READMEs + 3 STEP AI_GUIDEs: AI-attribution block + Where-this-fits.
- 3 workflow READMEs + 3 workflow ai/AI_GUIDEs: same.

Cross-check (§44) verified: 15 STEP_1 scripts (gaps at 003, 006, 015 noted),
9 STEP_2 (005 a/b/c/d for FastTree/IQ-TREE/VeryFastTree/PhyloBayes),
2 STEP_3 (render + write_run_log). Per-STEP conda envs match disk:
aiG-trees_gene_families-{rbh_rbf_homologs, phylogenetic_analysis, visualization}.

trees_gene_groups (TWO template variants + 2 frozen instances)
===============================================================

Filesystem changes:
- Deleted per-subproject research_notebook/ (.gitkeep only — no content
  to move).

17 AI_GUIDE-*.md → AI_GUIDE.md renames across BOTH templates (per §3):
- Subproject root: 1 (AI_GUIDE-trees_gene_groups.md)
- gene_groups-COPYME: 6 (STEP_{1,2,3} + 3 workflows)
- gene_groups_hgnc-COPYME: 10 (root + STEP_0 + 2 STEP_0 workflows + STEP_{1,2,3} + 3 STEP_{1,2,3} workflows)

Frozen-artifact exclusions (per §47 + memory
feedback_research_instances_are_frozen_artifacts): all gene_groups-hugo_hgnc/
and gene_groups-snap_family/ docs left untouched.

Bulk sed in template docs only: cross-ref filename rewrites; no
RUN-workflow.sbatch references found.

Doc enrichment:
- Subproject README: full rewrite. Was stale ("gene_groups_COPYME"
  with underscore — wrong, no such dir; missing the second template
  variant gene_groups_hgnc-COPYME; missing snap_family instance;
  research_notebook/ still in dir tree). Now accurately documents both
  templates + both frozen instances; explicit instance naming rules per
  memory feedback_instance_naming_follows_template_prefix.
- Subproject AI_GUIDE: AI-attribution block + Where-this-fits header
  (rest of the doc was already very rich — left intact).
- gene_groups-COPYME README: AI-attribution block + Where-this-fits;
  fixed stale dir-tree (was "gene_groups_COPYME" with underscore),
  fixed "workflow-COPYME-rbh_rbf_homologs" reference (actual dir lacks
  COPYME prefix — pre-§3 naming, flagged for deferred rename).
- gene_groups_hgnc-COPYME README + AI_GUIDE: AI-attribution block + Where-this-fits.
- STEP-level docs in both templates: AI-attribution block + Where-this-fits
  with parent/sibling/dependency links (3 STEPs × {README + AI_GUIDE}
  per template + STEP_0 in hgnc template).
- Workflow-level docs in both templates: AI-attribution block + Where-this-fits
  (3 workflows × {README + ai/AI_GUIDE} per template + 2 hgnc STEP_0 workflows).

Pre-§3 deferrals flagged (NOT fixed in this commit):
- gene_groups-COPYME/STEP_1-homolog_discovery/workflow-rbh_rbf_homologs/ (no COPYME prefix)
- gene_groups_hgnc-COPYME/STEP_1-homolog_discovery/workflow-rbh_rbf_homologs/ (no COPYME prefix)
- gene_groups_hgnc-COPYME/STEP_0-hgnc_based_rgs/workflow-hgnc_database/ (no COPYME prefix)
- gene_groups_hgnc-COPYME/STEP_0-hgnc_based_rgs/workflow-hgnc_user_list/ (no COPYME prefix)

Renaming these is a separate architectural change beyond docs-cleanup
scope. Flagged in the relevant Where-this-fits sections so future readers
know the inconsistency is known.

Drive-by cleanup
================

- trees_species/research_notebook/ai_research/.gitkeep: removed leftover
  zero-byte file from the 6186551 consolidation commit (originally missed).

Stats: 50 files changed, 1037 insertions(+), 259 deletions(-).
17+7 = 24 renames; remaining 26 files are content modifications
(enrichment + sed); 1 deletion (the trees_species .gitkeep).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 000specific

…ene_families/research_notebook/README.md …subproject-trees_gene_families/README.mdgigantic_project-COPYME/subprojects/trees_gene_families/research_notebook/README.md renamed to gigantic_project-COPYME/research_notebook/research_user/subproject-trees_gene_families/README.md gigantic_project-COPYME/subprojects/trees_gene_families/research_notebook/README.md renamed to gigantic_project-COPYME/research_notebook/research_user/subproject-trees_gene_families/README.md

@@ -1,6 +1,30 @@
 # AI Guide: trees_gene_families Subproject
 
-**For AI Assistants**: Read `../../AI_GUIDE-project.md` first for GIGANTIC overview, directory structure, and general patterns. This guide covers trees_gene_families-specific concepts and the three-step architecture.
+<!-- ============================================================================
+AI:      Claude Code | Opus 4.6 | 2026 February (initial)
+AI:      Claude Code | Opus 4.7 (1M context) | 2026 May 26 (detailed eval pass)
+Human:   Eric Edsinger
+============================================================================ -->
+
+## Where this fits
+
+- Parent (project): [`../../AI_GUIDE.md`](../../AI_GUIDE.md) — GIGANTIC overview + general patterns
+- Subproject README: [`README.md`](README.md)
+- Reads FROM:
+  - `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_gigantic_T1_proteomes/` — proteomes
+  - `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_blast_databases/` — pre-built BLAST databases
+  - `../phylonames/` — species naming (RGS headers reference; tree labels resolve via)
+  - `../../research_notebook/research_user/subproject-trees_gene_families/` — curated RGS FASTAs (per §1 consolidation; was per-subproject `research_notebook/` pre-2026-05-26)
+- Outputs TO (`output_to_input/<gene_family>/`):
+  - `STEP_1-homolog_discovery/` — AGS FASTAs
+  - `STEP_2-phylogenetic_analysis/` — newick trees + alignments
+  - `STEP_3-tree_visualization/` — PDFs + SVGs
+- Downstream consumers:
+  - `orthogroups_X_trees/` (when present) — cross-references gene-family trees with orthogroup assignments
+  - `upload_to_server/` — curated subset for the GIGANTIC server
+- Sibling: `../trees_gene_groups/` — gene groups via HGNC + curated lists, same three-STEP architecture
+
+**Read this guide first** for trees_gene_families-specific concepts and the three-step architecture, then drill into the STEP-level guides linked below.
 
 **Location**: `gigantic_project-COPYME/subprojects/trees_gene_families/`
 
@@ -21,36 +45,26 @@
 
 | User needs... | Go to... |
 |---------------|----------|
-| GIGANTIC overview, directory structure | `../../AI_GUIDE-project.md` |
+| GIGANTIC overview, directory structure | `../../AI_GUIDE.md` |
 | trees_gene_families concepts, pipeline architecture | This file |
-| RGS preparation, naming conventions | `research_notebook/README.md` |
-| STEP_1 homolog discovery | `gene_family_COPYME/STEP_1-homolog_discovery/AI_GUIDE-homolog_discovery.md` |
-| STEP_2 phylogenetic analysis | `gene_family_COPYME/STEP_2-phylogenetic_analysis/AI_GUIDE-phylogenetic_analysis.md` |
-| STEP_3 tree visualization | `gene_family_COPYME/STEP_3-tree_visualization/AI_GUIDE-phylogenetic_visualization.md` |
+| RGS preparation, naming conventions | `../../research_notebook/research_user/subproject-trees_gene_families/README.md` |
+| STEP_1 homolog discovery | `gene_family_COPYME/STEP_1-homolog_discovery/AI_GUIDE.md` |
+| STEP_2 phylogenetic analysis | `gene_family_COPYME/STEP_2-phylogenetic_analysis/AI_GUIDE.md` |
+| STEP_3 tree visualization | `gene_family_COPYME/STEP_3-tree_visualization/AI_GUIDE.md` |
 
 ---
 
 ## What This Subproject Does
 
 **Purpose**: Build phylogenetic trees for individual gene families across GIGANTIC species.
 
-**Current scale (sono project)**: 8 mechanosensitive channel gene families for Salk sonogenetics collaboration.
+**Current scale**: 76 gene family instances on disk under `gene_family-<name>/` covering channels (ion / mechanosensitive / chloride / TRP), receptors (GPCR / nuclear hormone / glutamate / glycine / nicotinic), enzymes (kinases, phosphatases, soluble + transmembrane guanylate cyclases, nitric oxide synthases, NDK), ligands (FGF / TGFβ / VEGF / WNT / GH), transporters (solute carriers, ABC, aquaporins), transcription factors (Fox/Forkhead, homeobox), and structural proteins (histones, stomatin, etc.). Includes the 8 Salk sonogenetics mechanosensitive families and the multi-batch HGNC + curated additions (`new_rgs_25mar2026/`, `new_rgs_31mar2026/`).
 
-**The 8 Gene Families**:
-
-| Gene Family | RGS Mode | RGS Seeds | Description |
-|-------------|----------|-----------|-------------|
-| acid_sensing_ion_channel_subunits | full-length | HGNC human | ASIC channels |
-| piezo_type_mechanosensitive_ion_channel_components | full-length | HGNC human | Piezo mechanosensors |
-| potassium_two_pore_domain_channel_subfamily_k | full-length | HGNC human | KCNK channels |
-| solute_carrier_family_26 | full-length | HGNC human | SLC26 / Prestin family |
-| stomatin_family | full-length | HGNC human | Stomatin scaffold proteins |
-| tmem63_osca_flyc1_mechanosensitive | full-length | HGNC human + venus flytrap | TMEM63/OSCA/FLYC1 |
-| transmembrane_channel_like_family | full-length | HGNC human | TMC channels |
-| transient_receptor_potential_cation_channels | **subsequence** | multi-species pore regions | TRP channels (pore-region RGS) |
+**Mechanosensitive (sono project) families** (8 — full-length except TRP which uses subsequence mode):
+acid_sensing_ion_channel_subunits, piezo_type_mechanosensitive_ion_channel_components, potassium_two_pore_domain_channel_subfamily_k, solute_carrier_family_26, stomatin_family, tmem63_osca_flyc1_mechanosensitive, transmembrane_channel_like_family, transient_receptor_potential_cation_channels.
 
 **Four-Phase Workflow**:
-1. **RGS Preparation** - Source, curate, and format reference gene sequences in `research_notebook/`
+1. **RGS Preparation** - Source, curate, and format reference gene sequences in `../../research_notebook/research_user/subproject-trees_gene_families/`
 2. **Homolog Discovery (STEP_1)** - Validate RGS, then find homologs via Reciprocal Best Hit / Reciprocal Best Family (RBH/RBF)
 3. **Phylogenetic Analysis (STEP_2)** - Align sequences, trim, build tree newick files (FastTree, IQ-TREE, VeryFastTree, PhyloBayes)
 4. **Tree Visualization (STEP_3)** - Render newick files as PDF + SVG using toytree (decoupled from STEP_2)
@@ -157,9 +171,9 @@ Full-length:   >rgs_channel-human-TRPV1-uniprot-Q8NER1
 Subsequence:   >rgs_channel-human-TRPV1-uniprot-Q8NER1_subsequence
 ```
 
-### RGS Preparation (research_notebook)
+### RGS Preparation (project-root research sandbox)
 
-RGS files are sourced, curated, and reformatted in `research_notebook/rgs_from_before/`. The flow:
+RGS files are sourced, curated, and reformatted in `../../research_notebook/research_user/subproject-trees_gene_families/rgs_from_before/` (per §1 consolidation; was per-subproject `research_notebook/` pre-2026-05-26). The flow:
 
 1. **Raw sources** in `rgs_sources/` - varied legacy formats from HGNC, UniProt, kinase/phosphatome databases
 2. **Conversion scripts** in `rgs_for_trees/new_rgs_*/` - reformat to GIGANTIC standard, produce mapping TSVs
@@ -168,7 +182,7 @@ RGS files are sourced, curated, and reformatted in `research_notebook/rgs_from_b
 
 Each conversion batch includes `mapping-*.tsv` files mapping original headers to new GIGANTIC headers for traceability.
 
-See `research_notebook/README.md` for full specification.
+See `../../research_notebook/research_user/subproject-trees_gene_families/README.md` for full specification.
 
 ---
 
@@ -226,21 +240,23 @@ See `research_notebook/README.md` for full specification.
 
 ```
 trees_gene_families/
-├── AI_GUIDE-trees_gene_families.md    # THIS FILE
+├── AI_GUIDE.md    # THIS FILE
 ├── README.md                          # Human documentation
 ├── RUN-setup_and_submit_step1_burst.sh                # Burst: STEP_1 for original RGS set
 ├── RUN-setup_and_submit_step2_burst.sh                # Burst: STEP_2 with size filter
 ├── RUN-setup_and_submit_new_rgs_31mar2026_burst.sh    # Burst: STEP_1 for new RGS set
 ├── RUN-setup_and_submit_sono_mechanosensitive_burst.sh # Burst: STEP_1 for 8 sono gene families
 ├── RUN-update_upload_to_server.sh                     # Update server symlinks
 │
-├── research_notebook/                 # RGS preparation + personal workspace
-│   └── rgs_from_before/              # RGS sources and formatted files
-│       ├── rgs_sources/              # Raw/legacy RGS files
-│       └── rgs_for_trees/            # GIGANTIC-formatted RGS files
-│           ├── new_rgs_25mar2026/    # Batch: channel subfamilies
-│           └── new_rgs_31mar2026/    # Batch: TRP, kinome, phosphatome, etc.
 ├── upload_to_server/                  # Server sharing
+# Note: no per-subproject research_notebook/ — per §1 consolidation,
+# RGS preparation sandbox lives at ../../research_notebook/research_user/subproject-trees_gene_families/
+#   ├── rgs_from_before/
+#   │   ├── rgs_sources/                  (raw/legacy RGS files)
+#   │   └── rgs_for_trees/                (GIGANTIC-formatted)
+#   │       ├── new_rgs_25mar2026/        (batch: channel subfamilies)
+#   │       └── new_rgs_31mar2026/        (batch: TRP, kinome, phosphatome, etc.)
+#   └── species_keeper_list-species70.tsv
 │
 ├── output_to_input/                   # FINAL OUTPUTS for downstream (gene family first)
 │   └── <gene_family>/                # One directory per gene family
@@ -270,10 +286,11 @@ trees_gene_families/
 ## Data Flow: Full Pipeline
 
 ```
-research_notebook/rgs_sources/         Raw/legacy RGS files from databases
+../../research_notebook/research_user/subproject-trees_gene_families/
+    rgs_from_before/rgs_sources/       Raw/legacy RGS files from databases
        │
        ▼
-research_notebook/rgs_for_trees/       Format to GIGANTIC standard (conversion scripts + mapping TSVs)
+    rgs_from_before/rgs_for_trees/     Format to GIGANTIC standard (conversion scripts + mapping TSVs)
        │
        ▼
 RUN-setup_and_submit_*_burst.sh        Automate: create gene_family dirs, populate inputs, submit SLURM
@@ -311,15 +328,17 @@ output_to_input/<gene_family>/STEP_3-tree_visualization/
 
 | Subproject | What | Path |
 |------------|------|------|
-| genomesDB | BLAST databases (per-species .aa files) | `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_gigantic_T1_blastp/` |
+| genomesDB | BLAST databases + proteomes | `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_gigantic_T1_{proteomes,blast_databases}/` |
 | phylonames | Species name mappings | `../phylonames/output_to_input/maps/` |
+| (project-root) | Curated RGS FASTAs + species keeper list | `../../research_notebook/research_user/subproject-trees_gene_families/` |
 
 ### Outputs TO
 
 | Location | What | Consumers |
 |----------|------|-----------|
-| `output_to_input/<gene_family>/STEP_1-homolog_discovery/` | AGS homolog sets | Internal (STEP_2) |
-| `output_to_input/<gene_family>/STEP_2-phylogenetic_analysis/` | Phylogenetic trees | Publication, downstream |
+| `output_to_input/<gene_family>/STEP_1-homolog_discovery/` | AGS homolog sets | Internal (STEP_2); downstream cross-ref subprojects |
+| `output_to_input/<gene_family>/STEP_2-phylogenetic_analysis/` | Newick trees + alignments | Publication, downstream; `orthogroups_X_trees/` when present |
+| `output_to_input/<gene_family>/STEP_3-tree_visualization/` | PDFs + SVGs + visualization summaries | `upload_to_server/`; publication figures |
 
 ---
 
@@ -347,15 +366,15 @@ Each workflow has its own conda env, defined in `workflow-COPYME-*/ai/conda_envi
 | STEP_2 | phylogenetic_analysis | `aiG-trees_gene_families-phylogenetic_analysis` | python, pyyaml, nextflow, mafft, clipkit, fasttree, iqtree, veryfasttree |
 | STEP_3 | tree_visualization | `aiG-trees_gene_families-visualization` | python, pyyaml, pip → toytree, toyplot, reportlab (no Qt) |
 
-**Migration note (2026-05-24)**: The old shared `ai_gigantic_trees_gene_families` env is deprecated. The per-workflow envs above replace it. numpy + scipy in STEP_1 are required by the rewritten script 008 (Hungarian optimal RGS-assignment); without them the script falls back to greedy assignment that fails-fast on residual ambiguity per the [PLAN](../trees_gene_groups/gene_groups_COPYME/STEP_1-homolog_discovery/PLAN-rgs_identification_improvements.md). STEP_3's env-creation includes broken-env self-heal (rebuilds if `bin/python` is missing).
+**Migration note (2026-05-24)**: The old shared `ai_gigantic_trees_gene_families` env is deprecated. The per-workflow envs above replace it. numpy + scipy in STEP_1 are required by the rewritten script 008 (Hungarian optimal RGS-assignment); without them the script falls back to greedy assignment that fails-fast on residual ambiguity per the [PLAN](../trees_gene_groups/gene_groups-COPYME/STEP_1-homolog_discovery/PLAN-rgs_identification_improvements.md). STEP_3's env-creation includes broken-env self-heal (rebuilds if `bin/python` is missing).
 
 ---
 
 ## Research Notebook Location
 
-AI sessions save to the project-wide sessions directory:
+AI sessions save to the project-root sessions directory (per §1 + §9):
 ```
-research_notebook/research_ai/sessions/
+../../research_notebook/research_ai/sessions/
 ```
 
 Workflow run logs save to each workflow's own `ai/logs/` directory:
@@ -399,7 +418,7 @@ ls output_to_input/*/STEP_3-tree_visualization/
 
 | File | Purpose | User Edits? |
 |------|---------|-------------|
-| `research_notebook/rgs_from_before/rgs_for_trees/` | Formatted RGS FASTA files | **YES** (source data) |
+| `../../research_notebook/research_user/subproject-trees_gene_families/rgs_from_before/rgs_for_trees/` | Formatted RGS FASTA files | **YES** (source data) |
 | `RUN-setup_and_submit_step1_burst.sh` | Burst setup + submit STEP_1 (original RGS) | **YES** (SLURM settings) |
 | `RUN-setup_and_submit_new_rgs_31mar2026_burst.sh` | Burst setup + submit STEP_1 (new RGS) | **YES** (SLURM settings, RGS path) |
 | `RUN-setup_and_submit_sono_mechanosensitive_burst.sh` | Burst setup + submit STEP_1 (8 sono families) | **YES** (SLURM settings) |

…families/AI_GUIDE-trees_gene_families.md …projects/trees_gene_families/AI_GUIDE.mdgigantic_project-COPYME/subprojects/trees_gene_families/AI_GUIDE-trees_gene_families.md renamed to gigantic_project-COPYME/subprojects/trees_gene_families/AI_GUIDE.md gigantic_project-COPYME/subprojects/trees_gene_families/AI_GUIDE-trees_gene_families.md renamed to gigantic_project-COPYME/subprojects/trees_gene_families/AI_GUIDE.md

@@ -1,5 +1,31 @@
 # trees_gene_families - Gene Family Phylogenetic Analysis
 
+<!-- ============================================================================
+AI:      Claude Code | Opus 4.6 | 2026 February (initial)
+AI:      Claude Code | Opus 4.7 (1M context) | 2026 May 26 (detailed eval pass)
+Human:   Eric Edsinger
+============================================================================ -->
+
+## Where this fits
+
+- Parent: [`../../README.md`](../../README.md) — gigantic_project-COPYME overview
+- Subproject AI guide: [`AI_GUIDE.md`](AI_GUIDE.md)
+- **Reads from**:
+  - `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_gigantic_T1_proteomes/` — proteomes for BLAST
+  - `../genomesDB/output_to_input/STEP_4-create_final_species_set/speciesN_blast_databases/` — pre-built BLAST databases (RGS as query)
+  - `../phylonames/` — species naming conventions (referenced by RGS headers + downstream tree labels)
+  - `../../research_notebook/research_user/subproject-trees_gene_families/` — curated RGS FASTAs (per §1 consolidation; was per-subproject `research_notebook/` pre-2026-05-26)
+- **Outputs to** (`output_to_input/<gene_family>/`):
+  - `STEP_1-homolog_discovery/` — AGS FASTAs (homolog sequences)
+  - `STEP_2-phylogenetic_analysis/` — newick trees + alignments
+  - `STEP_3-tree_visualization/` — PDFs + SVGs + visualization summaries
+- **Downstream consumers**:
+  - `orthogroups_X_trees/` (when present) — cross-references gene-family trees with orthogroup assignments
+  - `upload_to_server/` (subproject root) — curated subset of trees/alignments for the GIGANTIC server
+- Sibling subproject (similar pattern, different scope): `../trees_gene_groups/` (gene groups via HGNC + curated lists; same three-STEP architecture)
+
+---
+
 Build phylogenetic trees for individual gene families across GIGANTIC project species.
 
 **Current scale**: 76 gene family analyses covering channels, receptors, enzymes (kinases, phosphatases), ligands, transporters, transcription factors, and structural proteins.
@@ -14,22 +40,22 @@ The full workflow has four phases:
 
 | Phase | Where | Purpose |
 |-------|-------|---------|
-| RGS Preparation | `research_notebook/` | Source, curate, and format reference gene sequences |
+| RGS Preparation | `../../research_notebook/research_user/subproject-trees_gene_families/` | Source, curate, and format reference gene sequences |
 | STEP_1 | `gene_family-*/STEP_1-homolog_discovery/` | Validate RGS, find homologs via RBH/RBF BLAST |
 | STEP_2 | `gene_family-*/STEP_2-phylogenetic_analysis/` | Align, trim, build trees (produces newick files) |
 | STEP_3 | `gene_family-*/STEP_3-tree_visualization/` | Render trees as PDF + SVG using toytree |
 
 ## RGS Preparation (Before the Pipeline)
 
-Before running the three-step pipeline, RGS FASTA files must be prepared in GIGANTIC standard format. This happens in `research_notebook/`.
+Before running the three-step pipeline, RGS FASTA files must be prepared in GIGANTIC standard format. This happens in the project-root research sandbox at `../../research_notebook/research_user/subproject-trees_gene_families/` (per §1 consolidation; was per-subproject `research_notebook/` pre-2026-05-26).
 
 **RGS filename format**: `rgs_<category>-<source_species>-<description>.aa`
 
 **RGS header format**: `>rgs_<family_subfamily>-<species>-<gene>-<source>-<accession>`
 
-Within each dash-separated field, only letters, numbers, and underscores are allowed. See `research_notebook/README.md` for full specification and examples.
+Within each dash-separated field, only letters, numbers, and underscores are allowed. See `../../research_notebook/research_user/subproject-trees_gene_families/README.md` for full specification and examples.
 
-**RGS sources include**: HGNC gene groups, UniProt, kinase/phosphatome databases, and curated sets from prior GIGANTIC work. Conversion scripts in `research_notebook/rgs_from_before/rgs_for_trees/` reformat legacy headers to GIGANTIC standard and produce mapping TSVs for traceability.
+**RGS sources include**: HGNC gene groups, UniProt, kinase/phosphatome databases, and curated sets from prior GIGANTIC work. Conversion scripts in `../../research_notebook/research_user/subproject-trees_gene_families/rgs_from_before/rgs_for_trees/` reformat legacy headers to GIGANTIC standard and produce mapping TSVs for traceability.
 
 ## Three-Step Pipeline
 
@@ -65,13 +91,15 @@ trees_gene_families/
 │
 ├── output_to_input/                       # Shared outputs for downstream subprojects
 ├── upload_to_server/                      # Curated data for GIGANTIC server
-├── research_notebook/                     # Personal notes and exploratory work
 ├── slurm_logs/                            # SLURM job logs from burst submissions
+# Note: no per-subproject research_notebook/ — per §1, the project-root
+# research_notebook/research_user/subproject-trees_gene_families/ holds
+# the RGS preparation sandbox (rgs_from_before/, species_keeper_list, etc.)
 ├── RUN-setup_and_submit_step1_burst.sh             # Burst: set up + submit STEP_1 (original RGS set)
 ├── RUN-setup_and_submit_step2_burst.sh             # Burst: set up + submit STEP_2 (with size filter)
 ├── RUN-setup_and_submit_new_rgs_31mar2026_burst.sh # Burst: STEP_1 for new RGS set (TRP, kinome, phosphatome, etc.)
 ├── RUN-update_upload_to_server.sh                  # Update upload_to_server/ symlinks
-├── AI_GUIDE-trees_gene_families.md
+├── AI_GUIDE.md
 └── README.md
 ```
 
@@ -232,7 +260,7 @@ bash RUN-setup_and_submit_step2_burst.sh
 
 ### RUN-setup_and_submit_new_rgs_31mar2026_burst.sh
 
-Same pattern as the STEP_1 burst script, but for **new RGS files** prepared in `research_notebook/rgs_from_before/rgs_for_trees/new_rgs_31mar2026/`. This script:
+Same pattern as the STEP_1 burst script, but for **new RGS files** prepared in `../../research_notebook/research_user/subproject-trees_gene_families/rgs_from_before/rgs_for_trees/new_rgs_31mar2026/`. This script:
 
 1. Automatically derives gene family names from RGS filenames
 2. Creates gene_family directories from the COPYME template
@@ -282,4 +310,4 @@ STEP_3 runs locally and writes its own logs into `gene_family-*/STEP_3-tree_visu
 
 ## For AI Assistants
 
-See `AI_GUIDE-trees_gene_families.md` for detailed AI guidance.
+See `AI_GUIDE.md` for detailed AI guidance.