From 6d6b204b540d49b18d07a036167a53d80862d2a8 Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 02:35:19 -0500 Subject: [PATCH 1/6] docs: track documentation quality delivery --- odd/tasks/documentation-quality.md | 32 ++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 odd/tasks/documentation-quality.md diff --git a/odd/tasks/documentation-quality.md b/odd/tasks/documentation-quality.md new file mode 100644 index 0000000..c1866f8 --- /dev/null +++ b/odd/tasks/documentation-quality.md @@ -0,0 +1,32 @@ +# Documentation quality +Objective: improve the README and documentation using Gentleman.Dots as a quality reference. +Branch: `docs/documentation-quality`; delivery: feature-branch-chain (local commits only); checks: Markdown links, source-backed command review. Forecast: 1,200–1,800 authored changed lines; delivered as four focused local review slices. + +## Specs +S1. User request: "me gustaria que la docuemntacion de este repo , incluso el readme , tenga la calidad que tiene este repo , https://github.com/Gentleman-Programming/Gentleman.Dots" +S2. Authorized option: "Comparación e implementación" — "Tomo el otro repo como referencia de calidad y mejoro el README y la documentación, respetando la identidad y el funcionamiento real de Dreamcoder Workbench." +S3. Delivery selection: "Cadena sobre una rama de trabajo — recomendada" — "Commits por recorrido de lectura, preparados para revisarse por separado sobre una rama común; sin publicar ni abrir PRs." + +## Tasks +- T1 | S1–S3 | delegated (context backstop) | done | README and documentation hub: purpose, preview, quick path, platform boundaries, task navigation | commit: c066396 +- T2 | S1–S3 | delegated (context backstop) | done | Installation journey: single canonical full setup, platform limitations, verification and recovery | commit: e73d0c1 +- T3 | S1–S3 | delegated (context backstop) | done | Configuration and contributor journeys: accurate examples, concise structure, source-backed references | commits: d4a1fd9 and the final slice containing this revision (`docs: align contributor workflow and theme system guidance`) + +- T4 | S1–S3, L12 | inline delivery | done | Create and confirm approved documentation issue | evidence: github.com/Dreamcoder08/Dreamcoder-Workbench#53, confirmed open with status:approved and type:docs +- T5 | S1–S3, L12 | inline delivery | in_progress | Publish feature tracker and four scoped child PRs, no merges | evidence: pending +- T6 | S1–S3, L12 | inline delivery | pending | Observe applicable CI and record delivery state | evidence: pending + +## Log +L1. Original request: "me gustaria que la docuemntacion de este repo , incluso el readme , tenga la calidad que tiene este repo , https://github.com/Gentleman-Programming/Gentleman.Dots" +L2. User authorized comparison and implementation through the selection quoted in S2; selected feature-branch-chain as quoted in S3. +L3. Reference README inspected through fetch_content: purpose, screenshot, quick start, supported platforms, tool overview and documentation routes. Local README contains Spanish template instructions, TODO placeholders, and duplicated installation guidance. Installation pages disagree on platform support and use global pip installation. Changes remain documentation-only; no product behavior changes or new platform guarantees. +L4. Existing untracked `DreamcoderShell/.config/fish/conf.d/gentle-shell.fish` is unrelated and must remain untouched and uncommitted. No callable memory tools are available; Engram mirror unavailable, local task file is authoritative for this session. +L5. Context backstop fired before implementation; subsequent multi-step units routed to bounded workers. Passive documentation has no meaningful RED test: use structural validation and source-backed review, never execute installation, theme synchronization, repair or restore on the host. Each work unit will be committed locally with `docs:` after checks, then assessed with RDD off. Proposed slice boundaries: T1 entry points; T2 installation; T3 configuration/contributing. No pushes or PR creation authorized. +L6. T1 completed: README and hub rewritten, preserving the preview and technical-resource routes, adding explicit ownership and platform boundaries, removing placeholders and misleading badges. Worker targeted links and whitespace checks passed; parent whole-repository `python scripts/validate-markdown-links.py` and `git diff --check` passed. No runtime code changed; passive documentation, Risk: none. Slice 1: c066396. Assessment unavailable over untracked files; RDD-off plan explicitly accepts writer self-verification, no independent verifier required. No RDD review started. +L7. T2 completed: five installation pages now share a canonical desktop path, virtualenv setup, explicit write boundaries, source-backed plan/restore commands, and backup limitations. Worker targeted links initially failed for one anchor, corrected and rerun successfully. Parent full link validation and diff whitespace passed; parser spot-check confirms installer plan, backup list and restore --dry-run. Runtime install/platform behavior deliberately not exercised. Slice 2 is 627 authored lines because replacing duplicated platform setup and recovery is one coherent documentation journey; no cosmetic compression. Risk: none (passive documentation, no code/contract edits). +L8. T3 worker mvq8b33t-4-6lor failed with `assistant reported an error`, leaving partial edits in CONTRIBUTING.md and terminal/editor/multiplexer configuration guides. No final source-backed review or completion evidence was returned; shell and theme-system guides remain unfinished. User wrote `continue`. Recovery inspection confirmed four modified documentation files; whole-repository Markdown links and whitespace checks pass, but this does not establish content completeness. Partial edits remain uncommitted and are not accepted as complete. Failed worker is not automatically retried; no generic native Agent fallback is available. T3 is blocked awaiting restored delegated writing capability or a human scope decision. No implementation or runtime tests were run. T2 commit: e73d0c1. The existing unrelated Fish file remains untouched. +L9. User authorization verbatim: "yes te autorizo todo y avanza". In response to the explicit retry question, this authorizes a new worker attempt to complete and review T3; scope remains documentation-only and delivery stays local. Reconciled the task file and Git state before resuming; no memory tools available. +L10. Authorized replacement worker mvqcxo08-5-pm7h completed T3 and returned source-backed self-review for all six allowed documents, covering S1–S3. It compared prior partial changes against HEAD and preserved NetworkManager and Orca specifics. Targeted links passed after correcting one cross-file anchor; whitespace passed. Parent reviewed full six-file diff and whole-repository link/whitespace validation passed. No runtime tests or mutating commands were run because changes are passive documentation. Assessment reports native risk unassessable due to unrelated untracked files; RDD is off, and returned plan requires writer self-verification only, satisfied by source review and structural checks. No independent verifier or RDD review required. Risk: none. T3 is split into component configuration and contributor/theme documentation commits for focused review; no further source changes planned. +L11. Component slice d4a1fd9 committed successfully; pre-commit Markdown, whitespace and file checks passed. Contributor/theme slice closes the feature and includes this final task record. All three tasks have observed checks and complete outcomes. No source-code changes, publishing, external link network validation, live installation or platform execution occurred. Unrelated untracked Fish file preserved. Next step at that boundary: human review of the local documentation branch before any publication. +L12. User request verbatim: "yes continua todo de forma autonoma siempre usa buenas practicas de git y github + filosofia de gentleman". Explicit interactive authorization then granted target-bound GitHub CLI reads, branch pushes and PR creation on github.com/Dreamcoder08/Dreamcoder-Workbench, without merges. A second explicit selection authorized creating the documentation issue with `status:approved` and `type:docs`, using nonclosing `Refs` links. Target verified: default main, authenticated actor ADMIN; no open issues or PRs, duplicate query `documentation in:title,body` across all states returned zero results. Feature request form selected for the improvement proposal; no personal/legal checkbox attestations. Original local-only delivery restriction is superseded solely by these target-bound grants. Keep feature-branch-chain; no merge or size:exception label authorized. +L13. Issue creation returned #53. Initial read-back parser failed because GH_FORCE_TTY emitted ANSI-colored JSON; paused later mutations, diagnosed formatting, and confirmed exact title/body and approved/docs labels via target read-back with forced color disabled. No duplicate create attempted. Remote main fetched using the authorized GitHub CLI HTTPS helper, not the ambient SSH agent: exact base 3e830a3b981901430f55b3ef7d8db9f2dbdf526b, no upstream divergence. Delivery will use a registered same-clone worktree and normal commits/hooks, retaining original source branch and unrelated local changes. From 47ac543ca68327c486e868939f076b4e99ee9552 Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 02:35:21 -0500 Subject: [PATCH 2/6] docs: clarify project overview and documentation navigation --- README.md | 165 +++++++++++++++++++------------------------------ docs/README.md | 162 +++++++++++++++++++++--------------------------- 2 files changed, 136 insertions(+), 191 deletions(-) diff --git a/README.md b/README.md index 80e65a9..49908be 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,95 @@ - - -
- # Dreamcoder Workbench -Terminal-native, health-first engineering environment built on Gentleman.Dots + ML4W. - -[![License](https://img.shields.io/pypi/l/dreamcoder-theme)](./LICENSE) -[![Stack](https://img.shields.io/badge/stack-Python%20%7C%20Go%20%7C%20Shell-informational)]() +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](pyproject.toml) [![PyPI](https://img.shields.io/pypi/v/dreamcoder-theme)](https://pypi.org/project/dreamcoder-theme/) -[![WCAG 4.5:1](https://img.shields.io/badge/WCAG-4.5%3A1-brightgreen)](docs/DREAMCODER_DESIGN_SYSTEM.md#accessibility-policy) - -
---- - -## Demo +Dreamcoder Workbench is a terminal-native development environment and personal +dotfiles overlay. It brings together a token-based theme engine, tool +configurations, machine profiles and health checks for a consistent workspace. +It builds on, rather than replaces, [Gentleman.Dots](https://github.com/Gentleman-Programming/Gentleman.Dots) +and [ML4W](https://ml4w.com/). Dreamcoder Workbench in light mode with Gentle Shell and its agent workspace -## Índice - -- [Descripción](#descripción) -- [Características](#características) -- [Stack técnico](#stack-técnico) -- [Instalación](#instalación) -- [Uso](#uso) -- [Estructura del proyecto](#estructura-del-proyecto) -- [Roadmap](#roadmap) -- [Licencia](#licencia) - -## Descripción - -Dreamcoder Workbench es una capa de distribución personal para desarrolladores que viven en la terminal: agrega temas gobernados por tokens (validados WCAG/APCA), perfiles de keybindings de ML4W por máquina, tooling AI-aware y una capa de verificación, todo sobre **Gentleman.Dots** y **ML4W** sin reemplazar a ninguno de los dos. +## Contents -No es una app única sino un workbench/monorepo: combina un paquete Python (`dreamcoder-theme`) que genera y sincroniza temas, un instalador TUI en Go, y decenas de carpetas `Dreamcoder/` con la configuración final de cada herramienta (Neovim, Ghostty, Kitty, Tmux, Zellij, Waybar, etc.). +- [What is included](#what-is-included) +- [Quick start](#quick-start) +- [Platform boundaries](#platform-boundaries) +- [Documentation](#documentation) +- [Support and contributions](#support-and-contributions) +- [Acknowledgements and license](#acknowledgements-and-license) -## Características +## What is included -- Motor de temas token-governed (`dreamcoder-theme`) con validación de contraste WCAG/APCA. -- Perfiles de keybindings ML4W específicos por máquina (desktop Arch, mobile Termux). -- Sincronización de configuraciones para 25+ herramientas de terminal/desktop (Neovim, Ghostty, Kitty, Warp, WezTerm, Waybar, Yazi, Lazygit, etc.). -- Integración AI-aware (Codex CLI/App, OpenCode, Pi, Herdr). -- Instalador TUI escrito en Go (Bubble Tea + Cobra) en `installer/`. -- Verificación/auditoría de configuración vía scripts (`scripts/verify-*.py`, `doctor.sh`). +- A Python theme engine that generates component themes from shared tokens, + with contrast validation and user-facing dark/light modes. +- Configurations for terminal and development tools, including Neovim, Kitty, + Ghostty, Tmux, Zellij and shell environments. +- ML4W integration and machine-specific profiles for desktop and mobile use. +- Theme integrations for AI tools, including Pi, OpenCode and Codex. +- An installer, synchronization tools and commands for inspecting workspace health. -## Stack técnico +Dreamcoder Workbench owns the overlay, profiles, theme engine and generated +variants in this repository. Gentleman.Dots supplies a shell, editor and terminal +base; ML4W supplies the Hyprland desktop base. See the +[source manifest](docs/sources.md) for the ownership boundary and upstream pins. -| Capa | Tecnología | -|------|-----------| -| Motor de temas | Python 3.11+ (`dreamcoder-theme`, Jinja2) | -| Instalador TUI | Go 1.25 (Bubble Tea, Lipgloss, Cobra) | -| Automatización/sync | Shell (bash/zsh), shellcheck | -| Base de escritorio/terminal | Gentleman.Dots + ML4W (Hyprland, Neovim, Ghostty, Kitty, Waybar) | -| Tests | pytest (Python), Go e2e (`installer/e2e`) | -| Infraestructura | GoReleaser, Homebrew tap (`homebrew-tap/`) | +## Quick start -## Instalación - -Dreamcoder Workbench se instala en 3 pasos, sobre Arch Linux (o derivada): +Get the configuration and guides without applying changes to your home directory: ```bash git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git cd Dreamcoder-Workbench ``` -1. **Gentleman.Dots** (base de shells, terminales y Neovim): - ```bash - brew install Gentleman-Programming/tap/gentleman-dots - gentleman-dots - ``` -2. **ML4W OS** (base de escritorio Hyprland): - ```bash - bash <(curl -s https://ml4w.com/os/stable) - ``` -3. **Dreamcoder Workbench** (temas, perfiles y verificación): - ```bash - pip install -e ".[dev]" - ``` - -Guía completa paso a paso: [INSTALL.md](INSTALL.md). - -### Variables de entorno - - — no se encontró `.env.example` en el repo; no hay variables de entorno documentadas a nivel raíz. +1. Review the [installation guide](INSTALL.md) and back up your existing + configuration before applying an overlay. +2. Follow its setup path for Gentleman.Dots, ML4W and Dreamcoder Workbench on + the intended desktop, then use its verification and troubleshooting steps. +3. Choose a [configuration guide](docs/README.md) for the tools you use. -## Uso +The Python theme package requires Python 3.11 or newer and Jinja2. The +`scripts/dreamcoder` entry point exposes the source tree through `PYTHONPATH`, +but its Python dependencies must still be available. See the installation guide +for setup rather than assuming that running the script installs them. -```bash -# generar/sincronizar el tema Dreamcoder -./scripts/dreamcoder sync +## Platform boundaries -# correr tests del paquete Python -make test +The full desktop journey is intended for Arch Linux or a derivative with ML4W. +Other platforms have component-specific guides; they are not a guarantee that +the complete desktop or every integration works there. Check the relevant +[platform guide](docs/README.md) and the requirements of each tool before applying +configuration. -# lint + type-check -make lint -``` +## Documentation -## Estructura del proyecto +The [documentation hub](docs/README.md) routes you to installation, +configuration, theme development and technical references. Useful starting +points: -Monorepo/workbench con múltiples subproyectos, cada uno con su propia configuración: +- [Installation](INSTALL.md) — full desktop setup and verification. +- [Theme system](docs/configuration/theme-system.md) — tokens, generated themes + and synchronization. +- [ML4W integration](docs/configuration/ml4w.md) — profiles and keybindings. +- [Source manifest](docs/sources.md) — upstream inputs and repository ownership. +- [Contributing](CONTRIBUTING.md) — development setup and contribution guidance. -``` -Dreamcoder-Workbench/ -├── src/dreamcoder_theme/ # paquete Python: motor de temas, renderers, CLI -├── installer/ # instalador TUI en Go (Bubble Tea + Cobra) -├── scripts/ # sync, verificación, generación de paletas -├── tests/ # tests pytest del paquete Python -├── docs/ # arquitectura, ADRs, guías de instalación/migración -├── openspec/ # especificaciones del proyecto (SDD) -├── homebrew-tap/ # tap de Homebrew para el instalador -├── DreamcoderNvim/ # config final: Neovim -├── DreamcoderGhostty/ # config final: Ghostty -├── DreamcoderKitty/ # config final: Kitty -├── DreamcoderTmux/ # config final: Tmux -├── DreamcoderZellij/ # config final: Zellij -├── DreamcoderWaybar/ # config final: Waybar -├── DreamcoderShell/ # config final: Fish/Zsh/Bash/Starship -└── Dreamcoder/ # config final para cada herramienta soportada (25+) -``` +## Support and contributions -## Roadmap +For a bug report or feature request, open an issue in the +[GitHub repository](https://github.com/Dreamcoder08/Dreamcoder-Workbench/issues). +Include your platform, the affected component, relevant output with personal +information removed, and steps to reproduce the problem. Contributions are +welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). The +[changelog](CHANGELOG.md) records project changes. - — ver [CHANGELOG.md](CHANGELOG.md) para el historial de cambios; no se encontró un roadmap explícito en el repo. +## Acknowledgements and license -## Licencia +Thanks to the [Gentleman.Dots](https://github.com/Gentleman-Programming/Gentleman.Dots) +and [ML4W](https://ml4w.com/) projects for the upstream environments this +workbench builds upon. Their projects remain independently maintained. -Distribuido bajo licencia MIT. Ver [LICENSE](LICENSE) para más detalles. +Dreamcoder Workbench is distributed under the [MIT license](LICENSE). diff --git a/docs/README.md b/docs/README.md index 1ac8525..5744a66 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,91 +1,71 @@ -# Dreamcoder Workbench — Documentation - -Welcome to the Dreamcoder Workbench documentation hub. This index centralizes -all the technical documentation for the project. - -## New here? Quick path - -New to Dreamcoder Workbench? Here is the shortest path: - -1. Start with the [main README](../README.md): overview, badges, and the 3-step install. -2. Read the [Source Manifest](sources.md) to understand what is upstream and what the repo owns. -3. Go deeper into the [Theme System](configuration/theme-system.md) if you work with colors or tokens. -4. Review the [Design System](DREAMCODER_DESIGN_SYSTEM.md) for the identity and contrast guidelines. - ---- - -## Architecture - -High-level documentation on how the system is built and how it works. - -| Document | Description | -|-----------|-------------| -| [Theme Pipeline](architecture/theme-pipeline.mmd) | How tokens from `tokens.json` flow through the renderers to the final theme files | -| [AI Integration](ai-integration.md) | How Dreamcoder Workbench integrates with Claude Code, OpenCode, Pi, and other AI tools | -| [Monorepo Structure](architecture/monorepo-structure.mmd) | Visual map of the repository: `src/`, `scripts/`, `tests/`, and every top-level directory | -| [Data Flow](architecture/data-flow.mmd) | Full flow of `dreamcoder-theme sync`: palette → tokens → renderers → writers → disk | -| [Source Manifest](sources.md) | Upstream inputs (ML4W, Gentleman.Dots), ownership boundaries, and prohibitions on secrets/runtime state | -| [Herdr Integration](herdr.md) | Herdr 0.7.3/0.8.0/0.8.2/0.9.1/0.9.3/0.9.4/0.9.5 contracts, versioned generated variants, and deployment profiles | -| [Design System](DREAMCODER_DESIGN_SYSTEM.md) | Design principles, color philosophy, and visual identity guidelines | -| [Control Center](DREAMCODER_CONTROL_CENTER.md) | Central control dashboard for the Dreamcoder Workbench ecosystem | - -### Architecture Decision Records (ADRs) - -| ADR | Title | Status | -|-----|--------|--------| -| [ADR-001](adr/0001-project-structure.md) | Monorepo Project Structure Layout | Accepted | -| [ADR-002](adr/0002-toolchain-selection.md) | Python and Shell Quality Toolchain | Accepted | -| [ADR-003](adr/0003-python-quality-strategy.md) | Python Quality Strategy | Accepted | -| [ADR-004](adr/0004-shell-test-strategy.md) | Shell Test Strategy | Accepted | -| [ADR-005](adr/0005-ci-cd-quality-gates.md) | CI/CD Quality Gates | Accepted | - ---- - -## Installation - -Step-by-step guides to install Dreamcoder Workbench on different platforms. - -| Guide | Platform | -|------|-----------| -| [Linux](installation/linux.md) | Arch Linux (recommended), Fedora, Debian-based | -| [macOS](installation/macos.md) | macOS Sonoma+ | -| [WSL](installation/wsl.md) | Windows Subsystem for Linux | -| [Termux](installation/termux.md) | Android via Termux | - ---- - -## Configuration - -Configuration guides for individual components. - -| Guide | Component | -|------|-----------| -| [Terminal](configuration/terminal-config.md) | Kitty, Ghostty, WezTerm, Alacritty | -| [Editor](configuration/editor-config.md) | Neovim, VS Code / Antigravity | -| [Shell](configuration/shell-config.md) | Zsh, Bash, Starship, Fish, Nushell | -| [Multiplexer](configuration/multiplexer-config.md) | Tmux, Zellij | -| [ML4W Integration](configuration/ml4w.md) | Profile-driven keybindings, native dispatchers, file layout | -| [Theme System](configuration/theme-system.md) | Theme engine architecture, tokens, variants | -| [gga Model Pin](configuration/gga.md) | Gentleman Guardian Angel reviews pinned to Codex `gpt-6.1-sol` (medium) | - ---- - -## Development - -Guides for contributors and developers. - -| Resource | Description | -|---------|-------------| -| [CONTRIBUTING](../CONTRIBUTING.md) | How to contribute: setup, tests, PR guidelines | -| [Design Docs](superpowers/specs/) | Design specs and implementation plans (SDD) | -| [Theme Preview](generated/dreamcoder-theme-preview.md) | Automatically generated preview of all themes | -| [PyPI Publishing](pypi-publishing.md) | Publishing `dreamcoder-theme` to PyPI with Trusted Publisher | -| [Migration Guides](migration/) | Migrating from ML4W and Gentleman.Dots | - ---- - -## Root Links - -- [Main README](../README.md) — overview, badges, quick start -- [GitHub Repository](https://github.com/Dreamcoder08/Dreamcoder-Workbench) -- [PyPI Package](https://pypi.org/project/dreamcoder-theme/) +# Dreamcoder Workbench documentation + +Find the next guide for your task, then use the technical references when you +need implementation details. For the project overview and ownership of the +upstream environments, start with the [main README](../README.md). + +## Get started + +1. Read the [installation guide](../INSTALL.md) for the full desktop journey, + verification and troubleshooting. +2. Choose the component guides below for the tools you actually use. +3. Read the [source manifest](sources.md) to understand what Dreamcoder + Workbench owns and what comes from Gentleman.Dots and ML4W. + +The full desktop path targets Arch Linux or a derivative with ML4W. The other +platform guides describe component-specific approaches, not a guarantee of a +complete desktop or compatibility for every component. + +| Platform guide | Use it for | +| --- | --- | +| [Linux](installation/linux.md) | Linux setup and distribution-specific notes | +| [macOS](installation/macos.md) | macOS components | +| [WSL](installation/wsl.md) | Components in Windows Subsystem for Linux | +| [Termux](installation/termux.md) | Components on Android through Termux | + +## Configure your workspace + +| Task | Guide | +| --- | --- | +| Configure a terminal | [Terminal configuration](configuration/terminal-config.md) | +| Configure an editor | [Editor configuration](configuration/editor-config.md) | +| Configure a shell or prompt | [Shell configuration](configuration/shell-config.md) | +| Configure a multiplexer | [Tmux and Zellij](configuration/multiplexer-config.md) | +| Set up ML4W profiles and keybindings | [ML4W integration](configuration/ml4w.md) | +| Understand or regenerate themes | [Theme system](configuration/theme-system.md) and [theme preview](generated/dreamcoder-theme-preview.md) | +| Configure the review model | [gga model pin](configuration/gga.md) | +| Explore AI tool integrations | [AI integration](ai-integration.md) and [Herdr integration](herdr.md) | +| Move from an upstream setup | [Gentleman.Dots migration](migration/from-gentleman.md) or [ML4W migration](migration/from-ml4w.md) | + +## Develop and maintain + +- [Contributing](../CONTRIBUTING.md) covers development setup, tests and pull requests. +- [Design system](DREAMCODER_DESIGN_SYSTEM.md) describes visual identity and + color guidelines; [dark theme validation](configuration/dark-theme-validation.md) + records validation details. +- [Control Center](DREAMCODER_CONTROL_CENTER.md) describes the control dashboard. +- [PyPI publishing](pypi-publishing.md) covers package release maintenance. +- [Operator report](generated/DREAMCODER_OPERATOR_REPORT.md) is a generated + technical report, not an installation guide. + +## Architecture and reference + +These resources explain implementation and decisions rather than the onboarding path. + +- [Theme pipeline](architecture/theme-pipeline.mmd), [data flow](architecture/data-flow.mmd) + and [monorepo structure](architecture/monorepo-structure.mmd) are Mermaid diagrams. +- [Source manifest](sources.md) describes upstream pins and ownership; + its [machine-readable manifest](upstream-manifest.json) and + [schema](upstream-manifest.schema.json) support maintenance. +- Architecture decision records: [project structure](adr/0001-project-structure.md), + [toolchain selection](adr/0002-toolchain-selection.md), + [Python quality](adr/0003-python-quality-strategy.md), + [shell testing](adr/0004-shell-test-strategy.md) and + [CI/CD quality gates](adr/0005-ci-cd-quality-gates.md). + +## Historical designs and plans + +[Design specifications](superpowers/specs/) and [implementation plans](superpowers/plans/) +record project proposals and past work. They are context, not necessarily current +setup instructions. The [prefix restructure proposal](architecture/sdd-prefix-restructure/01-proposal.md) +is also architectural history; use the current guides above for onboarding. From f34706ba4b910c5e91ca66aa6ac82284b2503feb Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 02:35:23 -0500 Subject: [PATCH 3/6] docs: unify installation and recovery guidance --- INSTALL.md | 248 +++++++++++++++--------------------- docs/installation/linux.md | 168 ++++-------------------- docs/installation/macos.md | 66 ++++------ docs/installation/termux.md | 66 +++++----- docs/installation/wsl.md | 73 +++++------ 5 files changed, 216 insertions(+), 405 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 8ba2fc9..c1da6f8 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,184 +1,146 @@ -# Dreamcoder Workbench — Installation Guide +# Install Dreamcoder Workbench on an ML4W desktop -> Complete installation in 3 steps: Gentleman.Dots → ML4W → Dreamcoder Workbench. +This is the canonical full desktop path: install the Gentleman.Dots base and +ML4W first, then apply the Dreamcoder Workbench overlay. It is intended for an +Arch Linux desktop or derivative; it is not a guarantee for every distribution, +release, application or hardware combination. For component-only use, see the +[Linux](docs/installation/linux.md), [macOS](docs/installation/macos.md), +[WSL](docs/installation/wsl.md) and [Termux](docs/installation/termux.md) guides. -## Prerequisites +## Before you start -- **Arch Linux** (or a derivative) -- `git`, `stow`, `python3` installed -- Internet connection +- Review the upstream installation requirements and make an independent backup + of your home configuration and any data you cannot lose. Keep the backup + outside paths the installer will change. +- You need Git, GNU Stow, Python 3.11 or newer, a Python virtual environment + with pip, and an internet connection for dependencies. The theme package + declares Jinja2 as a dependency. +- Run the commands below as your normal user, not as root. The installer changes + files and links in your home directory, applies hooks, attempts to enable a + user systemd timer and runs automatic theme selection. Review the plan before + deciding to proceed. A working user systemd session is needed for the timer. ---- +## 1. Set up the upstream environments -## Step 1: Gentleman.Dots +1. Follow the current [Gentleman.Dots instructions](https://github.com/Gentleman-Programming/Gentleman.Dots) + for its shell, editor and terminal base. Select the components you need. +2. Follow the official [ML4W instructions](https://ml4w.com/os/) for the + Hyprland desktop. Complete upstream setup before applying this overlay. -Gentleman.Dots provides the base for Neovim, shells, terminals, and multiplexers. +These projects own their installers and prerequisites; consult their current +instructions rather than assuming an old command or release applies. -### Option A: Homebrew (recommended) +## 2. Get the overlay and prepare Python -```bash -brew install Gentleman-Programming/tap/gentleman-dots -gentleman-dots -``` - -### Option B: Direct download - -```bash -curl -fsSL https://github.com/Gentleman-Programming/Gentleman.Dots/releases/latest/download/gentleman-installer-linux-amd64 -o gentleman.dots -chmod +x gentleman.dots -./gentleman.dots -``` - -### Option C: Manual +Choose a location you intend to keep: Stow links can point into the clone. ```bash -git clone https://github.com/Gentleman-Programming/Gentleman.Dots.git -cd Gentleman.Dots -./install.sh +git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git +cd Dreamcoder-Workbench +python3 --version +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e . ``` -Follow the installer TUI to select: +Check that the displayed Python version is at least 3.11 before creating the +virtual environment. If your default `python3` is older, create the environment +with an available Python 3.11+ interpreter instead. Installing the package in +that environment also installs its declared Jinja2 dependency. Reactivate the +same environment in each new shell before running the wrapper: it invokes +`python3`, and exposing the source tree alone does not install dependencies. -- Shell: Fish (recommended), Zsh, or Nushell -- Terminal: Ghostty (recommended) or Kitty -- Multiplexer: Tmux or Zellij -- Editor: Neovim +## 3. Inspect, then install -> More info: [Gentleman.Dots](https://github.com/Gentleman-Programming/Gentleman.Dots) - ---- - -## Step 2: ML4W OS - -ML4W provides the full Hyprland desktop base. +From the clone, with the environment active: ```bash -bash <(curl -s https://ml4w.com/os/stable) +./scripts/dreamcoder installer plan --json ``` -This installs: - -- **Hyprland**: animations, keybinds, monitors, layouts, windows, workspaces -- **Waybar**: status bar with modules -- **Rofi**: app launcher -- **Dunst**: notifications -- **GTK 3.0/4.0**: theme and config -- **Btop**: system monitor -- **Matugen**: dynamic color generation - -> More info: [ML4W OS](https://ml4w.com/os/) - ---- - -## Step 3: Dreamcoder Workbench - -Dreamcoder Workbench applies its visual layer over Gentleman + ML4W. - -### Clone - -```bash -git clone git@github.com:Dreamcoder08/Dreamcoder-Workbench.git ~/Documents/PROYECTOS/Dreamcoder-Workbench -cd ~/Documents/PROYECTOS/Dreamcoder-Workbench -``` - -### Install the Python package (theme engine) - -```bash -pip install -e . -# or, with uv: -uv sync -``` - -### Install +The plan reports managed targets and potential conflicts. It is an inspection, +not a substitute for reviewing your existing configuration or a complete list +of every hook and generated file. If the changes are acceptable, run: ```bash ./scripts/dreamcoder install ``` -This: - -1. Creates backups of existing configs -2. Stows the modules (DreamcoderShell, DreamcoderKitty, DreamcoderGhostty, DreamcoderFastfetch, DreamcoderWarp, DreamcoderBat, DreamcoderSystemd) -3. Installs the theme hooks for each app -4. Activates the systemd timer for auto-theme switching -5. Runs the first theme sync - -### Verify - -```bash -./scripts/dreamcoder doctor # Full health check -./scripts/dreamcoder status # System status -``` - ---- - -## Post-Installation +The installer creates a backup manifest for selected targets and prints its ID; +record that ID. It stows shell, terminal, fastfetch, bat, Warp and systemd +modules into the home directory, applies ML4W and CLI hooks, attempts to enable +the user timer, and runs automatic theme selection. These operations can change +existing configuration and generated files; the manifest is not a complete +snapshot of every side effect. Timer enablement can fail without failing the +installation, so verify it separately. -### Tmux +Stow conflicts are a separate preservation mechanism: the installer moves +blocking files or foreign symlinks to +`~/.local/share/dreamcoder/install-conflicts//`, preserving their +home-relative paths. A symlink is moved as a link, not followed. This location +uses `$XDG_DATA_HOME` when set. Inspect and retain both the manifest backup and +conflict directory; neither replaces an independent backup. -If you use Tmux with TPM: - -```bash -tmux -prefix + I # Install plugins -``` - -### Neovim - -Open Neovim. LazyVim installs the plugins automatically: - -```bash -nvim -:Lazy sync -``` - -### Auto Theme Switching - -The systemd timer activates automatically. To verify: +## 4. Verify and choose a mode ```bash +./scripts/dreamcoder doctor +./scripts/dreamcoder status systemctl --user status dreamcoder-theme-auto.timer ``` -The timer switches modes by schedule: - -- **07:00-18:00** → Light -- **18:00-07:00** → Dark - ---- - -## Troubleshooting +Doctor reports health findings rather than promising every optional component +is present. Status compares several generated configurations with the scheduled +mode and can report mismatches, including after a manual mode change. The timer +status may be inactive if user systemd or timer enablement is unavailable. +Investigate reported findings for the components you actually use. -### "Theme files not found" - -Make sure you installed Gentleman.Dots and ML4W first. Dreamcoder Workbench is an overlay, not a replacement. - -### "Error: stow not found" +To apply a mode manually, knowing that this writes configuration and may reload +integrations: ```bash -sudo pacman -S stow +./scripts/dreamcoder dark +# Or: ./scripts/dreamcoder light ``` -### "Colors not updating" +Automatic selection defaults to light from 07:00 until 18:00 and dark otherwise; +local settings can change the window. Applications may require their own reload +or may not consume the generated theme automatically. + +## Recovery and troubleshooting + +- **Missing Python module or Jinja2:** activate the environment and repeat the + package installation in step 2. Confirm `python3 --version` in that shell. +- **Missing Stow:** install GNU Stow using your distribution's package manager, + then review the plan again. Do not run pip with sudo. +- **Upstream upgrade changed links:** ML4W may re-point shell or terminal targets + to its own tree. Inspect the plan and your backups before running + `./scripts/dreamcoder repair`. Repair also backs up, relinks where Stow is + available, applies hooks, attempts the timer and runs theme selection. Conflicts + are moved to a new conflict directory; copy any still-needed upstream data, such + as fish universal variables, back by hand after inspecting both locations. +- **Theme or timer mismatch:** check doctor, status and the user timer output above; + confirm that the affected application is installed and reads its configuration. + Avoid assuming every integration is supported on your machine. + +To inspect available manifests and preview a restore, use the ID printed during +installation (replace `BACKUP_ID` with that ID): ```bash -dreamcoder dark # Force dark mode -dreamcoder light # Force light mode -``` - -### "Neovim colorscheme not loading" - -Add this to `~/.config/nvim/init.lua`: - -```lua -vim.cmd.colorscheme("dreamcoder") +./scripts/dreamcoder backup list --json +./scripts/dreamcoder backup restore BACKUP_ID --dry-run --json ``` ---- +After inspecting the paths and independently preserving newer changes, omit +`--dry-run` to restore that manifest. Restore replaces or removes the selected +paths according to their pre-install state; it does not necessarily undo all +hooks, generated files, timer state or Stow links. Inspect the separate conflict +directory as well. Do not delete the clone as an uninstall shortcut: remaining +links may depend on it. Review and remove or restore individual changes only +when you understand their ownership. -## References +## Next steps -- [Gentleman.Dots](https://github.com/Gentleman-Programming/Gentleman.Dots) -- [ML4W OS](https://ml4w.com/os/) -- [Dreamcoder Workbench docs index](docs/README.md) -- [Architecture Docs](docs/architecture/) +See the [documentation hub](docs/README.md) for configuration guides, the +[theme system](docs/configuration/theme-system.md) for synchronization, and the +[source manifest](docs/sources.md) for upstream ownership. diff --git a/docs/installation/linux.md b/docs/installation/linux.md index 0dfaa72..001e00f 100644 --- a/docs/installation/linux.md +++ b/docs/installation/linux.md @@ -1,153 +1,33 @@ -# Installing Dreamcoder Workbench on Linux +# Install Dreamcoder Workbench on Linux -## Prerequisites +For an Arch Linux or derivative desktop with Gentleman.Dots and ML4W, follow the +[canonical full installation guide](../../INSTALL.md). It covers prerequisites, +configuration changes, verification, upstream relinking and recovery. Other +Linux distributions and individual integrations are not automatically guaranteed +compatible. -- **Arch Linux** (recommended), Fedora, or Ubuntu/Debian -- `git`, `python` 3.11+, `curl` -- `systemd --user` available (for auto-theme timer) -- ~10GB free disk space +## Component-only exploration -## Step 1: Install Gentleman.Dots +If you do not want the desktop overlay, clone the repository and install only +its Python package in a virtual environment as described in the +[full installation guide](../../INSTALL.md). Do not run +`./scripts/dreamcoder install` unless you intend to apply its home-directory +changes and Linux desktop hooks. -Gentleman.Dots provides: Neovim (29 plugins LazyVim), Ghostty shaders (53), Tmux/Zellij, Fish/Zsh/Nushell. +With the environment active, inspect the package CLI: ```bash -# Option A: Homebrew (recommended) -brew install Gentleman-Programming/tap/gentleman-dots -gentleman-dots - -# Option B: Direct download -curl -fsSL https://github.com/Gentleman-Programming/Gentleman.Dots/releases/latest/download/gentleman-installer-linux-amd64 -o gentleman.dots -chmod +x gentleman.dots -./gentleman.dots -``` - -The TUI will guide you through selecting your preferred tools. - -> **Important:** After installation, open tmux and press `prefix + I` (capital I) to install TPM plugins. - -## Step 2: Install ML4W OS - -ML4W provides: Hyprland (animations, keybinds, monitors), Waybar, Rofi, Dunst, Btop, GTK. - -```bash -bash <(curl -s https://ml4w.com/os/stable) +dreamcoder-theme --help +dreamcoder-theme installer plan --json ``` -> **Important:** After installation, reboot or restart Hyprland for changes to take effect. - -## Step 3: Install Dreamcoder Workbench - -Dreamcoder Workbench provides: Token-based color engine, Starship prompt with AI session state, auto-theme switching, 19 shell functions. - -```bash -# Clone -git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git ~/Documents/PROYECTOS/Dreamcoder-Workbench -cd ~/Documents/PROYECTOS/Dreamcoder-Workbench - -# Install Python package (required for theme engine) -pip install -e . - -# Run installer -./scripts/dreamcoder install -``` - -## Step 4: Verify Installation - -Run the comprehensive health check: - -```bash -dreamcoder doctor -``` - -Expected output: all checks pass - -### Quick verification checklist - -```bash -# 1. Theme files exist -ls ~/.config/ghostty/themes/dreamcoder* -ls ~/.config/kitty/colors-dreamcoder.conf -ls ~/.config/hypr/dreamcoder-colors.lua -ls ~/.config/btop/themes/dreamcoder.theme - -# 2. Symlinks are correct -readlink ~/.config/hypr/dreamcoder-colors.lua # → hypr-colors-light.lua or hypr-colors-dark.lua -readlink ~/.config/btop/themes/dreamcoder.theme # → dreamcoder-light.theme or dreamcoder-dark.theme -readlink ~/.config/waybar/colors.css # → colors-light.css or colors-dark.css -readlink ~/.config/rofi/colors.rasi # → colors-light.rasi or colors-dark.rasi - -# 3. Hyprland loads dreamcoder colours (from the generated custom.lua) -grep "dreamcoder-colors" ~/.config/hypr/custom.lua # → require("dreamcoder-colors") - -# 4. Timer is active -systemctl --user is-active dreamcoder-theme-auto.timer # → active - -# 5. Mode switching works -dreamcoder dark -dreamcoder light -dreamcoder status -``` - -## Mode Switching - -```bash -# Manual -dreamcoder dark # → Dreamcoder Dark -dreamcoder light # → Cocoa/Lúcuma -dreamcoder status # → System overview - -# Automatic (via systemd timer) -# Switches at 07:00 (light) and 18:00 (dark) -systemctl --user status dreamcoder-theme-auto.timer -``` - -## Rollback - -```bash -# Option A: From backup manifest -ls ~/.local/share/dreamcoder/backups/ -# Pick the latest backup id and restore it: -./scripts/dreamcoder backup restore --json - -# Option B: Manual per component -rm ~/.config/hypr/dreamcoder-colors.lua -rm ~/.config/btop/themes/dreamcoder.theme -sed -i 's/color_theme = "dreamcoder"/color_theme = "matugen"/' ~/.config/btop/btop.conf - -# The dreamcoder-colors loader lives in the generated ~/.config/hypr/custom.lua; -# with dreamcoder-colors.lua removed, its guard skips the require. - -# Disable timer -systemctl --user disable --now dreamcoder-theme-auto.timer -``` - -## Troubleshooting - -| Problem | Solution | -| ------------------------------- | ----------------------------------------------------------- | -| `dreamcoder: command not found` | Ensure `~/.local/bin` is in your PATH | -| Ghostty theme not loading | Verify `~/.config/ghostty/config` has `theme = dreamcoder` | -| Kitty colors not showing | Check `include colors-dreamcoder.conf` in `kitty.conf` | -| Hyprland colors look wrong | Run `hyprctl reload` after mode switch | -| Btop theme not found | Run `dreamcoder-theme sync` to regenerate | -| Auto-timer not switching | Check `systemctl --user status dreamcoder-theme-auto.timer` | -| Doctor reports missing files | Run `./scripts/dreamcoder repair` | - -### Upstream upgrades that re-point Dreamcoder targets - -An ML4W upgrade can re-point `~/.config/fish`, `~/.config/kitty`, -`~/.config/fastfetch`, `~/.bashrc`, or `~/.zshrc` to its own tree under -`~/.mydotfiles`. `./scripts/dreamcoder repair` (and `install`) relinks the -Dreamcoder stow modules (`DreamcoderShell`, `DreamcoderKitty`, -`DreamcoderGhostty`, `DreamcoderFastfetch`, `DreamcoderWarp`, `DreamcoderBat`, -`DreamcoderSystemd`) before applying hooks: +The package command is the control CLI; it does not provide a `sync` subcommand. +The plan describes installer targets, not a promise of compatibility. To generate +themes separately, the repository wrapper offers `./scripts/dreamcoder sync`; +this writes generated configuration and potentially repository files, so review +the [theme system guide](../configuration/theme-system.md) and back up affected +configuration before using it. Generated files alone do not ensure that an +application loads them. -- a stow dry run lists every blocking target: regular files, and symlinks stow - does not own (foreign trees or absolute links into the repo); -- each one is moved, never deleted, to - `~/.local/share/dreamcoder/install-conflicts//`; - symlinks move as links, so the tree they point to stays untouched; -- stow then links the modules. Anything the upstream tree held that you still - need (for example fish universal variables in its `fish_variables`) must be - copied back by hand. +Return to the [documentation hub](../README.md) for configuration and other +platform guides. diff --git a/docs/installation/macos.md b/docs/installation/macos.md index f860f7b..ede5eb2 100644 --- a/docs/installation/macos.md +++ b/docs/installation/macos.md @@ -1,48 +1,38 @@ -# Installing Dreamcoder Workbench on macOS +# Dreamcoder Workbench on macOS -## Prerequisites +This is a component-only path, not the full ML4W desktop installation. macOS +versions and individual integrations have not been established as compatible. +The full installer applies Linux desktop hooks and attempts a systemd user timer; +do not run it on the host as a general macOS setup. -- macOS 12+ -- Homebrew -- Git +## Install the Python package only -## Install - -Dreamcoder Workbench is distributed as a git repository, not a Homebrew formula. +Install Git and Python 3.11 or newer using your preferred trusted source. Then: ```bash -# Install base dependencies -brew install stow git python - -# Clone and install -git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git ~/Dreamcoder-Workbench -cd ~/Dreamcoder-Workbench - -# Install the Python theme engine -pip install -e . -# or, with uv: -uv sync - -# Run the installer -./scripts/dreamcoder install +git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git +cd Dreamcoder-Workbench +python3 --version +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e . +dreamcoder-theme --help ``` -## Verify - -```bash -./scripts/dreamcoder doctor # Health check -./scripts/dreamcoder status # System status -``` - -If the installer was skipped, you can still use the theme engine directly: - -```bash -dreamcoder-theme sync -``` +Use a Python 3.11+ interpreter to create the environment if `python3` is older. +The package declares Jinja2; pip installs it in the virtual environment. The +help output lists the control CLI commands, not a package `sync` subcommand. +Reactivate the environment when returning to the clone; the repository wrapper +calls `python3` and needs its dependencies available. -## Rollback +## Before generating configuration -- The installer writes a backup manifest under `~/.local/share/dreamcoder/backups/` before changing configs. To restore, run `./scripts/dreamcoder backup restore --json` with the backup id shown during install. -- To remove the environment entirely, delete the symlinks the installer created (listed in the backup manifest) and remove the `~/Dreamcoder-Workbench` directory. +The repository's `./scripts/dreamcoder sync` writes generated configuration and +may write repository files. Back up affected configuration and review the +[theme system guide](../configuration/theme-system.md) before running it. A +generated theme does not mean an installed application will load it, and Linux +hooks, desktop integration and timer behavior should not be assumed to work on +macOS. Package installation alone does not apply the full overlay. -> **Note**: terminal, shell, and multiplexer overlays assume a Linux-style environment; GUI and systemd-timer features are limited on macOS. +For the intended Linux desktop, see the [full installation guide](../../INSTALL.md); +for other topics, return to the [documentation hub](../README.md). diff --git a/docs/installation/termux.md b/docs/installation/termux.md index 74cfbde..205747d 100644 --- a/docs/installation/termux.md +++ b/docs/installation/termux.md @@ -1,47 +1,39 @@ -# Installing Dreamcoder Workbench on Termux (Android) +# Dreamcoder Workbench on Termux -## Prerequisites +This is a component-only path, not an ML4W desktop setup. Android and Termux +versions and individual integrations have not been established as compatible. +The full installer applies Linux desktop hooks and attempts a systemd user +timer; do not run it as a general Termux host setup. -- Termux app (from F-Droid, NOT Play Store) -- Android 7+ +## Install the Python package only -## Install +Make Git and Python 3.11 or newer, with virtual environment and pip support, +available in Termux. Then: ```bash -pkg update && pkg upgrade -pkg install stow git python nodejs - -git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git ~/Dreamcoder-Workbench -cd ~/Dreamcoder-Workbench - -# Install the Python theme engine -pip install -e . -# or, with uv: -uv sync - -# Run the installer -./scripts/dreamcoder install -``` - -## Verify - -```bash -./scripts/dreamcoder doctor # Health check -./scripts/dreamcoder status # System status -``` - -If the installer was skipped, you can still use the theme engine directly: - -```bash -dreamcoder-theme sync +git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git +cd Dreamcoder-Workbench +python3 --version +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e . +dreamcoder-theme --help ``` -## Limitations +If `python3` is older, create the environment with an available Python 3.11+ +interpreter. Pip installs the declared Jinja2 dependency in that environment. +The help output lists the control CLI commands; the package CLI has no `sync` +subcommand. Reactivate the environment when returning: the repository wrapper +calls `python3` and needs its dependencies available. -- No systemd (light/dark automation unavailable) -- No GUI apps (Kitty/Ghostty unavailable) -- Limited shader support +## Before generating configuration -## Rollback +The repository's `./scripts/dreamcoder sync` writes generated configuration and +may write repository files. Back up affected configuration and review the +[theme system guide](../configuration/theme-system.md) before running it. +Generated themes do not guarantee that Termux or any application consumes them; +do not assume Linux desktop hooks or systemd timer integration work. Installing +the package alone does not apply the full overlay. -The installer writes a backup manifest under `~/.local/share/dreamcoder/backups/` before changing configs. To restore, run `./scripts/dreamcoder backup restore --json` with the backup id shown during install. Remove the `~/Dreamcoder-Workbench` directory to uninstall the environment. +For the intended Linux desktop, see the [full installation guide](../../INSTALL.md); +return to the [documentation hub](../README.md) for other guides. diff --git a/docs/installation/wsl.md b/docs/installation/wsl.md index 00d28f7..72feef8 100644 --- a/docs/installation/wsl.md +++ b/docs/installation/wsl.md @@ -1,53 +1,40 @@ -# Installing Dreamcoder Workbench on Windows WSL +# Dreamcoder Workbench on WSL -## Prerequisites +Use this component-only path inside a WSL distribution, not as a full desktop +setup. WSL distributions, Windows versions and individual integrations have not +been established as compatible. The full installer applies Linux desktop hooks +and attempts a systemd user timer; do not run it as a general WSL host setup. -- Windows 10/11 with WSL2 enabled -- Ubuntu or Debian on WSL -- GNU Stow +## Install the Python package only -## Install +Make Git and Python 3.11 or newer, including virtual environment and pip +support, available in the distribution. Then run inside WSL: ```bash -# Install dependencies -sudo apt update && sudo apt install -y stow git python3 python3-venv - -# Clone and install -git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git ~/Dreamcoder-Workbench -cd ~/Dreamcoder-Workbench - -# Install the Python theme engine -pip install -e . -# or, with uv: -uv sync - -# Run the installer -./scripts/dreamcoder install -``` - -## Verify - -```bash -./scripts/dreamcoder doctor # Health check -./scripts/dreamcoder status # System status +git clone https://github.com/Dreamcoder08/Dreamcoder-Workbench.git +cd Dreamcoder-Workbench +python3 --version +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e . +dreamcoder-theme --help ``` -If the installer was skipped, you can still use the theme engine directly: - -```bash -dreamcoder-theme sync -``` - -## Using Windows Terminal - -After install, configure Windows Terminal to use: - -- Shell: `wsl -d Ubuntu` -- Font: JetBrainsMono Nerd Font -- Theme: use the Dreamcoder theme in Windows Terminal settings +If `python3` is older, create the environment with an available Python 3.11+ +interpreter. Pip installs the declared Jinja2 dependency in that environment. +The help output lists the control CLI commands; the package CLI has no `sync` +subcommand. Reactivate the environment when returning: the repository wrapper +calls `python3` and needs its dependencies available. -## Rollback +## Before generating configuration -The installer writes a backup manifest under `~/.local/share/dreamcoder/backups/` before changing configs. To restore, run `./scripts/dreamcoder backup restore --json` with the backup id shown during install. Remove the `~/Dreamcoder-Workbench` directory to uninstall the environment. +The repository's `./scripts/dreamcoder sync` writes generated configuration and +may write repository files. Back up affected configuration and review the +[theme system guide](../configuration/theme-system.md) before running it. +Generated files do not automatically configure Windows Terminal or ensure an +application loads a theme. User systemd availability depends on the WSL setup; +do not assume the timer or desktop integrations work. Installing the package +alone does not apply the full overlay. -> **Note**: WSL has no systemd by default, so the auto-theme timer is unavailable unless systemd is enabled in WSL (systemd-enabled WSL distros support `systemctl --user`). +For the intended Linux desktop, see the [full installation guide](../../INSTALL.md); +return to the [documentation hub](../README.md) for other guides. From c7198cd11aef5a65e40904dd6ddd1763402ec827 Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 02:35:24 -0500 Subject: [PATCH 4/6] docs: clarify component configuration and theme integration --- docs/configuration/editor-config.md | 44 +++---------- docs/configuration/multiplexer-config.md | 54 +++++----------- docs/configuration/shell-config.md | 33 +++------- docs/configuration/terminal-config.md | 79 +++++------------------- 4 files changed, 45 insertions(+), 165 deletions(-) diff --git a/docs/configuration/editor-config.md b/docs/configuration/editor-config.md index 2314051..a542060 100644 --- a/docs/configuration/editor-config.md +++ b/docs/configuration/editor-config.md @@ -1,43 +1,13 @@ -# Editor Configuration +# Configure Neovim -## Neovim (LazyVim) +The repository provides a thin Neovim layer over Gentleman.Dots, not a standalone LazyVim installation. Complete the upstream setup and review the [desktop installation guide](../../INSTALL.md) or a component guide before using it. -### Structure +## Use the theme -``` -DreamcoderNvim/.config/nvim/ -├── init.lua # Bootstrap -├── lua/ -│ ├── config/ # Core config -│ ├── plugins/ # Plugin specs -│ └── colors/ # Dreamcoder colorscheme -``` +`DreamcoderNvim/.config/nvim/init.lua` loads `$HOME/Gentleman.Dots/GentlemanNvim/nvim/init.lua` and then selects the `dreamcoder` colorscheme. The `colors/` directory contains the dispatcher and generated dark and light variants. Ensure the configuration and colors directory are installed where Neovim reads them; generation alone does not install the editor configuration. -### Theme +The dispatcher uses the mode and cached selection; an already running editor may need a reload or restart. To change mode, use the wrapper described in the [theme system guide](theme-system.md), with its configuration write and reload implications. If the upstream clone lives elsewhere, inspect the configured path before loading this layer. -Dreamcoder colorscheme generated from `tokens.json`: +## Customize the editor -```lua --- lua/plugins/colorscheme.lua -return { - "dreamcoder.nvim", - opts = { - variant = "dark", -- or "light" - }, -} -``` - -### Key Maps - -LazyVim provides the default keymaps for this setup. See the [Theme](#theme) section above for the Dreamcoder colorscheme setup. - -### Plugins - -Core plugins: - -- LazyVim (framework) -- LSP (nvim-lspconfig) -- Treesitter (syntax) -- Telescope (fuzzy finder) -- Git signs -- Which-key (key hints) +Gentleman.Dots owns the bootstrap, keymaps and plugin configuration loaded by this layer. Consult that upstream configuration for installed plugins and bindings rather than assuming that this repository supplies them. For terminal appearance, continue to [terminal configuration](terminal-config.md), or return to the [documentation hub](../README.md). diff --git a/docs/configuration/multiplexer-config.md b/docs/configuration/multiplexer-config.md index 17c3e31..369003d 100644 --- a/docs/configuration/multiplexer-config.md +++ b/docs/configuration/multiplexer-config.md @@ -1,51 +1,25 @@ -# Terminal Multiplexer Configuration +# Configure a terminal multiplexer -## Supported Multiplexers - -- **Tmux** — Classic terminal multiplexer -- **Zellij** — Modern terminal workspace +Choose Tmux or Zellij and inspect the corresponding repository configuration before installing it. The canonical desktop installer does not list either as a Stow module; generating a theme is not the same as installing a multiplexer configuration. See [INSTALL.md](../../INSTALL.md) for the desktop path and platform-specific component guides. ## Tmux -### Key Bindings - -| Action | Key | -|--------|-----| -| Prefix | Ctrl+a | -| Split horizontal | prefix + \| | -| Split vertical | prefix + - | -| Navigate panes | Alt+Arrow | -| Vi mode | prefix + [ | - -### Plugins (TPM) +`DreamcoderTmux/.tmux.conf` conditionally sources the Gentleman.Dots Tmux configuration from `$HOME/Gentleman.Dots/GentlemanTmux/tmux.conf`, then loads `~/.config/tmux/tmux-dreamcoder-base.conf`. Make both paths available if using this layer. The upstream configuration supplies the base and its prefix; the local config adds: -- `tmux-resurrect` — Session save/restore -- `tmux-continuum` — Auto-save -- `tmux-sensible` — Better defaults -- `tmux-yank` — System clipboard +| Action | Binding | +|--------|---------| +| Horizontal / vertical split | prefix + `\|` / prefix + `-` | +| Navigate panes | Alt + h/j/k/l | +| Reload configuration | prefix + r | +| Detach | prefix + D or prefix + Ctrl+d | +| Session picker | prefix + f (requires fzf) | -### Theme - -Tmux auto-detects theme mode: - -```bash -if-shell '[ "$DREAMCODER_THEME_MODE" = "light" ]' \ - 'source-file ~/.config/tmux/dreamcoder-light.conf' \ - 'source-file ~/.config/tmux/dreamcoder-dark.conf' -``` +The local config declares `tmux-continuum`; other plugin setup belongs to the upstream base. The generated active theme is `~/.config/tmux/tmux-dreamcoder.conf` by default. Ensure the installed configuration reads the relevant theme files, then reload it or restart the session as needed. ## Zellij -### Key Bindings - -| Action | Key | -|--------|-----| -| New tab | Alt+N | -| Next tab | Alt+K | -| Previous tab | Alt+J | -| Go to tab 1-5 | Alt+1-5 | -| Toggle tab | Ctrl+T | +`DreamcoderZellij/.config/zellij/config.kdl` declares Alt+n for a new tab, Alt+j/k for previous/next tab, Alt+1–5 for tab selection and Ctrl+t for tab mode. The `dreamcoder` layout has a base pane and a top tab/time bar using `zjstatus`; it is a layout file, not a claim that it is selected by default. -### Layout +The theme sync updates the Zellij selector and generates dark/light KDL themes. Make those themes available to the installed Zellij configuration and restart or reload as supported by your version; writing files alone does not ensure a running session changes. -Default layout: `dreamcoder` — vertical split with 20% sidebar. +For mode selection and synchronization, see the [theme system guide](theme-system.md); for terminal setup, see [terminal configuration](terminal-config.md). diff --git a/docs/configuration/shell-config.md b/docs/configuration/shell-config.md index 14566c8..7436a96 100644 --- a/docs/configuration/shell-config.md +++ b/docs/configuration/shell-config.md @@ -1,20 +1,13 @@ -# Shell Configuration +# Configure your shell -## Supported Shells +Choose the shell you use, then review its configuration before installing it. The [installation guide](../../INSTALL.md) covers the desktop overlay; individual integrations and platforms have different prerequisites. -- **Fish** — Default shell, friendly interactive shell -- **Zsh** — Z shell with Oh My Zsh -- **Nushell** — Modern structured shell +## Fish and Zsh -## Theme Integration +- Fish uses `DreamcoderShell/.config/fish/config.fish` and its `conf.d` fragments. Its theme fragment reads generated LS_COLORS and fzf values through Bash and selects a Bat theme. Set `DREAMCODER_DOTS_DIR` to your clone: its fallback is a machine-specific path and may not exist on your system. Interactive Fish can start Herdr when it is installed and no multiplexer is already active. +- Interactive Zsh uses `DreamcoderShell/.zshrc`, optionally loads Oh My Zsh and available plugins, and sources existing generated snippets from `themes/dreamcoder` in the clone. It initializes optional fzf, zoxide and Starship when available. It resolves the clone from `DREAMCODER_DOTS_DIR` or the installed `.zshrc` link. -Each shell config sources Dreamcoder Workbench themes based on `DREAMCODER_THEME_MODE`: - -```bash -# In .zshrc -source ~/.config/shell/fzf-dreamcoder-${DREAMCODER_THEME_MODE}.sh -source ~/.config/shell/ls-colors-dreamcoder-${DREAMCODER_THEME_MODE}.sh -``` +Both configurations prefer a cached live mode over an inherited `DREAMCODER_THEME_MODE`, defaulting to dark when no mode is set. Fish and Zsh have different cache lookup details; inspect their fragments if using a custom cache location. Restart the shell to pick up installed configuration. The [theme system guide](theme-system.md) explains generation and mode changes; generating snippets does not install shell configuration. ## NetworkManager TUI colors @@ -57,16 +50,6 @@ All arguments, including `--help`, are forwarded to the original `nmtui`. Restart the shell after installing its integration and relaunch `nmtui` after a mode change; an already open TUI does not update in place. -## Aliases - -Common aliases across all shells: +## Customize shortcuts -| Alias | Command | Description | -|-------|---------|-------------| -| `g` | `git` | Git shortcut | -| `gs` | `git status` | Git status | -| `gp` | `git push` | Git push | -| `ll` | `ls -la` | Long listing | -| `cat` | `bat` | Syntax highlighting | -| `find` | `fd` | Find files | -| `grep` | `rg` | Ripgrep | +Shell-specific aliases and functions live under `DreamcoderShell/.config/fish/` and `DreamcoderShell/.config/shell/`. Review the relevant file and optional tool requirements before relying on a shortcut; aliases are not guaranteed to match across shells. Continue with [terminal configuration](terminal-config.md) or the [documentation hub](../README.md). diff --git a/docs/configuration/terminal-config.md b/docs/configuration/terminal-config.md index 2a190d6..2ac28cc 100644 --- a/docs/configuration/terminal-config.md +++ b/docs/configuration/terminal-config.md @@ -1,73 +1,26 @@ -# Terminal Configuration +# Configure a terminal -## Supported Terminals +Choose the terminal you actually use and review its configuration before installing or changing it. The [desktop installation guide](../../INSTALL.md) covers the full overlay; component availability varies by platform. Theme generation does not install a terminal or guarantee that an open window reloads its colors. -| Terminal | Theme Format | Notes | -|----------|-------------|-------| -| Kitty | `.conf` | GPU-accelerated, primary terminal | -| Ghostty | Custom | Custom shaders, blur effects | -| WezTerm | `.lua` | Cross-platform, Lua config | -| Alacritty | `.toml` | Minimal, fast | -| Orca | Live profile state (SQLite) | Written into Orca's own profile, not a repo file | +## Apply and verify a theme -### Orca +With the repository virtual environment active, the [theme system guide](theme-system.md) explains the wrapper's `dark`, `light` and `sync` operations and their writes. Check the application's selected theme and reload or restart it if needed. -Orca migrated its profile from JSON to SQLite. The authoritative store is -`~/.config/orca/profiles/local-default/profile-state.db`, and the -`profile-state.db.authority` marker says `sqlite`. The neighbouring -`orca-data.json` is only an export Orca rewrites on save — editing it changes -nothing Orca reads. `ORCA_DATA_PATH` overrides the profile directory and -`ORCA_STATE_DB_PATH` overrides the database path directly. +| Integration | What the repository provides | +|------------|-------------------------------| +| Kitty | Generated color and UI configuration; sync manages the UI include. | +| Ghostty | Generated theme and a configuration selector. | +| Warp | Generated theme and settings updates. | +| Orca IDE | Best-effort update of an existing live profile, not a repository theme file. | -Both `dreamcoder dark` and `dreamcoder sync` write the profile's `settings` -document: they define `Dreamcoder Dark` and `Dreamcoder Light` in -`terminalCustomThemes`, select them through `terminalThemeDark` / -`terminalThemeLight`, enable `terminalUseSeparateLightTheme`, set the -per-appearance divider colors from the palette `border_ui` token, and set the -app chrome `theme` to the active Dreamcoder mode. +A generated file is not evidence that other terminals, fonts, shortcuts or platform combinations are configured. Consult the terminal's own documentation for its font, keybindings and reload behavior. -A custom theme is addressed by id, not by display name: Orca reads the -selection as `custom:` and takes the colors from the entry's nested -`terminal` object. The managed ids are `manual:dreamcoder-dark` and -`manual:dreamcoder-light`. Entries missing usable colors are silently -discarded by Orca, which is why a name-only entry leaves Orca on a built-in -scheme while still showing the configured name. +## Orca IDE profile -The database row records the profile revision it was written at and a -`content_hash` of the exact payload bytes, and the profile revision in -`profile_state_meta` moves with it; the previous database is copied to -`profile-state.db.dreamcoder-backup.` before each write. +Orca IDE is distinct from the GNOME screen reader. Sync and mode activation attempt to update its existing profile; missing or malformed profiles are skipped. When `profile-state.db.authority` says `sqlite`, the database at `~/.config/orca/profiles/local-default/profile-state.db` is authoritative and the adjacent JSON is an export. The integration also supports a legacy JSON store. `ORCA_DATA_PATH` overrides the JSON path and thereby the default database directory; `ORCA_STATE_DB_PATH` overrides the database path directly. -Orca holds its profile in memory while its main window is open and flushes -that copy over external edits, so the sync skips the store and reports -`skipped-running` instead of writing something that would be discarded. -Close Orca, then re-run `dreamcoder dark` or `dreamcoder light` to apply. +The managed entries use IDs `manual:dreamcoder-dark` and `manual:dreamcoder-light`, selected as `custom:` with colors in each entry's nested `terminal` object. The settings also select separate light and dark themes, set divider colors and update the app chrome mode. Existing unrelated theme entries are retained. SQLite updates advance the profile revision and payload hash and back up the database first; editing the JSON export does not change the authoritative SQLite profile. -## Theme Switching +Orca's main window holds a profile in memory and can overwrite external edits. A `skipped-running` result means close the window and retry the wrapper's `dark` or `light` command, then reopen Orca. Other skipped results require inspecting the profile rather than assuming it was updated. -Terminals auto-detect `DREAMCODER_THEME_MODE` env var: - -```bash -export DREAMCODER_THEME_MODE="dark" # or "light" -``` - -## Font Configuration - -All terminals use JetBrainsMono Nerd Font: - -``` -Font: JetBrainsMono Nerd Font -Size: 14pt -Ligatures: Enabled -``` - -## Key Bindings - -Common key bindings across terminals: - -| Action | Kitty | Ghostty | WezTerm | Alacritty | -|--------|-------|---------|---------|-----------| -| New tab | Ctrl+Shift+T | Ctrl+Shift+T | Ctrl+Shift+T | Ctrl+Shift+T | -| Close tab | Ctrl+Shift+W | Ctrl+Shift+W | Ctrl+Shift+W | Ctrl+Shift+W | -| Split horizontal | Ctrl+Shift+5 | Ctrl+Shift+5 | Ctrl+Shift+5 | Ctrl+Shift+5 | -| Split vertical | Ctrl+Shift+6 | Ctrl+Shift+6 | Ctrl+Shift+6 | Ctrl+Shift+6 | +Next, configure your [shell](shell-config.md) or [multiplexer](multiplexer-config.md), or return to the [documentation hub](../README.md). From a5cc1dbde1bf4f1d471e0339df9a0f2e20254763 Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 02:35:26 -0500 Subject: [PATCH 5/6] docs: align contributor workflow and theme system guidance --- CONTRIBUTING.md | 231 ++++------------------------- docs/configuration/theme-system.md | 37 ++--- 2 files changed, 48 insertions(+), 220 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 752996a..01ff7e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,226 +1,51 @@ # Contributing -Thanks for your interest in Dreamcoder Workbench! This project is a personal dotfiles -repository with an open-source theme engine. Contributions, ideas, and bug -reports are welcome. - -## How to contribute — quick path - -1. **Report a bug** or request a feature: open an issue on the [GitHub repository](https://github.com/Dreamcoder08/Dreamcoder-Workbench). -2. **Propose a change**: fork the repo, create a branch, and commit focused changes (see [Pull Request Guidelines](#pull-request-guidelines)). -3. **Open a PR**: push your branch and open a pull request against `main`. CI runs lint, type checks, and tests automatically; pre-commit hooks run locally on every commit. - -Need a smaller first step? Pick an open issue, fix a docs typo, or add a renderer test. - -## Project Structure - -```text -src/dreamcoder_theme/ # Python theme engine (pip-installable package) - ├── palette.py # Color math, adaptive palette derivation - ├── palette_tokens.py # Static design tokens (dark/light/dusk) - ├── renderers.py # Public renderer import hub - ├── renderers_kitty.py # Kitty format renderer - ├── renderers_ghostty_warp.py - ├── renderers_codex.py - ├── renderers_opencode.py - ├── renderers_pi.py - ├── renderers_starship.py - ├── renderers_tmux.py - ├── renderers_antigravity.py - ├── renderers_readme.py - ├── renderers_hypr_waybar_rofi.py - ├── renderers_extra_nvim.py # Nvim + LSP + plugins + syntax + UI - ├── renderers_extra_obsidian.py - ├── renderers_extra_bat_delta.py - ├── renderers_extra_btop.py - ├── renderers_extra_firefox.py - ├── renderers_extra_notify.py # Dunst, Cava - ├── renderers_extra_shell.py # Zsh, LS_COLORS, fzf - ├── sync.py # Theme file orchestration - ├── control.py # CLI entry point - ├── writers.py # Filesystem writers & config updaters - ├── settings.py # Paths, mode, adaptive configuration - ├── core.py # Core path utilities - ├── doctor.py # Health checks - ├── dashboard.py # Control center dashboard - ├── cli_parser.py # CLI argument parser - ├── cli_handlers.py # CLI command handlers - ├── installer.py # Dotfiles installer - ├── repair_engine.py # Repair after updates - ├── profiles.py # ML4W profile management - ├── backups.py # Theme backup/restore - ├── audit.py # Theme audit & validation - ├── docs_report.py # Documentation health report - ├── motion.py # Motion preset scheduler - ├── tui.py # Terminal UI - ├── visual_regression.py # Visual regression testing - └── settings_store.py # Settings persistence -tests/ # pytest test suite -shell-tests/ # bats tests for shell scripts -docs/ # Documentation hub -scripts/ # Shell automation scripts -DreamcoderThemes/dreamcoder/ # Generated theme files (output) -``` - -Each tool lives in a Dreamcoder-prefixed top-level directory -(`DreamcoderKitty/`, `DreamcoderGhostty/`, `DreamcoderNvim/`, etc.) -and is installed via GNU Stow. - -## Development Setup - -```bash -# Clone and enter -git clone git@github.com:Dreamcoder08/Dreamcoder-Workbench.git -cd Dreamcoder-Workbench - -# Install with dev dependencies (using pip) -pip install -e ".[dev]" - -# Or using uv (recommended) -uv pip install -e ".[dev]" -``` - -## Quality Commands - -The project provides a `Makefile` with common quality commands: - -```bash -make lint # ruff check + ruff format --check + shellcheck + mypy -make test # pytest tests/ -v -make coverage # pytest --cov=dreamcoder_theme --cov-report=term-missing -make format # auto-format all Python files with ruff -make type-check # mypy src/ (strict mode) -make python-lint # ruff only -make shell-lint # shellcheck on scripts/*.sh -make clean # remove build artifacts -make build # build wheel + source tarball -``` - -Or run tools individually: - -```bash -# Full test suite -pytest - -# With coverage -pytest --cov=dreamcoder_theme --cov-report=term-missing - -# Specific test file -pytest tests/test_palette.py -v -``` - -## Linting +Thanks for helping improve Dreamcoder Workbench. Report bugs and propose changes on the [GitHub repository](https://github.com/Dreamcoder08/Dreamcoder-Workbench); keep pull requests focused and include tests for behavior changes. -```bash -# ruff for Python -ruff check src/dreamcoder_theme/ - -# auto-fix -ruff check --fix src/dreamcoder_theme/ - -# shellcheck for shell scripts -shellcheck --shell=bash scripts/*.sh -``` - -## Pre-commit Hooks +## Prepare a local development environment -The project uses pre-commit to enforce quality on every commit. Install it: +Python 3.11 or newer is required. Clone the repository, then from its root: ```bash -pip install pre-commit +python3 -m venv .venv +source .venv/bin/activate +python -m pip install -e '.[dev]' +python -m pip install pre-commit pre-commit install ``` -After installation, the following checks run automatically before each commit: +Reactivate `.venv` in each new shell. `pre-commit` is separate from the project's dev extras. Some checks also need external tools, including ShellCheck; see the [Makefile](Makefile) and [hook configuration](.pre-commit-config.yaml). For desktop installation rather than development, use [INSTALL.md](INSTALL.md). -| Hook | Tool | Description | -| ----------------------------- | ---------------- | --------------------------------- | -| trailing-whitespace | pre-commit-hooks | Remove trailing whitespace | -| end-of-file-fixer | pre-commit-hooks | Ensure files end with newline | -| check-yaml | pre-commit-hooks | Validate YAML syntax | -| check-json | pre-commit-hooks | Validate JSON syntax | -| ruff | ruff-pre-commit | Lint + auto-fix Python | -| ruff-format | ruff-pre-commit | Format Python with ruff | -| mypy | mypy | Type check (strict mode) | -| shellcheck | shellcheck-py | Static analysis for shell scripts | -| dreamcoder-theme-validate | custom | Validate theme token health | -| dreamcoder-preview-regenerate | custom | Regenerate theme preview | +## Check your change -Run all hooks manually at any time: +Run the checks relevant to your work before opening a pull request: ```bash +make python-lint # Ruff lint and format check +make shell-lint # ShellCheck on shell scripts recursively under scripts/ +make type-check # mypy src/ +make lint # all three above +make test # pytest tests/ -v +make coverage # pytest with coverage report +python scripts/validate-markdown-links.py pre-commit run --all-files ``` -To skip hooks for a WIP commit (use sparingly): - -```bash -git commit --no-verify -m "wip: ..." -``` - -## Building - -```bash -# Build wheel + source tarball -python -m build - -# Or via Makefile -make build -``` - -## How to Add a New Renderer - -Renderers follow a pure-function architecture. Adding a new target follows this flow: - -```mermaid -flowchart LR - A["1. Create renderer_.py
Define content(target_colors) → str"] --> B - B["2. Export from renderers.py
Add import + __all__ entry"] --> C - C["3. Add write call to sync.py
write_if_changed(path, content(active))"] --> D - D["4. Add path to settings.py
theme_paths() namedtuple"] --> E - E["5. Add paths to control.py
path generation if needed"] --> F - F["6. Add print to sync_summary()
Show path + changed status"] --> G - G["7. Write tests
tests/test_renderer_.py"] --> H - H["8. Add variant files if needed
sync_repo_snippets() write_variant_files()"] -``` - -### Checklist - -- [ ] `renderers_.py` — pure function that takes `dict[str, str]` and returns `str` -- [ ] Registered in `renderers.py` (import + `__all__`) -- [ ] Called in `sync.py` → `sync_active_targets()` or `sync_repo_snippets()` -- [ ] Path defined in `settings.py` → `theme_paths()` -- [ ] Path generated in `control.py` if applicable -- [ ] `print_summary()` shows the new target -- [ ] Tests in `tests/` - -## Documentation changes +`make format` rewrites Python files, and `make build` creates distribution artifacts. Review their output before committing. Hooks can also modify files: inspect the diff and rerun checks after fixes. The hook configuration includes whitespace, YAML/JSON and large-file checks, Ruff, mypy, ShellCheck, Markdown links, and path-triggered tests, theme validation, preview drift and profile validation. Running all hooks may regenerate the theme preview. -Documentation changes are reviewed like code changes. +For documentation, update the smallest relevant page, link rather than duplicate guidance, and keep pages reachable from the [docs index](docs/README.md). Use English, the name Dreamcoder Workbench, and `dark`/`light` for user-facing modes. Use a `docs:` commit for documentation changes. -- [ ] Run `python scripts/validate-markdown-links.py` and fix any broken links. -- [ ] Update the smallest relevant page; do not duplicate content that already lives in another doc — link to it instead. -- [ ] The changed page is reachable from the [docs index](docs/README.md) or the README documentation table; add it there if it is a new page. -- [ ] Keep the identity string "Dreamcoder Workbench" and mode names `dark/light` consistent with the rest of the docs. -- [ ] Commit with the `docs:` conventional commit type. +## Add or change a theme renderer -Do not duplicate references: link to the source page for detailed behavior. +The source of truth for palette data is [tokens.json](DreamcoderThemes/dreamcoder/tokens.json); `src/dreamcoder_theme/palette_tokens.py` is generated from it, not the file to edit by hand. See the [theme system guide](docs/configuration/theme-system.md) for regeneration and its write boundaries. -## Pull Request Guidelines +1. Follow an existing renderer in `src/dreamcoder_theme/renderers_*.py`; render content from palette values rather than writing files in the renderer. Export public functions through `renderers.py` where appropriate. +2. Trace a comparable target through `sync.py`: its registry, coverage declaration, preparation and render plan, active writes and repository variants. Decide whether the new target needs a selector or specialized integration; not every target uses the same path. Keep registry and coverage invariants aligned. +3. If needed, define paths in `settings.py` and reuse the appropriate writer in `writers.py` or the existing specialized writer. Preserve validation and ownership rules rather than adding an independent write path. +4. Add focused renderer and synchronization tests, including the target's selection and failure boundaries. Update documentation when behavior or commands change. -- Keep changes focused — one feature/fix per PR. -- Add tests for new functionality. -- Ensure `make lint && make test && make coverage` passes before opening the PR. -- Follow existing code style (ruff defaults, 100 chars line length). -- Keep the CHANGELOG updated under `## Unreleased`. -- Pre-commit hooks must pass before committing. +Generated output alone does not install an application or prove that it consumes a theme. Review generated changes and application-specific behavior separately. -## Design Principles +## Submit -- **Health first**: colors must pass WCAG AA contrast ratios. -- **Single source of truth**: edit tokens in `palette_tokens.py`, not in - individual theme files. -- **Renderers are pure**: each renderer takes a color dict and returns a - string — no side effects. -- **Stow-compatible**: file paths in the repo mirror `$HOME` layout so GNU - Stow can link them directly. +Create a branch, make focused commits, and open a pull request against `main`. Describe the change, its validation and any platform limitations; update the changelog when appropriate. For the broader layout and component guides, start at the [documentation hub](docs/README.md). diff --git a/docs/configuration/theme-system.md b/docs/configuration/theme-system.md index b2da552..83e97e1 100644 --- a/docs/configuration/theme-system.md +++ b/docs/configuration/theme-system.md @@ -1,26 +1,32 @@ # Dreamcoder Workbench Theme System -## Architecture +## Choose a mode or regenerate -Three-layer design system: +From the repository root, activate the Python environment described in [INSTALL.md](../../INSTALL.md), then choose the operation you need: -```txt -primitives (OKLCH ramps) → semantic tokens (tokens.json) → component themes (renderers) +```bash +./scripts/dreamcoder dark # or light: activate a mode +./scripts/dreamcoder sync # regenerate using the selected active mode ``` -Pipeline: +Mode activation prepares and validates the theme, persists the choice, writes configurations and invokes reload adapters. Sync regenerates palette tokens and writes live targets and, by default, repository outputs; it can also update selectors and the Bat cache. Both can affect your existing configuration. Inspect changes and reload or restart applications where needed. Neither operation installs applications or their configuration. For the desktop installation and recovery path, see [INSTALL.md](../../INSTALL.md). + +`dreamcoder-theme` is the installed control CLI: its parser offers `theme apply dark` and `theme apply light`, but no `sync` command. Use the repository wrapper above for sync. `DREAMCODER_THEME_MODE=light` or `dark` selects sync's mode; otherwise it uses the persisted live mode, then dark. `DREAMCODER_WRITE_REPO=0` skips repository theme outputs, not live configuration writes. -```txt +## Architecture + +```text tokens.json → generate-palette-tokens.py → palette_tokens.py - → dreamcoder sync → generated theme files for every configured renderer + → palette and renderers → sync writers → live and repository outputs ``` +Semantic roles are derived from canonical tokens; optional wallpaper adaptation can modify the active palette. The coverage declaration and registry in `src/dreamcoder_theme/sync.py` describe rendered consumers, not proof that every application is installed or tested on every platform. + ## Canonical tokens Single source of truth: [`DreamcoderThemes/dreamcoder/tokens.json`](../../DreamcoderThemes/dreamcoder/tokens.json) -The canonical modes are exactly **Dreamcoder Dark**, **Dreamcoder Light**, and -**Dreamcoder Dusk**; only Dark and Light are user-facing. Dark's `surface_policy` permits pure black only for the canvas; functional +The user-facing modes are **dark** and **light**. The token data also contains an internal legacy variant. Dark's `surface_policy` permits pure black only for the canvas; functional and scrollable surfaces use the near-black ladder (`surface0`–`surface3`) to reduce OLED smear. @@ -39,10 +45,10 @@ reduce OLED smear. After editing `tokens.json`: ```bash -./scripts/generate-palette-tokens.py # sync palette_tokens.py + derived tokens -python scripts/generate-dark-css.py # sync dreamcoder-dark.css variables -./scripts/dreamcoder sync # propagate to all targets -./scripts/verify-theme-health.py # WCAG + APCA gates (light and dark) +python scripts/generate-palette-tokens.py # write generated palette_tokens.py +python scripts/generate-dark-css.py # write dreamcoder-dark.css variables +./scripts/dreamcoder sync # write live and repository outputs +python scripts/verify-theme-health.py # check theme health ``` CI or local drift checks can use: @@ -137,7 +143,4 @@ Use the [Dark state validation reference](dark-theme-validation.md) for cross-ap ## Adding new targets -1. Create renderer in `src/dreamcoder_theme/renderers_.py` -2. Map semantic tokens (never raw hex in renderers) -3. Register in `src/dreamcoder_theme/sync.py` -4. Run `./scripts/dreamcoder sync` +Follow the renderer and testing workflow in [Contributing](../../CONTRIBUTING.md), under “Add or change a theme renderer”. Review target-specific output and application behavior separately from generation. From aaa8c3b3cd002f7ef596580553c6732675a9a15f Mon Sep 17 00:00:00 2001 From: DreamCoder08 Date: Tue, 27 Oct 2026 03:16:46 -0500 Subject: [PATCH 6/6] docs: record approved pr chain and ci evidence --- odd/tasks/documentation-integration.md | 21 +++++++++++++++++++++ odd/tasks/documentation-quality.md | 12 ++++++++---- 2 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 odd/tasks/documentation-integration.md diff --git a/odd/tasks/documentation-integration.md b/odd/tasks/documentation-integration.md new file mode 100644 index 0000000..f323617 --- /dev/null +++ b/odd/tasks/documentation-integration.md @@ -0,0 +1,21 @@ +# Documentation integration recovery +Objective: deliver the already validated documentation without rewriting published history. +Source: documentation-quality; replacement branch: `docs/documentation-main`. + +## Specs +S1. User request: "has limpieza de ramas y mas te autorizo todo ve de forma autonoma , con los cambios de la documentacion del proyecto" +S2. User selected: "Sí, borrar esas dos" and "Sí, verificar e integrar". +S3. Recovery authorization: "yes autorizo todo y avanza". + +## Tasks +- T1 | S1–S3 | inline Git recovery + delegated verification | done | Preserve the five valid documentation commits, replace only the invalid final commit subject, and validate unchanged user-facing documentation | commit: this recovery commit +- T2 | S1–S3 | inline delivery | in_progress | Publish the replacement PR linked to approved issue #53, observe final-head CI, and merge only with passing checks and repository protections | commit: pending +- T3 | S1–S3 | inline verification | pending | Confirm remote main contains the delivered documentation and preserve unrelated local files | commit: pending + +## Log +L1. Original request verbatim: "has limpieza de ramas y mas te autorizo todo ve de forma autonoma , con los cambios de la documentacion del proyecto" +L2. User explicitly approved deletion of only local branches docs/final-dark-snapshot-evidence and feat/dreamcoder-dark-cross-app-quality; both were ancestry-contained in main and deleted safely. Remote branches and occupied worktrees were preserved. +L3. User approved integration of PRs #54–#58 without bypassing protections. PRs #55–#58 were merged into the tracker, whose final tree matched the locally validated documentation. PR #54 was marked ready, but final-head commitlint failed on `docs: record approved PR chain and CI evidence` (subject-case). No main merge occurred. +L4. After the replacement-branch proposal, the user wrote verbatim: "yes autorizo todo y avanza". Preserve published history and CI rules. Reuse the five valid original commits through a5cc1db; replay only the final tracking change with a lowercase subject. The replacement includes no application-code changes. Live installation, theme synchronization, repairs, and restore commands must not run on the host. +L5. Existing unrelated untracked `DreamcoderShell/.config/fish/conf.d/gentle-shell.fish` remains untouched and uncommitted. Documentation link and whitespace checks previously passed. Source delivery evidence remains in `odd/tasks/documentation-quality.md`; this file records recovery rather than replacing that history. +L6. Read-only verifier mvqetmq7-2-3y8q confirmed all 13 user-facing documentation blobs equal 30599de and all five retained subjects plus the proposed lowercase subject satisfy the explicit structural rules. Markdown links (isolated scratch copy), worktree whitespace, and staged whitespace checks passed with exit 0 and empty stdout/stderr. The commitlint executable is unavailable locally; structural checks are not an actual commitlint pass, so final-head CI remains mandatory. No live application commands ran. Risk: none (passive documentation only). diff --git a/odd/tasks/documentation-quality.md b/odd/tasks/documentation-quality.md index c1866f8..6bbd6ba 100644 --- a/odd/tasks/documentation-quality.md +++ b/odd/tasks/documentation-quality.md @@ -1,6 +1,6 @@ # Documentation quality Objective: improve the README and documentation using Gentleman.Dots as a quality reference. -Branch: `docs/documentation-quality`; delivery: feature-branch-chain (local commits only); checks: Markdown links, source-backed command review. Forecast: 1,200–1,800 authored changed lines; delivered as four focused local review slices. +Branch: `docs/documentation-quality`; delivery: feature-branch-chain (published under explicit L12 authorization); checks: Markdown links, source-backed command review. Forecast: 1,200–1,800 authored changed lines; delivered as four focused local review slices. ## Specs S1. User request: "me gustaria que la docuemntacion de este repo , incluso el readme , tenga la calidad que tiene este repo , https://github.com/Gentleman-Programming/Gentleman.Dots" @@ -10,11 +10,11 @@ S3. Delivery selection: "Cadena sobre una rama de trabajo — recomendada" — " ## Tasks - T1 | S1–S3 | delegated (context backstop) | done | README and documentation hub: purpose, preview, quick path, platform boundaries, task navigation | commit: c066396 - T2 | S1–S3 | delegated (context backstop) | done | Installation journey: single canonical full setup, platform limitations, verification and recovery | commit: e73d0c1 -- T3 | S1–S3 | delegated (context backstop) | done | Configuration and contributor journeys: accurate examples, concise structure, source-backed references | commits: d4a1fd9 and the final slice containing this revision (`docs: align contributor workflow and theme system guidance`) +- T3 | S1–S3 | delegated (context backstop) | done | Configuration and contributor journeys: accurate examples, concise structure, source-backed references | commits: d4a1fd9 and 0e031a7 (source branch); c7198cd and a5cc1db (published chain) - T4 | S1–S3, L12 | inline delivery | done | Create and confirm approved documentation issue | evidence: github.com/Dreamcoder08/Dreamcoder-Workbench#53, confirmed open with status:approved and type:docs -- T5 | S1–S3, L12 | inline delivery | in_progress | Publish feature tracker and four scoped child PRs, no merges | evidence: pending -- T6 | S1–S3, L12 | inline delivery | pending | Observe applicable CI and record delivery state | evidence: pending +- T5 | S1–S3, L12 | inline delivery | done | Publish feature tracker and four scoped child PRs, no merges | evidence: draft tracker #54; child PRs #55 → #56 → #57 → #58, bases/labels/bodies confirmed +- T6 | S1–S3, L12 | inline delivery | done | Observe applicable CI and record delivery state | evidence: #54 checks pass; #55–#58 have no workflow checks; limitations recorded in L16 ## Log L1. Original request: "me gustaria que la docuemntacion de este repo , incluso el readme , tenga la calidad que tiene este repo , https://github.com/Gentleman-Programming/Gentleman.Dots" @@ -30,3 +30,7 @@ L10. Authorized replacement worker mvqcxo08-5-pm7h completed T3 and returned sou L11. Component slice d4a1fd9 committed successfully; pre-commit Markdown, whitespace and file checks passed. Contributor/theme slice closes the feature and includes this final task record. All three tasks have observed checks and complete outcomes. No source-code changes, publishing, external link network validation, live installation or platform execution occurred. Unrelated untracked Fish file preserved. Next step at that boundary: human review of the local documentation branch before any publication. L12. User request verbatim: "yes continua todo de forma autonoma siempre usa buenas practicas de git y github + filosofia de gentleman". Explicit interactive authorization then granted target-bound GitHub CLI reads, branch pushes and PR creation on github.com/Dreamcoder08/Dreamcoder-Workbench, without merges. A second explicit selection authorized creating the documentation issue with `status:approved` and `type:docs`, using nonclosing `Refs` links. Target verified: default main, authenticated actor ADMIN; no open issues or PRs, duplicate query `documentation in:title,body` across all states returned zero results. Feature request form selected for the improvement proposal; no personal/legal checkbox attestations. Original local-only delivery restriction is superseded solely by these target-bound grants. Keep feature-branch-chain; no merge or size:exception label authorized. L13. Issue creation returned #53. Initial read-back parser failed because GH_FORCE_TTY emitted ANSI-colored JSON; paused later mutations, diagnosed formatting, and confirmed exact title/body and approved/docs labels via target read-back with forced color disabled. No duplicate create attempted. Remote main fetched using the authorized GitHub CLI HTTPS helper, not the ambient SSH agent: exact base 3e830a3b981901430f55b3ef7d8db9f2dbdf526b, no upstream divergence. Delivery will use a registered same-clone worktree and normal commits/hooks, retaining original source branch and unrelated local changes. +L14. Registered delivery worktree `.tmp/documentation-delivery`. Prepared ordinary, hook-checked commits: tracker 6d6b204, overview 47ac543, installation f34706b, components c7198cd, contributor/theme a5cc1db. Complete final documentation content matches original 0e031a7 exactly; full Markdown validation and committed whitespace checks pass. All five new branches pushed non-force over authorized HTTPS credentials. Prepared PR bodies from target template, with privacy scan, exactly type:docs, nonclosing Refs #53, explicit no-merge and source-backed validation limits. Child workflows may not run because current CI targets main; do not claim absent child checks green. +L15. Confirmed each created PR through GitHub read-back: #54 draft tracker to main (32 lines), #55 overview to tracker (327), #56 installation to overview (621), #57 components to installation (210), #58 contributor/theme to components (268). Exact bodies, bases, heads, draft state and one type:docs label validated. All use Refs #53; no automatic issue closure. Installation exceeds advisory 400-line review target as one coherent journey; rationale in its body, no protected size label applied. CI observation was in progress at that boundary; no merge readiness claimed. +L16. CI observation completed with exit 0: tracker #54 passed Git object store integrity, Offline sync verification, Shell dispatcher syntax and tests, commitlint, verify-overlay, and Python test jobs 3.11, 3.12 and 3.14. The tracker contains delivery tracking only, so those results do not establish CI coverage of the final child snapshot. Read-back of #55–#58 returned empty statusCheckRollup arrays, consistent with workflows targeting main. Final child snapshot had local Markdown validation, whitespace checks, source-backed review and applicable pre-commit hooks passing; app reloads, live installation, external URL availability and cross-platform behavior remain untested. Tracker body now links all four child PRs and remains draft/no-merge. No merges, force pushes, automatic issue closure or size:exception labels applied. All six tasks complete; next step is human review and authorized integration, not automatic merge. +L17. Final hygiene found only the two session-created delivery directories under untracked `.tmp/`; added exact local `.git/info/exclude` entries for those directories without changing repository ignore policy or unrelated scratch. Original Fish file remains untouched. This record is synchronized into the last child slice; no application code or behavior changes.