summaryrefslogtreecommitdiff
path: root/docs
Commit message (Collapse)AuthorAgeFilesLines
* docs(ai-kb): fold in review 6 and resolve the build-time decisionsCraig Jennings13 days1-28/+74
| | | | | | The latest design review was a UX and performance pass, and I folded its findings into the spec and the implementation tasks. The important one: human Emacs edits now use the same write path as agent writes. An ai-kb minor mode runs index, full lint, and commit under flock on after-save, so a hand edit can't quietly skip the safety gate. The rest: the generated index.org is now invisible to backlink and orphan logic (excluded from the scan, referenced as plain text rather than id-links), a required :SUMMARY: property feeds the index and query without inference, query gains lexical ranking with recency only as a tie-break, the switch installs a full org-roam profile rather than a two-variable swap, and the browsing surface (dashboard, find, search, show, backlinks, map) is named. I also answered the six build-time decisions: concrete raw and curation limits, performance budgets for the perf fixtures, the lexical scoring weights, org-roam-graph as the first map implementation, the after-save failure UX (the save always lands, the commit is gated, and a failure shows without trapping the buffer), and the after-save recursion guard. The numeric limits and budgets are starting points to calibrate. The rest are firm. Step 1 stays buildable.
* docs(design): incorporate ai-kb review 5Craig Jennings13 days1-21/+38
| | | | | | Review 5 was implementation-hardening, all of it sound, so I folded in all six findings. The important one: the commit gate now runs the full ai-kb lint over the change (index freshness, duplicate IDs, broken links, and a secret scan of nodes and raw/), not just org-lint on the edited node. If the write path is the safety boundary, gating only on single-node syntax would let a stale index or a leaked secret through. The rest, all adopted: an explicit org-lint fatal-check list so a future org-lint change can't silently move the gate, observable push failures surfaced through a state-file log and ai-kb doctor and a startup nudge so the KB can't go quietly local-only, a testable ai-kb query contract with text and --json output, and ID-first durable pointers since filenames change in curation but IDs don't. I also split the build plan into Step 1a (the safe write path) and 1b (query, curate, sync, push timer, workflow), since remember depends on index and lint and the adapter depends on remember.
* docs(design): resolve ai-kb open decisions and refresh provisioningCraig Jennings13 days1-10/+11
| | | | | | I resolved the four open decisions and baked the answers in: the store lives at ~/.local/share/ai-kb (XDG), the ai-kb CLI is a shell wrapper that calls emacs --batch for the org-lint and sync steps, the push runs off a background systemd --user timer rather than firing on every write (remember only commits locally), and curation is node-count-triggered with the workflow living in the rulesets .ai/workflows/ directory. I also refreshed the provisioning and Step 1 sections to match, since the push timer was a new piece: make ai-kb-init now installs and enables the ai-kb-push timer and service units, and doctor checks for them. Open decisions is empty now and the spec is fully decided.
* docs(design): fold ai-kb reviews 3-4 into the specCraig Jennings13 days1-115/+151
| | | | | | Reviews 3 (Codex, via Nexus/GraphRAG/Letta research) and 4 pushed on the write loop and the access layer rather than scope. I folded both in. The write path is now a real protocol: fetch and fast-forward before writing, org-lint the node, regenerate the index, commit locally always, and treat the push as best-effort and non-blocking so a failed push never errors or hangs the agent. That's the exact gpg-agent failure we hit earlier today. The index is regenerated from node properties by a script rather than hand-maintained, so it can't drift from the nodes. The access layer became an agent-neutral contract that lives in the repo, fronted by a minimal ai-kb CLI (doctor, query, remember, lint, curate, sync) with destructive operations human-only. That earns its place on Claude-only grounds: it's the clean home for the safe-write protocol and the lint and index steps. Cross-agent use is not a near-term goal, so Codex and Ollama adapters are deferred to vNext. The contract stays neutral in shape, so they're additive later. Added provenance fields, the T1/T2/T3 tier names, and the review dispositions. The spec is now Ready.
* docs(design): add ai-kb spec — global org-roam memory store for the agentCraig Jennings13 days1-0/+244
| | | | | | ai-kb is a global, durable, cross-project memory store for Claude Code: org-roam nodes holding lessons, principles, my preferences, and reusable procedures, distinct from the per-project memory files (which shrink to an index pointing into it). The spec covers the two-layer model (a git-versioned file store the agent reads/writes, and an Emacs switch command so I can browse it with backlinks), the sync model, the routing and proactive-write rules, the node format, and the startup retrieval contract. It folds in two reviews. The scope decision: v1 is the memory store, not a full Karpathy LLM Wiki. The heavy machinery (compiled wiki layer, source hashes, formal ingest pipeline, embedding search) is deferred to vNext, each with a reason. Storage is a dedicated private git repo at an XDG path rather than Syncthing or the public emacs-config repo, which would leak personal notes. Two Karpathy ideas earned their way into v1 because they pay off now: capturing the raw source when a node is compiled from external material, and an org-lint validity check on every write so malformed org never reaches the index. Review dispositions and the open decisions are recorded in the spec.
* docs(mail): document compose-buffer cleanup settingsCraig Jennings14 days1-0/+63
| | | | I added docs/mu4e-org-msg-compose-buffer-cleanup.org explaining the one setting that controls whether mail compose buffers close on exit (message-kill-buffer-on-exit), why org-msg needs no setting of its own (it reads the variable, never sets it), and the trap that a stray setter in org-msg's :config silently wins over the mu4e one.
* feat(calendar-sync): add Python helper for Google Calendar API syncCraig Jennings2026-05-191-0/+171
| | | | | | | | | | | | Google's .ics export drops per-occurrence response statuses on recurring events. When OOO auto-declines a meeting, the master event keeps PARTSTAT=ACCEPTED and declined instances inherit it. The .ics path can't filter the declines out. The API path expands recurrences server-side via singleEvents=True, and each occurrence carries its own attendees[].self.responseStatus. scripts/calendar_sync_api.py fetches events and renders them as org entries. OAuth is one-time per account. The refresh token lives at ~/.config/calendar-sync/token-<account>.json under 0600. Output matches the existing .ics shape: heading sanitization, LOCATION/ORGANIZER/STATUS/URL property drawer, HTML-stripped descriptions, org timestamps with weekday abbreviations. I wrote 30 stdlib-unittest tests against fixture JSON, covering rendering, filtering, timestamp formatting, and HTML cleanup. I left auth and HTTP uncovered — they're thin wrappers around the Google client libraries, best checked by running the script once after OAuth setup. docs/calendar-sync-api-setup.org walks through the Google Cloud OAuth client setup and the per-account auth bootstrap. .gitignore picks up Python bytecode now that the project has a Python helper. The Elisp dispatch (:fetcher 'api routing in calendar-sync.el) lands in a follow-up commit.
* docs(design): keep local gptel-magit design draft as .local.orgCraig Jennings2026-05-171-0/+592
| | | | Two drafts of `docs/design/gptel-git-tools-magit-backend.org` existed at the same path: a 592-line local copy and the 192-line upstream version that just landed in main. I renamed the local draft to `.local.org` so the upstream version can sit at the canonical path. I'll reconcile the two in a follow-up.
* docs(design): MCP-into-gptel + gh-as-gptel-tool specs + MCP phasesCraig Jennings2026-05-172-0/+2495
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Two new design docs in docs/design/ covering the next two GPTel work items, plus matching task scaffolding in todo.org. mcp-el-gptel-integration.org wires mcp.el into the config so GPTel gets access to the nine MCP servers Claude Code already uses (linear, notion, figma, slack-deepsat, drawio, google-calendar, google-docs-personal, google-docs-work, google-keep). The design covers async startup, the write-confirmation policy, a server-enablement defcustom, a doctor with live-auth-check, the audit buffer, and the mcp.el compatibility layer. The spec is at revision 3 after two code-review passes flagged a critical confirmation gap (gptel-confirm-tool-calls nil at ai-config.el:386 silently ignored per-tool :confirm slots) and several incorrect mcp.el API assumptions. Both are addressed. gptel-gh-tool.org wraps the gh CLI as a hybrid surface: 14 typed read wrappers plus one general write tool gated by :confirm t. Host/repo resolution is command-aware: --repo HOST/OWNER/REPO for repo commands, --hostname only for api and auth status. The runner enforces an irreversible-command blocklist, a 64KB in-flight output cap, and a debug-record plus last-error-buffer story. The spec is at revision 2 after a code-review pass corrected gh flag assumptions and reframed the safety story around per-tool confirm. todo.org gains a link to the MCP spec under the parent task plus nine TODO sub-tasks (one per implementation phase), and a new gh-tool TODO with the same spec-link shape.
* fix(coverage): include gptel-tools in instrumentation globCraig Jennings2026-05-161-0/+31
| | | | | | | | | | | | | | | | Undercover now instruments gptel-tools/*.el alongside modules/*.el, so the new git_status / git_log / git_diff / web_fetch tools (and their successors) report coverage instead of reading as zero. The matching pre-coverage clean step deletes gptel-tools/*.elc so stale byte-compiled artifacts don't shadow the .el sources. If Emacs loads the .elc first, undercover's source instrumentation never runs. docs/design/coverage.org gains an Elisp-coverage-producer subsection documenting the glob, the :merge-report dependence (SimpleCov merges cross-process reports, LCOV does not), and the missing-artifact failure mode.
* docs(design): network tools brainstorm + GPTel Tool Work hierarchyCraig Jennings2026-05-161-0/+407
| | | | | | | | | | | | | | | | Adds docs/design/gptel-network-tools.org capturing the brainstorm output for the next gptel-tools batch -- net_diagnose, net_discover, net_services, network_status, dns_lookup -- with argv shapes, target-gating guardrails for nmap, and a ~47-test sketch. Restructures the GPTel Tool Work parent in todo.org with seven themed categories: Git, Org, messaging, file/buffer, filesystem, media / reading, and dev workflow. Each carries a body framing the design choice and stub child themes. Filesystem covers the pandoc / imagemagick / ffmpeg / ripgrep / fd / file+exiftool / jq+yq surface plus an eshell escape hatch. Per-theme spec lands in the task body once written. Implementation tasks join as siblings once the spec is approved.
* docs(design): three new gptel / agentic design notesCraig Jennings2026-05-163-0/+448
| | | | | | | | | | | - gptel-git-tools-magit-backend.org -- spec for reimplementing the three current git_* tools on top of magit, plus three new tools (blame, show, branches). - gptel-agentic-tool-ideas.org -- brainstorm seed for additional agentic gptel tools. - agentic-knowledgebase.org -- design sketch for using org-roam as the agent's durable project memory with org-agenda as the execution layer.
* docs(gptel): add shortlist design doc for additional gptel toolsCraig Jennings2026-05-161-0/+205
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The Gptel Work project asked for a survey of published gptel tools with adopt / skip / defer decisions per candidate. I can't do a live community-tool survey from this session, so the doc covers the candidates the task body called out plus a few obvious adjacents. Decisions: - ADOPT (7): `search_in_files`, `git_status` / `git_log` / `git_diff` (three tools), `web_fetch`, `search_emacs_help`, `find_file_by_name`, `take_screenshot`. Each gets a sketch in the doc -- args, validation posture, implementation outline. - DEFER (2): `run_shell_command` (huge surface, click-fatigue risk; the ADOPT-bucket tools cover most legit use cases), `org_capture` (needs UX design for template pre-fill and the round-trip). - SKIP (1): `eval_elisp` (code execution from a model is too dangerous even with confirm-each-call). The doc also lists three follow-ups: the live community survey that this session couldn't do, per-tool implementation sub-tasks to be filed under the next iteration of Gptel Work, and a sandboxing-convention decision for `web_fetch` (allowlist of outbound URLs vs description-only warning). Three open questions at the bottom of the doc for review: build-all-at-once vs paired stages, `fd` as a hard dep vs `find` fallback, Hyprland-only screenshot vs Wayland-generic via a portal. Closes the Gptel Work PROJECT for this iteration -- all 9 in-scope sub-tasks landed this session.
* docs(design): commit music-config-without-emms spec + readiness reviewCraig Jennings2026-05-152-0/+842
| | | | | | | | | | | | | | | | | | | | | | | | | | | The spec lays out the EMMS-removal design: package-owned track and playlist structs, a narrow backend protocol with mpv as the v1 backend, state-change hooks replacing EMMS player hooks, an overlay-based selected-track marker, a fake-backend test architecture, a quantified performance budget, a 22-step parity walk, and the migration plan. The review tracks implementation readiness: which migration-plan step is safe to start, which decisions still block the rest, and the exact spec edits required. Two decisions landed this session and are now baked into the spec: - Platform support: Linux and macOS get full features; Windows runs in degraded mode (play/stop/next/previous only) because Emacs cannot natively connect to mpv's Windows named-pipe IPC. Anyone who wants full Windows parity can wire mpvc.exe shellout or a w32-* named-pipe client as a follow-up. - File-extension scope: cj/music-file-extensions stays as-is. webm and ape files in ~/music are intentionally skipped. Socket path now references temporary-file-directory instead of a hardcoded /tmp/ prefix so the spec stays consistent with the Windows section.
* docs(design): rewrite flycheck modeline customization specCraig Jennings2026-05-151-0/+315
| | | | | | | | | | | | | | | | | | Replaces the .ai/ draft (2025-11-14) with a corrected and tightened version under docs/design/. The earlier draft had stale line numbers pointing at a modeline-config.el layout that no longer exists, conflated Option 3's risky-local-variable requirement with Option 4's inline (:eval ...) approach, and missed the active-window gating convention used by the rest of the modeline. The new spec uses concrete line refs against current code, calls out flycheck-mode-line-color (which the old draft missed), recommends calling flycheck-mode-line-status-text directly instead of returning the nested (:eval ...) cons, and gates the segment to active window for consistency with cj/modeline-vc-branch and cj/modeline-misc-info. todo.org task points at the new path and drops the broken docs/flycheck-modeline-customization-spec.org link.
* docs(design): add company-to-corfu migration specCraig Jennings2026-05-151-0/+324
| | | | | | | | | | | | | | | | | | Replaces a thin third-party config snippet (one use-package corfu + one use-package cape, with no migration steps and no prescient piece) with a full spec covering the current company stack: corfu, cape, corfu-popupinfo, kind-icon, corfu-prescient. Maps every current company setting to its corfu equivalent (idle-delay, prefix-length, tooltip-limit, wrap, require-match, global-mode exclusions, doc popups, icon kinds, prescient sort). Walks the per-module fixups -- selection-framework, mail-config, ledger-config, latex-config, eshell-config, and the three prog-* mode hooks. Adds a test plan and risks section. todo.org points at the new doc; the broken :COMPLETE_CONFIG: property (which referenced the wrong line range in someday-maybe) is gone.
* chore(todo): close Python tree-sitter predicate bug as upstream-resolvedCraig Jennings2026-05-141-0/+23
| | | | | | | | | | | | | | | | | | | | The treesit-query-error redisplay flood diagnosed 2026-04-26 no longer reproduces. Versions: emacs 30.2-3 (was 30.2-2 at the time of the investigation, upgraded 2026-05-03), tree-sitter 0.26.8 (unchanged). The upstream Emacs version string is unchanged, but the Arch package revision bump most likely carries a downstream patch to treesit.c's predicate translation. Verified by re-running the documented repro: the exact failing query from python.el captures cleanly via `treesit-query-capture', and `font-lock-ensure' on a real .py file under `python-ts-mode' returns with no `treesit-query-error'. No local override needed. Mark the todo.org entry DONE, fix the stale `inbox/' path on the investigation-doc link (file now lives under `docs/'), update the cross-reference from the grammar-bootstrap task to note this no longer blocks it, and append a RESOLVED 2026-05-14 footer to the investigation doc so future-me can see why it got closed.
* docs: add Python tree-sitter font-lock predicate-mismatch diagnosticCraig Jennings2026-05-111-0/+196
| | | | Pins down why every Python buffer fires `treesit-query-error` on redisplay: Emacs 30.2 emits `#match` predicates, but tree-sitter 0.26 only accepts `#match?`. The doc has the reproduction, the six fix options with their trade-offs, and the verification path. The next pass picks up at decision-time instead of re-deriving the cause.
* docs(design): add Phase 5 cache helper design addendumCraig Jennings2026-05-101-0/+165
| | | | | | | | Per Phase 5 step 1 of utility-consolidation. Specifies the cache API to extract from org-agenda-config and org-refile-config (both have parallel TTL+building-guard implementations today). Documents the API: `cj/cache-make', `cj/cache-valid-p', `cj/cache-value-or-rebuild', `cj/cache-building-p', `cj/cache-invalidate'. Out-of-scope: modeline VC cache (buffer-local + key-based, not TTL). Per the spec, that's a future round. Documents the migration order (agenda first, refile second), test plan for the helper, and risk notes (cache-hit logging preservation, building-flag leak guard, async-timer interaction).
* docs: update test and coverage documentationCraig Jennings2026-05-101-20/+33
|
* docs(design): add Phase 1 utility inventoryCraig Jennings2026-05-101-0/+160
| | | | | | | | | | Phase 1 of utility-consolidation per docs/design/utility-consolidation.org. The inventory walks the spec's 30-entry Candidate Extraction Table and, for each helper, records: visibility, dependencies, side effects, callers in modules and tests, test file location, extraction priority, and a Migrate / Leave / Defer decision with rationale. Decisions: 11 Migrate, 3 Leave, 13 Defer. The Migrate items are grouped by phase in the spec's recommended order: Phase 2 (foundation helpers -- executable lookup, shell quoting, process runner, file-from-context), Phase 3 (Org-safe text sanitizers), Phase 4 (external-open consolidation). The Defer items mostly need a second production caller before promotion is justified. Discoveries worth recording: `cj/log-silently' already has 10 production callers (more than the spec's table suggested), and `cj/--file-manager-program-for' shipped today in dirvish-config.el is the new form of OS-dispatch consolidation -- Phase 4's `cj/external-open-command' should fold it in rather than re-deriving. No code behavior changes -- this is the spec's stated Phase 1 exit criterion.
* fix(ai-vterm): direction-based display + per-project tmux session namesCraig Jennings2026-05-071-1/+14
| | | | | | | | | | | | Two post-ship issues blocked practical use of the new launcher. The display rule used `display-buffer-in-side-window` with `(dedicated . t)`. Side-window dedication caused `set-window-buffer` to error during `buffer-move` (C-M-arrows), which left a half-finished swap with both sides showing the claude buffer. Then `switch-to-buffer` on a non-claude buffer in that dedicated window split instead of replacing. I rewrote the rule as `display-buffer-reuse-window -> display-buffer-use-some-window -> display-buffer-in-direction (right)`. The resulting window is ordinary, not dedicated, so swap and replace work normally. I also narrowed `vterm-toggle`'s broad lambda (which matches any vterm-mode buffer) to exclude `claude [` buffers. Otherwise vterm-toggle's `:defer` made it install last and capture our buffers first with its own bottom-split + dedicated treatment. The tmux side: vterm's auto-launch hook ran a bare `tmux\n`, so each session got an auto-named one. After an Emacs crash the tmux session would survive but I couldn't find it. A second F9 just spawned another. The launcher now sends `tmux new-session -A -s <basename> -c <dir> '<claude>; exec bash'`. The `-A` reattaches to a same-named session if it already exists. The `exec bash` keeps the tmux window alive if claude itself exits. A `cj/--ai-vterm-suppress-tmux` flag tells the existing vterm hook to skip its bare tmux step so the named launch runs instead. 11 new tests across 2 files cover the session-name and launch-command helpers. I updated tests for show-or-create and the display rule. All 34 ai-vterm tests are green.
* feat(ai-vterm): add Claude launcher with vertical-split vtermCraig Jennings2026-05-071-0/+146
| | | | | | | | The new module picks a Claude-template project from a filtered completing-read list. It scans the same roots the `ai` shell launcher uses, then opens or reuses a vterm buffer named `claude [<repo>]` on the right. F9 launches it. The prior `cj/toggle-gptel` binding moves from F9 to C-F9 so both AI tools share the same physical key. The display rule chains reuse-window -> use-some-window -> in-direction (right). The resulting window isn't dedicated. That matters because side-window dedication was breaking `buffer-move` (C-M-arrows) and `switch-to-buffer` replacement on the claude buffer. I also narrowed `vterm-toggle`'s display rule to skip `claude [` buffers. Otherwise it claimed them first with its bottom-split + dedicated treatment. I added 23 tests across 5 files: the buffer-name transform, candidate walker, show-or-create dispatch, picker, and display rule. Design lives at docs/design/ai-vterm.org.
* docs: add init.el load-graph and utility-consolidation specsCraig Jennings2026-05-042-0/+2045
| | | | | | | | | | | | I added two sibling design specs in `docs/design/`: `init-load-graph.org` covers untangling `init.el` from its current "everything eager in a fixed order" shape. It defines a layered architecture (early-init / foundation / core UX / domain workflow / optional), a module category table for every required file, a per-file commentary header standard with seven required lines, a six-phase migration plan with exit criteria, and a testing strategy split into automated batch checks, manual smoke checks, and startup performance baselines via `benchmark-init`. `utility-consolidation.org` is the sibling project. It covers extracting reusable helpers from feature modules into `system-lib.el` and a small set of topic libraries (`cj-process.el`, `cj-org-text.el`, `cj-cache.el`). It includes a candidate decision criteria section, a library file header standard with worked example, a candidate extraction table with priorities and proposed names, nine helper groups with API plus behavior contracts, naming rules, migration phases, test relocation policy, and a recommended first-three-commits sequence. Both specs are draft. No code change in this commit. The two projects are intentionally separated because the load-graph project asks "when does this load?" and the consolidation project asks "who owns this helper?". Those are different questions with different rollback shapes. Implementation tracking lives in `todo.org`.
* 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