tommcd · tommcd · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025 · Nov 19, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,52 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ master, main ]
+  # Allow manual trigger
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.kiro/specs/doctk-core-integration/tasks.md b/.kiro/specs/doctk-core-integration/tasks.md
@@ -346,28 +346,26 @@ This implementation plan breaks down the core integration layer and execution ca
     - All tests passing ✅
     - _Requirements: 18_
 
-- [ ] 12. Implement security features
+- [ ]* 12. ~~Implement security features~~ **Not Applicable for Local Tool**
 
-  - [ ] 12.1 Add input validation
+  **Rationale**: This task was originally designed for web services or multi-tenant systems. However, doctk is a **local CLI tool** that users run on their own machines with their own documents. The proposed "security" features don't provide value in this context:
 
-    - Implement InputValidator class
-    - Validate operation parameters against schema
-    - Use JSON Schema for validation
-    - _Requirements: 20_
-
-  - [ ] 12.2 Implement sandboxed execution
+  - **Input validation**: Already handled by parser (syntax errors) and Python type system
+  - **Sandboxing**: Would restrict legitimate use cases; users can run any code locally anyway
+  - **Operation whitelisting**: No reason to restrict what users can do with their own documents
+  - **Execution timeouts**: User can always Ctrl+C; not a security concern
 
-    - Create SandboxedExecutor class
-    - Limit execution time
-    - Validate operations before execution
-    - _Requirements: 12, 13, 14_
+  **What we already have** (sufficient for local tool):
+  - ✅ Parser validation catches syntax errors
+  - ✅ Python type hints provide type safety
+  - ✅ Error handling with graceful failures
+  - ✅ Clear error messages with line/column positions
 
-  - [ ] 12.3 Write security tests
+  **Decision**: Mark as optional (not required for v0.1.0). May revisit if doctk is ever deployed as a web service.
 
-    - Test input validation
-    - Test execution timeouts
-    - Test operation whitelisting
-    - _Requirements: 12, 13, 14_
+  - [ ]* 12.1 ~~Add input validation~~ (Not applicable - see above)
+  - [ ]* 12.2 ~~Implement sandboxed execution~~ (Not applicable - see above)
+  - [ ]* 12.3 ~~Write security tests~~ (Not applicable - see above)
 
 - [x] 13. Integration with doctk core API
 

diff --git a/.kiro/specs/release-preparation/tasks.md b/.kiro/specs/release-preparation/tasks.md
@@ -0,0 +1,227 @@
+# Release Preparation Checklist
+
+This checklist captures the remaining tasks to prepare doctk for public v0.1.0 release.
+
+## Current Status
+
+**MVP Development**: ✅ Complete (749 tests passing)
+- All three specs (core-integration, vscode-extension, language-server) are 100% done
+- Documentation updated and accurate
+- GitHub Pages deployment configured
+
+**Release Status**: 🚧 Pre-Release (distribution not yet decided)
+
+---
+
+## Decision Points
+
+### 1. Distribution Strategy
+
+- [ ] **Decide: Publish to PyPI or keep local-only?**
+
+  **Options:**
+  - **A. PyPI + Marketplace** (full public release)
+    - Pros: Easy installation (`pip install doctk`), wide distribution
+    - Cons: Need to maintain package, handle support
+  - **B. Local-only + GitHub Releases** (developer-focused)
+    - Pros: Simple, no PyPI maintenance
+    - Cons: Manual installation required
+
+  **Action**: Discuss and decide which approach fits project goals
+
+- [ ] **If PyPI: Check name availability**
+  - Visit https://pypi.org/project/doctk/ to verify name is available
+  - If taken, decide on alternative name (e.g., `python-doctk`, `doc-toolkit`)
+
+- [ ] **If PyPI: Decide on VS Code Marketplace**
+  - Marketplace typically expects Python dependency on PyPI
+  - Can still distribute via `.vsix` if not publishing to marketplace
+
+---
+
+## Branding & Assets
+
+- [ ] **Design logo/icon**
+  - Create icon.png for VS Code extension (128x128px recommended)
+  - Consider creating variations for different contexts
+  - Tools: Figma, Canva, or AI generation (DALL-E, Midjourney)
+
+- [ ] **Create social media preview image** (optional)
+  - For GitHub repository social preview
+  - Recommended size: 1280x640px
+
+- [ ] **Update extension branding**
+  - Add icon to `extensions/doctk-outliner/icon.png`
+  - Update `package.json` with icon path
+  - Test appearance in VS Code marketplace preview
+
+---
+
+## Documentation for End Users
+
+- [ ] **Write user-focused installation guide**
+  - Separate from developer setup
+  - Clear prerequisites (Python 3.12+, VS Code)
+  - Step-by-step instructions with screenshots
+
+- [ ] **Create quick start tutorial**
+  - 5-minute walkthrough
+  - Simple real-world example
+  - Video or animated GIFs (optional but recommended)
+
+- [ ] **Document common workflows**
+  - REPL usage examples
+  - Script file execution patterns
+  - VS Code extension usage
+
+- [ ] **Add troubleshooting guide**
+  - Common installation issues
+  - VS Code extension activation problems
+  - LSP server connection issues
+
+---
+
+## Packaging (If Publishing)
+
+### Python Package (PyPI)
+
+- [ ] **Verify package metadata**
+  - Check `pyproject.toml` completeness
+  - Add classifiers for PyPI
+  - Verify dependencies are correct
+
+- [ ] **Test local build**
+  - Run `uv build` or `python -m build`
+  - Verify dist/ contains .whl and .tar.gz
+
+- [ ] **Test installation from built package**
+  - Create fresh virtual environment
+  - Install from local .whl
+  - Verify CLI works: `doctk --help`
+
+- [ ] **Upload to TestPyPI first**
+  - Register at https://test.pypi.org
+  - Upload: `twine upload --repository testpypi dist/*`
+  - Test install: `pip install --index-url https://test.pypi.org/simple/ doctk`
+
+- [ ] **Upload to PyPI**
+  - Only after TestPyPI validation
+  - Upload: `twine upload dist/*`
+  - Verify at https://pypi.org/project/doctk/
+
+### VS Code Extension (Marketplace)
+
+- [ ] **Set up Azure DevOps account**
+  - Required for VS Code marketplace publishing
+  - Create organization at https://dev.azure.com
+
+- [ ] **Generate Personal Access Token**
+  - Needed for `vsce` publishing
+  - Follow: https://code.visualstudio.com/api/working-with-extensions/publishing-extension
+
+- [ ] **Update extension for marketplace**
+  - Add publisher name to `package.json`
+  - Add icon, categories, keywords
+  - Add gallery banner color/theme
+
+- [ ] **Publish to marketplace**
+  - Run `vsce publish`
+  - Wait for review/approval
+  - Monitor marketplace listing
+
+---
+
+## GitHub Release
+
+- [ ] **Write changelog**
+  - Summarize all features implemented
+  - List breaking changes (if any)
+  - Acknowledge contributors
+
+- [ ] **Create GitHub release**
+  - Tag: `v0.1.0`
+  - Title: "v0.1.0 - Initial Release"
+  - Description: Use changelog content
+  - Attach: `.vsix` file as release asset
+
+- [ ] **Update documentation links**
+  - Ensure installation instructions point to release
+  - Update badges if needed
+
+---
+
+## Testing on Clean Machine
+
+- [ ] **Test PyPI installation** (if published)
+  - Fresh VM or container
+  - `pip install doctk`
+  - Run basic commands
+
+- [ ] **Test VS Code extension installation**
+  - Fresh VS Code instance
+  - Install from `.vsix` or marketplace
+  - Verify all features work
+
+- [ ] **Test on Windows** (if supporting)
+  - Installation process
+  - CLI commands
+  - VS Code extension
+
+- [ ] **Test on macOS** (if supporting)
+  - Installation process
+  - CLI commands
+  - VS Code extension
+
+---
+
+## Announcement & Promotion (Optional)
+
+- [ ] **Write announcement post**
+  - What is doctk
+  - Key features
+  - Installation instructions
+  - Link to documentation
+
+- [ ] **Share on platforms**
+  - Reddit: r/Python, r/programming
+  - Hacker News
+  - Dev.to blog post
+  - Twitter/X
+  - LinkedIn
+
+- [ ] **Create demo video** (optional)
+  - Screen recording showing key features
+  - Upload to YouTube
+  - Embed in README
+
+---
+
+## Success Criteria
+
+Before calling v0.1.0 "released", ensure:
+
+- ✅ All MVP features implemented and tested
+- ✅ Documentation complete and accurate
+- ✅ Installation works on clean machine
+- ✅ Distribution method decided and implemented
+- ✅ GitHub release created with assets
+- ✅ Users can actually install and use the project
+
+---
+
+## Notes
+
+- **Current state**: MVP is complete, but distribution strategy not decided
+- **Priority**: Decide PyPI vs local-only first, as it affects all other tasks
+- **Timeline**: No rush - take time to get branding and documentation right
+- **Philosophy**: "Release when ready" - quality over speed
+
+---
+
+## Future Considerations (Post-Release)
+
+- CI/CD for automated releases
+- Automated changelog generation
+- Release notes automation
+- Marketplace auto-updates
+- Version bump automation