Skip to content

Latest commit

 

History

History
245 lines (202 loc) · 6.83 KB

.gp.md

File metadata and controls

245 lines (202 loc) · 6.83 KB

Kōyō Project Context

Project Overview

Kōyō is a keyboard configuration project focusing on QMK firmware for both Moonlander and Corne (crkbd) keyboards. The name (紅葉) refers to autumn leaves in Japanese, reflecting the project's aesthetic and design philosophy.

Base Instructions for GPT

Primary Directives

  1. Ask for specific files or code snippets when needed for context
  2. Request clarification when requirements are unclear
  3. Think step-by-step through complex problems
  4. Admit uncertainty rather than make assumptions
  5. Use established project patterns when suggesting solutions

When You Need Information

Always ask for:

  1. Specific file contents when modifying existing code
  2. Current implementation when suggesting changes
  3. Clarification about project context when unsure
  4. Confirmation before suggesting major changes

How to Ask

Use clear, specific requests like:

  • "Could you show me the current content of utils.sh?"
  • "To help with this, I need to see how this is currently implemented in {file}"
  • "Before proceeding, could you confirm if this follows your current pattern in {similar_file}?"
  • "I'm unsure about {specific_aspect}. Could you clarify?"

Response Pattern

  1. Acknowledge the context provided
  2. Ask for any missing information
  3. Present solution with explanations
  4. Offer to clarify or adjust as needed

Code Style Preferences

  • Follow existing patterns in the codebase
  • Use consistent error handling
  • Maintain existing logging patterns
  • Keep scripts focused and modular

Remember

  • The project uses specific logging functions (debug_log, success_log, etc.)
  • Config values should be accessed through get_config
  • Scripts should support --dry-run where applicable
  • Error handling should be consistent and clear

Key Project Files

  • config.yml: Central configuration file containing paths and keyboard-specific settings
  • utils.sh: Common utilities for logging and config reading
  • setup.sh: Installation script for dependencies and environment setup
  • update_svg.sh: Script for generating keyboard layout visualization
  • koyo: Main CLI tool

Directory Structure

koyo/
├── assets/                 # Visual assets and configs
│   ├── kd_config.yaml     # Keymap-drawer configuration
│   ├── kd_layout.yaml     # Keyboard layout specification
│   └── layout.svg         # Generated layout visualization
├── qmk/                   # QMK configurations
│   ├── crkbd/            # Corne keyboard files
│   │   ├── flash.sh      # Flashing script
│   │   └── src/          # Source files
│   └── moonlander/       # Moonlander keyboard files
│       ├── flash.sh      # Flashing script
│       └── src/          # Source files

Key Dependencies

  • QMK Firmware
  • keymap-drawer (for layout visualization)
  • yq (for YAML processing)
  • ZSH shell

Important Configuration Details

  1. QMK Setup:

    • Uses QMK CLI for firmware management
    • Configures QMK home directory
    • Handles both fresh installations and updates

  2. Layout Configuration:

    • Uses keymap-drawer for visualization
    • Supports custom key mappings and combos
    • Maintains consistent layout across keyboards

  3. Utility Functions:

    • Logging with colors and icons
    • Config reading with yq
    • Error handling and dry-run support

Common Tasks

  1. Setting up environment:

    ./setup.sh

  2. Updating layout SVG:

    ./update_svg.sh
# or
koyo update svg

  3. Flashing keyboards:

    koyo moonlander flash
koyo crkbd flash

Style Guidelines

  1. Script Structure:

    • Use strict mode (set -e)
    • Implement proper error handling
    • Support dry-run mode where applicable

  2. Logging:

    • Use utility functions: debug_log, success_log, error_log, warning_log
    • Provide clear, actionable feedback
    • Use consistent icons and colors

  3. Configuration:

    • Use YAML for configuration files
    • Access config values through get_config utility
    • Support environment-specific overrides

Common Issues and Solutions

  1. QMK Setup:

    • Always configure QMK home directory
    • Run qmk setup for fresh installations
    • Verify dependencies before operations

  2. Layout Generation:

    • Handle YAML syntax carefully, especially with special characters
    • Use proper keycode mappings in kd_config.yaml
    • Verify paths before operations

  3. Permission Issues:

    • Handle script permissions explicitly
    • Use sudo when needed for system-level operations
    • Check file existence before operations

Development Guidelines

  1. Error Handling:

    • Exit on critical errors
    • Provide helpful error messages
    • Clean up on exit when necessary

  2. Configuration:

    • Keep paths in config.yml
    • Use relative paths when possible
    • Support configuration overrides

  3. Testing:

    • Support dry-run mode
    • Verify dependencies
    • Check file permissions and existence

Key Features to Maintain

  1. Cross-keyboard compatibility
  2. Clear visual layout representation
  3. Easy setup and configuration
  4. Consistent error handling
  5. Clear user feedback
  6. Modular design

Core Code Patterns

Standard Script Structure

#!/usr/bin/env bash

# Get the directory of this script
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Source utilities
source "$SCRIPT_DIR/utils.sh"

# Enable strict mode
set -euo pipefail

# Get repo path from config
KOYO_REPO=$(eval echo "$(get_config '.paths.repo_dir')")

Standard Dependency Check Pattern

check_dependency() {
    debug_log "Checking dependency installation..."

    if ! command -v dependency &>/dev/null; then
        debug_log "Warning: dependency not found"

        if [[ "$DRY_RUN" == "true" ]]; then
            debug_log "Would prompt to install dependency"
            return
        fi

        prompt_log "Would you like to install dependency now? (y/n)"
        read -r response

        if [[ "$response" =~ ^[Yy]$ ]]; then
            # Installation logic here
            success_log "Dependency installed successfully"
        else
            warning_log "Please install dependency manually before continuing"
            exit 1
        fi
    else
        success_log "Dependency found"
    fi
}

Common Config Access Pattern

# config.yml
paths:
  qmk_dir: "$HOME/repos/qmk/qmk_firmware"
  repo_dir: "$HOME/repos/nikbrunner/koyo"
# Access in scripts
QMK_DIR=$(eval echo "$(get_config '.paths.qmk_dir')")

Standard Error Handling Pattern

if ! some_command; then
    error_log "Failed to execute command"
    exit 1
fi

Keymap Layout Pattern

# kd_layout.yaml example structure
layout: {qmk_keyboard: crkbd/rev1, qmk_layout: LAYOUT_split_3x5_3}
layers:
  LY_BAS:
  - {t: key, h: hold}  # Standard key with hold function
  - {t: tap, h: hold, s: shifted}  # Key with shift function