docs(contexts): sub-system docs for AI navigation - #22
Merged
Conversation
Add 5 focused context docs at .ai/contexts/*.md covering the natural
boundaries inside Switchboard:
- session-cache: SQLite + FTS5 + watcher + targeted refresh
- schedule-runner: in-process cron + .md storage + claude --resume -p
- subagent-observability: parent->child grouping + transcript view
- viewer-panel: reusable CodeMirror panel for Plans / Memory / .work-files
- ipc-bridge: trust boundary inventory (every IPC, every event)
Each doc: ~70-130 lines, structured around purpose, key files, public
surface, invariants, non-obvious behaviors, and "if you change this,
also check..." cross-references. Audience is AI agents who need to make
a focused change without re-reading 1800 LOC of main.js.
Also adds:
- .ai/contexts/README.md index + recommended reading order
- .ai/contexts/_issues.md observations captured while writing (not
blockers, opportunistic follow-ups)
- .ai/project.json contexts map
- shared-guidelines.md quick-orientation table now points at the
context docs instead of raw files
abasiri
pushed a commit
that referenced
this pull request
Aug 1, 2026
The push-to-talk handler (#22) intercepted every plain-Space keydown, calling preventDefault() and writing a raw space straight to the PTY. xterm's _keyDown runs the custom key handler BEFORE its composition helper, so during Korean/Japanese/Chinese composition this blocked the commit and reordered/dropped the in-progress syllable (e.g. "녕 " came out as " 녕"). Gate the direct-send path on !isImeComposing(e) (isComposing, or the Chromium keyCode 229 sentinel) so it only fires when no IME is composing — exactly when push-to-talk needs it. During composition the event now falls through to xterm's composition helper for correct commit behavior. Extracts the decision as a pure, exported predicate and adds unit tests. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds 5 focused context docs under `.ai/contexts/*.md` for the natural sub-systems of Switchboard. Audience: AI agents (and future-me) who need to make a focused change without re-reading 1849 LOC of `main.js`.
Each context doc follows the same shape: Purpose → Key files → Public surface → Invariants → Non-obvious behaviors → Change-also checklist. Optimized for one-page scannability.
Why
Adapting the `/context-engineering` skill (designed for Skaleet PHP/TS DDD projects) to an Electron app: the spirit (progressive disclosure, hot/warm/cold) is preserved, but the structure is flat (no `Domain/Application/Infrastructure` layers exist here).
The shared-guidelines.md quick-orientation table now routes to these context docs instead of raw files. `.ai/project.json` gets a `contexts` map so `/dispatch` planners can discover them programmatically.
Side-effect
`_issues.md` captures observations made while writing: `main.js` size, IPC return-shape inconsistencies, missing DST handling in scheduler, watcher cleanup risk in viewer-panel, etc. None are blockers — picked up opportunistically when adjacent work happens.
Risk
Docs only. No runtime change.