diff --git a/.gitignore b/.gitignore
index ddbe44f35..3031ae953 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,6 @@ docs/schema/erdiagram-autogen.md
 node_modules
 package-lock.json
 package.json
+
+# Internal documentation
+/internal/
diff --git a/docs/explanation/core-concepts.md b/docs/explanation/core-concepts.md
new file mode 100644
index 000000000..c198f8e02
--- /dev/null
+++ b/docs/explanation/core-concepts.md
@@ -0,0 +1,103 @@
+# Core Concepts
+
+Understanding the fundamental building blocks of ReproSchema.
+
+## The ReproSchema Hierarchy
+
+ReproSchema follows a three-level hierarchy that mirrors how research studies are organized:
+
+```
+Protocol
+└── Activity
+    └── Item
+```
+
+### Protocol
+
+A **Protocol** represents your entire research study or assessment battery. It's the top-level container that:
+- Defines the study's metadata (title, description, version)
+- Lists all activities (questionnaires, tasks) in the study
+- Controls the order and flow of activities
+- Manages study-wide settings and permissions
+
+Think of it as your study's blueprint.
+
+### Activity
+
+An **Activity** is a logical grouping of related questions or tasks. Common examples:
+- A standardized questionnaire (PHQ-9, GAD-7)
+- A demographic information form
+- A cognitive task
+- A custom assessment
+
+Activities:
+- Contain multiple items (questions)
+- Can be reused across different protocols
+- Have their own display logic and branching
+- Can be imported from the reproschema-library
+
+### Item
+
+An **Item** is an individual question or data collection point. It defines:
+- The question text and help text
+- The response type (text, multiple choice, slider, etc.)
+- Validation rules
+- Scoring information
+
+Items are the atomic units where actual data is collected.
+
+## How They Work Together
+
+1. **Composition**: A Protocol contains Activities, which contain Items
+2. **Reusability**: Activities and Items can be shared across protocols
+3. **Modularity**: Each level can be modified independently
+4. **Flexibility**: Mix custom and library components at any level
+
+## Schema Structure
+
+Each level is defined by a JSON-LD schema file that specifies:
+
+### Common Properties
+- `@context`: Links to vocabulary definitions
+- `@type`: The schema type (Protocol, Activity, or Item)
+- `@id`: Unique identifier
+- `prefLabel`: Display name
+- `description`: Detailed description
+
+### Level-Specific Properties
+
+**Protocol**:
+- `landingPage`: Welcome content
+- `ui.order`: Activity sequence
+- `ui.addProperties`: Activity configurations
+
+**Activity**:
+- `preamble`: Instructions
+- `ui.order`: Item sequence
+- `ui.addProperties`: Item configurations
+
+**Item**:
+- `question`: Question text
+- `ui.inputType`: Response widget type
+- `responseOptions`: Valid responses
+
+## Design Philosophy
+
+ReproSchema embraces several key principles:
+
+1. **Semantic Clarity**: Every element has explicit meaning
+2. **Reusability**: Build once, use many times
+3. **Interoperability**: Works with other standards
+4. **Version Control**: Track changes over time
+5. **Validation**: Ensure data quality from the start
+
+## Why This Structure?
+
+This hierarchical approach provides:
+- **Organization**: Natural grouping of related content
+- **Flexibility**: Mix and match components
+- **Standardization**: Consistent structure across studies
+- **Efficiency**: Reuse existing validated instruments
+- **Clarity**: Clear relationships between elements
+
+Understanding these concepts is essential for effectively using ReproSchema to create robust, reusable research instruments.
\ No newline at end of file
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
new file mode 100644
index 000000000..a3ecf4e14
--- /dev/null
+++ b/docs/explanation/index.md
@@ -0,0 +1,39 @@
+# Understanding ReproSchema
+
+Conceptual guides that explain how ReproSchema works and why it's designed the way it is.
+
+## 🧠 Core Concepts
+
+### Coming Soon
+- **Core Concepts** - Protocols, Activities, Items, and how they relate
+- **JSON-LD Fundamentals** - Why we use JSON-LD and how it enables interoperability
+- **Schema Architecture** - How ReproSchema is structured under the hood
+- **UI Rendering Process** - How schemas become interactive forms
+- **Design Patterns** - Best practices and common patterns
+
+## 🤔 Why Read These?
+
+Understanding the concepts behind ReproSchema helps you:
+
+- Make better design decisions
+- Debug issues more effectively
+- Extend ReproSchema for your needs
+- Contribute to the project
+
+## 📚 Related Resources
+
+- **[Tutorials](../tutorials/index.md)** - Learn by building
+- **[How-To Guides](../how-to/index.md)** - Accomplish specific tasks
+- **[Reference](../reference/index.md)** - Technical specifications
+- **[FAQ](../FAQ.md)** - Quick answers to common questions
+
+## 🔍 Current Documentation
+
+While we build out this section, you can find conceptual information in:
+- [Introduction](../introduction.md) - Project overview and motivation
+- [Project Structure](../project-structure.md) - Repository organization
+- [Schema Documentation](../schema/schema.md) - Technical details
+
+## 🚧 Under Development
+
+This section is being expanded to provide deeper insights into ReproSchema's design and architecture. Stay tuned!
\ No newline at end of file
diff --git a/docs/explanation/json-ld-basics.md b/docs/explanation/json-ld-basics.md
new file mode 100644
index 000000000..67fe71644
--- /dev/null
+++ b/docs/explanation/json-ld-basics.md
@@ -0,0 +1,201 @@
+# JSON-LD in ReproSchema
+
+Understanding why ReproSchema uses JSON-LD and how it enhances data interoperability.
+
+## What is JSON-LD?
+
+JSON-LD (JSON for Linked Data) is JSON with superpowers. It looks like regular JSON but includes semantic meaning that machines can understand.
+
+### Regular JSON vs JSON-LD
+
+**Regular JSON:**
+```json
+{
+    "name": "PHQ-9",
+    "type": "questionnaire",
+    "questions": 9
+}
+```
+
+**JSON-LD:**
+```json
+{
+    "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+    "@type": "reproschema:Activity",
+    "@id": "PHQ-9_schema",
+    "prefLabel": "PHQ-9",
+    "description": "Patient Health Questionnaire - 9 items"
+}
+```
+
+## Why JSON-LD?
+
+### 1. Semantic Clarity
+
+The `@context` tells machines exactly what each term means:
+- `prefLabel` isn't just a random property name
+- It maps to a standardized definition
+- Different systems can understand it consistently
+
+### 2. Interoperability
+
+JSON-LD enables:
+- Integration with other semantic web standards
+- Automatic conversion between formats
+- Linking to external vocabularies (schema.org, NIDM)
+
+### 3. Self-Documenting
+
+Each schema carries its own semantic information:
+- No need for external documentation to understand structure
+- Properties have standardized meanings
+- Relationships are explicit
+
+## Key JSON-LD Features in ReproSchema
+
+### @context
+
+Defines the vocabulary and term mappings:
+
+```json
+"@context": [
+    "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+    {
+        "rl": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/"
+    }
+]
+```
+
+This allows:
+- Using ReproSchema vocabulary
+- Creating shortcuts (like `rl:` for library references)
+- Mixing vocabularies
+
+### @type
+
+Specifies what kind of thing this is:
+
+```json
+"@type": "reproschema:Protocol"  // This is a Protocol
+"@type": "reproschema:Activity"  // This is an Activity
+"@type": "reproschema:Field"     // This is an Item/Field
+```
+
+### @id
+
+Provides a unique identifier:
+
+```json
+"@id": "depression_study_schema"
+```
+
+This enables:
+- Referencing from other schemas
+- Creating persistent links
+- Version tracking
+
+## Practical Benefits
+
+### 1. Automatic Validation
+
+Because terms have defined meanings, we can:
+- Validate structure automatically
+- Catch errors early
+- Ensure consistency
+
+### 2. Enhanced Tooling
+
+JSON-LD enables tools to:
+- Generate documentation automatically
+- Convert between formats
+- Create visualizations
+- Build user interfaces
+
+### 3. Future-Proofing
+
+As standards evolve:
+- New properties can be added without breaking existing schemas
+- Vocabularies can be extended
+- Backwards compatibility is maintained
+
+## Working with JSON-LD
+
+### Context Shortcuts
+
+Create readable shortcuts:
+
+```json
+"@context": {
+    "nidm": "http://purl.org/nidash/nidm#",
+    "schema": "http://schema.org/"
+}
+```
+
+Then use them:
+```json
+"nidm:hasAge": 25,
+"schema:author": "Researcher Name"
+```
+
+### Referencing Other Schemas
+
+Link to activities or items:
+
+```json
+"ui": {
+    "order": [
+        "../activities/phq9/phq9_schema",
+        "rl:GAD-7/GAD7_schema"
+    ]
+}
+```
+
+### Language Support
+
+Specify multiple languages:
+
+```json
+"prefLabel": {
+    "en": "Depression Questionnaire",
+    "es": "Cuestionario de Depresión",
+    "fr": "Questionnaire de Dépression"
+}
+```
+
+## Common Patterns
+
+### 1. Activity References
+
+```json
+"isAbout": "../activities/demographics/demographics_schema"
+```
+
+### 2. Conditional Display
+
+```json
+"isVis": "age > 18"
+```
+
+### 3. Response Bindings
+
+```json
+"valueRequired": true
+```
+
+## Best Practices
+
+1. **Always include @context** - It's required for JSON-LD
+2. **Use standard properties** - Don't create custom properties when standard ones exist
+3. **Reference, don't duplicate** - Link to existing schemas
+4. **Version your contexts** - Include version numbers in context URLs
+
+## Debugging Tips
+
+When schemas don't work as expected:
+
+1. **Validate the JSON-LD** - Use online validators
+2. **Check context URLs** - Ensure they're accessible
+3. **Verify @type values** - Must match vocabulary definitions
+4. **Test references** - Ensure all paths resolve correctly
+
+Understanding JSON-LD is key to leveraging ReproSchema's full power for creating interoperable, semantic research instruments.
\ No newline at end of file
diff --git a/docs/how-to/add-translations.md b/docs/how-to/add-translations.md
new file mode 100644
index 000000000..2e1555781
--- /dev/null
+++ b/docs/how-to/add-translations.md
@@ -0,0 +1,70 @@
+# Add Translations to Your Schema
+
+Add multilingual support to your ReproSchema protocols and activities.
+
+## Goal
+
+Create multilingual versions of your schemas without duplicating content.
+
+## Prerequisites
+
+- Existing ReproSchema activity or protocol
+- Translated text content
+- Text editor
+
+First here is the list of the questions of the EHI in French.
+
+```text
+Quelle main utilisez vous de préférence pour:
+
+1) Écrire (*)
+2) Dessiner
+3) Lancer (*)
+4) Utiliser une paire de ciseaux
+5) Utiliser une brosse à dents (*)
+6) Tenir un couteau (sans fourchette)
+7) Tenir une cuillère (*)
+8) Utiliser un balai (main supérieure)
+9) Tenir une allumette pour l'allumer
+10) Ouvrir une boîte (prendre le couvercle)
+
+i) Quel est le pied avec lequel vous préférez shooter?
+ii) Quel oeil utiliser-vous pour viser?
+```
+
+## Updating the items
+
+```json linenums="1" hl_lines="5-8 12-15"
+{
+  "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0-rc1/contexts/generic",
+  "@type": "reproschema:Field",
+  "@id": "writing",
+  "prefLabel": {
+    "en": "writing",
+    "fr": "écrire"
+  },
+  "description": "writing item of the EHI",
+  "schemaVersion": "1.0.0-rc1",
+  "version": "0.0.1",
+  "question": {
+    "en": "Writing",
+    "fr": "Écrire"
+  },
+  "ui": { "inputType": "radio" },
+  "responseOptions": "../leftRightValueConstraintsMultiLang.jsonld"
+}
+```
+
+## Updating the response options
+
+```json linenums="1" hl_lines="10-14 17-21 24-28 31-35 38-42"
+--8<-- "examples/activities/EHI/leftRightValueConstraintsMultiLang.jsonld"
+```
+
+## Updating the activity
+
+We need to update the `edinburgh_handedness_inventory_short.jsonld` so that the preamble question has both languages:
+
+```json linenums="1" hl_lines="5-8 13-16"
+--8<-- "examples/activities/EHI/edinburgh_handedness_inventory_short_multi_lang.jsonld"
+```
diff --git a/docs/how-to/create-protocol.md b/docs/how-to/create-protocol.md
new file mode 100644
index 000000000..9f80600fb
--- /dev/null
+++ b/docs/how-to/create-protocol.md
@@ -0,0 +1,83 @@
+# Create a Protocol from Scratch
+
+Create a ReproSchema protocol manually for full control over the structure.
+
+## Goal
+
+Create a custom protocol with your specific requirements without using templates.
+
+## Prerequisites
+
+- Text editor
+- Basic understanding of JSON
+- Terminal/command line access
+
+## Steps
+
+### 1. Create Directory Structure
+
+```bash
+# Create main directory
+mkdir my_protocol
+cd my_protocol
+
+# Create subdirectories
+mkdir protocols
+mkdir activities
+```
+
+### 2. Create Protocol Schema
+
+Create `protocols/my_protocol_schema.jsonld`:
+
+```json
+{
+    "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+    "@type": "reproschema:Protocol",
+    "@id": "my_protocol_schema",
+    "prefLabel": "My Research Protocol",
+    "description": "Description of your research protocol",
+    "landingPage": {
+        "@id": "README.md",
+        "@language": "en"
+    },
+    "ui": {
+        "order": [
+            "../activities/activity1/activity1_schema"
+        ],
+        "shuffle": false,
+        "addProperties": [
+            {
+                "isAbout": "../activities/activity1/activity1_schema",
+                "variableName": "activity1",
+                "prefLabel": "First Activity"
+            }
+        ]
+    }
+}
+```
+
+### 3. Add Activities
+
+For each activity in your protocol:
+1. Create a directory: `mkdir activities/activity_name`
+2. Create the activity schema file
+3. Add it to the protocol's `ui.order` and `ui.addProperties`
+
+### 4. Validate Your Protocol
+
+```bash
+reproschema -l DEBUG validate protocols/my_protocol_schema.jsonld
+```
+
+## Troubleshooting
+
+- **Validation errors**: Check JSON syntax and required fields
+- **Activities not showing**: Verify paths in `ui.order`
+- **Wrong display order**: Check the sequence in `ui.order` array
+
+## Next Steps
+
+- [Add activities to your protocol](create-activity.md)
+- [Visualize your protocol](visualize.md)
+- [Deploy your protocol](deploy-protocol.md)
\ No newline at end of file
diff --git a/docs/how-to/deploy-protocol.md b/docs/how-to/deploy-protocol.md
new file mode 100644
index 000000000..89dfdb54d
--- /dev/null
+++ b/docs/how-to/deploy-protocol.md
@@ -0,0 +1,281 @@
+# Deploy Your Protocol
+
+Deploy your validated ReproSchema protocol for data collection.
+
+## Goal
+
+Make your protocol accessible to participants through various deployment options.
+
+## Prerequisites
+
+- Validated ReproSchema protocol
+- Chosen deployment platform
+- Basic understanding of web hosting
+
+## Deployment Options
+
+### Option 1: GitHub Pages (Free)
+
+**Best for:** Small studies, proof of concepts, testing
+
+#### Steps
+
+1. **Push to GitHub**
+   ```bash
+   git add .
+   git commit -m "Add protocol for deployment"
+   git push origin main
+   ```
+
+2. **Enable GitHub Pages**
+   - Go to your repository settings
+   - Scroll to "Pages" section
+   - Select "Deploy from a branch"
+   - Choose "main" branch
+
+3. **Access Your Protocol**
+   ```
+   https://www.repronim.org/reproschema-ui/#/?url=https://YOUR_USERNAME.github.io/YOUR_REPO/protocols/protocol_schema.jsonld
+   ```
+
+### Option 2: Reproschema-Server (Recommended)
+
+**Best for:** Production studies, data collection, full features
+
+#### Using Docker
+
+1. **Clone reproschema-server**
+   ```bash
+   git clone https://github.com/ReproNim/reproschema-server
+   cd reproschema-server
+   ```
+
+2. **Configure Environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your settings
+   ```
+
+3. **Deploy with Docker**
+   ```bash
+   docker-compose up -d
+   ```
+
+4. **Upload Your Protocol**
+   - Access admin interface
+   - Upload protocol files
+   - Configure study settings
+
+### Option 3: Custom Hosting
+
+**Best for:** Custom integrations, institutional hosting
+
+#### Requirements
+
+- Web server (Apache, Nginx)
+- HTTPS support
+- CORS headers configured
+
+#### Steps
+
+1. **Upload Protocol Files**
+   ```bash
+   scp -r protocols/ user@your-server:/var/www/html/
+   ```
+
+2. **Configure CORS**
+   Add to your server config:
+   ```apache
+   Header always set Access-Control-Allow-Origin "*"
+   Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
+   ```
+
+3. **Test Access**
+   ```
+   https://www.repronim.org/reproschema-ui/#/?url=https://your-domain.com/protocols/protocol_schema.jsonld
+   ```
+
+## Configuration Options
+
+### Study Settings
+
+Configure study parameters in your protocol:
+
+```json
+{
+    "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+    "@type": "reproschema:Protocol",
+    "@id": "my_study_protocol",
+    "prefLabel": "My Research Study",
+    "description": "Description of the study",
+    "landingPage": {
+        "@id": "README.md",
+        "@language": "en"
+    },
+    "ui": {
+        "allow": [
+            "reproschema:AutoAdvance",
+            "reproschema:AllowExport",
+            "reproschema:DisableBack"
+        ]
+    }
+}
+```
+
+### Access Control
+
+#### Public Access
+No additional configuration needed.
+
+#### Restricted Access
+Use authentication parameters:
+
+```json
+{
+    "ui": {
+        "allow": [
+            "reproschema:RequireAuth"
+        ],
+        "authConfig": {
+            "type": "token",
+            "endpoint": "https://your-auth-server.com/validate"
+        }
+    }
+}
+```
+
+### Data Collection
+
+#### Local Storage (Testing)
+Data stored in browser localStorage.
+
+#### Server Storage (Production)
+Configure data endpoint:
+
+```json
+{
+    "ui": {
+        "dataEndpoint": "https://your-server.com/api/responses"
+    }
+}
+```
+
+## Pre-Deployment Checklist
+
+### Technical Validation
+
+- [ ] All schemas validate successfully
+- [ ] Protocol renders correctly in reproschema-ui
+- [ ] All activities and items load properly
+- [ ] Branching logic works as expected
+- [ ] Required fields are marked correctly
+
+### Content Review
+
+- [ ] All text is proofread and accurate
+- [ ] Instructions are clear and complete
+- [ ] Consent forms are legally compliant
+- [ ] Contact information is correct
+- [ ] Study information is complete
+
+### Testing
+
+- [ ] Test complete participant flow
+- [ ] Test on different devices (desktop, mobile, tablet)
+- [ ] Test in different browsers
+- [ ] Test with different languages (if applicable)
+- [ ] Verify data export/storage
+
+### Security & Privacy
+
+- [ ] HTTPS enabled
+- [ ] Data encryption configured
+- [ ] Privacy policy accessible
+- [ ] GDPR/HIPAA compliance verified
+- [ ] Backup systems in place
+
+## Monitoring and Maintenance
+
+### Analytics
+
+Track study progress:
+- Participation rates
+- Completion rates
+- Drop-off points
+- Technical issues
+
+### Updates
+
+For schema updates during data collection:
+1. Create new version of schema
+2. Test thoroughly
+3. Deploy to staging environment
+4. Migrate to production
+5. Update participant links
+
+### Data Management
+
+Regular tasks:
+- Export collected data
+- Backup data securely
+- Monitor storage capacity
+- Review data quality
+
+## Troubleshooting
+
+### Protocol Won't Load
+
+**Check:**
+- Schema validation passes
+- All file paths are correct
+- CORS headers are present
+- HTTPS is enabled
+
+### Data Not Saving
+
+**Check:**
+- Data endpoint configuration
+- Server permissions
+- Network connectivity
+- Storage capacity
+
+### Performance Issues
+
+**Solutions:**
+- Optimize schema file sizes
+- Use CDN for hosting
+- Minimize external dependencies
+- Enable compression
+
+## Post-Deployment
+
+### Participant Communication
+
+Provide participants with:
+- Direct protocol URL
+- Instructions for technical requirements
+- Contact information for support
+- Estimated completion time
+
+### Data Collection
+
+Monitor:
+- Response rates
+- Data quality
+- Technical issues
+- Participant feedback
+
+## Best Practices
+
+1. **Start Small**: Test with small groups before full deployment
+2. **Version Control**: Use semantic versioning for protocols
+3. **Documentation**: Keep deployment documentation updated
+4. **Security**: Regular security audits and updates
+5. **Backup**: Multiple backup strategies
+6. **Monitoring**: Continuous monitoring of all systems
+
+## Next Steps
+
+- [Set up data analysis pipeline](../tutorials/analyzing-data.md)
+- [Configure automated backups](backup-strategies.md)
+- [Monitor study progress](monitoring-guide.md)
\ No newline at end of file
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
new file mode 100644
index 000000000..69379fb31
--- /dev/null
+++ b/docs/how-to/index.md
@@ -0,0 +1,41 @@
+# How-To Guides
+
+Quick, practical guides for accomplishing specific tasks with ReproSchema.
+
+## 🎯 Find Your Task
+
+### Schema Creation & Management
+- 📝 **[Create a Protocol from Scratch](create-protocol.md)** - Manual protocol creation
+- 🍪 **[Use the Cookiecutter Template](use-cookiecutter.md)** - Quick start with templates
+- 📚 **[Use Library Assessments](use-library-assessments.md)** - Add pre-built questionnaires
+- ✅ **[Validate Your Schemas](validation.md)** - Check schemas for errors and compliance
+- 👁️ **[Visualize in ReproSchema UI](visualize.md)** - Preview your schemas as web forms
+
+### Content Management
+- 🌍 **[Add Translations](add-translations.md)** - Add multilingual support to schemas
+- 🚀 **[Deploy Your Protocol](deploy-protocol.md)** - Deploy for data collection
+
+### Coming Soon
+- 🔄 Convert from REDCap format
+- 🔧 Set up CI/CD validation
+- 🎨 Customize response types
+- 📊 Export and analyze data
+
+## 📋 How-To Guide Format
+
+Each guide follows a consistent structure:
+- **Goal**: What you'll accomplish
+- **Prerequisites**: What you need before starting
+- **Steps**: Clear, numbered instructions
+- **Troubleshooting**: Common issues and solutions
+
+## 🔄 Difference from Tutorials
+
+- **Tutorials** = Learning exercises (understanding focused)
+- **How-To Guides** = Task completion (results focused)
+
+For learning ReproSchema from scratch, see our [Tutorials](../tutorials/index.md).
+
+## 🚧 Under Development
+
+We're actively expanding our how-to guides. Need a guide that's not here yet? [Let us know](https://github.com/ReproNim/reproschema/issues)!
\ No newline at end of file
diff --git a/docs/how-to/use-cookiecutter.md b/docs/how-to/use-cookiecutter.md
new file mode 100644
index 000000000..22787b1fa
--- /dev/null
+++ b/docs/how-to/use-cookiecutter.md
@@ -0,0 +1,41 @@
+# Use the Cookiecutter Template
+
+Quickly create a new ReproSchema protocol using the official cookiecutter template.
+
+## Goal
+
+Generate a complete ReproSchema protocol structure with example activities in under 5 minutes.
+
+## Getting Started
+
+1.  **Prerequisite:**
+    Ensure you have Git and Cookiecutter installed on your system. If not, please refer to the installation guides for Git and Cookiecutter.
+
+1.  **Generate your Repository:**
+    Use the Reproschema Protocol Cookiecutter to create a new repository for your research protocol.
+    Run the following command in your terminal:
+
+    ```bash
+    cookiecutter gh:ReproNim/reproschema-protocol-cookiecutter
+    ```
+
+1.  Follow the prompts to customize your new protocol,
+    more details see [here](https://github.com/ReproNim/reproschema-protocol-cookiecutter#step-1-generate-the-protocol-files)
+
+## Customizing Your Protocol
+
+Once you run the Cookiecutter command, you will be prompted to make choices for your protocol, ranging from 1-5. These choices generate corresponding activities in your repository. Here's what you can do with these activities:
+
+1.  **Use as templates:**
+    The activities created based on your choices serve as templates.
+    You can use these to understand the structure and elements within the activities folder.
+    This is particularly useful if you're new to ReproSchema.
+    By exploring these templates, you'll get a clearer picture of how activities are structured and what kind of information they contain.
+
+1.  **Delete and start fresh:**
+    Alternatively, if you already have a clear idea of what your protocol needs, you can delete these generated activities.
+    This allows you to start from scratch, creating activities that are tailored specifically to your research needs.
+
+The inclusion of activity choices aims to provide users with a practical understanding of how activities are structured within ReproSchema protocols. Whether you use these as a starting point or prefer to create your own from the ground up, these templates are there to guide you in structuring your research protocol effectively.
+
+We provide more detailed instructions for customizing your protocol in the following pages using [reproschema-demo-protocol](https://github.com/ReproNim/reproschema-demo-protocol) as an example.
diff --git a/docs/how-to/use-library-assessments.md b/docs/how-to/use-library-assessments.md
new file mode 100644
index 000000000..2e33b092b
--- /dev/null
+++ b/docs/how-to/use-library-assessments.md
@@ -0,0 +1,102 @@
+# Use Assessments from the Library
+
+Integrate pre-built assessments from the reproschema-library into your protocol.
+
+## Goal
+
+Add standardized questionnaires (PHQ-9, GAD-7, etc.) to your protocol without recreating them.
+
+## Prerequisites
+
+- Existing protocol structure
+- Access to [reproschema-library](https://github.com/ReproNim/reproschema-library)
+
+## Steps
+
+### 1. Browse Available Assessments
+
+View available assessments at: https://github.com/ReproNim/reproschema-library/tree/master/activities
+
+Common assessments include:
+- PHQ-9 (Depression)
+- GAD-7 (Anxiety)
+- Demographics
+- BADS (Behavioral Activation)
+
+### 2. Add Library Context
+
+In your activity schema, add the library context:
+
+```json
+{
+    "@context": [
+        "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+        {
+            "rl": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/"
+        }
+    ]
+}
+```
+
+### 3. Reference Library Items
+
+In your activity's `addProperties`, reference library items:
+
+```json
+"addProperties": [
+    {
+        "isAbout": "rl:PHQ-9/items/phq9_1",
+        "variableName": "phq9_1", 
+        "prefLabel": "Little interest or pleasure",
+        "isVis": true
+    }
+]
+```
+
+### 4. Add to UI Order
+
+```json
+"order": [
+    "rl:PHQ-9/items/phq9_1",
+    "rl:PHQ-9/items/phq9_2"
+]
+```
+
+## Example: Complete PHQ-9 Integration
+
+```json
+{
+    "@context": [
+        "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+        {
+            "rl": "https://raw.githubusercontent.com/ReproNim/reproschema-library/master/activities/"
+        }
+    ],
+    "@type": "reproschema:Activity",
+    "@id": "depression_assessment",
+    "prefLabel": "Depression Assessment",
+    "ui": {
+        "order": [
+            "rl:PHQ-9/PHQ9_schema"
+        ],
+        "addProperties": [
+            {
+                "isAbout": "rl:PHQ-9/PHQ9_schema",
+                "variableName": "phq9",
+                "prefLabel": "PHQ-9 Depression Scale"
+            }
+        ]
+    }
+}
+```
+
+## Tips
+
+- Use complete assessments by referencing the activity schema
+- Mix library items with custom items
+- Override labels and descriptions as needed
+
+## Next Steps
+
+- [Create custom items](add-items.md)
+- [Combine multiple assessments](create-activity.md)
\ No newline at end of file
diff --git a/docs/how-to/validation.md b/docs/how-to/validation.md
index 4c1a49d2e..943e39f6b 100644
--- a/docs/how-to/validation.md
+++ b/docs/how-to/validation.md
@@ -1,24 +1,196 @@
-# Validation
+# Validate Your Schemas
 
-### Validating your schema
+Ensure your ReproSchema files are correctly formatted and compliant.
 
-If you want to validate a schema you have created:
+## Goal
 
-- install the reproschema python tools
+Validate schema files to catch errors before deployment.
+
+## Prerequisites
+
+- Python 3.7 or higher
+- pip (Python package manager)
+
+## Installation
+
+Install the reproschema validation tools:
 
 ```bash
 pip install reproschema
 ```
 
-- run its `validate` command
+## Basic Validation
+
+### Validate a Single File
+
+```bash
+reproschema validate path/to/schema.jsonld
+```
+
+### Validate a Directory
 
 ```bash
-reproschema --log-level DEBUG validate PATH_TO_VALIDATE
+reproschema validate protocols/
 ```
 
-!!! note
+This validates all `.jsonld` files in the directory and subdirectories.
+
+### Verbose Output
+
+For detailed validation information:
+
+```bash
+reproschema --log-level DEBUG validate protocols/
+```
+
+## Common Validation Errors
+
+### 1. Missing Required Fields
+
+**Error:**
+```
+ValidationError: '@context' is a required property
+```
+
+**Solution:** Add the required `@context`:
+```json
+{
+    "@context": "https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema",
+    ...
+}
+```
+
+### 2. Invalid @type
+
+**Error:**
+```
+ValidationError: 'Activity' is not valid under any of the given schemas
+```
+
+**Solution:** Use the correct type with prefix:
+```json
+"@type": "reproschema:Activity"
+```
+
+### 3. Invalid References
+
+**Error:**
+```
+ValidationError: Could not resolve '../activities/missing_activity'
+```
+
+**Solution:** Check that:
+- The file path is correct
+- The referenced file exists
+- Use forward slashes (/) not backslashes
+
+### 4. JSON Syntax Errors
+
+**Error:**
+```
+JSONDecodeError: Expecting ',' delimiter
+```
+
+**Solution:** 
+- Check for missing commas between properties
+- Ensure quotes are properly closed
+- Validate JSON syntax first using a JSON validator
+
+## Advanced Validation
+
+### Validate Specific Schema Version
+
+```bash
+reproschema validate --schema-version 1.0.0 protocols/
+```
+
+### Validate with Custom Context
+
+```bash
+reproschema validate --context https://your-context-url protocols/
+```
+
+### Validate Multiple Paths
+
+```bash
+reproschema validate protocols/ activities/ items/
+```
+
+## Validation Best Practices
+
+1. **Validate Early and Often**
+   - Run validation after each change
+   - Don't wait until deployment
+
+2. **Use Debug Mode for Development**
+   ```bash
+   reproschema --log-level DEBUG validate .
+   ```
+
+3. **Validate Before Commits**
+   Add to your git pre-commit hook:
+   ```bash
+   #!/bin/sh
+   reproschema validate protocols/ activities/
+   ```
+
+4. **Check References**
+   Ensure all referenced files exist before validation
+
+## Understanding Validation Output
+
+### Success Output
+```
+✓ protocols/my_protocol_schema.jsonld
+✓ activities/phq9/phq9_schema.jsonld
+All schemas are valid!
+```
+
+### Error Output
+```
+✗ protocols/my_protocol_schema.jsonld
+  - Line 15: Missing required field 'prefLabel'
+  - Line 23: Invalid reference to '../activities/missing'
+1 schema(s) failed validation
+```
+
+## Troubleshooting
+
+### Installation Issues
+
+If `pip install reproschema` fails:
+
+1. Upgrade pip:
+   ```bash
+   python -m pip install --upgrade pip
+   ```
+
+2. Try installing in a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   pip install reproschema
+   ```
+
+### Validation Hangs
+
+If validation seems stuck:
+- Check for circular references in schemas
+- Use `--timeout 30` to set a timeout
+- Validate files individually to isolate the issue
+
+### Context Loading Errors
+
+If you see "Could not load context":
+- Ensure you have internet connectivity
+- Check if context URLs are accessible
+- Try using a local context file
+
+## Next Steps
 
-    You can validate a single file or all the files in a folder and its subfolder.
+- [Set up CI/CD validation](setup-ci.md)
+- [Visualize validated schemas](visualize.md)
+- [Deploy validated protocols](deploy-protocol.md)
 
 ### Automating validation
 
diff --git a/docs/how-to/visualize.md b/docs/how-to/visualize.md
index 88fc9c8f1..30690694f 100644
--- a/docs/how-to/visualize.md
+++ b/docs/how-to/visualize.md
@@ -1,26 +1,154 @@
-# Visualize
+# Visualize Your Protocol
 
-If you want to visualize the graph represented by the JSON-LD file,
-we explain how to do this in [From JSON to JSON-LD](../FAQ.md#from-json-to-json-ld).
+Preview your ReproSchema protocols and activities as interactive web forms.
 
-If you want to visualize the protocol or the activity you have created as a web form,
-you can use the [reproschema-ui](https://github.com/ReproNim/reproschema-ui) to preview it.
-To do so you can pass the URL to your protocol or activity as a query
-to the [reproschema-ui app](https://www.repronim.org/reproschema-ui/)
+## Goal
 
-```https://www.repronim.org/reproschema-ui/#/?url=url-to-your-schema```
+Test and preview your schemas in a real user interface before deployment.
 
-If you are hosting a schema on github, make sure that you are passing the URL of the **raw** content of the schema.
-For example, our demo protocol can be accessed at this URL:
+## Try It Now!
 
-[https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema)
+Want to see ReproSchema in action? Click below to view our demo protocol:
 
-But to get access to the raw content of that file you must click on the `Raw` button
-once you have opened that page on github that will open this URL:
+[**🚀 View Demo Protocol**](https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema)
 
-[https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema](https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema).
+This demo includes various question types and branching logic to showcase ReproSchema capabilities.
 
-So in the end the URL to preview this protocol as a web form would be:
+## Prerequisites
 
-[https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema](
-https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema)
+- A valid ReproSchema protocol or activity
+- Web browser
+- Internet connection (for hosted UI)
+
+## Quick Start
+
+### Using the Hosted UI
+
+Visit the ReproSchema UI with your schema URL:
+
+```
+https://www.repronim.org/reproschema-ui/#/?url=YOUR_SCHEMA_URL
+```
+
+Replace `YOUR_SCHEMA_URL` with the direct link to your schema file.
+
+## Step-by-Step Guide
+
+### 1. Prepare Your Schema URL
+
+#### For GitHub-Hosted Schemas
+
+1. Navigate to your schema file on GitHub
+2. Click the "Raw" button
+3. Copy the raw URL
+
+**Example:**
+- GitHub URL: `https://github.com/ReproNim/reproschema-demo-protocol/blob/main/reproschema_demo_protocol/reproschema_demo_protocol_schema`
+- Raw URL: `https://raw.githubusercontent.com/ReproNim/reproschema-demo-protocol/main/reproschema_demo_protocol/reproschema_demo_protocol_schema`
+
+#### For Local Development
+
+Use a local server:
+
+```bash
+# Python 3
+python -m http.server 8000
+
+# Python 2
+python -m SimpleHTTPServer 8000
+```
+
+Then use: `http://localhost:8000/path/to/schema.jsonld`
+
+### 2. Construct the Preview URL
+
+Combine the base UI URL with your schema:
+
+```
+https://www.repronim.org/reproschema-ui/#/?url=https://raw.githubusercontent.com/YOUR_GITHUB_USERNAME/YOUR_REPO/main/path/to/schema.jsonld
+```
+
+### 3. Open and Test
+
+1. Open the constructed URL in your browser
+2. Navigate through your protocol
+3. Test all interactions and branching logic
+
+## Advanced Options
+
+### URL Parameters
+
+Add additional parameters to customize the preview:
+
+```
+https://www.repronim.org/reproschema-ui/#/
+  ?url=YOUR_SCHEMA_URL
+  &lang=es              # Language (en, es, fr, etc.)
+```
+
+### Running UI Locally
+
+For development, run the UI locally:
+
+```bash
+git clone https://github.com/ReproNim/reproschema-ui
+cd reproschema-ui
+npm install
+npm run serve
+```
+
+Then access at `http://localhost:8080`
+
+## Troubleshooting
+
+### Schema Doesn't Load
+
+**Problem:** Blank screen or loading spinner
+
+**Solutions:**
+1. **Check URL encoding** - Ensure special characters are encoded
+2. **Verify raw URL** - Must be direct file access, not GitHub page
+3. **Validate schema first** - Run validation before visualization
+4. **Check browser console** - Look for error messages
+
+### CORS Errors
+
+**Problem:** "Cross-Origin Request Blocked"
+
+**Solutions:**
+1. Use GitHub raw URLs (they include CORS headers)
+2. Host on a server with proper CORS configuration
+3. Use local development server
+
+### Missing Activities
+
+**Problem:** Protocol loads but activities are missing
+
+**Solutions:**
+1. Check activity paths in protocol schema
+2. Ensure all referenced files are accessible
+3. Use absolute URLs for external activities
+
+## Common Issues and Solutions
+
+### 1. Slow Loading
+
+- Optimize schema file size
+- Host schemas on fast CDN
+- Minimize external dependencies
+
+### 2. Mobile Display
+
+- Test responsive layout
+- Check touch interactions
+- Verify keyboard accessibility
+
+## Next Steps
+
+- [Validate your schemas](validation.md) before visualization
+- [Create a protocol](create-protocol.md) to visualize
+- [Use library assessments](use-library-assessments.md) in your protocol
+
+!!! note "Future Updates"
+
+    This guide will be updated when reproschema-ui or reproschema-server receive major updates. The demo protocol link will always showcase the latest features.
diff --git a/docs/reference/api-reference.md b/docs/reference/api-reference.md
new file mode 100644
index 000000000..6235e11d9
--- /dev/null
+++ b/docs/reference/api-reference.md
@@ -0,0 +1,457 @@
+# API Reference
+
+Python API documentation for working with ReproSchema programmatically.
+
+## Installation
+
+```bash
+pip install reproschema
+```
+
+## Basic Usage
+
+### Import the Module
+
+```python
+import reproschema as rs
+from reproschema import validate, convert
+```
+
+## Validation API
+
+### validate()
+
+Validate ReproSchema files.
+
+```python
+def validate(path, schema_version=None, context_url=None):
+    """
+    Validate ReproSchema files.
+    
+    Args:
+        path (str): Path to file or directory to validate
+        schema_version (str, optional): Schema version to validate against
+        context_url (str, optional): Custom context URL
+        
+    Returns:
+        bool: True if validation passes, False otherwise
+        
+    Raises:
+        ValidationError: If validation fails
+        FileNotFoundError: If path doesn't exist
+    """
+```
+
+#### Examples
+
+**Validate a single file:**
+```python
+from reproschema import validate
+
+# Validate a protocol
+is_valid = validate("protocols/my_protocol_schema.jsonld")
+print(f"Protocol is valid: {is_valid}")
+
+# Validate with specific version
+is_valid = validate("protocols/my_protocol_schema.jsonld", schema_version="1.0.0")
+```
+
+**Validate a directory:**
+```python
+# Validate all schemas in directory
+is_valid = validate("protocols/")
+
+# Validate multiple directories
+for directory in ["protocols/", "activities/", "items/"]:
+    is_valid = validate(directory)
+    print(f"{directory} is valid: {is_valid}")
+```
+
+**Handle validation errors:**
+```python
+from reproschema import validate, ValidationError
+
+try:
+    validate("invalid_schema.jsonld")
+except ValidationError as e:
+    print(f"Validation failed: {e}")
+    print(f"Errors: {e.errors}")
+except FileNotFoundError as e:
+    print(f"File not found: {e}")
+```
+
+## Conversion API
+
+### redcap2reproschema()
+
+Convert REDCap data dictionary to ReproSchema.
+
+```python
+def redcap2reproschema(csv_file, yaml_file=None, output_dir="output"):
+    """
+    Convert REDCap CSV to ReproSchema.
+    
+    Args:
+        csv_file (str): Path to REDCap CSV file
+        yaml_file (str, optional): Path to conversion configuration
+        output_dir (str): Output directory for generated schemas
+        
+    Returns:
+        dict: Conversion results and statistics
+    """
+```
+
+#### Examples
+
+**Basic conversion:**
+```python
+from reproschema import redcap2reproschema
+
+# Convert REDCap CSV
+result = redcap2reproschema("redcap_export.csv", output_dir="my_protocol")
+print(f"Converted {result['activities_created']} activities")
+```
+
+**With configuration:**
+```python
+# Use YAML configuration for custom mapping
+result = redcap2reproschema(
+    csv_file="redcap_export.csv",
+    yaml_file="conversion_config.yaml",
+    output_dir="my_protocol"
+)
+```
+
+### reproschema2redcap()
+
+Convert ReproSchema to REDCap format.
+
+```python
+def reproschema2redcap(protocol_path, output_file="redcap_dictionary.csv"):
+    """
+    Convert ReproSchema protocol to REDCap CSV.
+    
+    Args:
+        protocol_path (str): Path to protocol schema
+        output_file (str): Output CSV file path
+        
+    Returns:
+        str: Path to generated CSV file
+    """
+```
+
+#### Examples
+
+```python
+from reproschema import reproschema2redcap
+
+# Convert protocol to REDCap
+csv_path = reproschema2redcap("protocols/my_protocol_schema.jsonld")
+print(f"REDCap dictionary saved to: {csv_path}")
+```
+
+## Schema Loading API
+
+### load_schema()
+
+Load and parse ReproSchema files.
+
+```python
+def load_schema(path):
+    """
+    Load ReproSchema from file.
+    
+    Args:
+        path (str): Path to schema file
+        
+    Returns:
+        dict: Parsed schema data
+    """
+```
+
+#### Examples
+
+```python
+from reproschema import load_schema
+
+# Load protocol
+protocol = load_schema("protocols/my_protocol_schema.jsonld")
+print(f"Protocol name: {protocol['prefLabel']}")
+
+# Load activity
+activity = load_schema("activities/phq9/phq9_schema.jsonld")
+print(f"Activity type: {activity['@type']}")
+```
+
+### resolve_references()
+
+Resolve schema references and expand contexts.
+
+```python
+def resolve_references(schema, base_path="."):
+    """
+    Resolve all references in a schema.
+    
+    Args:
+        schema (dict): Schema with references
+        base_path (str): Base path for resolving relative references
+        
+    Returns:
+        dict: Schema with resolved references
+    """
+```
+
+## Schema Creation API
+
+### create_protocol()
+
+Create a new protocol schema.
+
+```python
+def create_protocol(name, description, activities=None):
+    """
+    Create a new protocol schema.
+    
+    Args:
+        name (str): Protocol name
+        description (str): Protocol description
+        activities (list, optional): List of activity references
+        
+    Returns:
+        dict: New protocol schema
+    """
+```
+
+#### Examples
+
+```python
+from reproschema import create_protocol, save_schema
+
+# Create new protocol
+protocol = create_protocol(
+    name="Depression Study",
+    description="A study measuring depression and anxiety",
+    activities=[
+        "../activities/phq9/phq9_schema",
+        "../activities/gad7/gad7_schema"
+    ]
+)
+
+# Save to file
+save_schema(protocol, "protocols/depression_study_schema.jsonld")
+```
+
+### create_activity()
+
+Create a new activity schema.
+
+```python
+def create_activity(name, description, items=None):
+    """
+    Create a new activity schema.
+    
+    Args:
+        name (str): Activity name
+        description (str): Activity description
+        items (list, optional): List of item references
+        
+    Returns:
+        dict: New activity schema
+    """
+```
+
+### create_item()
+
+Create a new item schema.
+
+```python
+def create_item(question, input_type, response_options=None):
+    """
+    Create a new item schema.
+    
+    Args:
+        question (str): Item question text
+        input_type (str): Input type (radio, text, etc.)
+        response_options (dict, optional): Response configuration
+        
+    Returns:
+        dict: New item schema
+    """
+```
+
+#### Examples
+
+```python
+from reproschema import create_item
+
+# Create text item
+text_item = create_item(
+    question="What is your name?",
+    input_type="text",
+    response_options={
+        "valueType": "xsd:string",
+        "maxLength": 100
+    }
+)
+
+# Create radio item
+radio_item = create_item(
+    question="How are you feeling?",
+    input_type="radio",
+    response_options={
+        "valueType": "xsd:integer",
+        "choices": [
+            {"value": 1, "name": "Very bad"},
+            {"value": 2, "name": "Bad"},
+            {"value": 3, "name": "Okay"},
+            {"value": 4, "name": "Good"},
+            {"value": 5, "name": "Very good"}
+        ]
+    }
+)
+```
+
+## Utility Functions
+
+### save_schema()
+
+Save schema to file.
+
+```python
+def save_schema(schema, file_path):
+    """
+    Save schema to JSON-LD file.
+    
+    Args:
+        schema (dict): Schema to save
+        file_path (str): Output file path
+    """
+```
+
+### get_schema_version()
+
+Get current schema version.
+
+```python
+def get_schema_version():
+    """
+    Get the current ReproSchema version.
+    
+    Returns:
+        str: Version string
+    """
+```
+
+### list_field_types()
+
+Get available field types.
+
+```python
+def list_field_types():
+    """
+    List all available input types.
+    
+    Returns:
+        list: Available input types
+    """
+```
+
+## Error Handling
+
+### ValidationError
+
+Raised when schema validation fails.
+
+```python
+class ValidationError(Exception):
+    def __init__(self, message, errors=None):
+        self.message = message
+        self.errors = errors or []
+        super().__init__(self.message)
+```
+
+### ConversionError
+
+Raised when format conversion fails.
+
+```python
+class ConversionError(Exception):
+    def __init__(self, message, source_format=None, target_format=None):
+        self.message = message
+        self.source_format = source_format
+        self.target_format = target_format
+        super().__init__(self.message)
+```
+
+## Configuration
+
+### Set Default Context
+
+```python
+from reproschema import set_default_context
+
+set_default_context("https://raw.githubusercontent.com/ReproNim/reproschema/1.0.0/contexts/reproschema")
+```
+
+### Set Validation Options
+
+```python
+from reproschema import set_validation_options
+
+set_validation_options({
+    "strict_mode": True,
+    "check_references": True,
+    "validate_context": True
+})
+```
+
+## Examples
+
+### Complete Workflow
+
+```python
+from reproschema import (
+    redcap2reproschema, 
+    validate, 
+    load_schema,
+    reproschema2redcap
+)
+
+# 1. Convert from REDCap
+result = redcap2reproschema("study.csv", output_dir="my_study")
+
+# 2. Validate generated schemas
+is_valid = validate("my_study/")
+if not is_valid:
+    print("Validation failed!")
+    exit(1)
+
+# 3. Load and inspect protocol
+protocol = load_schema("my_study/protocols/my_study_schema.jsonld")
+print(f"Protocol: {protocol['prefLabel']}")
+
+# 4. Convert back to REDCap for sharing
+redcap_file = reproschema2redcap("my_study/protocols/my_study_schema.jsonld")
+print(f"REDCap dictionary: {redcap_file}")
+```
+
+### Batch Processing
+
+```python
+import os
+from reproschema import validate
+
+# Validate all protocols in multiple directories
+study_dirs = ["study1/", "study2/", "study3/"]
+
+for study_dir in study_dirs:
+    if os.path.exists(f"{study_dir}/protocols/"):
+        is_valid = validate(f"{study_dir}/protocols/")
+        print(f"{study_dir}: {'✓ Valid' if is_valid else '✗ Invalid'}")
+```
+
+## See Also
+
+- [Field Types Reference](field-types.md)
+- [Validation How-To](../how-to/validation.md)
+- [Conversion How-To](../how-to/convert-from-redcap.md)
\ No newline at end of file
diff --git a/docs/reference/field-types.md b/docs/reference/field-types.md
new file mode 100644
index 000000000..a1c4eb748
--- /dev/null
+++ b/docs/reference/field-types.md
@@ -0,0 +1,522 @@
+# Field Types Reference
+
+Complete reference for all ReproSchema field types and their properties.
+
+## Input Types
+
+### Text Input
+
+#### `text`
+Single-line text input field.
+
+```json
+{
+    "ui": {
+        "inputType": "text"
+    },
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "maxLength": 255
+    }
+}
+```
+
+#### `multitext`
+Multi-line text input (textarea).
+
+```json
+{
+    "ui": {
+        "inputType": "multitext"
+    },
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "maxLength": 5000,
+        "rows": 5
+    }
+}
+```
+
+#### `email`
+Email input with validation.
+
+```json
+{
+    "ui": {
+        "inputType": "email"
+    },
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
+    }
+}
+```
+
+### Numeric Input
+
+#### `number`
+Numeric input field.
+
+```json
+{
+    "ui": {
+        "inputType": "number"
+    },
+    "responseOptions": {
+        "valueType": "xsd:integer",
+        "minValue": 0,
+        "maxValue": 100
+    }
+}
+```
+
+#### `float`
+Decimal number input.
+
+```json
+{
+    "ui": {
+        "inputType": "float"
+    },
+    "responseOptions": {
+        "valueType": "xsd:decimal",
+        "minValue": 0.0,
+        "maxValue": 100.0,
+        "precision": 2
+    }
+}
+```
+
+### Selection Input
+
+#### `radio`
+Radio button selection (single choice).
+
+```json
+{
+    "ui": {
+        "inputType": "radio"
+    },
+    "responseOptions": {
+        "valueType": "xsd:integer",
+        "minValue": 0,
+        "maxValue": 4,
+        "multipleChoice": false,
+        "choices": [
+            {
+                "value": 0,
+                "name": "Never"
+            },
+            {
+                "value": 1,
+                "name": "Rarely"
+            },
+            {
+                "value": 2,
+                "name": "Sometimes"
+            },
+            {
+                "value": 3,
+                "name": "Often"
+            },
+            {
+                "value": 4,
+                "name": "Always"
+            }
+        ]
+    }
+}
+```
+
+#### `select`
+Dropdown selection.
+
+```json
+{
+    "ui": {
+        "inputType": "select"
+    },
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "multipleChoice": false,
+        "choices": [
+            {
+                "value": "usa",
+                "name": "United States"
+            },
+            {
+                "value": "canada",
+                "name": "Canada"
+            },
+            {
+                "value": "other",
+                "name": "Other"
+            }
+        ]
+    }
+}
+```
+
+#### `selectMultiple`
+Multiple selection dropdown.
+
+```json
+{
+    "ui": {
+        "inputType": "select"
+    },
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "multipleChoice": true,
+        "choices": [
+            {
+                "value": "reading",
+                "name": "Reading"
+            },
+            {
+                "value": "sports",
+                "name": "Sports"
+            },
+            {
+                "value": "music",
+                "name": "Music"
+            }
+        ]
+    }
+}
+```
+
+### Range Input
+
+#### `slider`
+Slider for numeric ranges.
+
+```json
+{
+    "ui": {
+        "inputType": "slider"
+    },
+    "responseOptions": {
+        "valueType": "xsd:integer",
+        "minValue": 0,
+        "maxValue": 10,
+        "step": 1,
+        "minLabel": "No pain",
+        "maxLabel": "Worst pain"
+    }
+}
+```
+
+### Date/Time Input
+
+#### `date`
+Date picker.
+
+```json
+{
+    "ui": {
+        "inputType": "date"
+    },
+    "responseOptions": {
+        "valueType": "xsd:date",
+        "minValue": "1900-01-01",
+        "maxValue": "2024-12-31"
+    }
+}
+```
+
+#### `time`
+Time picker.
+
+```json
+{
+    "ui": {
+        "inputType": "time"
+    },
+    "responseOptions": {
+        "valueType": "xsd:time"
+    }
+}
+```
+
+#### `datetime`
+Date and time picker.
+
+```json
+{
+    "ui": {
+        "inputType": "datetime"
+    },
+    "responseOptions": {
+        "valueType": "xsd:dateTime"
+    }
+}
+```
+
+### Media Input
+
+#### `audioRecord`
+Audio recording input.
+
+```json
+{
+    "ui": {
+        "inputType": "audioRecord"
+    },
+    "responseOptions": {
+        "valueType": "schema:AudioObject",
+        "maxDuration": 300,
+        "mediaType": "audio/wav"
+    }
+}
+```
+
+#### `audioPassage`
+Audio playback with passage recording.
+
+```json
+{
+    "ui": {
+        "inputType": "audioPassage"
+    },
+    "responseOptions": {
+        "valueType": "schema:AudioObject",
+        "passages": [
+            {
+                "id": "rainbow_passage",
+                "text": "When the sunlight strikes raindrops in the air...",
+                "audio": "https://example.com/rainbow.mp3"
+            }
+        ]
+    }
+}
+```
+
+#### `image`
+Image upload.
+
+```json
+{
+    "ui": {
+        "inputType": "image"
+    },
+    "responseOptions": {
+        "valueType": "schema:ImageObject",
+        "maxSize": 5242880,
+        "acceptedFormats": ["image/jpeg", "image/png"]
+    }
+}
+```
+
+#### `video`
+Video recording or upload.
+
+```json
+{
+    "ui": {
+        "inputType": "video"
+    },
+    "responseOptions": {
+        "valueType": "schema:VideoObject",
+        "maxDuration": 120,
+        "maxSize": 104857600
+    }
+}
+```
+
+### Special Input Types
+
+#### `static`
+Display-only content (no user input).
+
+```json
+{
+    "ui": {
+        "inputType": "static"
+    },
+    "question": "Please read the following instructions carefully..."
+}
+```
+
+#### `consent`
+Consent checkbox with terms.
+
+```json
+{
+    "ui": {
+        "inputType": "consent"
+    },
+    "responseOptions": {
+        "valueType": "xsd:boolean",
+        "requiredValue": true
+    }
+}
+```
+
+#### `location`
+Geographic location input.
+
+```json
+{
+    "ui": {
+        "inputType": "location"
+    },
+    "responseOptions": {
+        "valueType": "schema:GeoCoordinates",
+        "enableHighAccuracy": true
+    }
+}
+```
+
+## Response Options Properties
+
+### Common Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `valueType` | string | Data type of the response (xsd:string, xsd:integer, etc.) |
+| `multipleChoice` | boolean | Allow multiple selections |
+| `requiredValue` | boolean | Whether a response is required |
+| `minValue` | varies | Minimum allowed value |
+| `maxValue` | varies | Maximum allowed value |
+
+### Text Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `maxLength` | integer | Maximum character length |
+| `pattern` | string | Regular expression for validation |
+| `placeholder` | string | Placeholder text |
+
+### Numeric Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `step` | number | Increment step for numeric inputs |
+| `precision` | integer | Decimal places for float values |
+| `unitCode` | string | Unit of measurement (kg, cm, etc.) |
+
+### Choice Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `choices` | array | Array of choice objects |
+| `choice.value` | varies | Stored value |
+| `choice.name` | string/object | Display label (can be multilingual) |
+| `choice.image` | string | URL to choice image |
+
+### Media Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `maxDuration` | integer | Maximum duration in seconds |
+| `maxSize` | integer | Maximum file size in bytes |
+| `mediaType` | string | MIME type |
+| `acceptedFormats` | array | Array of accepted MIME types |
+
+## Validation Rules
+
+### Required Fields
+
+```json
+{
+    "responseOptions": {
+        "requiredValue": true
+    }
+}
+```
+
+### Conditional Requirements
+
+```json
+{
+    "responseOptions": {
+        "requiredValue": "age >= 18"
+    }
+}
+```
+
+### Custom Validation
+
+```json
+{
+    "responseOptions": {
+        "valueType": "xsd:string",
+        "pattern": "^[A-Z]{2}\\d{6}$",
+        "invalidMessage": "Please enter a valid ID (e.g., AB123456)"
+    }
+}
+```
+
+## Multilingual Support
+
+### Multilingual Labels
+
+```json
+{
+    "choices": [
+        {
+            "value": 1,
+            "name": {
+                "en": "Yes",
+                "es": "Sí",
+                "fr": "Oui"
+            }
+        },
+        {
+            "value": 0,
+            "name": {
+                "en": "No",
+                "es": "No",
+                "fr": "Non"
+            }
+        }
+    ]
+}
+```
+
+## Advanced Features
+
+### Dynamic Value Constraints
+
+```json
+{
+    "responseOptions": {
+        "valueType": "xsd:integer",
+        "minValue": 0,
+        "maxValue": "age_at_enrollment"
+    }
+}
+```
+
+### Computed Values
+
+```json
+{
+    "ui": {
+        "inputType": "number",
+        "readOnly": true
+    },
+    "compute": [
+        {
+            "variableName": "bmi",
+            "jsExpression": "weight / (height * height)"
+        }
+    ]
+}
+```
+
+## Best Practices
+
+1. **Choose Appropriate Types**: Use the most specific input type for better UX
+2. **Set Constraints**: Always define min/max values for numeric inputs
+3. **Provide Help Text**: Use `description` field for instructions
+4. **Consider Mobile**: Some input types work better on mobile devices
+5. **Validate Early**: Use appropriate validation patterns
+6. **Internationalize**: Provide translations for all user-facing text
+
+## See Also
+
+- [Schema Specification](schema-spec.md)
+- [Create Items Tutorial](../tutorials/create-new-items.md)
+- [Validation Guide](../how-to/validation.md)
\ No newline at end of file
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 000000000..de504019b
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,55 @@
+# Reference Documentation
+
+Complete technical specifications and API documentation for ReproSchema.
+
+## 📖 Available References
+
+### Schema Specifications
+- **[Field Types](field-types.md)** - Complete field types and response options reference
+- **[Schema Specification](../schema/schema.md)** - Complete ReproSchema specification
+- **[Assessment Library](../library.md)** - Available questionnaires and instruments
+
+### API Documentation
+- **[Python API Reference](api-reference.md)** - Complete Python API documentation
+
+### Coming Soon
+- **CLI Reference** - Command-line tool documentation
+- **Properties Reference** - Complete property definitions
+
+## 🔍 Quick Links
+
+### Common Field Types
+- `text` - Single line text input
+- `multitext` - Multi-line text input
+- `select` - Dropdown selection
+- `radio` - Radio button selection
+- `slider` - Numeric slider
+- `date` - Date picker
+- `time` - Time picker
+- `audioRecord` - Audio recording
+
+### Key Properties
+- `@id` - Unique identifier
+- `@type` - Schema type
+- `prefLabel` - Display label
+- `description` - Help text
+- `isAbout` - Links items to activities
+- `order` - Display sequence
+- `isVis` - Visibility conditions
+
+## 📚 How to Use This Reference
+
+- **Look up specific details** when implementing
+- **Find complete lists** of options and properties
+- **Check exact syntax** and requirements
+- **See examples** of each feature
+
+## 🔗 Related Sections
+
+- **[Tutorials](../tutorials/index.md)** - Learn ReproSchema step-by-step
+- **[How-To Guides](../how-to/index.md)** - Accomplish specific tasks
+- **[Explanation](../explanation/index.md)** - Understand the concepts
+
+## 🚧 Expanding Coverage
+
+We're working on comprehensive reference documentation. Need something specific? [Open an issue](https://github.com/ReproNim/reproschema/issues)!
\ No newline at end of file
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 000000000..01df09764
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,51 @@
+# Tutorials
+
+Welcome to the ReproSchema tutorials! These step-by-step guides will teach you how to create and work with ReproSchema from the ground up.
+
+## 🎯 Learning Path
+
+Our tutorials are designed to be followed in order, with each building on the previous:
+
+1. **[Getting Started with ReproSchema](using-reproschema.md)** - Set up your environment and understand the basics
+2. **[Create Your First Protocol](create-new-protocol.md)** - Build a complete study protocol from scratch
+3. **[Create Your First Activity](create-new-activity.md)** - Design questionnaires and assessments
+4. **[Add Items to Activities](create-new-items.md)** - Create individual questions and response types
+5. **[Finalize Your Protocol](finalizing-the-protocol.md)** - Polish and prepare for deployment
+6. **[Translate Your Assessments](translating-an-activity.md)** - Add multilingual support
+
+## 📚 What You'll Learn
+
+By completing these tutorials, you will:
+
+- ✅ Understand the core concepts of ReproSchema (protocols, activities, items)
+- ✅ Create a working protocol with multiple activities
+- ✅ Design various types of questions and response formats
+- ✅ Validate and test your schemas
+- ✅ Deploy your protocol for data collection
+
+## 🚀 Before You Begin
+
+Make sure you have:
+
+- Basic knowledge of JSON format
+- A text editor or IDE
+- Python installed (for validation tools)
+- Git (optional but recommended)
+
+## 💡 Tutorial Philosophy
+
+Our tutorials follow these principles:
+
+- **Learn by Doing**: Each tutorial results in working code
+- **Progressive Complexity**: Start simple, add features gradually
+- **Real-World Examples**: Based on actual research protocols
+- **Complete Understanding**: Explain not just "how" but "why"
+
+## 🆘 Getting Help
+
+- If something isn't clear, check our [FAQ](../FAQ.md)
+- For quick task references, see our [How-To Guides](../how-to/index.md)
+- For technical details, consult the [Reference](../reference/index.md)
+- Join our [community chat](https://mattermost.brainhack.org/brainhack/channels/repronim-reproschema)
+
+Ready to start? Begin with [Getting Started with ReproSchema](using-reproschema.md) →
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 3c1628d2e..532601d3d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -38,30 +38,54 @@ theme:
 nav:
   - Welcome: "index.md"
   - Introduction: "introduction.md"
-  - Project structure: "project-structure.md"
-  - Schema:
-      - Schema overview: "schema/schema.md"
-      - Schema documentation: "schema/doc-linkml-autogen/index.md"
-      - Schema diagram: schema/erdiagram-autogen.md
+  
+  # Learning Path
+  - Tutorials:
+      - Overview: "tutorials/index.md"
+      - Getting Started: "tutorials/using-reproschema.md"
+      - Create a Protocol: "tutorials/create-new-protocol.md"
+      - Create an Activity: "tutorials/create-new-activity.md"
+      - Create Items: "tutorials/create-new-items.md"
+      - Finalize Protocol: "tutorials/finalizing-the-protocol.md"
+      - Add Translations: "tutorials/translating-an-activity.md"
+  
+  # Task Guides
+  - How-To Guides:
+      - Overview: "how-to/index.md"
+      - Create Protocol from Scratch: "how-to/create-protocol.md"
+      - Use Cookiecutter Template: "how-to/use-cookiecutter.md"
+      - Use Library Assessments: "how-to/use-library-assessments.md"
+      - Add Translations: "how-to/add-translations.md"
+      - Validate Schemas: "how-to/validation.md"
+      - Visualize in UI: "how-to/visualize.md"
+      - Deploy Protocol: "how-to/deploy-protocol.md"
+  
+  # Understanding
+  - Explanation:
+      - Overview: "explanation/index.md"
+      - Core Concepts: "explanation/core-concepts.md"
+      - JSON-LD Basics: "explanation/json-ld-basics.md"
+      - Project Structure: "project-structure.md"
+  
+  # Technical Reference
+  - Reference:
+      - Overview: "reference/index.md"
+      - Field Types: "reference/field-types.md"
+      - Python API: "reference/api-reference.md"
+      - Schema Specification: "schema/schema.md"
+      - Schema Documentation: "schema/doc-linkml-autogen/index.md"
+      - Schema Diagram: "schema/erdiagram-autogen.md"
+      - Assessment Library: "library.md"
+  
+  # Legacy User Guide (being migrated)
   - User Guide:
-      - Create a research protocol: "user-guide/create-new-protocol.md"
-      - Adopt assessments from the library: "user-guide/adopt-assessments.md"
-      - Create new assessments for a protocol: "user-guide/create-new-assess.md"
-      - Add a feedback section: "user-guide/setup-feedback.md"
-      - Finalize the protocol: "user-guide/finalize-protocol.md"
+      - Create Protocol (Cookiecutter): "user-guide/create-new-protocol.md"
+      - Adopt from Library: "user-guide/adopt-assessments.md"
+      - Create Assessments: "user-guide/create-new-assess.md"
+      - Add Feedback: "user-guide/setup-feedback.md"
+      - Finalize Protocol: "user-guide/finalize-protocol.md"
       - Toolkit: "user-guide/tools.md"
-  - Tutorial:
-      - Intro: "tutorials/using-reproschema.md"
-      - Create a protocol: "tutorials/create-new-protocol.md"
-      - Create a new activity: "tutorials/create-new-activity.md"
-      - Create new items: "tutorials/create-new-items.md"
-      - Finalize the protocol: "tutorials/finalizing-the-protocol.md"
-      - Translate a questionnaire: "tutorials/translating-an-activity.md"
-      - Demographic information : "tutorials/collecting-demographics-information.md"
-  - How to guides:
-      - Validation: "how-to/validation.md"
-      - Visualize: "how-to/visualize.md"
-
+  
   - FAQ: "FAQ.md"
   - Contributing: "CONTRIBUTING.md"