Skip to content

Commit 618fd96

Browse files
committed
docs: clarify docxology/template role in projects README
1 parent 5eaf145 commit 618fd96

23 files changed

+74
-131
lines changed

projects/README.md

Lines changed: 74 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,14 @@
11
# Projects Directory
22

3-
This directory contains multiple **standalone research projects**, each with independent source code, tests, analysis scripts, and manuscripts. Each project operates completely independently while leveraging shared infrastructure for common operations.
3+
This directory contains multiple **standalone research projects**, each with independent source code, tests, analysis scripts, and manuscripts. Each project operates completely independently while being executed, tested, and rendered by the overarching **[docxology/template](https://github.com/docxology/template/)** infrastructure.
44

5-
## Exemplar Projects Showcase
5+
## Active Projects
66

7-
This directory contains **two active projects** demonstrating the template's full capabilities:
7+
This directory contains **one active project**:
88

9-
### 🚀 **code_project**: Computational Research Exemplar
9+
### **act_inf_metaanalysis**: Active Inference Meta-Analysis
1010

11-
An optimization research project featuring:
12-
13-
- **Advanced Algorithms**: Full gradient descent implementation with convergence analysis
14-
- **Publication-Quality Output**: Professional LaTeX manuscript with cross-references
15-
- **Rigorous Testing**: 100% test coverage with performance benchmarks
16-
- **Automated Analysis**: Script-driven figure generation and data visualization
17-
18-
### 🎨 **blake_active_inference**: Interdisciplinary Manuscript Exemplar
19-
20-
A manuscript-focused research project exploring Active Inference through William Blake's epistemology:
21-
22-
- **29-Section Manuscript**: Comprehensive academic paper with synthesis mappings
23-
- **Publication Pipeline**: Full rendering with figures and bibliography
24-
- **Show-Not-Tell Methodology**: Demonstrates research template for theory-heavy projects
11+
An Active Inference meta-analysis research project.
2512

2613
**Note:** Archived projects are preserved in `projects_archive/` for reference but are not actively executed.
2714

@@ -85,24 +72,22 @@ mv projects_archive/myproject projects/myproject
8572

8673
# Project will be automatically discovered on next run.sh execution
8774

88-
| `code_project/` | Optimization algorithms research | ✅ Active |
89-
| `blake_active_inference/` | Blake × Active Inference manuscript | ✅ Active |
75+
| `act_inf_metaanalysis/` | Active Inference meta-analysis research | ✅ Active |
9076

91-
**Archived projects** are available in `projects_archive/` for historical reference (e.g., `cognitive_integrity`, `active_inference_meta_pragmatic`, `medical_ai`).
77+
**Archived projects** are available in `projects_archive/` for historical reference (e.g., `code_project`, `blake_active_inference`, `cognitive_integrity`, `active_inference_meta_pragmatic`).
9278

9379
```mermaid
9480
graph TD
9581
subgraph projects["projects/ - Multi-Project Container"]
96-
CODE[code_project/<br/>Optimization Research<br/>Gradient descent algorithms]
97-
BLAKE[blake_active_inference/<br/>Interdisciplinary Manuscript<br/>Blake × Active Inference]
82+
PROJ[act_inf_metaanalysis/<br/>Active Inference Meta-Analysis]
9883
CUSTOM[your_project/<br/>Custom research<br/>Your algorithms here]
9984
100-
CODE --> CODE_SRC[src/<br/>optimizer.py<br/>gradient_descent]
101-
CODE -->CODE_TESTS[tests/<br/>34 tests<br/>100% coverage]
102-
CODE --> CODE_SCRIPTS[scripts/<br/>Analysis pipeline<br/>API documentation]
103-
CODE --> CODE_MANUSCRIPT[manuscript/<br/>Research paper<br/>Equations & figures]
104-
CODE --> CODE_OUTPUT[output/<br/>Generated figures<br/>Disposable]
105-
CODE --> CODE_CONFIG[pyproject.toml<br/>Project metadata]
85+
PROJ --> PROJ_SRC[src/<br/>Research algorithms]
86+
PROJ --> PROJ_TESTS[tests/<br/>Test suite]
87+
PROJ --> PROJ_SCRIPTS[scripts/<br/>Analysis pipeline]
88+
PROJ --> PROJ_MANUSCRIPT[manuscript/<br/>Research paper]
89+
PROJ --> PROJ_OUTPUT[output/<br/>Generated outputs<br/>Disposable]
90+
PROJ --> PROJ_CONFIG[pyproject.toml<br/>Project metadata]
10691
end
10792
10893
subgraph Infrastructure["🔧 Shared Infrastructure"]
@@ -118,25 +103,25 @@ graph TD
118103
CURSORRULES[infrastructure_modules.md<br/>testing_standards.md<br/>documentation_standards.md]
119104
end
120105
121-
CODE -->|Validated by| VALIDATION
122-
CODE -->|Rendered by| RENDERING
123-
CODE -->|Reported by| REPORTING
124-
CODE -->|Discovered by| SCRIPTS_ROOT
106+
PROJ -->|Validated by| VALIDATION
107+
PROJ -->|Rendered by| RENDERING
108+
PROJ -->|Reported by| REPORTING
109+
PROJ -->|Discovered by| SCRIPTS_ROOT
125110
126-
CODE_SRC -->|Imports from| INFRA
127-
CODE_SCRIPTS -->|Imports from| INFRA
128-
CODE_SCRIPTS -->|Orchestrated by| SCRIPTS_ROOT
111+
PROJ_SRC -->|Imports from| INFRA
112+
PROJ_SCRIPTS -->|Imports from| INFRA
113+
PROJ_SCRIPTS -->|Orchestrated by| SCRIPTS_ROOT
129114
130-
CODE -->|Complies with| STANDARDS
115+
PROJ -->|Complies with| STANDARDS
131116
STANDARDS --> CURSORRULES
132117
133-
CODE_MANUSCRIPT -->|Rendered to| CODE_OUTPUT
118+
PROJ_MANUSCRIPT -->|Rendered to| PROJ_OUTPUT
134119
135120
classDef project fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
136121
classDef infra fill:#fff3e0,stroke:#e65100,stroke-width:2px
137122
classDef compliance fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
138123
139-
class CODE,CODE_SRC,CODE_TESTS,CODE_SCRIPTS,CODE_MANUSCRIPT,CODE_OUTPUT,CODE_CONFIG,BLAKE project
124+
class PROJ,PROJ_SRC,PROJ_TESTS,PROJ_SCRIPTS,PROJ_MANUSCRIPT,PROJ_OUTPUT,PROJ_CONFIG project
140125
class INFRA,SCRIPTS_ROOT,VALIDATION,RENDERING,REPORTING infra
141126
class STANDARDS,CURSORRULES compliance
142127
```
@@ -151,42 +136,42 @@ Each project is **operated upon** by infrastructure modules while maintaining in
151136
from infrastructure.project import discover_projects, validate_project_structure
152137

153138
# Automatically discovers all valid projects
154-
projects = discover_projects(Path(".")) # Finds code_project, blake_active_inference, etc.
139+
projects = discover_projects(Path(".")) # Finds act_inf_metaanalysis, etc.
155140

156141
# Validates project structure
157-
is_valid, message = validate_project_structure(Path("projects/code_project"))
142+
is_valid, message = validate_project_structure(Path("projects/act_inf_metaanalysis"))
158143
# Returns: (True, "Valid project structure")
159144
```
160145

161146
### 🧪 **Test Execution** (`scripts/01_run_tests.py`)
162147

163148
```bash
164149
# Runs project-specific tests with infrastructure orchestration
165-
python3 scripts/01_run_tests.py --project code_project
150+
python3 scripts/01_run_tests.py --project {name}
166151

167152
# Infrastructure validates structure, then runs:
168-
# pytest projects/code_project/tests/ --cov=projects/code_project/src --cov-fail-under=90
153+
# pytest projects/{name}/tests/ --cov=projects/{name}/src --cov-fail-under=90
169154
```
170155

171156
### ⚙️ **Analysis Scripts** (`scripts/02_run_analysis.py`)
172157

173158
```python
174159
# Discovers and executes project scripts
175-
python3 scripts/02_run_analysis.py --project code_project
160+
python3 scripts/02_run_analysis.py --project {name}
176161

177162
# Infrastructure finds and runs:
178-
# projects/code_project/scripts/optimization_analysis.py
179-
# projects/code_project/scripts/generate_api_docs.py
163+
# projects/{name}/scripts/analysis_pipeline.py
164+
# projects/{name}/scripts/generate_figures.py
180165
```
181166

182167
### 📄 **PDF Rendering** (`scripts/03_render_pdf.py`)
183168

184169
```python
185170
# Renders project manuscript using infrastructure.rendering
186-
python3 scripts/03_render_pdf.py --project code_project
171+
python3 scripts/03_render_pdf.py --project {name}
187172

188173
# Infrastructure processes:
189-
# projects/code_project/manuscript/*.md -> PDF with figures
174+
# projects/{name}/manuscript/*.md -> PDF with figures
190175
```
191176

192177
### **Quality Validation** (`scripts/04_validate_output.py`)
@@ -202,9 +187,9 @@ python3 scripts/04_validate_output.py --project project
202187

203188
```python
204189
# Organizes final deliverables
205-
python3 scripts/05_copy_outputs.py --project blake_active_inference
190+
python3 scripts/05_copy_outputs.py --project {name}
206191

207-
# Copies from projects/blake_active_inference/output/ to output/blake_active_inference/
192+
# Copies from projects/{name}/output/ to output/{name}/
208193
```
209194

210195
## Project Isolation Principles
@@ -283,33 +268,27 @@ Every project must comply with development standards defined in `.cursorrules/`:
283268
Each project follows this structure:
284269

285270
```
286-
307: projects/
287-
308: ├── code_project/ # Optimization research project
288-
309: │ ├── src/ # Source code
289-
310: │ ├── tests/ # Test suite
290-
311: │ ├── scripts/ # Analysis scripts
291-
312: │ ├── manuscript/ # Research manuscript
292-
313: │ ├── output/ # Generated outputs (not in git)
293-
314: │ └── pyproject.toml # Project configuration
294-
315: ├── blake_active_inference/ # Blake × Active Inference manuscript
295-
316: │ ├── src/
296-
317: │ ├── tests/
297-
318: │ ├── scripts/
298-
319: │ ├── manuscript/
299-
320: │ └── pyproject.toml
300-
321: ├── myresearch/ # Custom project 1
301-
322: │ └── ...
302-
323: └── experiment2/ # Custom project 2
303-
324: └── ...
271+
projects/
272+
├── act_inf_metaanalysis/ # Active Inference meta-analysis
273+
│ ├── src/ # Source code
274+
│ ├── tests/ # Test suite
275+
│ ├── scripts/ # Analysis scripts
276+
│ ├── manuscript/ # Research manuscript
277+
│ ├── output/ # Generated outputs (not in git)
278+
│ └── pyproject.toml # Project configuration
279+
├── myresearch/ # Custom project 1
280+
│ └── ...
281+
└── experiment2/ # Custom project 2
282+
└── ...
304283
```
305284

306285
## Creating a New Project
307286

308287
### Option 1: Copy the Template
309288

310289
```bash
311-
# Copy an existing project as a starting point (choose code_project or cogsec templates)
312-
cp -r projects/code_project projects/myresearch
290+
# Copy an existing project as a starting point
291+
cp -r projects/act_inf_metaanalysis projects/myresearch
313292

314293
# Customize pyproject.toml
315294
vim projects/myresearch/pyproject.toml
@@ -474,14 +453,11 @@ Example:
474453

475454
```
476455
output/
477-
├── code_project/ # Optimization research project
456+
├── act_inf_metaanalysis/ # Active Inference meta-analysis
478457
│ ├── pdf/
479458
│ ├── figures/
480459
│ └── ...
481-
├── blake_active_inference/ # Blake × Active Inference
482-
│ ├── pdf/
483-
│ └── ...
484-
└── your_project/ # Your custom research project
460+
└── your_project/ # Your custom research project
485461
└── ...
486462
```
487463

@@ -578,47 +554,30 @@ Available projects are automatically discovered - use `--project {name}` to spec
578554

579555
## Real Project Examples
580556

581-
### ⚙️ **Optimization Research** (`projects/code_project/`)
582-
583-
Project demonstrating gradient descent algorithms:
584-
585-
**Standalone Guarantees:**
586-
587-
- **Tests**: 34 tests for optimization algorithms with convergence and stability validation
588-
- **Methods**: Gradient descent implementation in `src/optimizer.py`
589-
- **Manuscript**: Research manuscript with algorithm description and analysis
590-
591-
**Infrastructure Operations:**
592-
593-
```bash
594-
# pipeline execution
595-
python3 scripts/execute_pipeline.py --project code_project --core-only
596-
```
597-
598-
### 🎨 **Blake Active Inference** (`projects/blake_active_inference/`)
557+
### **Active Inference Meta-Analysis** (`projects/act_inf_metaanalysis/`)
599558

600-
Interdisciplinary manuscript mapping William Blake's epistemology to Active Inference:
559+
Active Inference meta-analysis research project:
601560

602561
**Standalone Guarantees:**
603562

604-
- **Tests**: Validation of manuscript content and rendering pipeline
605-
- **Methods**: Synthesis mapping and correspondence analysis in `src/`
606-
- **Manuscript**: 29-section academic paper with extended analysis
563+
- **Tests**: Test suite validating analysis algorithms
564+
- **Methods**: Meta-analysis implementation in `src/`
565+
- **Manuscript**: Research manuscript with analysis and figures
607566

608567
**Infrastructure Operations:**
609568

610569
```bash
611-
# Render manuscript via infrastructure
612-
python3 scripts/03_render_pdf.py --project blake_active_inference
570+
# Pipeline execution
571+
python3 scripts/execute_pipeline.py --project act_inf_metaanalysis --core-only
613572
```
614573

615574
## Creating New Projects
616575

617576
### Method 1: Copy Existing Project (Recommended)
618577

619578
```bash
620-
# Copy a, working project as template
621-
cp -r projects/code_project projects/my_research
579+
# Copy an existing project as template
580+
cp -r projects/act_inf_metaanalysis projects/my_research
622581
cd projects/my_research
623582

624583
# Update project metadata
@@ -639,38 +598,23 @@ cd ../..
639598
python3 -c "from infrastructure.project import validate_project_structure; print(validate_project_structure(Path('projects/my_research')))"
640599
```
641600

642-
### Method 2: Start from Small Project
601+
### Method 2: Start from Scratch
643602

644603
```bash
645-
# Use minimal template for code-focused research
646-
cp -r projects/code_project projects/optimization_research
647-
cd projects/optimization_research
648-
649-
# Replace optimization algorithms with your research
650-
vim src/optimizer.py # Your algorithm here
651-
vim tests/test_optimizer.py # Your tests here
652-
653-
# Update manuscript content
654-
vim manuscript/01_introduction.md
655-
vim manuscript/02_methodology.md
656-
```
657-
658-
### Method 3: Manuscript-Focused Research
604+
# Create minimal project structure
605+
mkdir -p projects/my_new_project/{src,tests,scripts,manuscript}
606+
touch projects/my_new_project/src/__init__.py
607+
touch projects/my_new_project/tests/__init__.py
659608

660-
```bash
661-
# Use blake_active_inference as template for manuscript-heavy research
662-
cp -r projects/blake_active_inference projects/literature_review
663-
cd projects/literature_review
609+
# Add your research algorithms
610+
vim projects/my_new_project/src/my_algorithm.py
664611

665-
# Focus on manuscript content with equations
666-
vim manuscript/01_abstract.md
667-
vim manuscript/02_introduction.md
668-
vim manuscript/03_methodology.md
669-
vim manuscript/04_analysis.md
612+
# Add corresponding tests
613+
vim projects/my_new_project/tests/test_my_algorithm.py
670614

671-
# Add minimal supporting code
672-
vim src/theoretical_model.py
673-
vim tests/test_theoretical_model.py
615+
# Update manuscript content
616+
vim projects/my_new_project/manuscript/01_introduction.md
617+
vim projects/my_new_project/manuscript/02_methodology.md
674618
```
675619

676620
## Troubleshooting
@@ -869,10 +813,9 @@ The `projects/` directory implements a **standalone project paradigm** with infr
869813
- **Quality Gates**: 90% coverage, documentation, type safety
870814
- **Infrastructure Access**: Import from `infrastructure/` modules for shared utilities
871815

872-
### 🎯 **Real Examples**
816+
### 🎯 **Active Project**
873817

874-
- **blake_active_inference**: Blake × Active Inference (interdisciplinary manuscript)
875-
- **code_project**: Optimization algorithms (computational research template)
818+
- **act_inf_metaanalysis**: Active Inference meta-analysis research
876819

877820
**Note:** Archived projects are preserved in `projects_archive/` for reference.
878821

projects_archive/active_inference_meta_pragmatic/manuscript/02_background.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/04_background.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/manuscript/03_quadrant_model.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/06_quadrant_model.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/manuscript/04_security_implications.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/07_security_implications.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/manuscript/05_discussion.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/08_discussion.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/manuscript/06_acknowledgments.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/10_acknowledgments.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/manuscript/07_appendix.md renamed to projects_archive/active_inference_meta_pragmatic/manuscript/11_appendix.md

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/scripts/generate_quadrant_matrix.py renamed to projects_archive/active_inference_meta_pragmatic/scripts/01_generate_quadrant_matrix.py

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/scripts/generate_active_inference_concepts.py renamed to projects_archive/active_inference_meta_pragmatic/scripts/02_generate_active_inference_concepts.py

File renamed without changes.

projects_archive/active_inference_meta_pragmatic/scripts/generate_fep_visualizations.py renamed to projects_archive/active_inference_meta_pragmatic/scripts/03_generate_fep_visualizations.py

File renamed without changes.

0 commit comments

Comments
 (0)