Document theme presets (F4/F5/F7) and the fixed background role
Keybindings.md: Colors page's F4/F5 double-duty (cycle/save theme
presets) and the standalone cycle_theme_preset (F7) key, reachable
from anywhere.
Config-Reference.md: [theme]'s background role description updated —
it genuinely paints the whole screen now, not "almost always inherit"
— plus the preset-cycling mention and a fully refreshed
[navigation.keys] table (cycle_theme_preset, bt_power_toggle,
bt_pairable_toggle were all missing; wifi_forget/wifi_connect_hidden/
wifi_power_toggle's example values were stale from before their own
rename).
Architecture.md: how theme_presets.py/main.py's do_cycle_theme_preset/
do_save_theme_preset/theme_setup.apply_background fit together.
Getting-Started.md: a beginner-friendly pointer to F4's ready-made
schemes, right where the tutorial already walks through hand-picking
one color at a time.
50cdb60
Accuracy pass: preview_data registry, clock->rwb rename, missing sections
Architecture.md / Writing-a-Module.md:
- Document the new preview_data + PREVIEW_RENDERERS registry mechanism
(replaces the old single-consumer preview_tables field) - the actual
reason this wiki run happened. New subsection in Architecture.md,
new "Richer content in the preview panel" section in
Writing-a-Module.md with a worked example.
- Fixed every reference to a standalone clock.py module - it was
renamed to rwb.py once weather.py gave it a second thing to show,
months ago, but the wiki never caught up. Kept the teaching example
in Writing-a-Module.md (still pedagogically useful as a minimal
module) but corrected its false claims about a real shipped file.
- Module lists updated to include rwb/bars/sysmon, which existed
nowhere in Architecture.md or Writing-a-Module.md at all despite
being real, shipped, default-preset modules.
Config-Reference.md:
- Added scan/wifi_forget/wifi_connect_hidden/wifi_power_toggle to
[navigation.keys] - the entire WiFi/Bluetooth browsing key set was
completely undocumented.
- Replaced the stale [clock] section with [rwb] (correct section name)
plus a new [weather] section - weather config (lat/lon/geoclue/
ip_approx/name/code) didn't exist in the wiki at all despite being a
real, substantial opt-in feature.
- Fixed two false "not shown in the default layout preset" claims for
control and sysmon - both are actually placed in the default preset
today, contradicting what the page said.
Home.md: Status blurb updated to mention what's actually landed since
the last pass (sysmon, bars, the connectivity D-Bus agent overhaul),
not just control toggles + media.
4bf6a16
Add Your-First-Contribution.md: a real onboarding path for code contributors
Prompted by an LLM council session on tuicc's architecture readability —
the council converged (independently across multiple advisors and peer
review) on: nobody has ever tested this repo's docs against a human
without full session context, and the gap isn't the code architecture
itself (praised independently by two advisors and an earlier external
review), it's that CLAUDE/NOTES/*.md and the wiki's existing pages serve
two different audiences without a clear entry point for either.
Getting-Started.md is explicitly "no coding required" (end-user setup).
CONTRIBUTING.md has solid PR-review rules but no walkthrough — it
assumes you already know your way around the codebase. Nothing filled
the actual gap: a first-time code contributor's path from "cloned the
repo" to "made one real change and saw it work."
New page walks through: a one-minute mental model (Provider abstraction,
registry-pattern modules, dataclass+function state convention — pointing
to Architecture.md for depth, not duplicating it), then a concrete,
zero-invented-scope worked example — uncommenting the already-shipped,
already-documented Night Light [[control.toggle]] example from
defaults/config.toml, reading it next to Config-Reference.md's contract,
running it for real (including deliberately trying it without gammastep
installed, to see the project's no-silent-failure principle fire for
real instead of just reading about it) — then writing one of your own
as practice, explicitly not meant to become a real PR (packaged toggle
examples are curated, not "add more" — see VISION.md's own reasoning).
Closes with what a genuinely good first real PR looks like (docs fix,
small module, new provider) and hands off to CONTRIBUTING.md.
Linked from Home.md (right after Getting-Started, as the other kind of
"getting started") and from CONTRIBUTING.md's own opening (a pointer
before the review rules, for anyone who isn't ready for them yet).
d7c0659
Fix resize-mode docs stale after today's LoopState/handle_editing_key work
Two passages described main.py as deciding "which key means what, in
what order" for resize's editing level — no longer true: that dispatch
moved into resize_mode.handle_editing_key() during today's main.py
refactor (EditKeyResult/_handoff, a returned-signal handoff to main.py's
own do_*() functions instead of a direct call). Browsing-level dispatch
is unchanged, still directly in main.py, deliberately. Fixed in
Architecture.md's "Editing the layout from inside tuicc" section and
Keybindings.md's "Resize mode" internals paragraph.
Architecture.md also gained a short paragraph noting app_setup.py/
build_app() (one-time construction) and loop_state.py/LoopState (the
explicit object that replaced every closure/nonlocal main()'s loop used
to rely on) — previously unmentioned anywhere in the wiki.
Separately: new_preset (F5), added the day before this session's own
work, was never documented anywhere in the wiki. Added across
Keybindings.md (the configurable-keys list, the F-key behavior
paragraph, the live REPL cfg.keybinds example — regenerated from a real
load_config() call rather than guessed) and Config-Reference.md (the
Level-2 bullet list, a new dedicated paragraph mirroring save_layout/
cycle_preset's own, the example config.toml snippet, the keybind
reference table). Architecture.md's own save_layout/save_new_preset
paragraph updated to say new_preset is now wired to F5, not "still
exists separately... for anywhere that actually wants one" (true when
written, before F5 existed).
5f8fba4
Config Reference: [media]/[sysmon] visible_slots, restructure sysmon section
- New [media] section (replaces the old "no config section" framing) —
visible_slots, the fixed-slot-plus-scroll row count for Now Playing/
Output, independently configurable from [sysmon]'s own copy.
- [sysmon] promoted to its own top-level header (was folded into
[[sysmon.block]]'s own heading) — now covers visible_slots for the
window list, with [[sysmon.block]] as a subsection for the stats
grid's per-metric config, matching how the module actually has two
independently-configurable pieces now, not just one.
- Fixed "No per-window config" claim — visible_slots DOES configure
part of the window list now, only per-row content/sort is still
fixed.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
98bbbfc
Config Reference: add [[sysmon.block]] — the System module's own config
Full field reference for the system monitor's stats grid: metric
(cpu/ram/disk/load/cputemp/hot/swap, validated at load time),
enabled, column/row (row is an order within its column, not a shared
index — columns don't need equal block counts), warning/urgent
(per-block, different units per metric, RAM/DISK colored by real
usage percent even though the displayed text is used/available),
label. Covers the collision check (two enabled blocks can't share a
position), the packaged-layout fallback when [sysmon] has no [[block]]
entries, why load/swap have no thresholds by default (documented in
VISION.md's own R6 section), and HOT's own THROTTLED-flag placement
tradeoff. Also documents the per-window list above the grid (no config
section of its own — always every window, sorted by resource drain,
NICE positive-only 0-19).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
44ad759
Getting Started: control/media modules also stay open after Enter
f52e2e6
Home: bump date stamp, reflect control/media/StatusWorker in page blurbs
c701c3d
Keybindings: control and media never dismiss either
3b981df
Config Reference: add [audio], [[control.toggle]] (full contract), and a media-module no-config note
b59844d
Architecture: document StatusWorker/Domain pattern, add control/media to module list + diagram
d2ae181
Writing a Module: fix stale ctx.connectivity/ConnectivityWorker, add control/media/cava, document the two-level browsing/expanded pattern
cd303c1
Writing a WM Provider: correct mark_self() fallback risk framing
Confirmed live (see main repo): the mark_self() fallback race isn't
just a rapid-back-to-back-instance-launch edge case as previously
written — a single ordinary launch can mismark an unrelated window
(a slow-to-yield-focus app still holding focus for a moment) as
tuicc itself, silently hiding it from every list tuicc shows. Also
notes why the same [pid=...] for_window trick no_focus_next_window()
uses doesn't generalize to fix this (mark_self() runs from inside
tuicc, typically wrapped in a terminal — its own pid isn't the
window-owning process's pid the WM would match on).
4116abe
Writing a WM Provider: point mark_self/scratchpad references to Summoning Tuicc
1f588cd
Architecture: point dismiss-lifecycle WM setup reference to Summoning Tuicc
e166043
Config Reference: point self_app_id/fullscreen_only setup steps to Summoning Tuicc
6bca020
Getting Started: point to Summoning Tuicc instead of README for full per-WM detail
dcafabf
Home: link the new Summoning Tuicc page
5b5638a
Summoning Tuicc: new page — full per-WM reference, migrated from README
5627905
Home: mention Quick install in the Getting Started blurb
6288da2
Architecture: document focus_self()'s fullscreen parameter
7184abe
Config Reference: document fullscreen_only, install.sh, i3 power-menu swap
aa259ec
Getting Started: add Quick install section (install.sh)
d66c86d
Writing a WM Provider: fix stale model.py dataclass listing (pid, defaults)
Window/Region/WMState listing was missing the pid field and
field(default_factory=list) defaults added to model.py in an earlier,
unrelated commit (predates today's R1/resize/nav pass, caught during
verification). Also add pid=leaf.pid to sway.py's _leaf_to_window
example and the matching "i3 has no pid" comment to i3.py's, so both
listings stay literal, accurate copies of current source.
8366a4d
Home: bump date stamp, reflect nav/lifecycle changes in page blurbs
- Architecture bullet: mention the persistent-process lifecycle,
reword spatial nav to past tense
- Keybindings bullet: mention vim keybinds, Tab/Shift+Tab-driven
- Status: date bump, add a summon/dismiss callout pointing at
Getting Started's keybind section
01164fb
Writing a WM Provider: rewrite for close_window, dismiss_self, focus_self
- Provider contract: close_window is now abstract/required; add
dismiss_self/focus_self as optional; fix mark_self's app_id
signature; "five required, three optional (of five total)" instead
of the old four-required-one-optional count
- Refresh sway.py/i3.py listings: close_window, mark_self's
app_id-criteria branch + fallback, dismiss_self, focus_self
- Rewrite "Filtering tuicc's own window" into a combined section
covering mark_self/dismiss_self/focus_self as one shared-mark
mechanism; reframe the old "known, deliberately-unfixed limitation"
— self_app_id now eliminates the race, the focus-timing assumption
only applies to the no-self_app_id fallback path
- Fix Architecture.md's inbound link to this page's renamed heading/anchor
b3a6487
Writing a Module: should_exit -> should_dismiss, name dismiss_after_confirm
- handle() example and its explanation updated for the dismiss vs.
quit model (Provider.dismiss_self(), Ctrl+C is the only real quit)
- Name the pending-confirm dict's key explicitly as dismiss_after_confirm
- Reword the NavItem.rect explanation: it drives tab_order(), not a
separate spatial/geometric navigation system (removed)
ff868fa
Getting Started: update for scratchpad-summon model, dismiss vs. quit
- Running it / Launching it with a keybind: replace one-shot relaunch
workflow with the scratchpad-toggle model, point to README's
Summoning tuicc and contrib/sway/tuicc_toggle.py
- Add a forward-reference near the top flagging the day-to-day setup
- Controls table: Tab/Shift+Tab/arrow rows, vim keys, Enter/Escape
reframed as dismiss, Ctrl+C reframed as the only real quit
- F2 resize-mode paragraph: two-level session, F3 overwrite-in-place
2a99e78
Config Reference: update for R1 lifecycle, resize sessions, nav renames
- [wm]: add self_app_id/return_to_origin rows, point setup-step block
at README's Summoning tuicc instead of duplicating four WM snippets
- Resize mode section: F3 overwrite-in-place fix, two-level
browsing/editing session (renamed functions)
- [navigation.keys]: switch_module -> previous, add vim_* keys, split
the key-description table to match tab/previous/left-right/up-down
- Quit-key paragraph reframed as dismiss vs. quit, not a gap
- [[quick_actions.action]]: document the exit_after field
d6650d5
Keybindings: rewrite for Tab/Shift+Tab-driven nav, dismiss vs. quit, resize sessions
- switch_module renamed to previous throughout; document vim_left/
vim_right/vim_up/vim_down and that they're gated on vim_mode.
- Rewrite "How a keypress becomes an action": no more spatial-search
arrow-key logic (sibling_in_same_group/nearest_in_direction/leftmost-
window fallback), replaced with the real current model — Tab/
previous roll across module boundaries, arrows/vim-keys are pure
duplicates.
- Rewrite the whole Resize mode section for the persistent two-level
browsing/editing session and renamed resize_mode.py functions.
- Reframe Ctrl+C as the only real quit (deliberate, not a gap) now
that confirm/Escape dismiss instead of exiting.
- Refresh the example cfg.keybinds output in the testing section.
fe0c41b