Terminal Workbench

A portable, keyboard-first terminal workspace for Pop!/Ubuntu and Fedora.

This repository is the source of truth for:

• Kitty, shell, CLI-tool and Neovim configuration;
• Pi extensions, skills and tutorial plans;
• a small bootstrap interface for package checks and profile planning;
• an optional local Tutor bridge between shell/Neovim and Pi.

It does not contain credentials, private keys, browser data, host inventories or machine-specific overrides. Put machine-specific choices in ignored *.local files.

Tutor Workbench

The new local learning workbench provides a browser UI, durable questions, learning paths and explicit terminal demonstrations. It uses the Pi Coding Agent SDK as its model harness and the same lesson controller and progress journal as the native Tutor. Work still happens in your Kitty and Neovim; existing Codex OAuth and DeepSeek profiles stay on the machine that owns them.

After the one-time setup below, run tutor from any working directory. It opens the learning workbench in your browser and uses ~/tutor for practice (or an explicit --cwd PATH). tutor --no-open starts it without opening a browser.

The standalone installer in this repository installs the system prerequisites, the latest stable Node, Kitty, Neovim, fzf and Pi releases, plus the built Tutor UI. It does not require the private dotfiles-work repository, which restores your wider developer workstation separately. PI_NODE_BIN chooses Node; PI_TUTOR_SDK_ROOT can select the SDK independently. Releases are resolved from official upstream sources at installation time and verified against their published checksums. SDK compatibility is checked before activation. Shared tools are installed once under ~/.local/share/workbench-tools; the shell, desktop and Tutor use the same Kitty.

# Linux: from this checkout, as your normal user:
bash install.sh              # preview, no changes or downloads
bash install.sh --apply      # install prerequisites, runtime and launchers

# Connect only your model/provider in Pi:
~/.local/bin/pi-workbench    # /login, then /model, then exit Pi
~/.local/bin/tutor

On Windows, run the following from PowerShell in this checkout:

.\install.ps1                # preview
.\install.ps1 -Apply         # WSL2 + Ubuntu + the same Linux installer

Windows uses WSL2 and WSLg, not a native Windows runtime. Initial WSL setup can require an administrator prompt, restart and creation of a Linux user; rerun the same installer to continue. See Windows installation. The Tutor opens in your Windows browser; the terminal and editor run in Ubuntu.

The installer targets current glibc Linux systems with apt, dnf, pacman or zypper, on x86_64 and ARM64, particularly Pop!_OS/Ubuntu. macOS, musl Linux and other architectures are not currently supported. This is not a guarantee for every Linux distribution or every learning lab's external infrastructure.

The managed tutor and tutor-workbench commands live in ~/.local/bin, which must be on your PATH to use their short names. The app guides model login and offers Modellverbindung neu laden after setup. Releases live outside your checkout and learning progress stays in ~/.local/state/tutor-workbench. Existing model credentials and settings are preserved. Re-run the installer after updating the source; see installer details. The migration checkpoints document the separation of UI, local service and Pi worker.

For development in an existing checkout with an existing Pi runtime, the older npm --prefix tutor/web ci, npm --prefix tutor/web run build and ./workbench configure --yes workflow remains available; it is not the complete installer.

Current status: Tutor V1 contract

Tutor V1 is the current documented target and replaces Tutor V0. It remains opt-in: a checkout alone enables no shell hook, Neovim plugin, package installation or user configuration. The explicit ./workbench configure --yes step installs only the documented managed links and Pi theme selection.

The V1 contract is intentionally narrow:

• A natural request such as “I want to learn X but do not know how” lets Pi start Tutor through the hidden tutor_session tool; /tutor-debug remains for recovery.
• Inside configured Kitty, starting a lesson validates the goal first, then opens or reuses a vertical work pane and selects its shell source atomically.
• Zsh reports real command_finished events. command_result steps may complete on the first fresh matching command; passive shell/editor state still requires a fresh nonmatch → match transition.
• Completion creates exactly one token-bound next request. Pi briefly interprets the result and continues with one next task rather than exposing internal tool data.
• Tutor internals render no tool rows; the UI keeps one compact footer for connection, directory, exit status and real problems.
• Every completed direct command in the connected Tutor-Zsh can provide its bounded last-command output to the active model, regardless of success or failure. Capture stays internal, is limited to the selected Kitty window and capped at 2 KiB per command; the learner does not repeat terminal output in chat. Output is untrusted data and is not secret-redacted.
• After a successful Tutor finish, it may offer a short, non-binding knowledge check exactly once and starts it only after the learner agrees.

Read the full contract in docs/meta/tutor-v1.md. docs/meta/tutor-v0.md is archived/deprecated context only.

Collaborative Kitty and shell tutorial

The researched Kitty tutor pack covers Kitty, kittens, Zsh/Fish comparison and optional terminal tools. The interactive-tutor skill loads only the relevant modules for a lesson. Each chapter is taught as small user-executed steps, not an automatic installation; the earlier compact path remains in docs/terminal-tutorial.md.

The broader terminal education pack adds system integration, automation, DevOps and cloud modules without loading the whole curriculum into each lesson. The terminal-workbench skill routes to one relevant module and card; web-research applies the package's source and version rules.

The portable tutorial progress records accepted Kitty chapters for another machine. The work-journal skill keeps the precise cross-session resume state in ignored local/tutor-progress.json, using atomic writes and revision checks without storing terminal history. Orchid Bloom Deep is versioned for both Kitty and Pi.

Preview the ten researched and custom palette variants without changing configuration:

python3 tutor/bin/preview-palettes.py

The repository launcher tutor/bin/pi-tutor keeps the normal Pi credentials, model settings and sessions but disables automatic extension, skill, prompt and theme discovery. It loads the Tutor extension, five repository skills and the versioned theme; the tutor has Pi's read-only read, grep, find and ls tools for relevant local-file inspection, while shell, edit and write tools remain disabled. The skills remain available as explicit commands, but are not advertised for automatic loading during Tutor turns. The launcher explicitly loads the selected profile's local pi-web-access, @juicesharp/rpiv-ask-user-question and pi-memory extensions despite automatic discovery being disabled. Web access can be disabled with PI_TUTOR_WEB_ACCESS=0; the profile's local memory is shared across Tutor and GPT Tutor. pi/bin/pi starts normal Pi with its bundled Node runtime without changing the shell's global ASDF selection. pi/bin/pi-gpt preserves the isolated GPT profile while selecting the same theme; tutor/bin/pi-tutor-gpt loads the same Tutor resources with that profile’s GPT login, model defaults and Pi sessions. It never copies credentials or falls back to ambient OPENAI_* configuration. ./workbench configure --yes links the Pi wrapper and all three profile launchers into ~/.local/bin; external Pi packages and provider credentials remain machine-local.

See portable setup for installation, boundaries and rollback.

Repository layout

workbench                         Bootstrap entry point
install.sh / install.ps1           Standalone Linux / Windows-WSL Tutor installation
installer/                        Pinned runtimes, dependency setup, launcher generation
profiles/{apt,dnf}/               Distro-specific package names per profile
config/                           Versioned Kitty and shell configuration
nvim/                             The minimal Neovim setup and optional Tutor plugin
pi/extensions/                    Pi runtime extensions
pi/skills/                        Tutor and shortcut skills
pi/themes/                        Pi TUI themes
pi/bin/                           Profile launchers
tutor/                            Protocol, clients and Tutor launcher
tests/                            Fast, non-destructive checks
docs/                             Architecture and operational notes

Bootstrap model

./workbench doctor                # Read-only detection
./workbench plan core kitty       # Print packages and next actions
./workbench configure             # Preview managed links/settings
./workbench configure --yes       # Back up conflicts and install managed config
./workbench apply --yes core      # Install only requested package profiles

apply is guarded and should only be used when you intentionally want the platform package manager to make changes.

Development checks

./tests/test-workbench.sh
node --test tests/lesson.test.mjs tests/protocol.test.mjs tests/tutor-controller.test.mjs tests/tutor-listener-lifecycle.test.mjs
python3 tests/test-palettes.py
python3 tests/test-work-journal.py
python3 docs/kitty-tutor-pack/tools/check_pack.py
python3 docs/terminal-ausbildung/tools/check_pack.py
python3 docs/provider-cloud-P01/tools/check_package.py
python3 -B tutor/bin/sync-provider-cloud-catalog.py --check
python3 docs/linux-betrieb-LX10/tools/check_package.py
python3 docs/linux-betrieb-LX03/tools/check_package.py --source-docs docs
python3 docs/linux-betrieb-LX04/tools/check_package.py --docs docs
python3 -B docs/linux-betrieb-LX05/tools/check_package.py --docs-root docs --json
python3 -B docs/linux-betrieb-LX06/tools/check_package.py \
  --source-root terminal-ausbildung=docs/terminal-ausbildung \
  --source-root linux-betrieb-LX05=docs/linux-betrieb-LX05
python3 -B docs/linux-betrieb-LX07/tools/check_package.py --prior-docs docs
python3 -B docs/linux-betrieb-LX08/tools/check_package.py
python3 -B docs/linux-betrieb-LX09/tools/check_package.py
python3 -B docs/linux-betrieb-LX11/tools/check_package.py
python3 -B tools/read-dialog-werkstatt.py validate
python3 -B tools/check-content-checksums.py
python3 -B docs/meta/LERNHUB-SPEC/tools/check_spec.py --repo-root .
python3 -B tutor/bin/sync-linux-betrieb-catalog.py --check
python3 -B tutor/bin/build-learning-module-overlays.py --check

These checks do not install packages, change user configuration or contact a network service.

Lernhub

Der vorhandene pi-tutor bietet mit /lernhub eine gemeinsame Lernwerkstatt für Kitty, Terminal-Ausbildung, Neovim, Provider Cloud und Linux-Betrieb. Sie verbindet Lehrkarten, Wiederaufnahme, nachvollziehbare Hilfe und eine Tastaturoberfläche. Linux-Betrieb enthält LX03 bis LX11 als getrennte Module desselben logischen Pakets; LX08, LX09 und LX11 sind jetzt ebenfalls im Katalog erreichbar. Zusätzlich zu B01–B04 haben 33 Linux- und DevOps-Module lokale Lehrpläne mit zusammenhängenden Aufgaben. Technische Praxisanforderungen bleiben vom empfohlenen Wissen getrennt, sind bereits in Lernwegkarten und Stationsdetails sichtbar und werden passend zu Teilroute, Managerkontext, Fallphase und Laborzustand geprüft. Die Startvorbereitung läuft als View-State derselben nativen TUI; aktuelle zielgebundene Befunde veralten bei einer neuen Pi-Sitzung, und offene Befunde sperren nur praktische Systemaktionen. LX06/LX07 aktivieren bei Import, Start oder Resume niemals automatisch einen Fehler; LX07 legt dabei auch keine Konten oder Units an. Bestehende persönliche Lernstände und Playlists werden nicht automatisch migriert oder erweitert.

Einstieg, optionale Arbeitsbegleitung und Migration: Lernhub-Integration. Nachweis und Live-Grenzen: Abnahmeübersicht.

Aktueller Umfang, Prüfnachweise und verbleibende Grenzen: Modulmigration vom 5. Oktober 2026.