Commit 35e6704e3ebe

@@ -0,0 +1,452 @@
+# Configure Workflow
+
+Modern Emacs configuration using use-package, package managers, and best practices for Emacs 29+.
+
+## Modern Configuration (2025)
+
+### Recommended Approach
+
+**Emacs 29+**: use-package is built-in
+- No need to install use-package separately
+- Clean, declarative package configuration
+- Lazy loading for fast startup
+
+## Configuration Structure
+
+```
+~/.emacs.d/
+├── early-init.el      # Early initialization (Emacs 27+)
+├── init.el            # Main configuration
+├── custom.el          # Custom-set variables (optional)
+└── lisp/              # Custom Elisp files
+    └── my-functions.el
+```
+
+## early-init.el
+
+Runs before package initialization and GUI setup:
+
+```elisp
+;;; early-init.el --- Early initialization  -*- lexical-binding: t -*-
+
+;; Disable package.el in favor of straight.el (optional)
+;; Or keep it for use-package with package.el
+(setq package-enable-at-startup t)
+
+;; Improve startup time
+(setq gc-cons-threshold most-positive-fixnum
+      gc-cons-percentage 0.6)
+
+;; Disable unnecessary UI elements early
+(push '(menu-bar-lines . 0) default-frame-alist)
+(push '(tool-bar-lines . 0) default-frame-alist)
+(push '(vertical-scroll-bars) default-frame-alist)
+
+;; Prevent unwanted runtime compilation
+(setq native-comp-deferred-compilation nil)
+
+;;; early-init.el ends here
+```
+
+## init.el (Modern with use-package)
+
+### Basic Setup
+
+```elisp
+;;; init.el --- Emacs configuration  -*- lexical-binding: t -*-
+
+;; Reset GC threshold after startup
+(add-hook 'emacs-startup-hook
+          (lambda ()
+            (setq gc-cons-threshold (* 16 1024 1024)
+                  gc-cons-percentage 0.1)))
+
+;; Package archives
+(require 'package)
+(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
+(add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/") t)
+(package-initialize)
+
+;; Ensure use-package is available
+(unless (package-installed-p 'use-package)
+  (package-refresh-contents)
+  (package-install 'use-package))
+
+(require 'use-package)
+(setq use-package-always-ensure t)  ; Auto-install packages
+
+;; Keep customizations in separate file
+(setq custom-file (expand-file-name "custom.el" user-emacs-directory))
+(when (file-exists-p custom-file)
+  (load custom-file))
+
+;;; init.el ends here
+```
+
+### Essential Packages
+
+```elisp
+;; Magit - Git interface
+(use-package magit
+  :bind ("C-x g" . magit-status)
+  :config
+  (setq magit-display-buffer-function
+        #'magit-display-buffer-same-window-except-diff-v1))
+
+;; Company - Completion
+(use-package company
+  :hook (prog-mode . company-mode)
+  :custom
+  (company-idle-delay 0.2)
+  (company-minimum-prefix-length 2)
+  :bind (:map company-active-map
+         ("C-n" . company-select-next)
+         ("C-p" . company-select-previous)))
+
+;; Vertico - Minibuffer completion
+(use-package vertico
+  :init
+  (vertico-mode 1)
+  :custom
+  (vertico-cycle t))
+
+;; Marginalia - Rich annotations
+(use-package marginalia
+  :init
+  (marginalia-mode 1))
+
+;; Orderless - Flexible matching
+(use-package orderless
+  :custom
+  (completion-styles '(orderless basic))
+  (completion-category-overrides '((file (styles basic partial-completion)))))
+
+;; Which-key - Key binding help
+(use-package which-key
+  :init
+  (which-key-mode 1)
+  :custom
+  (which-key-idle-delay 0.5))
+```
+
+### Programming
+
+```elisp
+;; LSP (choose one: eglot or lsp-mode)
+
+;; Eglot (built-in since Emacs 29)
+(use-package eglot
+  :ensure nil  ; Built-in
+  :hook ((python-mode . eglot-ensure)
+         (go-mode . eglot-ensure)
+         (rust-mode . eglot-ensure)))
+
+;; OR lsp-mode (more features, heavier)
+(use-package lsp-mode
+  :hook ((python-mode . lsp)
+         (go-mode . lsp))
+  :commands lsp
+  :custom
+  (lsp-headerline-breadcrumb-enable nil))
+
+;; Tree-sitter (built-in since Emacs 29)
+(use-package treesit
+  :ensure nil
+  :config
+  (setq treesit-language-source-alist
+        '((python "https://github.com/tree-sitter/tree-sitter-python")
+          (rust "https://github.com/tree-sitter/tree-sitter-rust")
+          (go "https://github.com/tree-sitter/tree-sitter-go"))))
+```
+
+### Org Mode
+
+```elisp
+(use-package org
+  :ensure nil  ; Built-in
+  :custom
+  (org-directory "~/org")
+  (org-agenda-files '("~/org/agenda.org"))
+  (org-startup-indented t)
+  (org-hide-emphasis-markers t)
+  :config
+  (org-babel-do-load-languages
+   'org-babel-load-languages
+   '((emacs-lisp . t)
+     (python . t)
+     (shell . t))))
+
+(use-package org-roam
+  :custom
+  (org-roam-directory "~/org/roam")
+  :bind (("C-c n l" . org-roam-buffer-toggle)
+         ("C-c n f" . org-roam-node-find)
+         ("C-c n i" . org-roam-node-insert))
+  :config
+  (org-roam-db-autosync-mode))
+```
+
+## Alternative: straight.el
+
+For reproducible configuration with pinned versions:
+
+### Bootstrap
+
+```elisp
+;;; init.el with straight.el
+
+;; Bootstrap straight.el
+(defvar bootstrap-version)
+(let ((bootstrap-file
+       (expand-file-name "straight/repos/straight.el/bootstrap.el"
+                         user-emacs-directory))
+      (bootstrap-version 6))
+  (unless (file-exists-p bootstrap-file)
+    (with-current-buffer
+        (url-retrieve-synchronously
+         "https://raw.githubusercontent.com/radian-software/straight.el/develop/install.el"
+         'silent 'inhibit-cookies)
+      (goto-char (point-max))
+      (eval-print-last-sexp)))
+  (load bootstrap-file nil 'nomessage))
+
+;; Install use-package
+(straight-use-package 'use-package)
+(setq straight-use-package-by-default t)
+
+;; Now use packages normally
+(use-package magit)
+(use-package company
+  :hook (prog-mode . company-mode))
+```
+
+### Lockfile
+
+straight.el creates `straight/versions/default.el` with pinned versions:
+
+```elisp
+;; Example lockfile entry
+(("magit" . "abc123...")
+ ("company" . "def456..."))
+```
+
+Commit this file for reproducible installs.
+
+## Performance Optimization
+
+### Startup Time
+
+```elisp
+;; Measure startup time
+(add-hook 'emacs-startup-hook
+          (lambda ()
+            (message "Emacs loaded in %s with %d garbage collections."
+                     (format "%.2f seconds"
+                             (float-time
+                              (time-subtract after-init-time before-init-time)))
+                     gcs-done)))
+
+;; Lazy load packages
+(use-package markdown-mode
+  :defer t
+  :mode "\\.md\\'")
+
+(use-package yaml-mode
+  :defer t
+  :mode "\\.ya?ml\\'")
+
+;; Defer non-essential packages
+(use-package dashboard
+  :defer 1  ; Load 1 second after startup
+  :config
+  (dashboard-setup-startup-hook))
+```
+
+### Native Compilation
+
+Emacs 28+ with native compilation:
+
+```elisp
+;; Enable native compilation
+(when (and (fboundp 'native-comp-available-p)
+           (native-comp-available-p))
+  (setq native-comp-async-report-warnings-errors nil)
+  (setq native-comp-deferred-compilation t))
+```
+
+## Configuration Patterns
+
+### Theme
+
+```elisp
+(use-package modus-themes
+  :ensure nil  ; Built-in since Emacs 28
+  :config
+  (setq modus-themes-bold-constructs t
+        modus-themes-italic-constructs t)
+  (load-theme 'modus-vivendi t))
+
+;; Or external theme
+(use-package doom-themes
+  :config
+  (load-theme 'doom-one t))
+```
+
+### Keybindings
+
+```elisp
+;; Global keybindings
+(global-set-key (kbd "C-c f") #'find-file)
+(global-set-key (kbd "C-c b") #'switch-to-buffer)
+
+;; With use-package
+(use-package ace-window
+  :bind ("M-o" . ace-window))
+
+;; Define custom keymap
+(defvar my-leader-map (make-sparse-keymap)
+  "Personal leader keymap.")
+
+(global-set-key (kbd "C-c m") my-leader-map)
+(define-key my-leader-map (kbd "f") #'find-file)
+(define-key my-leader-map (kbd "b") #'switch-to-buffer)
+```
+
+### Custom Functions
+
+```elisp
+;; In lisp/my-functions.el
+(defun my/open-config ()
+  "Open init.el."
+  (interactive)
+  (find-file (expand-file-name "init.el" user-emacs-directory)))
+
+(defun my/reload-config ()
+  "Reload init.el."
+  (interactive)
+  (load-file (expand-file-name "init.el" user-emacs-directory)))
+
+(global-set-key (kbd "C-c e c") #'my/open-config)
+(global-set-key (kbd "C-c e r") #'my/reload-config)
+
+;; Load custom functions
+(add-to-list 'load-path (expand-file-name "lisp" user-emacs-directory))
+(require 'my-functions)
+```
+
+## Debugging Configuration
+
+### Profile Startup
+
+```bash
+# Built-in profiler
+emacs --debug-init
+
+# Or use esup (Emacs Start Up Profiler)
+M-x package-install RET esup RET
+M-x esup
+```
+
+### use-package Debug
+
+```elisp
+;; Show what use-package does
+(setq use-package-verbose t)
+(setq use-package-compute-statistics t)
+
+;; View statistics
+M-x use-package-report
+```
+
+## Migration from Old Config
+
+### From require to use-package
+
+```elisp
+;; Old way
+(add-to-list 'load-path "~/.emacs.d/lisp/some-package")
+(require 'some-package)
+(setq some-package-variable value)
+(global-set-key (kbd "C-c s") #'some-package-command)
+
+;; New way
+(use-package some-package
+  :load-path "lisp/some-package"
+  :custom
+  (some-package-variable value)
+  :bind ("C-c s" . some-package-command))
+```
+
+## Best Practices
+
+1. **Use lexical binding**: `;;; -*- lexical-binding: t -*-`
+2. **Lazy load packages**: Use `:defer`, `:hook`, or `:mode`
+3. **Keep customizations separate**: Use `custom-file`
+4. **Organize by category**: Group related packages
+5. **Comment your config**: Explain non-obvious settings
+6. **Version control**: Keep `.emacs.d` in git
+7. **Measure startup time**: Keep it under 2 seconds
+8. **Use built-in features**: Prefer built-in over external packages
+9. **Pin critical packages**: Use straight.el for important configs
+10. **Test incrementally**: Add packages one at a time
+
+## Example Complete Configuration
+
+### Minimal Modern Config
+
+```elisp
+;;; init.el --- Minimal modern Emacs config  -*- lexical-binding: t -*-
+
+;; Package setup
+(require 'package)
+(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))
+(package-initialize)
+
+;; use-package (built-in Emacs 29+)
+(require 'use-package)
+(setq use-package-always-ensure t)
+
+;; UI improvements
+(setq inhibit-startup-screen t
+      initial-scratch-message nil
+      ring-bell-function 'ignore)
+(menu-bar-mode -1)
+(tool-bar-mode -1)
+(scroll-bar-mode -1)
+(show-paren-mode 1)
+(global-hl-line-mode 1)
+(global-display-line-numbers-mode 1)
+
+;; Editing
+(setq-default indent-tabs-mode nil
+              tab-width 4)
+(electric-pair-mode 1)
+(delete-selection-mode 1)
+(save-place-mode 1)
+(global-auto-revert-mode 1)
+
+;; Essential packages
+(use-package magit
+  :bind ("C-x g" . magit-status))
+
+(use-package vertico
+  :init (vertico-mode))
+
+(use-package which-key
+  :init (which-key-mode))
+
+;; Theme
+(use-package modus-themes
+  :ensure nil
+  :config
+  (load-theme 'modus-vivendi t))
+
+;;; init.el ends here
+```
+
+## Resources
+
+- [use-package Documentation](https://github.com/jwiegley/use-package)
+- [straight.el](https://github.com/radian-software/straight.el)
+- [Emacs Package Manager Comparison](https://www.reddit.com/r/emacs/wiki/packages)
+- [Sacha Chua's Emacs Config](https://sachachua.com/dotemacs/)

@@ -0,0 +1,507 @@
+# Debug Workflow
+
+Debug Emacs Lisp code using edebug, the debugger, and diagnostic tools.
+
+## edebug (Recommended)
+
+### Instrument Function
+
+```elisp
+;; Place cursor in function definition
+(defun my-function (arg)
+  "Example function."
+  (let ((result (* arg 2)))
+    (+ result 10)))
+
+;; Instrument for debugging
+C-u C-M-x  ; or M-x edebug-defun
+```
+
+### Debug Controls
+
+| Key | Action |
+|-----|--------|
+| `SPC` | Step through (next form) |
+| `n` | Next (skip over function calls) |
+| `i` | Step into function |
+| `o` | Step out of function |
+| `g` | Go (continue execution) |
+| `b` | Set breakpoint |
+| `u` | Unset breakpoint |
+| `e` | Evaluate expression |
+| `q` | Quit debugging |
+| `?` | Show help |
+
+### Breakpoints
+
+```elisp
+(defun my-function (arg)
+  (let ((x (* arg 2)))
+    (edebug)  ; Hard-coded breakpoint
+    (+ x 10)))
+
+;; Or set breakpoint interactively
+;; While stopped in edebug, press 'b' at any point
+```
+
+### Conditional Breakpoints
+
+```elisp
+(defun process-list (items)
+  (dolist (item items)
+    (when (edebug-break-when (> item 100))  ; Break if item > 100
+      (process-item item))))
+```
+
+### View Variables
+
+```elisp
+;; While in edebug:
+e  ; Evaluate expression
+;; Type: my-var RET
+;; Shows value of my-var
+
+;; Or evaluate any expression
+e (+ 1 2) RET  ; Shows 3
+```
+
+## debug (Built-in Debugger)
+
+### Enable Debugger
+
+```elisp
+;; Debug on error
+M-x toggle-debug-on-error
+
+;; Or in code
+(setq debug-on-error t)
+
+;; Debug on quit (C-g)
+(setq debug-on-quit t)
+```
+
+### Trigger Debugger
+
+```elisp
+(debug)  ; Explicit breakpoint
+
+;; Or cause an error
+(error "Debug this")
+```
+
+### Debugger Buffer
+
+When debugger activates:
+
+```
+Debugger entered--Lisp error: (wrong-type-argument number-or-marker-p nil)
+  +(nil 5)
+  my-function(nil)
+  eval((my-function nil) nil)
+  ...
+```
+
+Controls:
+- `c` - Continue
+- `d` - Step through
+- `e` - Evaluate expression
+- `q` - Quit
+- `r` - Return value
+- `b` - Set breakpoint
+
+## Diagnostic Tools
+
+### message
+
+```elisp
+(defun my-function (arg)
+  (message "arg: %S" arg)  ; Log to *Messages*
+  (let ((result (* arg 2)))
+    (message "result: %S" result)
+    (+ result 10)))
+```
+
+### prin1 / princ
+
+```elisp
+(defun my-function (items)
+  (prin1 items)  ; Print to current buffer
+  (terpri)       ; Newline
+  ...)
+```
+
+### trace-function
+
+```elisp
+;; Enable tracing
+M-x trace-function RET my-function RET
+
+;; Run function
+(my-function 5)
+
+;; View trace output in *trace-output*
+;; Shows: arguments, return value, depth
+
+;; Disable
+M-x untrace-function RET my-function RET
+
+;; Trace all calls
+M-x trace-function-foreground RET my-function RET
+```
+
+Example trace output:
+```
+1 -> (my-function 5)
+1 <- my-function: 20
+```
+
+### benchmark
+
+```elisp
+(require 'benchmark)
+
+;; Time single call
+(benchmark-run 1
+  (my-expensive-function))
+;; => (0.523 0 0.0)  ; seconds, GCs, GC time
+
+;; Time multiple calls
+(benchmark-run 1000
+  (my-function 10))
+
+;; With formatted output
+(benchmark-run-compiled 1000
+  (my-function 10))
+```
+
+### profiler
+
+```elisp
+;; Start CPU profiler
+M-x profiler-start RET cpu RET
+
+;; Run code to profile
+(dotimes (i 10000)
+  (my-function i))
+
+;; View report
+M-x profiler-report
+
+;; Stop profiling
+M-x profiler-stop
+```
+
+Profiler report shows:
+- Function call counts
+- Time spent in each function
+- Call tree
+
+## Common Debugging Patterns
+
+### Check Variable Value
+
+```elisp
+(defun my-function (arg)
+  (let ((result (expensive-calculation arg)))
+    ;; Check value
+    (unless (numberp result)
+      (error "Expected number, got: %S" result))
+    result))
+```
+
+### Assert
+
+```elisp
+(defun my-function (arg)
+  (cl-assert (numberp arg) t "ARG must be a number, got %S" arg)
+  (cl-assert (> arg 0) t "ARG must be positive, got %S" arg)
+  (* arg 2))
+```
+
+### Conditional Logging
+
+```elisp
+(defvar my-package-debug nil
+  "Enable debug logging when non-nil.")
+
+(defun my-package--debug (format-string &rest args)
+  "Log debug message if debugging is enabled."
+  (when my-package-debug
+    (apply #'message (concat "DEBUG: " format-string) args)))
+
+(defun my-function (arg)
+  (my-package--debug "Processing arg: %S" arg)
+  ...)
+```
+
+### Backtrace
+
+```elisp
+(defun my-function ()
+  ;; Print backtrace
+  (message "Backtrace:\n%s" (backtrace-to-string))
+  ...)
+```
+
+## Debugging Macros
+
+### macroexpand
+
+```elisp
+;; Expand macro once
+(macroexpand '(when condition body))
+;; => (if condition (progn body))
+
+;; Expand completely
+(macroexpand-all '(when condition (when other more)))
+
+;; Interactive
+M-x pp-macroexpand-last-sexp
+```
+
+### Example Macro Debugging
+
+```elisp
+(defmacro my-with-temp-buffer (&rest body)
+  `(with-temp-buffer
+     (message "Entering temp buffer")
+     ,@body
+     (message "Exiting temp buffer")))
+
+;; Check expansion
+(macroexpand '(my-with-temp-buffer
+               (insert "test")))
+```
+
+## Interactive Debugging
+
+### eval-expression
+
+```elisp
+M-: (my-function 5) RET
+;; Shows result in minibuffer
+```
+
+### ielm (Emacs Lisp REPL)
+
+```elisp
+M-x ielm
+
+ELISP> (setq x 10)
+10
+ELISP> (* x 2)
+20
+ELISP> (require 'my-package)
+t
+ELISP> (my-package-test-function)
+```
+
+### scratch Buffer
+
+```elisp
+;; In *scratch* buffer
+(defun test ()
+  (* 2 3))
+
+;; Evaluate
+C-x C-e  ; At end of form
+;; => 6
+
+;; Evaluate and insert result
+C-u C-x C-e
+;; => (defun test () (* 2 3))6
+```
+
+## Debugging Strategies
+
+### Binary Search
+
+```elisp
+(defun complex-function (arg)
+  (let ((step1 (do-step-1 arg)))
+    (message "After step 1: %S" step1)  ; Add checkpoints
+    (let ((step2 (do-step-2 step1)))
+      (message "After step 2: %S" step2)
+      (let ((step3 (do-step-3 step2)))
+        (message "After step 3: %S" step3)
+        step3))))
+```
+
+### Simplify
+
+```elisp
+;; Original complex function
+(defun complex-function (arg)
+  (complicated-logic arg))
+
+;; Simplified version for testing
+(defun complex-function (arg)
+  ;; (complicated-logic arg)
+  42)  ; Replace with simple value
+
+;; Gradually uncomment to find issue
+```
+
+### Isolate
+
+```elisp
+;; Extract problematic code
+(defun test-isolated ()
+  "Test just the problematic part."
+  (let ((test-input '(1 2 3)))
+    (problematic-function test-input)))
+
+;; Run in isolation
+(test-isolated)
+```
+
+## Debugging Hooks
+
+### Trace Hook Execution
+
+```elisp
+(defun trace-hook (hook-var)
+  "Trace execution of hooks in HOOK-VAR."
+  (dolist (func (symbol-value hook-var))
+    (trace-function func)))
+
+;; Example
+(trace-hook 'emacs-lisp-mode-hook)
+```
+
+### Debug Mode Activation
+
+```elisp
+(defun my-mode ()
+  "My mode with debugging."
+  (interactive)
+  (message "Activating my-mode")
+  (message "Hooks: %S" my-mode-hook)
+
+  ;; Wrap hook execution
+  (condition-case err
+      (run-hooks 'my-mode-hook)
+    (error
+     (message "Error in hook: %s" (error-message-string err)))))
+```
+
+## Performance Debugging
+
+### Time Function Calls
+
+```elisp
+(defun time-it (func &rest args)
+  "Time execution of FUNC with ARGS."
+  (let ((start (current-time)))
+    (apply func args)
+    (float-time (time-since start))))
+
+;; Usage
+(time-it #'my-expensive-function arg1 arg2)
+```
+
+### Memory Usage
+
+```elisp
+;; Before
+(garbage-collect)
+(let ((mem-before (memory-use-counts)))
+
+  ;; Run code
+  (my-function)
+
+  ;; After
+  (garbage-collect)
+  (let ((mem-after (memory-use-counts)))
+    (message "Memory used: %S"
+             (cl-mapcar #'- mem-after mem-before))))
+```
+
+## Debugging Buffer Issues
+
+### Inspect Buffer
+
+```elisp
+;; View buffer properties
+(buffer-local-variables)
+
+;; Check major mode
+major-mode
+
+;; Check buffer state
+(buffer-modified-p)
+(buffer-file-name)
+(point)
+(point-min)
+(point-max)
+```
+
+### Debugging Point Movement
+
+```elisp
+(defun my-function ()
+  (save-excursion  ; Save point
+    (message "Point before: %d" (point))
+    (goto-char (point-min))
+    (message "Point during: %d" (point))
+    (some-operation)
+    (message "Point after: %d" (point))))
+```
+
+## Common Issues
+
+### Wrong Type Argument
+
+```elisp
+;; Error: (wrong-type-argument number-or-marker-p nil)
+
+;; Debug
+(defun my-function (arg)
+  (unless (numberp arg)
+    (error "Expected number, got: %S (type: %S)"
+           arg (type-of arg)))
+  (+ arg 5))
+```
+
+### Void Variable
+
+```elisp
+;; Error: (void-variable my-var)
+
+;; Check if bound
+(boundp 'my-var)  ; => nil
+
+;; Fix
+(defvar my-var nil "Documentation")
+```
+
+### Void Function
+
+```elisp
+;; Error: (void-function my-func)
+
+;; Check if defined
+(fboundp 'my-func)  ; => nil
+
+;; Check if it's a macro
+(macrop 'my-func)
+```
+
+## Best Practices
+
+1. **Use edebug**: Most powerful debugging tool
+2. **Add logging**: Strategic `message` calls
+3. **Write tests**: Find bugs early
+4. **Check types**: Validate arguments
+5. **Use assertions**: cl-assert for invariants
+6. **Profile first**: Find real bottlenecks
+7. **Simplify**: Break complex functions
+8. **Read backtraces**: Understand error source
+9. **Test incrementally**: Small changes
+10. **Document assumptions**: Why code should work
+
+## Resources
+
+- [edebug Manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html)
+- [Debugging Manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/Debugging.html)
+- [Profiler](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html)

@@ -0,0 +1,515 @@
+# Document Workflow
+
+Write comprehensive documentation for Emacs Lisp packages: docstrings, README, and Info manuals.
+
+## Docstrings
+
+### Function Docstrings
+
+```elisp
+(defun my-package-process-file (file &optional verbose callback)
+  "Process FILE and return the result.
+
+FILE should be a path to a readable file.  Optional argument
+VERBOSE, when non-nil, enables progress messages.  Optional
+argument CALLBACK is called with the result when processing
+completes.
+
+The function reads FILE, processes its contents, and returns
+a list of processed items.  If FILE cannot be read, returns nil.
+
+Example usage:
+
+  (my-package-process-file \"input.txt\" t)
+  (my-package-process-file \"data.csv\" nil #'my-callback)
+
+Returns a list of the form (ITEM1 ITEM2 ...), or nil if FILE
+cannot be processed.
+
+Signals an error if FILE does not exist or is not readable.
+
+See also `my-package-process-directory'."
+  ...)
+```
+
+### Docstring Guidelines
+
+1. **First line**: Complete sentence, under 80 characters
+2. **Argument names**: UPPERCASE when mentioned
+3. **Blank line**: After first sentence (for summary)
+4. **Return value**: Document what function returns
+5. **Signals**: Document errors that may be raised
+6. **Examples**: Show typical usage
+7. **See also**: Reference related functions
+
+### Variable Docstrings
+
+```elisp
+(defvar my-package-timeout 30
+  "Timeout in seconds for network operations.
+
+This value controls how long to wait before giving up on
+network requests.  A value of 0 means no timeout.
+
+Changing this value affects all future operations but does
+not impact currently running operations.")
+
+(defvar my-package--internal-state nil
+  "Internal state for my-package.
+This variable should not be modified directly.")
+```
+
+### Custom Variables
+
+```elisp
+(defcustom my-package-auto-save t
+  "Whether to automatically save after operations.
+
+When non-nil, files are automatically saved after processing.
+When nil, you must manually save changes.
+
+You can also set this locally per buffer using:
+
+  (setq-local my-package-auto-save nil)"
+  :type 'boolean
+  :safe #'booleanp
+  :group 'my-package)
+
+(defcustom my-package-backends '(backend1 backend2)
+  "List of backends to use for processing.
+
+Each backend should be a symbol recognized by my-package.
+Backends are tried in order until one succeeds.
+
+Available backends:
+  backend1 - Fast but limited
+  backend2 - Slower but more features
+  backend3 - Requires external program"
+  :type '(repeat (choice (const :tag "Backend 1" backend1)
+                         (const :tag "Backend 2" backend2)
+                         (const :tag "Backend 3" backend3)))
+  :group 'my-package)
+```
+
+## Package Commentary
+
+```elisp
+;;; my-package.el --- Brief description  -*- lexical-binding: t -*-
+
+;; [Headers...]
+
+;;; Commentary:
+
+;; My Package provides tools for processing data files.
+;;
+;; Features:
+;;
+;; - Process multiple file formats
+;; - Batch processing support
+;; - Customizable backends
+;; - Integration with other tools
+;;
+;; Basic usage:
+;;
+;;     (require 'my-package)
+;;     (my-package-enable)
+;;     (my-package-process-file "data.csv")
+;;
+;; Configuration:
+;;
+;;     (setq my-package-auto-save nil)
+;;     (setq my-package-timeout 60)
+;;
+;; For more information, see the Info manual:
+;;
+;;     C-h i m My Package RET
+;;
+;; Or visit the project page:
+;;
+;;     https://github.com/user/my-package
+
+;;; Code:
+```
+
+## README.md
+
+### Complete README Structure
+
+```markdown
+# My Package
+
+[![MELPA](https://melpa.org/packages/my-package-badge.svg)](https://melpa.org/#/my-package)
+[![CI](https://github.com/user/my-package/workflows/CI/badge.svg)](https://github.com/user/my-package/actions)
+
+Brief one-sentence description of what the package does.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Installation
+
+### MELPA
+
+```elisp
+(use-package my-package
+  :ensure t
+  :config
+  (my-package-enable))
+```
+
+### Manual
+
+Clone this repository:
+
+```bash
+git clone https://github.com/user/my-package.git
+```
+
+Add to your `init.el`:
+
+```elisp
+(add-to-list 'load-path "/path/to/my-package")
+(require 'my-package)
+```
+
+## Usage
+
+### Basic Usage
+
+```elisp
+;; Enable globally
+(my-package-mode 1)
+
+;; Or in specific buffers
+(add-hook 'text-mode-hook #'my-package-mode)
+```
+
+### Commands
+
+| Command | Description | Keybinding |
+|---------|-------------|------------|
+| `my-package-enable` | Enable the package | - |
+| `my-package-process` | Process current buffer | `C-c m p` |
+| `my-package-export` | Export to file | `C-c m e` |
+
+### Configuration
+
+```elisp
+;; Set timeout
+(setq my-package-timeout 60)
+
+;; Choose backend
+(setq my-package-backend 'backend2)
+
+;; Disable auto-save
+(setq my-package-auto-save nil)
+```
+
+## Customization
+
+All options can be customized via:
+
+```
+M-x customize-group RET my-package RET
+```
+
+Key options:
+
+- `my-package-timeout` - Operation timeout in seconds
+- `my-package-auto-save` - Automatically save after processing
+- `my-package-backend` - Which backend to use
+
+## Examples
+
+### Example 1: Process File
+
+```elisp
+(my-package-process-file "data.csv" t)
+```
+
+### Example 2: Batch Processing
+
+```elisp
+(my-package-process-directory "~/data/" "\\.csv$")
+```
+
+## Troubleshooting
+
+### Package doesn't load
+
+Make sure the package is in your `load-path`:
+
+```elisp
+(add-to-list 'load-path "/path/to/my-package")
+```
+
+### Command not found
+
+Ensure the package is loaded:
+
+```elisp
+(require 'my-package)
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new features
+4. Ensure all tests pass
+5. Submit a pull request
+
+## License
+
+GPL-3.0-or-later
+
+## Acknowledgments
+
+- Thanks to contributor1
+- Thanks to contributor2
+```
+
+## Info Manual
+
+### Create Manual
+
+**doc/my-package.texi**:
+
+```texinfo
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename my-package.info
+@settitle My Package Manual
+@documentencoding UTF-8
+@c %**end of header
+
+@copying
+This manual is for My Package version 1.0.
+
+Copyright @copyright{} 2025 Your Name
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation.
+@end quotation
+@end copying
+
+@titlepage
+@title My Package Manual
+@subtitle For version 1.0
+@author Your Name
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@node Top
+@top My Package
+
+My Package provides tools for processing data files.
+
+@menu
+* Introduction::      What is My Package?
+* Installation::      Installing the package
+* Usage::             How to use the package
+* Configuration::     Customization options
+* Index::             Complete index
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+My Package helps you process data files efficiently.
+
+@node Installation
+@chapter Installation
+
+Install from MELPA:
+
+@lisp
+(use-package my-package
+  :ensure t)
+@end lisp
+
+@node Usage
+@chapter Usage
+
+@section Basic Usage
+
+Enable the package:
+
+@lisp
+(my-package-enable)
+@end lisp
+
+@section Commands
+
+@table @code
+@item my-package-enable
+Enable the package globally.
+
+@item my-package-process-file
+Process a single file.
+@end table
+
+@node Configuration
+@chapter Configuration
+
+@defvar my-package-timeout
+Timeout in seconds for operations.
+@end defvar
+
+@defvar my-package-auto-save
+Whether to auto-save after processing.
+@end defvar
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+```
+
+### Build Info Manual
+
+```bash
+# Generate info file
+makeinfo doc/my-package.texi -o my-package.info
+
+# View
+info -f my-package.info
+
+# Install system-wide
+sudo install-info my-package.info /usr/share/info/dir
+```
+
+### Include in Package
+
+```elisp
+;; In Eask
+(package-file "my-package.el")
+(files "my-package.el" "my-package-utils.el" "my-package.info")
+```
+
+## CHANGELOG.md
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New feature in development
+
+## [1.2.0] - 2025-01-15
+
+### Added
+- New command `my-package-export` for exporting data
+- Support for CSV format
+- Interactive completion for file selection
+
+### Changed
+- Improved performance of file processing (30% faster)
+- Updated documentation with more examples
+- Refactored backend system for extensibility
+
+### Deprecated
+- `my-package-old-function` - Use `my-package-new-function` instead
+
+### Removed
+- Removed support for deprecated format X
+
+### Fixed
+- Fixed bug in error handling (#42)
+- Fixed memory leak in batch processing (#45)
+- Corrected documentation typo (#48)
+
+### Security
+- Fixed potential security issue with file paths
+
+## [1.1.0] - 2025-01-01
+
+### Added
+- Initial public release
+- Basic file processing
+- Customization options
+
+## [1.0.0] - 2024-12-15
+
+### Added
+- Initial development version
+```
+
+## Documentation Tools
+
+### checkdoc
+
+```elisp
+;; Check docstrings
+M-x checkdoc
+
+;; Check current buffer
+M-x checkdoc-current-buffer
+
+;; Fix automatically
+M-x checkdoc-eval-current-buffer
+```
+
+### package-lint
+
+```bash
+# Check documentation
+eask lint checkdoc
+```
+
+## Best Practices
+
+### Docstrings
+
+1. **Complete sentences**: Start with capital, end with period
+2. **First line summary**: Complete thought, under 80 chars
+3. **Document arguments**: Use UPPERCASE for arg names
+4. **Document return**: What does function return?
+5. **Document signals**: What errors can occur?
+6. **Examples**: Show typical usage
+7. **Cross-references**: Link to related functions
+
+### README
+
+1. **Clear title**: What is the package?
+2. **Installation**: Simple, copy-paste instructions
+3. **Usage examples**: Show common use cases
+4. **Configuration**: List key options
+5. **Screenshots**: If UI-heavy (optional)
+6. **Badges**: MELPA, CI status
+7. **Contributing**: How to help
+8. **License**: Clear license information
+
+### Info Manual
+
+1. **Comprehensive**: More detail than README
+2. **Organized**: Logical chapter structure
+3. **Examples**: Lots of code examples
+4. **Index**: Complete index for searching
+5. **Cross-references**: Link related sections
+
+## Resources
+
+- [Docstring Tips](https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html)
+- [Texinfo Manual](https://www.gnu.org/software/texinfo/manual/texinfo/)
+- [Keep a Changelog](https://keepachangelog.com/)
+- [README Template](https://github.com/othneildrew/Best-README-Template)

@@ -0,0 +1,479 @@
+# Lint Workflow
+
+Check code quality, style, and MELPA compliance using package-lint, checkdoc, and byte-compilation.
+
+## Linting Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| **package-lint** | MELPA compliance | Before publishing |
+| **checkdoc** | Docstring quality | Always |
+| **byte-compile** | Code correctness | Always |
+| **elisp-lint** | Comprehensive linting | CI/CD |
+| **flycheck** | Real-time linting | Development |
+
+## package-lint (MELPA Compliance)
+
+### Installation
+
+```bash
+# With Eask
+eask install-deps --dev
+
+# Or manually
+M-x package-install RET package-lint RET
+```
+
+### Run
+
+```elisp
+;; Interactive
+M-x package-lint-current-buffer
+
+;; Batch mode
+emacs -batch -l package-lint.el -f package-lint-batch-and-exit my-package.el
+
+;; With Eask
+eask lint package
+```
+
+### Common Issues
+
+#### Missing Package Headers
+
+```elisp
+;; Bad - missing headers
+;;; my-package.el --- Description
+
+;; Good - all required headers
+;;; my-package.el --- Description  -*- lexical-binding: t -*-
+;; Author: Name <email>
+;; Version: 0.1.0
+;; Package-Requires: ((emacs "29.1"))
+;; Keywords: tools
+;; URL: https://github.com/user/repo
+```
+
+#### Package-Requires Format
+
+```elisp
+;; Bad - wrong format
+;; Package-Requires: (emacs "29.1")
+
+;; Good - list of lists
+;; Package-Requires: ((emacs "29.1"))
+
+;; With dependencies
+;; Package-Requires: ((emacs "29.1") (dash "2.19"))
+```
+
+#### Symbol Naming
+
+```elisp
+;; Bad - no package prefix
+(defun enable-feature ()
+  ...)
+
+;; Good - consistent prefix
+(defun my-package-enable-feature ()
+  ...)
+
+;; Bad - inconsistent prefix
+(defun my-pkg-enable ()  ; Different from package name
+  ...)
+
+;; Good - matches package name
+(defun my-package-enable ()
+  ...)
+```
+
+## checkdoc (Docstring Quality)
+
+### Run
+
+```elisp
+;; Interactive
+M-x checkdoc
+
+;; Current buffer
+M-x checkdoc-current-buffer
+
+;; Batch mode
+emacs -batch -l checkdoc -f checkdoc-file my-package.el
+
+;; With Eask
+eask lint checkdoc
+```
+
+### Docstring Rules
+
+#### Functions
+
+```elisp
+;; Bad - incomplete docstring
+(defun my-package-process (file)
+  "Process file."
+  ...)
+
+;; Good - complete documentation
+(defun my-package-process (file &optional verbose)
+  "Process FILE and return results.
+
+If VERBOSE is non-nil, print progress messages.
+
+FILE should be a readable file path.  Returns a list of
+processed items, or nil if FILE cannot be read.
+
+Signals an error if FILE does not exist."
+  ...)
+```
+
+#### Variables
+
+```elisp
+;; Bad
+(defvar my-package-timeout 30)
+
+;; Good
+(defvar my-package-timeout 30
+  "Timeout in seconds for network operations.")
+```
+
+#### Customizable Variables
+
+```elisp
+;; Good
+(defcustom my-package-enable-feature t
+  "Whether to enable the special feature.
+
+When non-nil, the package will automatically enable the
+feature when activated."
+  :type 'boolean
+  :group 'my-package)
+```
+
+### Common Docstring Issues
+
+#### Capitalization
+
+```elisp
+;; Bad - doesn't start with capital
+(defun my-func ()
+  "process the data."
+  ...)
+
+;; Good
+(defun my-func ()
+  "Process the data."
+  ...)
+```
+
+#### Period
+
+```elisp
+;; Bad - no period
+(defun my-func ()
+  "Process the data"
+  ...)
+
+;; Good
+(defun my-func ()
+  "Process the data."
+  ...)
+```
+
+#### Argument Documentation
+
+```elisp
+;; Bad - mentions args in lowercase
+(defun my-func (arg1 arg2)
+  "Process arg1 and arg2."
+  ...)
+
+;; Good - uppercase for arguments
+(defun my-func (arg1 arg2)
+  "Process ARG1 and ARG2."
+  ...)
+```
+
+## Byte Compilation
+
+### Compile
+
+```bash
+# Single file
+emacs -batch -f batch-byte-compile my-package.el
+
+# All .el files
+emacs -batch -f batch-byte-compile *.el
+
+# With Eask
+eask compile
+```
+
+### Common Warnings
+
+#### Undefined Functions
+
+```elisp
+;; Warning: function `some-func' is not known to be defined
+
+;; Fix 1: Require the package
+(require 'some-package)
+
+;; Fix 2: Declare function
+(declare-function some-func "some-package" (arg1 arg2))
+
+;; Fix 3: Suppress if intentional
+(with-no-warnings
+  (some-func args))
+```
+
+#### Unused Variables
+
+```elisp
+;; Warning: Unused lexical variable `unused'
+
+;; Fix: Use underscore prefix
+(defun my-func (_unused arg)
+  (do-something arg))
+```
+
+#### Free Variables
+
+```elisp
+;; Warning: reference to free variable `undefined-var'
+
+;; Fix: Declare or define
+(defvar undefined-var nil
+  "Documentation for the variable.")
+```
+
+## elisp-lint (Comprehensive)
+
+### Installation
+
+```elisp
+;; In Eask
+(development
+ (depends-on "elisp-lint"))
+```
+
+### Run
+
+```bash
+# With Eask
+eask lint elisp-lint
+
+# Direct
+elisp-lint my-package.el
+```
+
+### Configure
+
+```elisp
+;; .elisp-lint.yml (if using directly)
+```
+
+elisp-lint includes:
+- checkdoc
+- package-lint
+- byte-compile checks
+- indentation
+- trailing whitespace
+
+## Flycheck (Real-time Linting)
+
+### Setup
+
+```elisp
+(use-package flycheck
+  :ensure t
+  :init (global-flycheck-mode)
+  :config
+  (setq flycheck-emacs-lisp-load-path 'inherit))
+
+;; Add checkers
+(use-package flycheck-package
+  :ensure t
+  :after flycheck
+  :config
+  (flycheck-package-setup))
+```
+
+### Checkers
+
+- `emacs-lisp` - Byte compilation
+- `emacs-lisp-checkdoc` - Docstrings
+- `emacs-lisp-package` - Package headers
+
+## Eask Linting
+
+### Eask File
+
+```elisp
+(package "my-package" "0.1.0" "Description")
+
+(script "lint" "eask lint package checkdoc")
+(script "lint:all" "eask lint package checkdoc elisp-lint")
+
+(development
+ (depends-on "package-lint")
+ (depends-on "elisp-lint"))
+```
+
+### Run
+
+```bash
+# Run configured lint script
+eask run lint
+
+# Individual linters
+eask lint package
+eask lint checkdoc
+eask lint elisp-lint
+
+# All together
+eask lint package checkdoc elisp-lint
+```
+
+## CI/CD Linting
+
+### GitHub Actions
+
+```yaml
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: jcs090218/setup-emacs@master
+        with:
+          version: '29.2'
+
+      - uses: emacs-eask/setup-eask@master
+
+      - name: Install dependencies
+        run: eask install-deps --dev
+
+      - name: Lint package
+        run: eask lint package
+
+      - name: Check documentation
+        run: eask lint checkdoc
+
+      - name: Byte compile
+        run: eask compile
+
+      - name: Comprehensive lint
+        run: eask lint elisp-lint
+```
+
+## Fix Common Issues
+
+### Indentation
+
+```bash
+# Auto-indent file
+emacs -batch my-package.el \
+  --eval '(indent-region (point-min) (point-max))' \
+  -f save-buffer
+
+# Or in Emacs
+M-x mark-whole-buffer
+M-x indent-region
+```
+
+### Trailing Whitespace
+
+```bash
+# Remove trailing whitespace
+emacs -batch my-package.el \
+  --eval '(delete-trailing-whitespace)' \
+  -f save-buffer
+
+# Or in Emacs
+M-x delete-trailing-whitespace
+```
+
+### Auto-format
+
+```elisp
+;; Auto-remove trailing whitespace on save
+(add-hook 'before-save-hook #'delete-trailing-whitespace)
+
+;; Auto-indent on save
+(add-hook 'emacs-lisp-mode-hook
+          (lambda ()
+            (add-hook 'before-save-hook
+                      (lambda ()
+                        (when (eq major-mode 'emacs-lisp-mode)
+                          (indent-region (point-min) (point-max))))
+                      nil t)))
+```
+
+## Pre-commit Hook
+
+**.git/hooks/pre-commit**:
+
+```bash
+#!/bin/bash
+
+echo "Running lint checks..."
+
+# Check if eask is available
+if command -v eask &> /dev/null; then
+    eask lint package checkdoc || exit 1
+    eask compile || exit 1
+else
+    echo "Eask not found, skipping lint"
+fi
+
+exit 0
+```
+
+Make executable:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+## Best Practices
+
+1. **Lint before committing**: Catch issues early
+2. **Fix all warnings**: Don't ignore byte-compile warnings
+3. **Complete docstrings**: Document all public functions
+4. **Consistent naming**: Use package prefix everywhere
+5. **CI integration**: Automate linting in CI
+6. **Use lexical binding**: Always `;;; -*- lexical-binding: t -*-`
+7. **Check MELPA compliance**: Use package-lint
+8. **Clean code**: No trailing whitespace
+9. **Proper indentation**: Use Emacs auto-indent
+10. **Declare dependencies**: List all Package-Requires
+
+## Quick Checklist
+
+Before publishing:
+
+- [ ] `eask lint package` passes
+- [ ] `eask lint checkdoc` passes
+- [ ] `eask compile` completes without warnings
+- [ ] All functions have docstrings
+- [ ] All variables have docstrings
+- [ ] Package headers complete and correct
+- [ ] Lexical binding enabled
+- [ ] All symbols properly prefixed
+- [ ] No trailing whitespace
+- [ ] Proper indentation
+- [ ] Tests pass
+
+## Resources
+
+- [package-lint](https://github.com/purcell/package-lint)
+- [checkdoc Manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html)
+- [Flycheck](https://www.flycheck.org/)
+- [elisp-lint](https://github.com/gonewest818/elisp-lint)

@@ -0,0 +1,568 @@
+# Package Workflow
+
+Create well-structured Emacs Lisp packages following modern conventions and MELPA requirements.
+
+## Package Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Single-file** | One `.el` file | simple-mode.el |
+| **Multi-file** | Multiple `.el` files | magit (magit.el, magit-*.el) |
+| **With dependencies** | Requires other packages | Uses Package-Requires |
+
+## Creating a Package
+
+### Step 1: Initialize with Eask
+
+```bash
+# Create package directory
+mkdir my-package
+cd my-package
+
+# Initialize Eask project
+eask init
+
+# This creates:
+# - Eask file
+# - my-package.el (with template)
+# - .gitignore
+```
+
+### Step 2: Package File Structure
+
+**my-package.el** (main file):
+
+```elisp
+;;; my-package.el --- Brief description  -*- lexical-binding: t -*-
+
+;; Copyright (C) 2025 Your Name
+
+;; Author: Your Name <your.email@example.com>
+;; Version: 0.1.0
+;; Package-Requires: ((emacs "29.1"))
+;; Keywords: convenience, tools
+;; URL: https://github.com/yourusername/my-package
+;; SPDX-License-Identifier: GPL-3.0-or-later
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Longer description of what this package does.
+;;
+;; Usage:
+;;
+;;     (require 'my-package)
+;;     (my-package-enable)
+;;
+;; Customization:
+;;
+;;     (setq my-package-option value)
+
+;;; Code:
+
+(require 'cl-lib)  ; If using cl-lib functions
+
+(defgroup my-package nil
+  "Customization group for my-package."
+  :group 'tools
+  :prefix "my-package-"
+  :link '(url-link "https://github.com/yourusername/my-package"))
+
+(defcustom my-package-enable-feature t
+  "Whether to enable the feature."
+  :type 'boolean
+  :safe #'booleanp
+  :group 'my-package)
+
+;;;###autoload
+(defun my-package-enable ()
+  "Enable my-package."
+  (interactive)
+  (my-package-mode 1)
+  (message "My Package enabled"))
+
+(defvar my-package-mode-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map (kbd "C-c m t") #'my-package-toggle)
+    map)
+  "Keymap for `my-package-mode'.")
+
+;;;###autoload
+(define-minor-mode my-package-mode
+  "Minor mode for my-package."
+  :lighter " MyPkg"
+  :keymap my-package-mode-map
+  :global t
+  :group 'my-package
+  (if my-package-mode
+      (my-package--enable)
+    (my-package--disable)))
+
+(defun my-package--enable ()
+  "Internal function to enable my-package."
+  ;; Setup code here
+  )
+
+(defun my-package--disable ()
+  "Internal function to disable my-package."
+  ;; Cleanup code here
+  )
+
+(provide 'my-package)
+;;; my-package.el ends here
+```
+
+### Step 3: Eask Configuration
+
+**Eask** file:
+
+```elisp
+(package "my-package"
+         "0.1.0"
+         "Brief description of my package")
+
+(website-url "https://github.com/yourusername/my-package")
+(keywords "convenience" "tools")
+
+(package-file "my-package.el")
+
+(script "test" "echo \"Run tests..\" && eask test ert")
+(script "lint" "echo \"Linting..\" && eask lint package checkdoc")
+(script "ci" "eask install-deps && eask compile && eask test && eask lint")
+
+(source "gnu")
+(source "melpa")
+
+(depends-on "emacs" "29.1")
+;; Add package dependencies here
+;; (depends-on "dash")
+
+(development
+ (depends-on "ert-runner")
+ (depends-on "package-lint"))
+```
+
+### Step 4: Tests
+
+**my-package-test.el**:
+
+```elisp
+;;; my-package-test.el --- Tests for my-package  -*- lexical-binding: t -*-
+
+(require 'ert)
+(require 'my-package)
+
+(ert-deftest my-package-test-enable ()
+  "Test that enabling works."
+  (my-package-mode 1)
+  (should my-package-mode)
+  (my-package-mode -1)
+  (should-not my-package-mode))
+
+(ert-deftest my-package-test-function ()
+  "Test main functionality."
+  ;; Your tests here
+  (should (functionp 'my-package-enable)))
+
+(provide 'my-package-test)
+;;; my-package-test.el ends here
+```
+
+### Step 5: README.md
+
+```markdown
+# My Package
+
+Brief description of what your package does.
+
+## Installation
+
+### MELPA
+
+```elisp
+(use-package my-package
+  :ensure t)
+```
+
+### Manual
+
+Clone this repository and add to your `load-path`:
+
+```elisp
+(add-to-list 'load-path "/path/to/my-package")
+(require 'my-package)
+```
+
+## Usage
+
+```elisp
+;; Enable my-package
+(my-package-enable)
+
+;; Or use minor mode
+(my-package-mode 1)
+```
+
+## Configuration
+
+```elisp
+(setq my-package-enable-feature nil)
+```
+
+## License
+
+GPL-3.0-or-later
+```
+
+## Multi-file Package
+
+For larger packages with multiple files:
+
+### Structure
+
+```
+my-package/
+├── my-package.el          # Main entry point
+├── my-package-core.el     # Core functionality
+├── my-package-ui.el       # UI components
+├── my-package-utils.el    # Utilities
+├── test/
+│   ├── my-package-test.el
+│   └── my-package-core-test.el
+├── Eask
+└── README.md
+```
+
+### Main File (my-package.el)
+
+```elisp
+;;; my-package.el --- Main entry point  -*- lexical-binding: t -*-
+
+;; [Headers as before]
+
+;;; Code:
+
+(require 'my-package-core)
+(require 'my-package-ui)
+(require 'my-package-utils)
+
+;;;###autoload
+(defun my-package-setup ()
+  "Set up my-package."
+  (interactive)
+  (my-package-core-initialize)
+  (my-package-ui-setup))
+
+(provide 'my-package)
+;;; my-package.el ends here
+```
+
+### Submodule (my-package-core.el)
+
+```elisp
+;;; my-package-core.el --- Core functionality  -*- lexical-binding: t -*-
+
+;; Copyright (C) 2025 Your Name
+;; Author: Your Name <your.email@example.com>
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Core functionality for my-package.
+
+;;; Code:
+
+(defun my-package-core-initialize ()
+  "Initialize core functionality."
+  ;; Implementation
+  )
+
+(provide 'my-package-core)
+;;; my-package-core.el ends here
+```
+
+## Package Headers Reference
+
+### Required Headers
+
+```elisp
+;; Author: Your Name <email@example.com>
+;; Version: 0.1.0
+;; Package-Requires: ((emacs "29.1"))
+;; Keywords: convenience tools
+;; URL: https://github.com/user/repo
+```
+
+### Optional Headers
+
+```elisp
+;; Maintainer: Different Person <maintainer@example.com>
+;; Created: 2025-01-01
+;; SPDX-License-Identifier: GPL-3.0-or-later
+;; Homepage: https://mypackage.example.com
+```
+
+### Keywords
+
+Standard keywords (for `M-x finder-by-keyword`):
+
+- `abbrev` - Abbreviation handling
+- `calendar` - Calendar and diary
+- `comm` - Communications
+- `convenience` - Convenience features
+- `data` - Data manipulation
+- `docs` - Documentation
+- `emulations` - Emulations of other editors
+- `extensions` - Emacs Lisp language extensions
+- `faces` - Fonts and faces
+- `files` - File handling
+- `frames` - Frame manipulation
+- `games` - Games
+- `hardware` - Hardware support
+- `help` - Help and documentation
+- `hypermedia` - Hypermedia
+- `i18n` - Internationalization
+- `internal` - Internal use
+- `languages` - Programming languages
+- `lisp` - Lisp support
+- `local` - Local customization
+- `maint` - Maintenance tools
+- `mail` - Mail handling
+- `matching` - Pattern matching
+- `mouse` - Mouse support
+- `multimedia` - Multimedia
+- `news` - News handling
+- `outlines` - Outline mode
+- `processes` - Process control
+- `terminals` - Terminal emulation
+- `tex` - TeX and friends
+- `tools` - Programming tools
+- `unix` - Unix features
+- `vc` - Version control
+- `wp` - Word processing
+
+## Common Patterns
+
+### Customization Group
+
+```elisp
+(defgroup my-package nil
+  "Customization for my-package."
+  :group 'tools
+  :prefix "my-package-"
+  :link '(url-link :tag "GitHub" "https://github.com/user/my-package"))
+
+(defcustom my-package-directory "~/.my-package"
+  "Directory for my-package data."
+  :type 'directory
+  :group 'my-package)
+
+(defcustom my-package-backends '(backend1 backend2)
+  "List of backends to use."
+  :type '(repeat (choice (const :tag "Backend 1" backend1)
+                         (const :tag "Backend 2" backend2)))
+  :group 'my-package)
+```
+
+### Faces
+
+```elisp
+(defface my-package-highlight
+  '((t :inherit highlight))
+  "Face for highlighted items."
+  :group 'my-package)
+
+(defface my-package-error
+  '((t :inherit error))
+  "Face for errors."
+  :group 'my-package)
+```
+
+### Hooks
+
+```elisp
+(defvar my-package-mode-hook nil
+  "Hook run after `my-package-mode' is enabled.")
+
+(defvar my-package-before-process-hook nil
+  "Hook run before processing.")
+
+;; Run hooks
+(run-hooks 'my-package-mode-hook)
+```
+
+### Autoloads
+
+```elisp
+;;;###autoload
+(defun my-package-enable ()
+  "Enable my-package globally."
+  (interactive)
+  (my-package-mode 1))
+
+;;;###autoload
+(add-to-list 'auto-mode-alist '("\\.mypkg\\'" . my-package-mode))
+```
+
+## Development Workflow
+
+### 1. Install Dependencies
+
+```bash
+eask install-deps
+```
+
+### 2. Byte Compile
+
+```bash
+eask compile
+```
+
+### 3. Run Tests
+
+```bash
+eask test ert
+```
+
+### 4. Lint
+
+```bash
+eask lint package
+eask lint checkdoc
+```
+
+### 5. Package
+
+```bash
+eask package
+```
+
+Output: `dist/my-package-0.1.0.tar`
+
+## CI/CD with GitHub Actions
+
+**.github/workflows/test.yml**:
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        emacs-version: ['29.1', '29.2', 'snapshot']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: jcs090218/setup-emacs@master
+        with:
+          version: ${{ matrix.emacs-version }}
+
+      - uses: emacs-eask/setup-eask@master
+        with:
+          version: 'snapshot'
+
+      - name: Install dependencies
+        run: eask install-deps
+
+      - name: Byte compile
+        run: eask compile
+
+      - name: Run tests
+        run: eask test ert
+
+      - name: Lint
+        run: |
+          eask lint package
+          eask lint checkdoc
+```
+
+## Versioning
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Incompatible API changes
+- **MINOR**: Add functionality (backwards-compatible)
+- **PATCH**: Bug fixes (backwards-compatible)
+
+Example: `1.2.3` → MAJOR.MINOR.PATCH
+
+### Update Version
+
+```bash
+# In my-package.el header
+;; Version: 1.0.0
+
+# In Eask
+(package "my-package" "1.0.0" "Description")
+
+# Create git tag
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```
+
+## Common Issues
+
+### Package-Requires Format
+
+```elisp
+;; Correct
+;; Package-Requires: ((emacs "29.1") (dash "2.19.1"))
+
+;; Wrong - no spaces
+;; Package-Requires: ((emacs "29.1")(dash "2.19.1"))
+
+;; Wrong - single dep not in list
+;; Package-Requires: (emacs "29.1")
+```
+
+### Lexical Binding
+
+Always use:
+
+```elisp
+;;; my-package.el --- Description  -*- lexical-binding: t -*-
+```
+
+### Provide Statement
+
+Must match filename:
+
+```elisp
+;; File: my-package.el
+(provide 'my-package)  ; Correct
+
+;; File: my-package.el
+(provide 'my-pkg)  ; Wrong!
+```
+
+## Best Practices
+
+1. **Use lexical binding**: `;;; -*- lexical-binding: t -*-`
+2. **Follow naming conventions**: All symbols prefixed with package name
+3. **Complete headers**: All required headers present
+4. **Autoloads**: Mark entry points with `;;;###autoload`
+5. **Tests**: Write tests for all functionality
+6. **Documentation**: Complete docstrings for all public functions
+7. **Version control**: Use git, tag releases
+8. **CI**: Set up automated testing
+9. **CHANGELOG**: Maintain version history
+10. **License**: Include GPL-compatible license
+
+## Resources
+
+- [Emacs Package Development](https://www.gnu.org/software/emacs/manual/html_node/elisp/Packaging.html)
+- [MELPA Contributing Guide](https://github.com/melpa/melpa/blob/master/CONTRIBUTING.org)
+- [Eask Documentation](https://emacs-eask.github.io/)
+- [Package Lint](https://github.com/purcell/package-lint)