docs: comprehensive documentation reorganization and enhancement

.gitignore

@@ -15,3 +15,6 @@ docs/schema/erdiagram-autogen.md
 node_modules
 package-lock.json
 package.json
+
+# Internal documentation
+/internal/

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.

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!

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.