chore: DevKit conformance

.claude/settings.json

@@ -0,0 +1,46 @@
+{
+  "_comment": "Project-level Claude Code settings. Committed to repo.",
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(gh:*)",
+      "Bash(make:*)",
+      "Bash(npx:*)",
+      "Bash(cargo:*)",
+      "Bash(rustup:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(echo:*)",
+      "Bash(pwd:*)",
+      "Bash(which:*)",
+      "Bash(command:*)",
+      "Bash(wc:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(sort:*)",
+      "Bash(uniq:*)",
+      "Bash(diff:*)",
+      "Bash(test:*)",
+      "Bash(bash:*)",
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Task",
+      "Skill",
+      "WebFetch",
+      "WebSearch",
+      "mcp__*"
+    ],
+    "deny": [
+      "Bash(rm -rf /)"
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}

.devkit.json

@@ -0,0 +1,9 @@
+{
+  "project": "DigitalRain",
+  "tier": "full",
+  "profile": "rust",
+  "family": "Personal",
+  "managed_by": null,
+  "created": "2026-03-21",
+  "devkit_version": "2.7.1"
+}

.github/workflows/ci.yml

@@ -6,6 +6,13 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   CARGO_TERM_COLOR: always
 
@@ -47,3 +54,15 @@ jobs:
 
       - name: Build release
         run: cargo build --release
+
+  markdown-lint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Lint Markdown
+        uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: "**/*.md #target #node_modules #.git"

.gitignore

@@ -9,10 +9,14 @@
 # IDE
 .idea/
 .vscode/
-.claude/
+.claude/*
+!.claude/settings.json
 *.swp
 *.swo
 
+# Dependencies (from npx markdownlint-cli2)
+node_modules/
+
 # OS
 Thumbs.db
 .DS_Store

.markdownlint.json

@@ -1,3 +1,3 @@
 {
-  "extends": "../.markdownlint.json"
+  "extends": "../../.markdownlint.json"
 }

CLAUDE.md

@@ -1,10 +1,12 @@
 # DigitalRain - Project Instructions
 
 ## Overview
+
 Terminal-based Matrix digital rain effect built in Rust using crossterm.
 Classic green phosphor CRT aesthetic with gold highlight characters.
 
 ## Tech Stack
+
 - **Language**: Rust (edition 2024)
 - **Terminal**: crossterm (cross-platform, Windows-first)
 - **CLI**: clap (argument parsing)
@@ -13,25 +15,44 @@ Classic green phosphor CRT aesthetic with gold highlight characters.
 - **Platform**: dirs (platform-native config directory)
 
 ## Architecture
+
 - Effect trait system: each visual effect implements a common `Effect` trait
 - Double-buffered cell grid: compose frame in memory, flush once per frame
 - CLI argument parsing for effect selection and parameter tuning
 - TOML config file support for saving presets
 
 ## Key Design Decisions
+
 - Windows is the primary target; Linux/macOS are secondary
 - True color (24-bit RGB) for smooth gradients; graceful degradation to 256-color
 - Half-width katakana (U+FF66-U+FF9F) for Matrix-authentic characters
 - Single binary distribution (no runtime dependencies)
 
+## Quick Start
+
+```bash
+make hooks          # Install pre-push hook (one-time setup)
+make ci             # Run full CI check locally (fmt + lint + test + build)
+make run            # Run the application
+```
+
 ## Build & Run
+
 ```bash
 cargo build --release
 cargo run -- --help
+make build          # Alias for cargo build --release
+make test           # Alias for cargo test
+make lint           # cargo clippy --all-targets -- -D warnings
+make lint-md        # markdownlint on all .md files
+make lint-all       # lint + lint-md
+make fmt            # cargo fmt check
+make clean          # cargo clean
 ```
 
 ## Project Structure
-```
+
+```text
 src/
   main.rs           - Entry point, CLI args, main loop, crossfade wiring
   terminal.rs       - crossterm setup/teardown, raw mode, alternate screen
@@ -63,13 +84,14 @@ src/
 ```
 
 ## Conventions
+
 - Keep code well-commented (developer is learning Rust)
 - Prefer clarity over cleverness
 - Use `cargo clippy` and `cargo fmt` before committing
-- keep Readme.md file updated for GitHub repo
-- Maintain documentation with version history and updated command usage.
-- implement tests for debuging
-- Commit to GitHub after successful build.
-- Start a new github branch before implementing new features or making large changes to the core.
-- Please include proper references in the code and support files for sources used in building this project.
-- give credit if we use someone's code or data. 
+- Keep README.md updated for GitHub repo
+- Maintain documentation with version history and updated command usage
+- Implement tests for debugging
+- Commit to GitHub after successful build
+- Start a new GitHub branch before implementing new features or making large changes to the core
+- Include proper references in the code and support files for sources used in building this project
+- Give credit if we use someone's code or data

Makefile

@@ -0,0 +1,29 @@
+.PHONY: build test lint lint-md lint-all fmt ci hooks run clean
+
+build:
+	cargo build --release
+
+test:
+	cargo test
+
+lint:
+	cargo clippy --all-targets -- -D warnings
+
+lint-md:
+	npx --yes markdownlint-cli2 "**/*.md" "#target" "#node_modules" "#*/node_modules" "#.git"
+
+lint-all: lint lint-md
+
+fmt:
+	cargo fmt --all -- --check
+
+ci: fmt lint-all test build
+
+hooks:
+	cp scripts/pre-push .git/hooks/pre-push
+
+run:
+	cargo run
+
+clean:
+	cargo clean

README.md

@@ -65,7 +65,7 @@ cargo run --release
 
 ## Usage
 
-```
+```text
 digital_rain [OPTIONS]
 ```
 

docs/REQUIREMENTS.md

@@ -1,12 +1,14 @@
 # DigitalRain - Requirements Specification
 
 ## Vision
+
 A terminal-based visual effects application inspired by the Matrix digital rain.
 Windows-first, cross-platform, with a flexible effect system and rich customization.
 
 ## Core Requirements
 
 ### CR-1: Classic Matrix Rain Effect
+
 - Green phosphor characters falling in vertical columns
 - Half-width katakana characters (film-authentic) mixed with ASCII digits and symbols
 - Leading character is bright white/green, trail fades through progressively darker greens
@@ -15,18 +17,21 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 - Gold highlight characters appear occasionally (as in the film)
 
 ### CR-2: True Color Rendering
+
 - 24-bit RGB color support for smooth gradient trails
 - Phosphor green primary palette: bright white lead -> vivid green -> dark green -> near-black tail
 - Gold accent palette for highlight characters
 - Graceful degradation to 256-color on limited terminals
 
 ### CR-3: Windows-First Cross-Platform
+
 - Primary target: Windows Terminal, PowerShell, cmd.exe
 - Secondary: Linux terminals, macOS Terminal/iTerm2
 - Single standalone binary (no runtime dependencies)
 - Proper terminal cleanup on exit (Ctrl+C, window close)
 
 ### CR-4: Command-Line Interface
+
 - `--effect <name>` - Select which effect to run
 - `--speed <value>` - Control animation speed
 - `--density <value>` - Control rain density (sparse to heavy)
@@ -38,19 +43,22 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 - `--help` - Usage information
 
 ### CR-5: Effect System Architecture
+
 - Common `Effect` trait that all effects implement
 - Effects are self-contained modules with their own state
 - Easy to add new effects by implementing the trait
 - Effect registry for discovery and selection
 - Compositor to manage active effect rendering
 
 ### CR-6: Configuration
+
 - TOML config file for persistent settings (~/.config/digitalrain/config.toml)
 - Named presets bundling palette + speed + density + charset + effect
 - CLI arguments override config file values
 - Built-in presets: "classic", "gold", "monochrome", "cyberpunk"
 
 ### CR-7: Interactive Runtime Controls
+
 - `q` / `Esc` - Quit
 - `Space` - Pause/resume
 - `+` / `-` - Increase/decrease speed
@@ -60,18 +68,21 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 - `?` - Show keybindings overlay
 
 ### CR-8: CRT Simulation
+
 - Scanline effect using dim/bright alternating rows
 - Phosphor glow approximation using background colors on adjacent cells
 - Screen flicker/noise
 - Toggleable via CLI flag (`--crt`) and runtime key
 
 ### CR-9: Depth/Parallax Layers
+
 - Multiple rain layers at different speeds and brightness levels
 - Foreground: fast, bright, large characters
 - Background: slow, dim, creates depth illusion
 - Configurable number of layers and speed/brightness ratios
 
 ### CR-10: Additional Effects
+
 - **Classic**: Standard Matrix rain (CR-1)
 - **Cascade**: Top-down wave revealing characters
 - **Pulse**: Brightness waves radiating outward
@@ -85,14 +96,17 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 ## Future / Stretch Goals
 
 ### SG-1: Embedded Messages
+
 - "WAKE UP NEO" style text appearing within the rain
 - Configurable message text
 - Message dissolves back into rain after display
 
 ### SG-2: Audio-Reactive Mode
+
 - Modulate rain intensity/speed based on system audio
 
 ### SG-3: Performance Dashboard
+
 - FPS counter overlay
 - CPU usage display
 - Adaptive frame rate based on terminal size
@@ -118,6 +132,7 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 ## Phased Development
 
 ### Phase 1: Foundation [COMPLETE]
+
 - Project structure, build system
 - Terminal setup/teardown (alternate screen, raw mode, cleanup)
 - Cell buffer with dirty-cell tracking
@@ -127,27 +142,31 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 - Effect trait scaffolding
 
 ### Phase 2: CLI & Core Configuration
+
 - clap-based argument parsing (--effect, --speed, --density, --color, --fps, etc.)
 - Effect registry with --list-effects
 - --random flag for random effect + parameters
 - Speed, density, and color palette as runtime-configurable parameters
 - Wire CLI values through to the rain simulation
 
 ### Phase 3: Interactive Controls & Polish
+
 - Runtime keyboard controls (pause, speed, density, effect cycling)
 - Keybindings overlay (`?` key)
 - Terminal resize handling improvements
 - Graceful degradation on limited terminals (256-color fallback)
 - Performance tuning and frame timing refinement
 
 ### Phase 4: CRT Simulation & Depth Layers
+
 - CRT scanline post-processing pass
 - Phosphor glow approximation (background color bleed on adjacent cells)
 - Screen flicker/noise overlay
 - Multi-layer parallax rain (foreground + background at different speeds/brightness)
 - `--crt` flag and runtime toggle
 
 ### Phase 5: Additional Effects
+
 - Cascade effect
 - Pulse effect
 - Glitch effect
@@ -157,6 +176,7 @@ Windows-first, cross-platform, with a flexible effect system and rich customizat
 - Effect transitions (smooth crossfade between effects)
 
 ### Phase 6: Configuration & Presets
+
 - TOML config file loading (~/.config/digitalrain/config.toml)
 - Named presets ("classic", "gold", "monochrome", "cyberpunk")
 - CLI overrides config file values

scripts/pre-push

@@ -11,12 +11,12 @@ echo "--- cargo test"
 cargo test
 
 echo "--- cargo clippy"
-cargo clippy -- -D warnings
+cargo clippy --all-targets -- -D warnings
 
 echo "--- cargo fmt check"
 cargo fmt -- --check
 
 echo "--- markdownlint"
-npx --yes markdownlint-cli2 "**/*.md" "#target" || echo "WARNING: markdownlint found issues (non-blocking)"
+npx --yes markdownlint-cli2 "**/*.md" "#target" "#node_modules" "#*/node_modules" "#.git"
 
 echo "==> pre-push: all checks passed"