aesthetic.computer
Monorepo for Aesthetic.Computer
aesthetic.computer
1# Aesthetic Computer Documentation TODO
2
3*Last updated: September 16, 2025*
4
5## 🎯 Current Focus: Documentation System Setup
6
7### Phase 1: Infrastructure Setup
8- [ ] **Reorganize reference folder structure**
9 - [x] Create main README.md with system overview
10 - [x] Create TODO.md for tracking work
11 - [ ] Create organized folder structure (api/, kidlisp/, pieces/, system/, tools/)
12 - [ ] Move existing Ableton docs to ableton/ subfolder
13 - [ ] Set up templates for consistent documentation
14
15### Phase 2: API Documentation Analysis
16- [ ] **Dynamic API Surface Analysis**
17 - [ ] Create mock BIOS system for testing disk.mjs API
18 - [ ] Build tool to automatically discover all exported functions from disk.mjs
19 - [ ] Map function signatures, parameters, and return types
20 - [ ] Cross-reference with docs.js manual documentation
21 - [ ] Generate API coverage report showing documented vs undocumented functions
22
23- [ ] **JavaScript API Reference**
24 - [ ] Extract and document all graphics functions (wipe, ink, box, circle, etc.)
25 - [ ] Document input handling functions (pointer, keyboard, touch)
26 - [ ] Document audio/sound system API
27 - [ ] Document networking/socket functions
28 - [ ] Document storage/session functions
29 - [ ] Document math/utility functions
30 - [ ] Create examples for each API category
31
32### Phase 3: KidLisp Documentation
33- [ ] **Language Reference**
34 - [ ] Extract LLM API spec from kidlisp.mjs into readable format
35 - [ ] Create comprehensive syntax guide
36 - [ ] Document all built-in functions with examples
37 - [ ] Create tutorial progression from basic to advanced
38 - [ ] Document integration with JavaScript API
39
40- [ ] **KidLisp Function Catalog**
41 - [ ] Graphics functions (wipe, ink, line, box, circle, tri, etc.)
42 - [ ] Animation functions (wiggle, timing expressions)
43 - [ ] Math operations (+, -, *, /, comparisons)
44 - [ ] Variable and function definition (def, later)
45 - [ ] Control flow and logic
46 - [ ] Image/media functions (paste, stamp)
47
48### Phase 4: Piece Documentation System
49- [ ] **Piece Structure Documentation**
50 - [ ] Document piece lifecycle (boot, paint, act, sim, beat, leave)
51 - [ ] Explain piece metadata and configuration
52 - [ ] Document export patterns and conventions
53 - [ ] Create piece template examples
54
55- [ ] **Piece Catalog System**
56 - [ ] Tool to analyze existing pieces for documentation
57 - [ ] Generate piece index with descriptions and features
58 - [ ] Cross-reference pieces with API usage
59 - [ ] Create searchable piece database
60
61### Phase 5: Development Tools Integration
62- [ ] **CLI Documentation Explorer**
63 - [ ] Design command-line interface for browsing docs
64 - [ ] Integration with existing kidlisp-tools
65 - [ ] Search functionality across all documentation
66 - [ ] Examples and code snippet browsing
67
68- [ ] **Emacs Integration**
69 - [ ] Create 'docs' tab configuration for Emacs
70 - [ ] Key bindings for quick documentation lookup
71 - [ ] Integration with AC development workflow
72 - [ ] Live documentation updates
73
74### Phase 6: Testing and Validation
75- [ ] **Documentation Test Suite**
76 - [ ] Automated testing of code examples in documentation
77 - [ ] Validation that API documentation matches implementation
78 - [ ] Link checking for all documentation references
79 - [ ] Style and consistency checking
80
81- [ ] **Coverage Analysis**
82 - [ ] Generate reports on documentation coverage
83 - [ ] Identify undocumented API functions
84 - [ ] Track documentation debt and technical writing needs
85 - [ ] Performance metrics for documentation updates
86
87## 🔧 Technical Implementation Notes
88
89### API Analysis Tools Needed
901. **Mock BIOS Creator**: Simulate AC environment for testing disk.mjs
912. **Function Extractor**: Parse disk.mjs to find all exported functions
923. **Signature Analyzer**: Determine function parameters and types
934. **Coverage Mapper**: Compare actual API vs documented API
945. **Example Validator**: Test all code examples in documentation
95
96### Documentation Architecture
97- **Markdown-based**: Easy to edit, version control, and integrate
98- **Modular structure**: Separate concerns (API, language, pieces, system)
99- **Cross-references**: Links between different documentation sections
100- **Searchable**: CLI and web-based search capabilities
101- **Executable examples**: Code snippets that can be tested automatically
102
103### Integration Points
104- **docs.js**: Web endpoint for API documentation
105- **prompt.mjs**: Command discovery and piece launching
106- **kidlisp-tools**: CLI development tools
107- **Emacs config**: Editor integration for documentation browsing
108- **VS Code extension**: IDE integration for development
109
110## 📈 Success Metrics
111
112- **API Coverage**: % of disk.mjs functions documented
113- **Example Coverage**: % of documented functions with working examples
114- **KidLisp Coverage**: % of language features documented with examples
115- **Piece Coverage**: % of existing pieces with documentation
116- **Tool Integration**: Functional CLI explorer and Emacs integration
117- **Developer Productivity**: Reduced time to find API information
118
119## 🎨 Future Enhancements
120
121- **Interactive Documentation**: Live examples that run in browser
122- **Video Tutorials**: Recorded demonstrations of concepts
123- **Community Contributions**: System for user-contributed documentation
124- **Auto-generation**: Tools that update docs from code comments
125- **Multilingual Support**: Documentation in multiple languages