Skip to content

Commit 62d3426

Browse files
NiloCKNiloCK
authored
Update Docs (#812)
- **[docs] add docs for studio-mode in static courses** - **add inline cli docs for studio cmd** - **add instructions for pack, unpack, studio cmds** - **add: running thoughts on quilt.json spec** - **update readme**
2 parents adc0e10 + db19459 commit 62d3426

File tree

6 files changed

+625
-49
lines changed

6 files changed

+625
-49
lines changed

‎agent/quiltDotJSON/a.1.assessment.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Assessment: skuilder.json Specification
2+
3+
## Context
4+
5+
The user wants to create a `skuilder.json` specification to formally define what constitutes a Skuilder project, similar to how `package.json` defines an npm package.
6+
7+
## Current Project Analysis
8+
9+
### Existing Structure
10+
11+
The Vue Skuilder project currently uses `skuilder.config.json` with a basic structure:
12+
13+
```json
14+
{
15+
"title": "Project Name",
16+
"dataLayerType": "static" | "couch",
17+
"course": "courseId-uuid",
18+
"couchdbUrl": "http://localhost:5984",
19+
"theme": {...}
20+
}
21+
```
22+
23+
### Identified Gaps
24+
25+
1. **Missing project metadata**: no version, author, description
26+
2. **Fragmented configuration**: parameters scattered across different files
27+
3. **Lack of validation**: no JSON schema for validation
28+
4. **No dependency management**: Skuilder dependencies not specified
29+
5. **Incomplete deployment configuration**: limited options
30+
31+
## Proposed Options
32+
33+
### Option 1: Minimal Extension
34+
- Extend existing `skuilder.config.json`
35+
- Add basic metadata and validation
36+
- Minimal impact on existing projects
37+
38+
**Advantages:**
39+
- Simple migration
40+
- Backward compatibility
41+
- Minimal changes
42+
43+
**Disadvantages:**
44+
- Limited functionality
45+
- No complete standardization
46+
47+
### Option 2: Complete Specification
48+
- Create a new complete `skuilder.json` specification
49+
- Include all aspects: metadata, configuration, deployment
50+
- Complete JSON schema with validation
51+
52+
**Advantages:**
53+
- Complete standardization
54+
- Maximum flexibility
55+
- Advanced tooling possible
56+
57+
**Disadvantages:**
58+
- Migration required for existing projects
59+
- Increased complexity
60+
61+
### Option 3: Hybrid Approach
62+
- Maintain `skuilder.config.json` for compatibility
63+
- Introduce optional `skuilder.json` with advanced features
64+
- Progressive migration
65+
66+
**Advantages:**
67+
- Smooth transition
68+
- User choice
69+
- Controlled evolution
70+
71+
**Disadvantages:**
72+
- Two formats to maintain
73+
- Potential confusion
74+
75+
## Unique Features to Specify
76+
77+
### 1. Course System
78+
- Supported question types
79+
- Learning data structure
80+
- Educational metadata
81+
82+
### 2. Dual Data Layer
83+
- Static vs dynamic configuration
84+
- CouchDB parameters
85+
- Synchronization
86+
87+
### 3. Educational Themes
88+
- Business presets
89+
- Visual customization
90+
- Dark/light modes
91+
92+
### 4. Studio Tools
93+
- Edit mode configuration
94+
- Development parameters
95+
- Pack/unpack workflow
96+
97+
### 5. Plugin Architecture
98+
- Extensible question types
99+
- Learning domains
100+
- Custom components
101+
102+
## Key Specification Elements
103+
104+
### Proposed Structure
105+
106+
```json
107+
{
108+
"$schema": "https://schema.skuilder.org/project/v1.0.json",
109+
"version": "1.0",
110+
"project": {
111+
"name": "string",
112+
"title": "string",
113+
"description": "string",
114+
"version": "string",
115+
"author": "string",
116+
"license": "string"
117+
},
118+
"skuilder": {
119+
"version": "string",
120+
"type": "standalone" | "platform",
121+
"dataLayer": {
122+
"type": "static" | "couch",
123+
"static": {...},
124+
"couch": {...}
125+
}
126+
},
127+
"ui": {
128+
"theme": {...},
129+
"branding": {...},
130+
"features": {...}
131+
},
132+
"courses": {
133+
"registry": "string",
134+
"categories": ["string"],
135+
"questionTypes": ["string"],
136+
"dataShapes": ["string"]
137+
},
138+
"build": {...},
139+
"development": {...},
140+
"deployment": {...},
141+
"scripts": {...}
142+
}
143+
```
144+
145+
### Benefits of this Approach
146+
147+
1. **Standardization**: Consistent structure for all projects
148+
2. **Validation**: JSON schema for automatic validation
149+
3. **Tooling**: Auto-completion and validation in editors
150+
4. **Flexibility**: Support for multiple configurations
151+
5. **Scalability**: Versioning and automatic migration
152+
153+
## Recommendation
154+
155+
**I recommend Option 2: Complete Specification** for the following reasons:
156+
157+
1. **Necessary standardization**: The project is mature enough to benefit from a complete specification
158+
2. **Advanced tooling**: A complete specification enables more sophisticated CLI tools
159+
3. **Ecosystem**: Facilitates template creation and integration with other tools
160+
4. **Documentation**: The specification serves as living documentation of the framework
161+
5. **Manageable migration**: The CLI can automate migration from `skuilder.config.json`
162+
163+
### Recommended Next Steps
164+
165+
1. **Define complete JSON schema** with validation
166+
2. **Create templates** for different project types
167+
3. **Implement migration** from current format
168+
4. **Develop tooling** (validation, auto-completion)
169+
5. **Document** the specification with examples
170+
171+
This approach will position Vue Skuilder as a professional educational framework with clear standards and excellent developer experience.

‎agent/quiltDotJSON/a.2.quilt-dependency-assessment.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Assessment: Quilt-Based Content Dependency System
2+
3+
## Context
4+
5+
The goal is to create a `quilt.json` specification that enables educational content sharing and dependency management. This allows courses to depend on and reuse content from other courses without duplication, while maintaining clear interfaces for content consumption.
6+
7+
## Use Case Example
8+
9+
A Doomsday algorithm course needs modular arithmetic (mod 7) content. Instead of duplicating this content, it should be able to:
10+
- Declare a dependency on a `math` quilt
11+
- Specify it only needs the `mod7` subset
12+
- Let the math course determine how to best serve that need
13+
14+
## Core Architecture
15+
16+
### ContentSource Interface Analysis
17+
18+
From `@packages/db/src/core/interfaces/contentSource.ts`, the key interface is:
19+
20+
```typescript
21+
export interface StudyContentSource {
22+
getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
23+
getNewCards(n?: number): Promise<StudySessionNewItem[]>;
24+
}
25+
```
26+
27+
### Proposed Quilt Structure
28+
29+
```json
30+
{
31+
"serviceDef": {
32+
"name": "ContentSource",
33+
"version": "1.0",
34+
"adapter": "StaticDataLayerProvider"
35+
},
36+
"metadata": {
37+
"id": "math-core-v1",
38+
"name": "Core Mathematics",
39+
"version": "1.0.0",
40+
"description": "Foundational math concepts",
41+
"author": "...",
42+
"license": "..."
43+
},
44+
"provides": {
45+
"skills": [
46+
{
47+
"id": "modular-arithmetic",
48+
"name": "Modular Arithmetic",
49+
"subsets": ["mod7", "mod12", "general-modular"]
50+
},
51+
{
52+
"id": "basic-algebra",
53+
"name": "Basic Algebra",
54+
"subsets": ["linear-equations", "quadratic-equations"]
55+
}
56+
]
57+
},
58+
"dependencies": {
59+
"requires": [
60+
{
61+
"quilt": "arithmetic-basics",
62+
"version": "^1.0.0",
63+
"skills": ["addition", "subtraction", "multiplication"]
64+
}
65+
],
66+
"suggests": [
67+
{
68+
"quilt": "number-theory",
69+
"version": "^2.0.0",
70+
"skills": ["prime-factorization"],
71+
"reason": "Enhanced explanations for modular arithmetic"
72+
}
73+
]
74+
},
75+
"content": {
76+
"source": {
77+
"type": "static",
78+
"path": "./courses/math-core"
79+
},
80+
"index": {
81+
"skills": {
82+
"modular-arithmetic": {
83+
"cards": ["mod-intro-001", "mod7-examples-001", "mod7-practice-001"],
84+
"prerequisites": ["multiplication", "division-remainder"],
85+
"difficulty": "intermediate"
86+
}
87+
}
88+
}
89+
}
90+
}
91+
```
92+
93+
## Key Components
94+
95+
### 1. Service Definition
96+
- **Interface compatibility**: Which ContentSource version this quilt implements
97+
- **Adapter specification**: How the quilt's data gets consumed (StaticDataLayerProvider, CouchDataLayerProvider, etc.)
98+
99+
### 2. Skill Taxonomy
100+
- **Provides**: What educational skills/concepts this quilt offers
101+
- **Subsets**: Granular divisions of skills for precise dependency management
102+
- **Prerequisites**: Skills needed before accessing this content
103+
104+
### 3. Dependency Management
105+
- **Requires**: Hard dependencies on other quilts
106+
- **Suggests**: Soft dependencies that enhance the experience
107+
- **Version constraints**: Semantic versioning for compatibility
108+
109+
### 4. Content Mapping
110+
- **Source location**: Where the actual content lives
111+
- **Skill indexing**: Maps skills to specific cards/content
112+
- **Metadata**: Difficulty, prerequisites, learning objectives
113+
114+
## Implementation Considerations
115+
116+
### Content Discovery
117+
```typescript
118+
interface QuiltRegistry {
119+
findQuiltsBySkill(skill: string): Promise<QuiltDescriptor[]>;
120+
resolveQuilt(id: string, version: string): Promise<QuiltInstance>;
121+
validateDependencies(quilt: QuiltDescriptor): Promise<ValidationResult>;
122+
}
123+
```
124+
125+
### Dependency Resolution
126+
```typescript
127+
interface DependencyResolver {
128+
resolveSkillChain(requiredSkills: string[]): Promise<ContentPlan>;
129+
buildStudySession(plan: ContentPlan, user: UserDBInterface): Promise<StudyContentSource>;
130+
}
131+
```
132+
133+
### Content Filtering
134+
```typescript
135+
interface ContentFilter {
136+
filterBySkills(source: StudyContentSource, skills: string[]): StudyContentSource;
137+
filterByDifficulty(source: StudyContentSource, level: DifficultyLevel): StudyContentSource;
138+
filterByPrerequisites(source: StudyContentSource, userSkills: string[]): StudyContentSource;
139+
}
140+
```
141+
142+
## Benefits
143+
144+
### 1. Content Reusability
145+
- Courses can share foundational content without duplication
146+
- Specialized courses can focus on their unique value-add
147+
- Consistent presentation of core concepts across the ecosystem
148+
149+
### 2. Modular Architecture
150+
- Clean separation of concerns
151+
- Easier maintenance and updates
152+
- Scalable content ecosystem
153+
154+
### 3. Adaptive Learning
155+
- Precise skill targeting
156+
- Prerequisite enforcement
157+
- Intelligent content recommendations
158+
159+
### 4. Ecosystem Growth
160+
- Lower barrier to creating specialized courses
161+
- Encourages contribution to shared knowledge bases
162+
- Natural evolution toward comprehensive curriculum coverage
163+
164+
## Challenges
165+
166+
### 1. Skill Taxonomy Standardization
167+
- Need agreed-upon skill identifiers
168+
- Difficulty levels must be consistent
169+
- Prerequisite relationships need validation
170+
171+
### 2. Content Quality Assurance
172+
- Ensure dependencies provide quality content
173+
- Version compatibility across skill updates
174+
- Consistent learning experience across quilts
175+
176+
### 3. Performance Implications
177+
- Dependency resolution complexity
178+
- Content loading from multiple sources
179+
- Caching strategies for composed content
180+
181+
## Recommendation
182+
183+
This quilt-based approach addresses a real architectural need in educational content systems. It enables:
184+
185+
1. **Composable curricula** where courses can be built from reusable skill-based components
186+
2. **Efficient content creation** by leveraging existing, well-tested educational content
187+
3. **Consistent learning experiences** through standardized skill taxonomies
188+
4. **Scalable content ecosystems** that grow organically
189+
190+
The proposed structure balances flexibility with standardization, providing clear interfaces while allowing for diverse content sources and presentation styles.
191+
192+
### Next Steps
193+
194+
1. **Define core skill taxonomy** for foundational subjects
195+
2. **Implement dependency resolver** in the CLI
196+
3. **Create quilt registry** for content discovery
197+
4. **Build content filtering system** for subset selection
198+
5. **Develop migration tools** to convert existing courses to quilts
199+
200+
This approach transforms Vue Skuilder from a course platform into a composable educational content ecosystem.

0 commit comments

Comments
 (0)