aboutsummaryrefslogtreecommitdiff
path: root/docs
Commit message (Collapse)AuthorAgeFilesLines
* docs(design): add gloss package design docCraig Jennings2026-04-291-0/+316
| | | | Captures the v1 design for the gloss Emacs package: layered five-module split, Wiktionary REST as the online source, side-buffer picker for ambiguous terms, libxml HTML strip, mtime-based cache invalidation. The implementation is a separate repo, but the design work happened in this tree, so the doc lives alongside the other design archives here.
* docs(design): add debug-profiling.el module brainstorm outputCraig Jennings2026-04-261-0/+203
| | | | | | | | | | Captures the agreed v1 shape for a new =debug-profiling.el= module: targeted slow-command investigation, two features ("profile next command" and "time region or sexp"), each split into pure helper plus interactive wrapper. Migrates the existing =profiler-*= bindings and =cj/benchmark-this-method= out of =config-utilities.el=. Stays on the existing =C-c d= debug umbrella prefix. Six approaches were considered: three conventional, plus three tail samples (macro-first, log-and-grep, treesit picker). Recommendation is the boring named-operation surface backed by a thin wrapper over the built-in =profiler.el= and =benchmark.el=. The other five options are recorded with reasons-rejected so a future reader can see what was weighed. Design covers architecture, data flow, error handling, testing approach, and observability. Two open questions are parked: default REPS for =cj/time--expr=, and whether to capture =cpu+mem= or just =cpu=. Both are fine to defer until v1 has been used on the queued org-capture target-building investigation. Implementation will run via =/start-work= against this design.
* feat(coverage): wire make coverage target + simplecov pipelineCraig Jennings2026-04-221-18/+20
| | | | | | | | | | | | | | | | Completes the coverage v1 pipeline by adding the Makefile target, the undercover driver script, the exclusion list, and the .gitignore entry. Uses simplecov JSON rather than LCOV as the collection format. The LCOV vs simplecov choice: Undercover's :merge-report t option only supports simplecov. Since the pipeline runs tests per-file (matching test-unit's isolation pattern) and accumulates coverage across runs, merge-report is required. LCOV is better-supported by external coverage viewers, but for a primarily interactive workflow the on-disk format is an internal detail. Other moves in this commit: - Renamed cj/--coverage-parse-lcov to cj/--coverage-parse-simplecov and rewrote its tests for the JSON schema. Same signature, same semantics (file to set of covered lines), different parser. - Renamed the backend protocol's :lcov-path key to :report-path, format-neutral and matching the renamed cj/--coverage-elisp-report-path function. - The coverage target deletes modules/*.elc before running so undercover can instrument the .el sources. Without this, byte-compiled versions shadow the instrumentation and only a handful of pre-loaded modules end up with coverage data. - Excluded tests/test-all-comp-errors.el from make coverage runs. That test byte-compiles every module, which fails under undercover's instrumentation. Excluded only from coverage. Normal make test still runs it. - Updated docs/design/coverage.org to reflect the simplecov pivot with a historical note on why we moved off LCOV. Verified end-to-end: make coverage produces .coverage/simplecov.json with 2717 of 4559 executable lines hit across 44 tracked modules.
* docs: add design docs for coverage and dev-setup-projectCraig Jennings2026-04-222-0/+318
| | | | | | | | | | Two new design docs for pending todo.org tickets. docs/design/coverage.org describes diff-aware coverage reporting with pluggable backends. Primary use case is pre-commit feedback on in-flight changes. LCOV is the shared output format across languages. docs/design/dev-setup-project.org describes an interactive helper that detects a project's shape and writes per-subdirectory .dir-locals.el files for the F4/F6/F7 dev block, with optional starter Makefile generation. Three-tier detection: existing Makefile, existing package.json or pyproject.toml scripts, or fall-back generation. Both tickets in todo.org reference their design docs via org file: links.
* chore: Move docs folder to .gitignoreCraig Jennings2025-11-068-5471/+0
| | | | | | | | | | | | | | | Removed docs/ from version control to keep session notes, personal workflows, and V2MOM documentation private. These files remain on disk but are no longer tracked by git. Files removed from tracking: - docs/NOTES.org (session history) - docs/EMACS-CONFIG-V2MOM.org (personal goals) - docs/SOMEDAY-MAYBE.org (research backlog) - docs/values-comparison.org - docs/workflows/*.org (workflow templates) The docs/ folder still exists locally but is now gitignored.
* feat: Add AssemblyAI transcription backend with speaker diarizationCraig Jennings2025-11-062-1306/+104
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Integrated AssemblyAI as the third transcription backend alongside OpenAI API and local-whisper, now set as the default due to superior speaker diarization capabilities (up to 50 speakers). New Features: - AssemblyAI backend with automatic speaker labeling - Backend switching UI via C-; T b (completing-read interface) - Universal speech model supporting 99 languages - API key management through auth-source/authinfo.gpg Implementation: - Created scripts/assemblyai-transcribe (upload → poll → format workflow) - Updated transcription-config.el with multi-backend support - Added cj/--get-assemblyai-api-key for secure credential retrieval - Refactored process environment handling from if to pcase - Added cj/transcription-switch-backend interactive command Testing: - Created test-transcription-config--transcription-script-path.el - 5 unit tests covering all 3 backends (100% passing) - Followed quality-engineer.org guidelines (test pure functions only) - Investigated 18 test failures: documented cleanup in todo.org Files Modified: - modules/transcription-config.el - Multi-backend support and UI - scripts/assemblyai-transcribe - NEW: AssemblyAI integration script - tests/test-transcription-config--transcription-script-path.el - NEW - todo.org - Added test cleanup task (Method 3, priority C) - docs/NOTES.org - Comprehensive session notes added Successfully tested with 33KB and 4.1MB audio files (3s and 9s processing).
* docs: Add session notes for terminology refactor and template polishCraig Jennings2025-11-051-0/+57
| | | | | | | Documented comprehensive session covering: - Terminology refactor (session → workflow) - Template enhancements in ~/documents/claude/ - Clear docs/ versioning policy for code vs non-code projects
* refactor: Rename "session" to "workflow" for documented processesCraig Jennings2025-11-056-53/+1359
| | | | | | | | | | | | | | | | | | | | | | | | | | This resolves the ambiguity where "session" meant two different things: - Working session (time period we work together) - Documented routine/workflow (process to achieve a goal) Changes: - Renamed docs/sessions/ → docs/workflows/ - Renamed create-session.org → create-workflow.org - Updated all references throughout: - "session type" → "workflow" - "session workflow" → "workflow" - "session definition" → "workflow definition" - "Available Session Types" → "Available Workflows" Updated files: - docs/NOTES.org - All workflow references updated - docs/workflows/*.org - All workflow files updated with new terminology - ~/documents/claude/NOTES.org - Template updated - ~/documents/claude/NOTES-NEW.org - New template updated Terminology now clear: - "Let's run the refactor workflow" = Execute existing workflow - "I want to create a refactor workflow" = Create new workflow definition - "This session" = Working time period (unchanged)
* docs: Create generic V2MOM session workflow and consolidate NOTES.orgCraig Jennings2025-11-053-217/+1100
| | | | | | | | | | | | | | | - Created docs/sessions/create-v2mom.org with fully generic V2MOM workflow - Applicable to any project: health, finance, software, personal goals - 8-phase process with examples across multiple domains - Time estimate: 2-3 hours to create a V2MOM - Consolidated NOTES.org files (deleted root, enhanced docs/NOTES.org) - Integrated generic protocols from template - Added User Information, Session Protocols, File Preferences sections - Enhanced with Reminders Protocol and wrap-up workflow - Single comprehensive 1252-line reference for all sessions - Updated docs/EMACS-CONFIG-V2MOM.org metadata
* feat: Configure scratch buffer for org-mode with cursor at endCraig Jennings2025-11-051-0/+34
| | | | | | | | | | | - Set initial-major-mode to org-mode for *scratch* buffer - Add emacs-startup-hook to position cursor at end of buffer - Update greeting message comment syntax from ;; to # for org-mode - Re-enable debug flag reset on startup in early-init.el This makes the scratch buffer immediately ready for org-mode note-taking with cursor positioned for typing, eliminating manual mode switching and cursor movement.
* fix: Resolve Google Calendar password prompts every 10 minutesCraig Jennings2025-11-051-0/+51
| | | | | | | | | | | | | | | | | | | | | | | Problem: oauth2-auto.plist passphrase requested every ~10 minutes during gcal-sync auto-sync, interrupting workflow despite 400-day gpg-agent cache. Root cause: auth-config.el was setting GPG_AGENT_INFO to nil, telling Emacs to ignore gpg-agent entirely. Additionally, plstore caching was loading too late in org-gcal-config. Solution: - Disabled GPG_AGENT_INFO override to allow gpg-agent usage - Added auth-source-cache-expiry (24-hour cache for credentials) - Moved plstore configuration from org-gcal-config to auth-config - Enabled plstore-cache-passphrase-for-symmetric-encryption globally - Set plstore-encrypt-to nil for symmetric encryption Files modified: - modules/auth-config.el: Added plstore config, removed agent bypass - modules/org-gcal-config.el: Removed duplicate plstore config - docs/NOTES.org: Session notes documenting fix Testing: Restart Emacs and verify no password prompts for 30+ minutes.
* docs: Add comprehensive external dependencies auditCraig Jennings2025-11-041-0/+45
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Created config-dependencies.org documenting all external (non-Emacs) dependencies required for full configuration functionality. Analysis covers: - ~50 external dependencies across all feature areas - Organized by functionality (media, email, programming, documents, etc.) - Package names for pacman/yay/pip/npm/go installation - Required vs optional status for each dependency - Quick reference commands for minimal/recommended/full installs Key features documented: - Audio/video recording (ffmpeg, libpulse) - Transcription (whisper, languagetool) - Email (mu, isync, msmtp) - Programming language support (LSP servers for Go, Python, C, Bash, JS/TS) - Document generation (pandoc, LaTeX, PDF tools) - Media handling (yt-dlp, mpv) - Desktop integration (dunst, xdg-utils) Next steps: - Compare with archsetup script to identify gaps - Create dependency verification script - Ensure archsetup installs all Emacs requirements Session notes added documenting the analysis process.
* docs: Add wrap-up phrase variations to NOTES.orgCraig Jennings2025-11-041-2/+2
| | | | | Added 'wrap up', 'wrap this up', and 'wrap it up' to recognized wrap-up trigger phrases for future sessions.
* docs: Add session notes for 2025-11-04 grammar checker test suiteCraig Jennings2025-11-041-0/+66
| | | | | | | | Documented comprehensive test suite implementation: - 15 tests covering LanguageTool integration (6 unit + 9 integration) - Test fixtures with known grammar errors - Applied quality-engineer.org testing philosophy - All tests passing and integrated with Makefile
* feat: Add LanguageTool integration for comprehensive grammar checkingCraig Jennings2025-11-041-0/+31
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Integrated LanguageTool as an on-demand grammar checker, replacing the previously disabled proselint checker. Changes: - Created scripts/languagetool-flycheck wrapper for flycheck integration - Converts LanguageTool JSON output to flycheck format - Includes suggestions in error messages - 30-second timeout for large files - Updated modules/flycheck-config.el: - Defined languagetool checker for text/markdown/org/gfm modes - Updated cj/flycheck-prose-on-demand to use LanguageTool - Added installation instructions (sudo pacman -S languagetool) - Improved documentation clarity - Usage: Press C-; ? in org/text/markdown files - Enables flycheck with LanguageTool - Shows errors in *Flycheck errors* buffer - On-demand only (no performance impact) - Updated docs/NOTES.org: - Added best practice: Test Emacs launch after non-trivial changes - Example: emacs --eval "(kill-emacs)" - Catches startup errors before committing - Disabled weather debug mode (wttrin-debug nil) - Marked todo.org grammar checker task as DONE LanguageTool catches real grammar issues (subject-verb agreement, tense, punctuation, common mistakes) that proselint missed. Installation: LanguageTool 6.6 (222MB) from Arch repos Dependencies: Python 3 (for wrapper script)
* fix: Resolve async buffer error and improve modeline spacingCraig Jennings2025-11-041-1/+38
| | | | | | | | | | | | - Fixed critical "Selecting deleted buffer" error on startup - wttrin-mode-line-mode now activates after init completes - Uses after-init-hook to prevent async buffer deletion - Weather widget loads safely after Emacs finishes initializing - Improved modeline right-side spacing - Added 2 non-breaking spaces after misc-info segment - Prevents weather icon from appearing flush with edge - Non-breaking spaces survive right-align trimming
* fix: Update transcription keybindings for clarityCraig Jennings2025-11-041-2/+2
| | | | | | | | | Changed transcription submenu keybindings: - C-; t t → C-; t a (transcribe audio) - C-; t b → C-; t v (view transcriptions) - C-; t k → unchanged (kill transcription) More intuitive mnemonics: a=audio, v=view, k=kill
* feat: Add complete async audio transcription workflowCraig Jennings2025-11-041-0/+82
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Implemented full transcription system with local Whisper and OpenAI API support. Includes comprehensive test suite (60 tests) and reorganized keybindings for better discoverability. Features: - Async transcription (non-blocking workflow) - Desktop notifications (started/complete/error) - Output: audio.txt (transcript) + audio.log (process logs) - Modeline integration showing active transcription count - Dired integration (press T on audio files) - Process management and tracking Scripts: - install-whisper.sh: Install Whisper via AUR or pip - uninstall-whisper.sh: Clean removal with cache cleanup - local-whisper: Offline transcription using installed Whisper - oai-transcribe: Cloud transcription via OpenAI API Tests (60 passing): - Audio file detection (16 tests) - Path generation logic (11 tests) - Log cleanup behavior (5 tests) - Duration formatting (9 tests) - Active counter & modeline (11 tests) - Integration workflows (8 tests) Keybindings: - Reorganized gcal to C-; g submenu (s/t/r/c) - Added C-; t transcription submenu (t/b/k) - Dired: T to transcribe file at point
* docs: Add session notes for 2025-11-03 modeline polish workCraig Jennings2025-11-031-0/+39
| | | | | | | | | Session Summary: - Fixed all checkdoc linting errors in modeline-config.el - Created /wrap-it-up workflow automation (slash command + phrase recognition) - Added reminder for Flymake/Flycheck modeline integration decision All work committed and pushed. Clean session ending.
* docs: Add reminder for Flymake/Flycheck modeline integration decisionCraig Jennings2025-11-031-0/+25
| | | | | | | | | | | | | Added new "PENDING DECISIONS" section to NOTES.org with reminder about modeline error/warning integration discussion. Questions to decide: - Flymake vs Flycheck - Format preference (counts vs symbols, clickable?) - Placement (left vs right side) - Active window only? Implementation ready - just needs user preferences.
* feat: Add /wrap-it-up slash command and phrase recognitionCraig Jennings2025-11-031-0/+24
| | | | | | | | | | | | | | | | | Created comprehensive session wrap-up workflow triggered by: - Slash command: /wrap-it-up - Phrases: "let's wrap it up", "that's a wrap", "let's call it a wrap" Workflow: 1. Write session notes to docs/NOTES.org (decisions, work, context) 2. Git commit and push all changes to all remotes 3. Friendly goodbye summary with accomplishments and reminders Added dual documentation: - .claude/commands/wrap-it-up.md for explicit /wrap-it-up command - docs/NOTES.org terminology section for phrase recognition Makes session endings consistent and ensures no work is lost.
* style: Fix checkdoc warnings in video-audio-recording.elCraig Jennings2025-11-031-204/+228
| | | | | | | | | | | | | Resolved 6 checkdoc linting warnings: - Added double spaces after periods in docstrings (Emacs convention) - Changed "calls" to "call" in docstring (imperative form) All linting checks now pass: - checkdoc: ✓ No warnings - make lint: ✓ Passes - All 83 tests: ✓ Still passing Also updated docs/sessions/refactor.org to be more generic/reusable.
* fix: Swap print keybinding and add confirmation promptCraig Jennings2025-11-031-0/+21
| | | | | | | | | | | | | | | | | | | | | | Print operations are now safer and more intuitive: Keybinding changes: - C-; b p → copy file path (safe, common action) - C-; b P → print to PostScript (dramatic, requires shift) Print function improvements: - Add y-or-n-p confirmation before printing - C-u prefix skips confirmation and enables color printing - Prevents accidental waste of paper/toner Serves V2MOM Values: - Intuitive: Dramatic actions require shift key - Intuitive: Prevents muscle memory mistakes - Simple: Reliability through confirmation Also updated docs/NOTES.org with Makefile availability note. Closes inbox items from emacs-inbox-zero session (2025-11-03).
* docs: Add Emacs Lisp development best practices to NOTESCraig Jennings2025-11-011-0/+153
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Document lessons learned from chime-org-contacts.el development about preventing parenthesis errors in Emacs Lisp code. Key Topics: - AI code generation strategies (small functions, immediate testing) - Human developer tools (paredit, smartparens, rainbow-delimiters) - Real-world case study from chime-org-contacts.el refactoring - Tools and workflow summary table Problem Identified: Both AI and humans struggle with deeply nested Emacs Lisp functions due to difficulty counting parentheses manually. Solution Documented: Break complex functions into small (< 15 line) helpers: - Easier to verify correctness - Easier to test independently - Self-documenting through clear function names - AI and humans both succeed Tools Referenced: - Structural editing: paredit, smartparens, lispy - Real-time validation: flycheck, flymake - Visual aids: rainbow-delimiters-mode - CI/CD: pre-commit hooks with check-parens This section serves as permanent reference for future Emacs Lisp development in this repository and others.
* feat: Add session workflow framework and complete first inbox zeroCraig Jennings2025-11-016-46/+1488
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Created emacs-inbox-zero session definition and validated it by executing the workflow. Processed 5 inbox items to zero in 10 minutes. Session Framework: - Created docs/sessions/ directory for session definitions - Added create-session.org (meta-workflow for creating sessions) - Added emacs-inbox-zero.org (weekly inbox processing workflow) - Updated NOTES.org with terminology and session tracking Inbox Zero Results: - Deleted 1 duplicate task (chime fix) - Moved 2 to Method 1: org-capture performance [#B], EMMS keybindings [#D] - Moved 2 to someday-maybe: dashboard icons, persistence files - Recognized perfectionism pattern (V2MOM Obstacle #4) Learnings captured in living documents: - Save Q&A answers incrementally during session creation - Capture useful context during triage (impact estimates, theories) - Validation by execution catches what theory misses Files reorganized: - Renamed docs files to UPPERCASE for consistency - Removed SESSION-HANDOFF-ACTIVE-PROJECT.org (replaced by NOTES.org) V2MOM Metrics fulfilled: - Weekly triage consistency: ✓ (2025-11-01) - Active todo count: 29 items (working toward < 20)
* admin: rework todo to focus on the v2momCraig Jennings2025-11-012-42/+1726
| | | | | | - wrote a v2mom about what the config should deliver - focused the inbox only on tasks related to the v2mom - moved all other tasks to someday-maybe
* docs: Add active project handoff documentsCraig Jennings2025-10-313-0/+669
Introduce detailed session handoff documents for Craig's Emacs configuration project. These provide strategic clarity using the V2MOM framework and outline current progress, project goals, recommended actions, and key insights. This addition aims to streamline handovers and ensure continuity between sessions, facilitating a systematic approach to addressing identified challenges and opportunities for improvement.