aboutsummaryrefslogtreecommitdiff
path: root/docs
Commit message (Collapse)AuthorAgeFilesLines
* docs(theme-selector): document underline and strike in the theme.json contractCraig Jennings31 hours1-1/+2
| | | | Record the two new face booleans in the README contract and the spec's state-and-export-policy block, including that the converter writes them as :underline t and :strike-through t.
* feat(theme-selector): add relative height to the package-face schemaCraig Jennings37 hours1-18/+85
| | | | | | I folded a relative height field into the tier-3 spec and brought Phase 1's schema in line. A face's height is a float multiplier off the base font (1.3 is 1.3x the running font, never a point size), so it stays portable across fonts and machines, and it's omitted from export at 1.0. The font family itself stays in font-config.el, where it belongs; the theme owns only relative size. Height is read straight off the face and does not cascade through inherit, because Emacs multiplies float heights along an inherit chain and headings should each size off the body, not compound off the level above. The org starter now seeds heading heights and the fixed-pitch inherits that keep code and tables monospace under variable-pitch prose. The self-test gained a height assertion and still reports PASS.
* docs(theme-selector): finalize package-faces spec and emit implementation tasksCraig Jennings37 hours1-8/+8
| | | | | | Craig resolved the last two opens: hybrid-and-split inventory (org/magit/elfeed bespoke first, the generated all-package inventory as a later phase) and the custom color picker built after tier 3. With inheritance already settled, the rubric moves to Ready. I emitted the phase breakdown into todo.org under Emacs Open Work: one task per implementation phase plus a test-surface task, all marked solo since each builds and self-verifies through node, headless screenshots, and import/export round-trips. A Manual testing task collects the two human judgments that aren't solo: whether the seeded package defaults look right and whether the large org and magit tables stay usable.
* docs(theme-selector): settle inheritance as model-and-override in the specCraig Jennings38 hours1-22/+29
| | | | Craig settled the inheritance question: model it rather than flatten it. Each face's resolved color shows in the table marked as inherited, the mock preview paints every face with its effective color, and overriding any face is one assignment that flips it from inherited to explicit. Export keeps the :inherit relationship for faces left alone and writes explicit attributes only for the ones overridden. Seeded defaults open showing org's real cascade. That clears one of the three open decisions; inventory split and picker timing remain.
* docs(theme-selector): incorporate Codex review into the package-faces specCraig Jennings43 hours1-11/+154
| | | | | | I ran spec-response against Codex's review. Added implementation phases, acceptance criteria, the package-face inventory source, and state/export semantics with a source field that distinguishes seeded defaults from user edits from deliberate clears. The inventory is hybrid and split: the generated all-package path is its own phase after org, magit, and elfeed, so the three bespoke apps don't wait on it and the scope-explosion risk Codex flagged stays contained. Two findings I modified with reasons in the dispositions section, the rest accepted. Renamed the spec to -spec.org for the workflow precondition. The rubric is now Ready with caveats, and three decisions stay open for me: the inheritance representation, hybrid-vs-curated-only inventory, and the custom picker timing.
* docs(theme-selector): fold first-round answers into the package-faces specCraig Jennings43 hours1-38/+186
| | | | I folded the first-round answers into the tier-3 spec. org now carries its complete defface set instead of an 18-face sample, v1 apps are org, magit, and elfeed, and the generic fallback is a fully editable table so any package can be themed. I answered the inheritance question with an optional inherit field (absolute default, opt-in cascade) and added a custom-color-picker proposal. Two decisions stay open: confirming the inheritance representation and when to build the picker.
* docs(theme-selector): spec the tier-3 package-faces sectionCraig Jennings44 hours1-0/+220
| | | | I spec'd a third tier for the tool: package-specific faces, edited one application at a time, org-mode first. It covers the app dropdown, a per-app face table, a bespoke org-document preview, the theme.json packages schema, and how the build step consumes it. It's awaiting review and ends with five open questions.
* docs(design): spec the dupre-clear contrast-first theme, add taskCraig Jennings47 hours1-0/+89
| | | | A plan for a contrast-first AAA sibling of the dupre theme. It keeps dupre's hues but builds them Prot's way, with contrast as the founding constraint, where the in-progress dupre revision is mood-first and lands at AA. The spec records the modus methodology analysis, the AA-to-AAA starting palette, the hard blue-keyword decision, and enough context to resume cold months from now. The task in Emacs Open Work links to it.
* feat(pearl): add multi-account config, rename module to pearl-configCraig Jennings3 days1-1/+1
| | | | | | The pearl package moved from a single Linear workspace to multi-account, so the config follows. pearl-accounts now declares two workspaces, one for work and one personal, each resolving its own API key from authinfo and rendering to its own Org file. pearl-default-account picks which one opens, and pearl-switch-account swaps at runtime. This replaces the old single-account setup (pearl-org-file-path plus one pearl-api-key lookup). The module file moves from linear-config.el to pearl-config.el to match the package name. init.el, the module-headers allowlist, and the module-inventory row follow the rename.
* fix(term): make F9 and F12 reach Emacs inside ghostel buffersCraig Jennings4 days1-3/+8
| | | | | | | | F9 did nothing in an agent buffer: ghostel's semi-char mode forwards every key not in ghostel-keymap-exceptions to the pty, and ghostel-semi-char-mode-map outranks the major-mode map, so the F9-family and F12 bindings I'd put in ghostel-mode-map never fired. The keys went to Claude/the shell, which ignored them. I added the F9 family (in ai-term) and F12 plus C-; (in term-config) to ghostel-keymap-exceptions and rebuilt the semi-char map with ghostel--rebuild-semi-char-keymap. add-to-list updates the list but not the already-built map, so the rebuild is what actually lets the keys through. C-; had the same latent bug for the same reason. Two regression tests assert the keys are in the exceptions and that the rebuilt semi-char map no longer forwards them. I also corrected the spec note that claimed binding in ghostel-mode-map was enough (true for vterm, wrong for ghostel) and codified the gotcha.
* feat(term): replace vterm with ghostel as the terminal engineCraig Jennings4 days3-3/+418
| | | | | | | | I swapped the terminal engine from vterm to ghostel (libghostty-vt) everywhere. term-config replaces vterm-config (the F12 terminal, the C-; x menu, tmux history capture), and ai-term replaces ai-vterm (the F9 Claude-agent launcher). ghostel renders the agent TUI without vterm's flicker under heavy streaming, and one engine now covers every terminal workflow. Two behavior changes fall out of the swap. F9 launches in a terminal frame now: ghostel renders in TTY frames, so the old GUI-only guard is gone. Terminal windows no longer dim when unfocused: ghostel resolves its palette into the native module per-terminal, so there's no per-window color hook to dim through the way vterm had. auto-dim drops its vterm color-advice path, the dashboard Terminal button launches ghostel, and the vterm and vterm-toggle packages are removed. The tmux pane-history and copy-mode machinery carried over unchanged. It keys on the pty tty, which ghostel exposes.
* docs(design): file org-roam shared-KB brainstormCraig Jennings9 days1-0/+420
|
* docs: reshape todo backlog and add buttercup evaluationCraig Jennings12 days1-0/+117
| | | | | | | | | | | | Walked the open-task backlog twice tonight. The first pass was a content audit (is each task still factually accurate?). The second was a relevance/priority review. Together they surfaced enough drift to be worth landing as one batch rather than dribbling into the next session. The audit filed three new completion-task parents, each with an audit-finding body and child-task recommendations: F-key Completion (roughly 75% shipped per evidence), Terminal GPG pinentry Completion (no trace of the prior branch on this machine, treat as fresh), and Localrepo Documentation (build is shipped, docs land in three artifacts, four gap-fix tasks spin out as siblings). Headline-indicators-wrap and Buttercup closed DONE, Rework-dev-F-keys cancelled as superseded. Manual Testing and Validation became its own top-level task with the 10 misfiled verify children moved in. Walk started tonight (tests 1 and 2 verified, two signel bugs surfaced and fixed in the same session), deferred to 2026-05-29 for the message-sending tests. The Buttercup eval doc captures the rubric I came to during the brainstorm: adopt the moment a project crosses the "test reader is no longer the test author at write-time" threshold. ERT stays the right default until then. None of my projects have crossed yet. Lint pass resolved all 21 org-lint follow-ups inline rather than letting them accumulate in a hidden inbox: 5 wrong-prefix design-doc links (../docs/design/X.org should have been docs/design/X.org), 4 file:line bare references wrapped in code formatting, 1 timestamp moved out of org-link brackets, 1 nested src block converted to begin_example, the wttrin diagnostic's stale link replaced with a note about where the surviving record lives, 8 markdown-bold patterns converted to org italics, 2 verbatim ** TODO references trimmed so the linter stops misreading them as headings.
* docs(signel): harden initiate-message spec to ReadyCraig Jennings13 days2-4/+233
| | | | | | | | | | | | | | | | I wrote an initiate-message workflow spec on top of the existing Signal client design doc, covering the keymap, name-based picker, message-to-self, and the whole flow. A follow-up review caught three blockers I'd hand-waved: signel had no JSON-RPC success-result dispatch path (so cj/signel--fetch-contacts couldn't actually receive listContacts results), D4's "auto-connect when linked" didn't define what "linked" meant or how process death surfaced, and the contact cache had no ownership or invalidation story. I verified the central one against the fork. signel--dispatch handles only "receive" and error responses, so success results were dropped. Then I folded all three into an Architecture additions subsection: a request-callback table keyed by JSON-RPC id with cleanup on success/error/reconnect, a cj/signel--ensure-started contract with branches for live process / account-set / account-nil, and a cj-owned cj/signel--contact-cache separate from signel's receive-time map. A second review pass caught the remaining sync/async boundary. completing-read is synchronous and the fetch is async. I resolved it with pre-warm on connect plus a bounded accept-process-output fallback for cold caches, so the warm case feels instant and a dead daemon can't hang Emacs. The follow-up re-review then converged to Ready-with-caveats and surfaced one concrete code finding I'd missed: the #2 input-clobber fix has to cover both signel--insert-msg AND signel--insert-system-msg, since both delete from the prompt line through point-max. The pieces-to-build entry and the prompt-preservation regression test now name both paths. A few smaller tightenings landed in the same pass. The listContacts assumption is now a researched fact (verified on 94 contacts), the two open questions on account source and fork remote are marked decided (defcustom in the gitignored local config, local checkout with no remote for now), and a forward-flag in the scope summary names the four notification details to spec before that later slice starts. docs/design/signal-client-review.org carries the review as the closure record. todo.org gets two tasks: a [#B] for the JSON-RPC success-result dispatch (the first build step), and a [#D] for groups in the picker as a vNext after the 1:1 flow is stable. Spec is Ready. Implementation order is pinned to the Pieces-to-build list. RPC dispatch first, then the guard, then fetch/cache, then the picker and keymap, then the clobber fix.
* feat(signal): add Signal client foundation on a signel forkCraig Jennings14 days1-0/+88
| | | | | | | | | | I'm building a Signal client in Emacs on signal-cli (linked as a secondary device) with a fork of the signel package as the front end. signel is on MELPA but effectively abandoned, and the behavior I want needs internal edits, so owning a fork beats advising a dead package. Full rationale and the rejected alternatives are in docs/design/signal-client.org. This lands the signal-cli-independent foundation: contact-list parsing for a completing-read picker, and the predicate that suppresses a notification for the chat being actively viewed. Both are pure and unit-tested without a linked account. cj/signal--parse-contacts was corrected against a live account (signal-cli 0.14 puts givenName/familyName at the top level, not under profile), and verified across all 94 real contacts. The use-package wiring loads the fork from ~/code/signel, sources the account from a gitignored signal-config.local.el (a phone number is an identifier, not a credential, and this keeps it off the mirror without a GPG prompt), and turns off auto-open so an incoming message can't steal a window. Verified live: signel-start spawns the jsonRpc process, loads the account, and receives over the channel. The fork edits (notify routing, the upstream input-clobber bug) and the contact-picker command are still to come.
* docs: add vterm/eat/ghostel terminal comparisonCraig Jennings14 days1-0/+121
| | | | Research notes weighing the three Emacs terminal backends (vterm, eat, ghostel) on maintenance risk, rendering fidelity, and best-fit role. Referenced by the "Consolidate to EAT" task as the basis for that evaluation.
* feat(auto-dim): dim non-selected windows via auto-dim-other-buffersCraig Jennings2026-05-251-4/+5
| | | | | | | | I added auto-dim-config, a module that loads my local auto-dim-other-buffers fork and dims windows that don't have focus so the selected window stands out. A non-selected window drops to a pure-black background with faded gray text. The dimmed faces live in the dupre theme (themes/dupre-faces.el) so they track theme switches, and the module remaps default, the font-lock faces, and org-block onto them so syntax-highlighted code fades too rather than staying lit. Fringe is left out because dimming it forces a full-frame refresh that flickers on this non-pgtk build. dim-on-focus-out is nil, so tabbing to a browser or terminal on Hyprland doesn't dim the whole frame. vterm and agent windows don't dim either, because the terminal paints its own per-cell colors past the face remap. I'm keeping that, since the agent's output stays readable while I work in code on the other side. The module loads after the theme, carries a load-graph header, joins the header-contract allowlist, and the inventory moves to 103 of 103 classified.
* docs(load-graph): classify elfeed-config, the last init moduleCraig Jennings2026-05-251-21/+7
| | | | | | elfeed-config was the only init module without a load-graph header. It was deferred because annotating the header triggers a byte-compile, which broke its tests. With that test rewritten to use real structs, I added the header (Layer 4, optional, currently eager but a command-loaded deferral candidate, runtime requires user-constants, system-lib, media-utils), added elfeed-config to the header-contract allowlist, and moved it from the inventory's deferred and pending sections into the Batch 8 table. That brings the inventory to 102 of 102 modules classified, completing the Phase 1 classification pass.
* refactor(load-graph): make hidden module dependencies explicitCraig Jennings2026-05-241-10/+14
| | | | | | | | | | | | | Phase 2 of the load-graph project. I fixed the seven hidden dependencies the classification surfaced, so each module declares what it uses instead of relying on init order. - system-defaults now requires host-environment and user-constants at runtime. They were eval-when-compile only, but env-bsd-p and user-home-dir are read at load, so the compiled module couldn't load standalone. - custom-buffer-file, dev-fkeys, calendar-sync, and video-audio-recording require keybindings and drop their (when (boundp 'cj/custom-keymap) ...) shims. The shim silently dropped the C-; binding when the module loaded before keybindings. The explicit require makes the dependency real. - flycheck-config and mail-config require keybindings for their cj/custom-keymap bindings (a use-package :map and a direct keymap-set). - Removed a dead eval-when-compile (defvar cj/custom-keymap) in transcription-config; nothing there used the variable. No init.el load-order change. keybindings and the foundation modules already load before these, so the requires are no-ops at startup and only fix standalone and test loading. I verified each fix with a fresh emacs --batch (require 'X), then swept all modules standalone: every one loads or fails only with a clear missing-package message. Full make test, make validate-modules, and an init smoke all pass. Module headers and the inventory's hidden-dependency section are updated to mark the seven resolved.
* docs(load-graph): classify remaining domain and optional modulesload-graph-classify-endCraig Jennings2026-05-241-21/+38
| | | | | | Final classification batch: the last 19 modules — linear-config, local-repository, lorem-optimum, mail-config, markdown-config, music-config, pdf-config, quick-video-capture, reconcile-open-repos, restclient-config, slack-config, system-commands, telega-config, tramp-config, transcription-config, video-audio-recording, vterm-config, weather-config, wrap-up. I annotated each header, added a Batch 9 table to the inventory, and extended the validation allowlist. 101 of 102 modules are now classified; only elfeed-config remains, deferred on its test fix. Two more hidden dependencies turned up. video-audio-recording uses the boundp shim for its C-; r binding, and mail-config registers C-; e directly without requiring keybindings, so it errors standalone rather than degrading. Both recorded for Phase 2.
* docs(load-graph): classify domain, integration, and optional modulesCraig Jennings2026-05-241-19/+47
| | | | | | | | | | Eighth classification batch: 17 domain/integration/optional modules — ai-config, ai-vterm, browser-config, calendar-sync, calibredb-epub-config, chrono-tools, dirvish-config, dwim-shell-config, erc-config, eshell-config, eww-config, flyspell-and-abbrev, games-config, gloss-config, httpd-config, jumper, latex-config. I annotated each header, added a Batch 8 table to the inventory, and extended the validation allowlist. 82 of 102 modules are now classified. Almost all are eager only by init order and become command/hook/mode-loaded. calendar-sync stays eager when its .local.el is present. One new hidden dependency: calendar-sync guards its C-; g registration with a boundp shim and doesn't require keybindings, so the binding drops standalone. I deferred elfeed-config rather than annotate it. Its header edit triggers byte-compilation, and the existing tests only pass when the module loads as interpreted source — the compiled cj/elfeed-process-entries inlines an elfeed struct accessor the stubs can't intercept, and the batch test environment has no elfeed package to build real structs. It needs its tests rewritten first, recorded in the inventory and a new todo task. Also made the header allowlist scoping test durable: it used games-config (now classified) as its unclassified example; switched to a sentinel name plus a duplicate-entry guard.
* docs(load-graph): classify Org modulesCraig Jennings2026-05-241-15/+26
| | | | | | Seventh classification batch: the thirteen Org modules — config, agenda, babel, capture, contacts, drill, export, noter, refile, reveal, roam, webclipper, hugo. I annotated each header, added a Batch 7 table to the inventory, and extended the validation allowlist. 65 of 102 modules are now classified. The daily workflows (config, agenda, capture, refile, roam) keep their eager reason per the spec's Phase 6 target. Babel and contacts move to after-load; export, reveal, drill, noter, webclipper, and hugo become command-loaded. The agenda and refile idle-timer caches are recorded as the side effects the spec already tracks for cache-lifecycle work. No new hidden dependencies.
* docs(load-graph): classify programming modulesCraig Jennings2026-05-241-12/+22
| | | | | | Sixth classification batch: prog-general plus the language modules — prog-c, prog-go, prog-lisp, prog-python, prog-webdev, prog-json, prog-yaml, prog-shell, prog-training. I annotated each header, added a Batch 6 table to the inventory, and extended the validation allowlist. 52 of 102 modules are now classified. prog-general owns the shared defaults and tree-sitter/LSP policy and stays eager. The language modules are eager only by init order and should load by major mode, so they're tagged Phase 6 deferral candidates. prog-shell's after-save executable hook is the one side effect worth scoping. No new hidden dependencies.
* docs(load-graph): classify dev, diff, help, lint, and VC modulesCraig Jennings2026-05-241-11/+26
| | | | | | Fifth classification batch: the development-workflow entry points and package config — coverage-core, coverage-elisp, dev-fkeys, diff-config, help-config, help-utils, flycheck-config, test-runner, vc-config. I annotated each header, added a Batch 5 table to the inventory, and extended the validation allowlist. 42 of 102 modules are now classified. Two more hidden dependencies turned up, both about cj/custom-keymap. dev-fkeys repeats the custom-buffer-file boundp shim for its C-; P binding. flycheck-config binds (:map cj/custom-keymap ...) through use-package without requiring keybindings, so it fails to load standalone. Both recorded for the Phase 2 dependency pass.
* docs(load-graph): classify UI and core-UX modulesCraig Jennings2026-05-241-12/+22
| | | | | | Fourth classification batch: the modules that shape the first interactive frame — ui-config, ui-theme, ui-navigation, font-config, selection-framework, modeline-config, mousetrap-mode, popper-config, dashboard-config, nerd-icons-config. I annotated each header, added a Batch 4 table to the inventory, and extended the validation allowlist. 33 of 102 modules are now classified. These mostly stay eager: each has a real first-frame reason (theme, font, modeline, completion stack, landing page). No new hidden dependencies. popper-config carries the spec's open question about its enabled/disabled state, noted for the deferral phase.
* docs(load-graph): classify core libraries and command modulesCraig Jennings2026-05-241-9/+18
| | | | | | Third classification batch: the remaining core and library command modules from init.el's early block — external-open, media-utils, auth-config, keyboard-macros, system-utils, text-config, undead-buffers. I annotated each with the load-graph header contract, added a Batch 3 table to the inventory, and extended the validation allowlist. 23 of 102 modules are now classified. No new hidden dependencies in this batch. auth-config stays eager because other modules need credentials early; the command libraries (external-open, media-utils, keyboard-macros) are eager only by init order and flagged as Phase 4 deferral candidates.
* docs(load-graph): classify text/editing command modulesCraig Jennings2026-05-241-11/+29
| | | | | | Second classification batch: the nine custom-* text/editing command helpers (case, comments, datetime, buffer-file, line-paragraph, misc, ordering, text-enclose, whitespace). I annotated each with the load-graph header contract and added a Batch 2 table to the inventory. They're all Layer 2, eager only to register a C-; submap at load, with no necessary eager reason, so all are Phase 3/4 deferral candidates. The inventory records a second hidden dependency for Phase 2: custom-buffer-file guards its C-; b registration with (when (boundp 'cj/custom-keymap) ...) and declares the keymap only via eval-when-compile, so the binding silently drops when the module loads without keybindings.
* docs(load-graph): seed module inventory and annotate foundation headersCraig Jennings2026-05-241-0/+180
| | | | | | I started the init.el load-graph classification with the foundation batch. I added docs/design/module-inventory.org as the living per-module inventory and annotated the seven foundation modules (system-lib, user-constants, host-environment, system-defaults, keyboard-compat, keybindings, config-utilities) with the load-graph header contract: layer, category, load shape, eager reason, top-level side effects, runtime requires, and direct-test-load safety. I changed no load order, so init.el keeps its current eager order. The inventory records one hidden dependency for Phase 2: system-defaults uses host-environment and user-constants symbols at load while declaring them eval-when-compile, so the compiled module cannot load standalone.
* docs(ai-kb): fold in review 6 and resolve the build-time decisionsCraig Jennings2026-05-241-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 Jennings2026-05-241-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 Jennings2026-05-241-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 Jennings2026-05-241-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 Jennings2026-05-241-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 Jennings2026-05-231-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.