feat: update versioning and release checklist for alpha development

CHANGELOG.md

@@ -4,8 +4,25 @@ All notable changes to Astrolabe will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+**Note**: Astrolabe is currently in alpha (pre-1.0) development. Version numbers below 1.0.0 indicate active development status. A stable 1.0 release will occur after public launch and thorough testing.
+
 ---
-## [1.1.0] - 2025-11-17
+## [Unreleased]
+
+### Added
+- (New features currently in development)
+
+### Fixed
+- (Bugfixes will be listed here)
+
+### Changed
+- (Improvements and refinements will be listed here)
+
+### Removed
+- (Removed features will be listed here)
+
+---
+## [0.2.0] - 2025-11-17
 
 ### Added
 - **Visual Chart Builder**: Create Vega-Lite visualizations without writing JSON
@@ -20,12 +37,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - URL state support (`#datasets/dataset-123/build`)
   - Browser back/forward navigation integrated
   - Creates snippets with auto-generated names and dataset references
+- **Progressive Web App (PWA) Support**: Install Astrolabe as standalone app with offline functionality
+  - Service worker caches all application files and CDN dependencies
+  - Full offline access after initial load
+  - Install button in browser for desktop/mobile installation
+  - Runs in standalone window without browser chrome
+  - "Add to Home Screen" support on iOS/Android
+  - Automatic cache updates when app version changes
+  - Works seamlessly with existing IndexedDB and localStorage
 
-## [1.0.0] - 2025-10-15
+---
+## [0.1.0] - 2025-10-15
 
-### Initial Release
+### Added
 
-Complete feature set for lightweight Vega-Lite snippet management.
+Initial alpha release with complete feature set for lightweight Vega-Lite snippet management.
 
 #### Core Features
 - Three-panel resizable layout with drag handles and panel memory
@@ -97,36 +123,13 @@ Complete feature set for lightweight Vega-Lite snippet management.
 
 ---
 
-## [Unreleased]
-
-### Added
-- **Progressive Web App (PWA) Support**: Install Astrolabe as standalone app with offline functionality
-  - Service worker caches all application files and CDN dependencies
-  - Full offline access after initial load
-  - Install button in browser for desktop/mobile installation
-  - Runs in standalone window without browser chrome
-  - "Add to Home Screen" support on iOS/Android
-  - Automatic cache updates when app version changes
-  - Works seamlessly with existing IndexedDB and localStorage
-
-### Fixed
-- (Bugfixes will be listed here)
-
-### Changed
-- (Improvements and refinements will be listed here)
-
-### Removed
-- (Removed features will be listed here)
-
----
-
 ## Release Notes
 
-### v1.0.0 - Feature-Complete MVP
+### Alpha Development Status
 
-Astrolabe v1.0 represents a complete, production-ready implementation of a browser-based Vega-Lite snippet manager. The application is fully functional with no known critical bugs.
+Astrolabe is currently in alpha (pre-1.0) development. The application is feature-complete and functional, but has not been publicly released or extensively tested across all browsers and platforms.
 
-**Development Timeline**: October 2024 - October 2025
+**Development Timeline**: October 2024 - November 2025
 
 **Key Accomplishments**:
 - Zero external dependencies (beyond CDN libraries)
@@ -149,26 +152,9 @@ Astrolabe v1.0 represents a complete, production-ready implementation of a brows
 
 ---
 
-## Upgrade Guide
+## Data Compatibility
 
-### From Pre-Release to v1.0
+All alpha versions maintain backward compatibility. Snippets (localStorage), datasets (IndexedDB), and settings persist across updates with no migration required.
-
-No migration required. All features are additive and backward-compatible with any data created during development.
-
-**Data Compatibility**:
-- Snippets in localStorage: No changes to schema
-- Datasets in IndexedDB: No changes to schema
-- Settings in localStorage: New settings added with defaults
-
-**New Settings** (automatically applied):
-- `editor.fontSize`: Default 14px
-- `editor.tabSize`: Default 2
-- `editor.minimap`: Default true
-- `editor.wordWrap`: Default 'on'
-- `editor.lineNumbers`: Default 'on'
-- `dateFormat`: Default 'smart'
-- `renderDebounceDelay`: Default 1500ms
-- `theme`: Default 'light'
 
 ---
 

CLAUDE.md

@@ -18,9 +18,9 @@ Instructions for Claude Code when working on this project.
 
 ## Current Status
 
-**Version**: 1.0.0 (Feature-complete MVP)
+**Version**: 0.3.0 (Alpha - pre-1.0 development)
 **Deployment**: Live at astrolabe-viz.com
-**Mode**: Maintenance and iterative improvements
+**Mode**: Alpha testing and iterative improvements
 
 ### Core Capabilities
 - Snippet management with draft/published workflow
@@ -56,6 +56,9 @@ When implementing changes:
 - Test thoroughly across different browsers when possible
 - Maintain backward compatibility with existing data
 
+### Release Process
+Astrolabe uses semantic versioning with alpha releases (`0.x.y`) until public launch. Each release requires version updates in four files: `config.js` (APP_VERSION), `sw.js` (CACHE_NAME), `CLAUDE.md`, and `CHANGELOG.md`. See `project-docs/release-checklist.md` for the complete workflow.
+
 ## Development Principles
 
 - **Lean**: No frameworks, no build step, minimal dependencies

index.html

@@ -33,6 +33,7 @@
         <div class="header-left">
             <img src="src/favicon.svg" class="header-icon" alt="Astrolabe">
             <span class="header-title">Astrolabe</span>
+            <span class="version-badge" id="app-version-badge">v0.3.0</span>
         </div>
         <div class="header-links">
             <span class="header-link" id="import-link" title="Import snippets and datasets">Import</span>

project-docs/release-checklist.md

@@ -0,0 +1,20 @@
+# Release Checklist
+
+## Version Update
+- [ ] Update `APP_VERSION` in `src/js/config.js`
+- [ ] Update `CACHE_NAME` in `sw.js`
+- [ ] Update version in `CLAUDE.md`
+- [ ] Update `CHANGELOG.md` with changes and date
+
+## Release
+- [ ] Commit: `git commit -m "chore: bump version to X.Y.Z"`
+- [ ] Tag: `git tag vX.Y.Z`
+- [ ] Push: `git push && git push --tags`
+
+## Verify
+- [ ] Test version displays in header
+- [ ] Test basic functionality
+
+## Version Numbering
+- **Alpha**: `0.x.y` (current)
+- **Stable**: `1.0.0+` (after public release)

src/js/app.js

@@ -19,6 +19,12 @@ if ('serviceWorker' in navigator) {
 }
 
 document.addEventListener('DOMContentLoaded', function () {
+    // Display app version in header
+    const versionBadge = document.getElementById('app-version-badge');
+    if (versionBadge && typeof APP_VERSION !== 'undefined') {
+        versionBadge.textContent = `v${APP_VERSION}`;
+    }
+
     // Initialize user settings
     initSettings();
 

src/js/config.js

@@ -1,3 +1,6 @@
+// Application version (update with each release)
+const APP_VERSION = '0.3.0';
+
 // Global variables and configuration
 let editor; // Global editor instance
 let renderTimeout; // For debouncing

src/styles.css

@@ -43,6 +43,8 @@ body { font-family: var(--font-main); height: 100vh; overflow: hidden; backgroun
 .header-left { display: flex; align-items: center; gap: 10px; }
 .header-icon { width: 24px; height: 24px; display: block; flex-shrink: 0; }
 .header-title { font-size: 14px; font-weight: bold; }
+.version-badge { font-size: 10px; padding: 2px 6px; background: var(--win-gray-dark); color: var(--bg-white); border-radius: 3px; font-weight: 500; }
+:root[data-theme="experimental"] .version-badge { background: var(--win-gray-darker); color: var(--text-secondary); }
 .header-links { display: flex; gap: 16px; }
 .header-link { font-size: 12px; text-decoration: underline; cursor: pointer; color: var(--text-primary); }
 .header-link:hover { background: var(--win-blue); color: var(--bg-white); }

sw.js

@@ -1,4 +1,5 @@
-const CACHE_NAME = 'astrolabe-v1.0.0';
+// IMPORTANT: Update this version with each release (must match APP_VERSION in config.js)
+const CACHE_NAME = 'astrolabe-v0.3.0';
 const URLS_TO_CACHE = [
   '/',
   '/index.html',