Photonamus Industries Forums - Public AI Context Library

Creative Tool Chain Package - Volume 1

Tue, 08 Sep 2026 13:05:57 +0000

Creative Toolchain Package — Volume 1

Eight context documents covering the open-source creative stack from pixel art to 3D rendering
Load them into your AI assistant and get real answers instead of hallucinated menus

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This package is a set of context documents designed to give an AI assistant deep, working knowledge of eight creative applications. Not surface-level summaries — full interface references, tool lists, keyboard shortcuts, settings locations, rendering configs, file format support, and the kind of detail that turns "I think that setting is somewhere in preferences" into an actual answer.

Every document follows the same structure: what the software is, what changed in the current version, complete interface and tool breakdowns, workflow-relevant settings, performance notes for real hardware, and pipeline integration guidance. They're written to be pasted into a conversation or attached as context files. The AI reads the document, and then it knows where things are instead of guessing.

The scope is a full open-source creative production stack — 2D art, vector graphics, image editing, pixel art, video editing, screen recording, and 3D. Everything here runs on Linux. Some of it runs on Windows and macOS too. The package covers the latest stable versions as of mid-2026.

─── ◆ ───

What's in the Package

Eight context documents:

Blender 5.0.1: 3D modeling, sculpting, animation, rendering, compositing, video editing — the full suite.
GIMP 3.2.2: Raster image editing, photo retouching, color correction, batch processing, non-destructive filters.
Inkscape 1.4: Vector graphics — SVG native, path operations, Live Path Effects, trace bitmap, tiled clones.
Kdenlive 26.08: Non-linear video editing — multi-track timeline, effects, color grading, speech-to-text, multi-cam.
Krita 6.0.1: Digital painting, illustration, 2D animation, brush engine deep-dive, AI diffusion integration.
OBS Studio 32.2: Screen recording and live streaming on Linux — PipeWire, Wayland capture, encoding setup.
PixiEditor 2.1: Pixel art, raster painting, vector, and animation with a node graph engine underneath.
Pro Motion NG V8: Indexed-color pixel art and sprite animation in the Deluxe Paint tradition — tile maps, color cycling, palette constraints.

─── ◆ ───

How to Use These

Grab the zip attached to this post. Each document is a standalone markdown file. Pick the one that matches the tool you're working with and load it into your AI conversation — paste the contents, attach the file, or drop it into a project as a reference document. The AI will then have accurate, version-specific knowledge of the interface, tools, settings, and workflows instead of relying on training data that may be years out of date.

These pair well with each other. Working on a game art pipeline? Load Pro Motion NG and PixiEditor together. Doing a video project? Load Kdenlive and OBS. Need to go from 2D concept to 3D model? Load Krita and Blender. The documents are sized to fit comfortably in modern context windows individually, and most combinations of two or three will fit together.

─── ◆ ───

Blender 5.0.1

The everything-machine for 3D. This document covers the 5.0 release — geometry nodes overhaul, node-based modifiers, native ACES color management, Cycles adaptive subdivision out of experimental, EEVEE hair rendering rewrite, and the new UV editing system. The reference walks through every mode (Object, Edit, Sculpt, Vertex Paint, Weight Paint, Texture Paint, Pose, Particle Edit), the full Properties Editor tab-by-tab, all node systems (Shader, Geometry, Compositing), the modifier stack, render engine differences, add-on management, and performance tuning.

Covers: Modeling, sculpting, animation, rigging, simulation, rendering (Cycles + EEVEE), compositing, motion tracking, video editing, Grease Pencil 2D animation, geometry nodes, file formats, Linux resource paths.

Code:
Blender-5_0_1-Context.md

Version:  5.0.1 (December 2025 patch; base release November 2025)
Platform:  Linux (native), Windows, macOS
License:  GPL-2.0-or-later

Sections:
  - What Is Blender 5.0 / What's New in 5.0
  - Interface Architecture
  - Modes — Blender's Modal System
  - Properties Editor — Tab-by-Tab Reference
  - Essential Keyboard Shortcuts
  - Render Engines (Cycles, EEVEE, Workbench)
  - Node Systems (Shader, Geometry, Compositing)
  - Modifier System
  - Add-on / Extension System
  - AI Integration
  - Performance on Your Hardware
  - File Formats
  - Resource Locations (Linux)
  - Quick Reference — "Where Is That Setting?"

─── ◆ ───

GIMP 3.2.2

The first major GIMP release in seven years rewrote nearly everything under the hood — GTK3 port, proper HiDPI scaling, native Wayland support, non-destructive filters, multi-layer selection, and the death of floating selections. This document covers both the 3.0 foundational changes and the 3.2 additions, with a complete tool list, dockable dialog reference, layer system breakdown, color management setup, the Python 3 scripting system, and a Photoshop-to-GIMP translation table for anyone crossing over.

Covers: Raster editing, photo retouching, non-destructive filter workflows, layer management, color profiles, scripting and plugins, batch processing, format support, and where GIMP fits alongside Krita in a production pipeline.

Code:
GIMP-3_2_2-Context.md

Version:  3.2.2 (March 2026; latest stable 3.2.4, April 2026)
Platform:  Linux (GTK3, native Wayland), macOS, Windows
License:  GPL-3.0+

Sections:
  - What Changed: GIMP 3.x vs 2.10
  - Interface Architecture
  - The Toolbox — Complete Tool List
  - Dockable Dialogs — GIMP's Panel System
  - Essential Keyboard Shortcuts
  - Non-Destructive Filters (GIMP 3.0+)
  - Layer System
  - Color Management
  - Scripting & Plugin System
  - Performance Optimization for Your Hardware
  - Photoshop-to-GIMP Translation
  - File Format Support
  - Resource Locations (Linux)
  - Quick Reference — "Where Is That Setting?"
  - Krita vs GIMP — When to Use Each

─── ◆ ───

Inkscape 1.4

The leading open-source vector editor, SVG-native. This document covers the 1.4 "Geek Edition" series through the 1.4.4 maintenance release, with notes on the incoming 1.5 GTK4 port. Full reference for the toolbox, dialog system, Live Path Effects for non-destructive path modification, Trace Bitmap for vectorizing raster images, the tiled clones system, extensions, SVG filters, and pipeline integration with the rest of the stack.

Covers: Vector drawing and editing, SVG authoring, path operations, boolean operations, LPEs, bitmap tracing, clones, extensions, color management, format support, and Illustrator-to-Inkscape translation.

Code:
Inkscape-1_4-Context-Doc.md

Version:  1.4.4 (May 2026; latest stable)
Platform:  Linux (GTK3), Windows, macOS, FreeBSD
License:  GPL-2.0-or-later
Native:    SVG (Scalable Vector Graphics)

Sections:
  - What Is Inkscape / Version Status
  - Interface Architecture
  - The Toolbox — Complete Tool List
  - Dialogs — The Panel System
  - Essential Keyboard Shortcuts
  - Live Path Effects (LPEs)
  - Trace Bitmap — Vectorizing Raster Images
  - Clones and Tiled Clones
  - Extensions System
  - Filters (SVG Filters)
  - Color Management
  - File Format Support
  - Performance Notes for Your Hardware
  - Photoshop/Illustrator → Inkscape Translation
  - Pipeline Integration

─── ◆ ───

Kdenlive 26.08

The most feature-complete non-linear video editor in the Linux ecosystem. This document covers the 26.08 release — drag-and-drop track reordering, gap markers, multi-clip speed changes, document patch versioning — along with highlights from the 25.12 and 26.04 releases that brought AI-powered object segmentation, rewritten OpenTimelineIO support, and fullscreen monitor mirroring. Complete reference for timeline editing, effects and filters, transitions, title creation, speech-to-text, multi-cam workflows, rendering profiles, and hardware-accelerated encoding.

Covers: Multi-track video editing, 3-point editing, proxy workflows, keyframe animation, nested sequences, color correction with scopes, audio mixing, effects (MLT/FFmpeg/frei0r/LADSPA), rendering, and performance tuning.

Code:
Kdenlive-Context.md

Version:  26.08.0 (August 2026; latest stable)
Platform:  Linux (KDE/Qt), Windows, macOS
License:  GPL-3.0-or-later
Built on:  MLT Framework, FFmpeg, frei0r, LADSPA

Sections:
  - What Is Kdenlive / Release Cycle / Recent Highlights
  - Interface Architecture
  - Settings / Preferences
  - Timeline Editing
  - Essential Keyboard Shortcuts
  - Effects and Filters
  - Transitions and Compositions
  - Titles and Graphics
  - Speech to Text
  - Multi-Cam Editing
  - Rendering (Export)
  - AI Features
  - File Formats
  - Performance for Your Hardware
  - Resource Locations (Linux)

─── ◆ ───

Krita 6.0.1

The digital painting and illustration powerhouse. This document covers the 6.0 Qt6 port alongside the parallel 5.3 Qt5 branch — same features, different toolkit underneath. Includes the full brush engine deep-dive (pixel, color smudge, shape, quick, clone, deform, tangent normal, and more), the complete docker reference where most of Krita's power actually lives, workspace customization, the filter system, layer types and blending, Python scripting, AI Diffusion plugin integration, and the Pop-up Palette system.

Covers: Digital painting, illustration, concept art, 2D animation, brush system architecture, layer management, filter workflows, drawing assistants, scripting, AI generation, format support, and performance optimization.

Code:
Krita-6_0_1-Context.md

Version:  6.0.1 (March 2026; stable production branch is 5.3.2.1)
Platform:  Linux (Ubuntu Studio), macOS, Windows
License:  GPL-3.0

Sections:
  - What Is Krita 6.0 vs 5.3
  - Interface Architecture
  - Dockers — The Deep Settings Layer
  - Workspace Customization
  - Essential Keyboard Shortcuts
  - Brush System Deep Dive
  - Settings Deep Dive — Where Everything Lives
  - Filters (Built-in)
  - Layer System
  - Python Scripting & Plugin System
  - AI Integration — Krita AI Diffusion
  - File Format Support
  - Performance Optimization for Your Hardware
  - Pop-up Palette (Right-Click Menu)
  - Drawing Assistants

─── ◆ ───

OBS Studio 32.2

The standard for screen recording and live streaming, configured for Linux. This document is specifically tuned for a PipeWire + Wayland + AMD setup — it covers the Linux screen capture situation (what works, what doesn't, and why), PipeWire audio integration, the full source type list, encoding settings optimized for real hardware, filter chains, scene composition workflows, the plugin ecosystem, virtual camera setup, and the distinction between profiles and scene collections.

Covers: Screen recording, live streaming, scene composition, video encoding (x264, VAAPI, AMF), audio mixing, source types, filters, plugins, virtual camera, PipeWire/Wayland-specific configuration, and hardware-matched encoding profiles.

Code:
OBS-Studio-Linux-Context.md

Version:  32.2.2 (August 2026; latest stable)
Platform:  Linux (X11 and Wayland), Windows, macOS
License:  GPL-2.0
Target:    Ubuntu Studio 26.04 LTS, KDE Plasma 6, PipeWire, AMD RX 580

Sections:
  - What Is OBS Studio
  - Installation on Ubuntu Studio 26.04
  - The Linux Screen Capture Situation (Critical)
  - Audio on Linux — PipeWire Integration
  - Interface Layout
  - Source Types (Complete List)
  - Encoding Settings for Your Hardware
  - Keyboard Shortcuts (Hotkeys)
  - Filters (Per-Source and Per-Audio)
  - Scenes & Sources — Workflow
  - Plugins & Extensions
  - Virtual Camera
  - Profiles & Scene Collections
  - Resource Locations (Linux)
  - Quick Reference — "Where Is That Setting?"

─── ◆ ───

PixiEditor 2.1

A fast-moving project that started as a pixel art editor and evolved into a universal 2D editor with a node graph engine running underneath everything. Version 2.1 added a node-based brush engine, sub-pixel precision painting, tablet support, smart layers, and stabilizers. The document covers the three-toolset system (Drawing, Vector, Adjustments), the full node graph with every built-in node listed, the layer and color systems, frame-by-frame animation, the extension browser, and how it fits into a game asset pipeline alongside the other tools in this package.

Covers: Pixel art, raster painting, vector graphics, animation, node-based procedural generation, custom shaders, spritesheet export, extension system, and game asset pipeline integration.

Code:
PixiEditor-2_1-Context.md

Version:  2.1.2.2 (August 2026; latest stable)
Platform:  Windows, macOS, Linux (AvaloniaUI)
License:  LGPL v3 (free and open-source; paid Steam version funds development)
Built with: C#, AvaloniaUI, SkiaSharp

Sections:
  - What Is PixiEditor / Version History
  - Interface Architecture
  - The Toolset System (Drawing, Vector, Adjustments)
  - Tools by Toolset
  - The Node Graph
  - Layer System
  - Color System
  - Animation
  - File Formats
  - Extension System
  - Keyboard Shortcuts
  - Performance Notes for Your Hardware
  - Pipeline Integration
  - Quick Reference — "Where Is That Setting?"

─── ◆ ───

Pro Motion NG V8

A pixel art and sprite animation editor built in the Deluxe Paint tradition — indexed color mode, palette-first workflows, and the "grab pixels as a brush" paradigm that replaced conventional selections. This is the tool professionals at Yacht Club Games, WayForward, and Sega have used for hardware-accurate retro art. The document covers the conceptual shift from modern editors, Linux compatibility via bundled Wine, the full toolbox, all 25+ paint modes, the indexed palette system with per-hardware constraints (C64, NES, SNES, Game Boy), tile map creation, animation, pattern drawing, bitmap fonts, and how Pro Motion and PixiEditor complement each other in a pipeline.

Covers: Indexed-color pixel art, sprite animation, tile map editing, color cycling, halftone dithering, palette constraints, Deluxe Paint workflow concepts, Linux/Wine setup, and pipeline integration with PixiEditor and the broader stack.

Code:
ProMotionNG-V8-Context-Doc.md

Version:  8.0.11.x (V8 series, actively maintained)
Platform:  Windows native; Linux/macOS via bundled Wine
License:  Proprietary, $39 one-time purchase (Free Edition available)
Developer: Jan Zimmermann / Cosmigo, Germany

Sections:
  - What Is Pro Motion NG / The Deluxe Paint Lineage
  - Linux Compatibility
  - Interface Architecture
  - The Toolbox — Drawing Tools
  - Paint Modes (25+ Modes)
  - Color System — Indexed Palettes
  - Layer System
  - Animation System
  - Tile Map System
  - Pattern Drawing (Seamless Textures)
  - Bitmap Fonts
  - Selections and Transformations
  - Key Keyboard Shortcuts
  - Preferences Deep Dive
  - Plugin System

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Creative Toolchain Package — Volume 1. Built for PhotonamusWeb by Photonamus.

Creative_Tool_Chain_Package-Volume_1.zip (Size: 79.77 KB / Downloads: 0)

Retro Game Audio Bible

Sun, 23 Aug 2026 03:47:21 +0000

Retro Game Audio Bible — Context Document

Complete reference for chip-era game music — hardware, synthesis, composition techniques, and the constraints that defined each generation's sound

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This context document gives an AI assistant deep expertise in retro game audio from the chip and cartridge era — everything from the earliest PSG sound generators through the last generation before CD-quality streaming made constraints irrelevant. It covers the hardware, the synthesis paradigms, the composition techniques, and the philosophy that made this music iconic.

The scope is intentional: it stops at the point where audio became unlimited. Once a system is just streaming a pre-mixed studio recording off a disc, it's out of scope. This document lives in the world of chips, cartridges, small samples, and real-time synthesis.

─── ◆ ───

What It Covers

Sequencing vs streaming — the foundational concept that explains why chip-era music works the way it does, and why every clever trick is a workaround for channel count, waveform type, memory, or CPU time
Three synthesis paradigms — PSG (fixed waveforms), FM synthesis (operator modulation), and sample-based (PCM/wavetable), with clear explanations of how each sounds and why
System-by-system reference — detailed breakdowns for Atari 2600 (TIA), NES/Famicom (2A03), Game Boy (DMG), Sega Master System (SN76489), Commodore 64 (SID), arcade FM era (YM2151), Sega Genesis (YM2612), SNES (S-SMP/SPC700), Amiga (Paula), and PC sound cards (AdLib/OPL)
Universal composer techniques — arpeggiation, channel economy, rapid parameter modulation, duty cycle manipulation, instrument multiplexing, sample looping, percussion strategy, and composing for loops
Loop length reference data — typical single-loop durations by music type with specific reference points from Secret of Mana, Final Fantasy VI, Chrono Trigger, and ActRaiser
The constraint-to-aesthetic principle — why every limitation produced a distinctive sonic signature that people now deliberately recreate
Timeline summary — 1977 through 1992, system by system, chip by chip
Application notes — practical guidance for using this knowledge in AI music generation, tracker composition, or era-specific emulation

─── ◆ ───

How to Use It

Paste the contents into a new conversation as context, or attach the file directly. The AI will then understand the technical underpinnings of each era's sound well enough to help with composition, generation prompting, sound design discussions, or any project where you need to nail a specific retro audio aesthetic.

Pairs well with music generation tools like ACE-Step when targeting specific era sounds — the prompting guidance in this document translates directly into caption dimensions for generation workflows.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Document Contents

Code:
# Retro Game Audio Bible

**Scope:** Game music from the chip/cartridge era — from the earliest PSG sound through the last generation before CD-quality streaming audio became the norm. Covers hardware constraints, how composers worked within them, and the techniques that defined each era's sound.

**Explicit boundary:** This document stops at the point where audio became "unlimited" — i.e., Red Book CD audio, full MP3-grade streaming tracks, PSX/Saturn CDDA and beyond. We stay in the world of chips, cartridges, small samples, and real-time synthesis. The moment a system is just streaming a pre-mixed studio recording off a disc, it's out of scope.

---

## 1. The Core Concept: Sequencing vs. Streaming

The single most important distinction in retro game audio:

**Streaming (out of scope):** Store a finished audio recording, play it back. Like a CD or MP3. Storage cost scales with length and quality. No real-time flexibility.

**Sequencing (the entire chip era):** Store a set of tiny instrument definitions (waveforms or short samples) plus a compact list of instructions — "play this note on this channel at this time, with this volume envelope." The sound chip generates the audio in real time. Storage cost is tiny; a full song might be a few KB. This is functionally like MIDI + a sound font.

Almost everything in this document is about sequencing. The composer isn't recording audio — they're writing a program that tells a synthesizer what to do, note by note, frame by frame. The constraints are about:
- How many things can play at once (channels/voices/polyphony)
- What each channel can sound like (waveform types, synthesis method)
- How much memory the instrument data + sequence data can occupy
- How much CPU time is available to update the sound chip

Understanding this is the key that unlocks everything else. Every clever trick in retro game music is a workaround for one of those four limits.

---

## 2. The Three Synthesis Paradigms

### 2.1 PSG (Programmable Sound Generator)
The earliest and simplest. Generates a small set of fixed waveforms — square/pulse, triangle, noise — directly in hardware. You control pitch, volume, and (sometimes) duty cycle. That's mostly it. Cheap, limited, and responsible for the classic "8-bit bleep" sound.

Examples: NES 2A03, Game Boy DMG, Sega Master System SN76489, Atari TIA, General Instruments AY-3-8910 (MSX, ZX Spectrum).

### 2.2 FM Synthesis (Frequency Modulation)
A leap forward. Instead of fixed waveforms, FM uses "operators" (sine wave oscillators) that modulate each other's frequency. A 4-operator channel can produce complex, evolving, metallic, bell-like, brass-like, or organ-like timbres impossible on a PSG. Harder to program — the relationship between operator settings and resulting sound is unintuitive — but vastly more expressive.

FM arrived in arcades in 1984 (Marble Madness, Yamaha YM2151) and became the factory standard for game composers from the mid-1980s to mid-1990s. The Yamaha DX7 synthesizer popularized the same technology.

Examples: Sega Genesis YM2612, arcade YM2151, PC AdLib/Sound Blaster OPL2/OPL3, Sega Master System FM add-on YM2413.

### 2.3 Sample-Based (PCM / Wavetable)
Store actual recorded audio snippets (samples) and play them back at varying pitches. This is how you get "real" instruments — a recorded piano note, a drum hit, an orchestral stab. The constraint is memory: samples eat storage fast, so early sample-based systems used tiny, short, low-bit-depth samples and looped them.

Examples: SNES S-SMP (fully sample-based), Amiga Paula, arcade PCM chips, and the sample channels bolted onto otherwise-PSG/FM systems (NES DMC, Genesis DAC channel).

**The hybrid reality:** Most 16-bit systems mixed paradigms. The Genesis is FM + PSG + one sample channel. The NES is PSG + one sample channel. This layering — melodic FM/PSG voices plus sampled percussion — defined the 16-bit sound.

---

## 3. System-by-System Reference

### 3.1 Atari 2600 (TIA) — 1977
- **Chip:** TIA (Television Interface Adaptor)
- **Channels:** 2
- **Type:** PSG, extremely primitive
- **The brutal constraint:** The TIA couldn't play in tune. Its pitch was derived from dividing the video clock, so available pitches didn't map to a proper musical scale. Composers had to choose notes that were "close enough" and write melodies that hid the tuning problems. This is the hardest compositional constraint of any system here.
- **Takeaway:** When the hardware can't even produce correct pitches, composition becomes about working around fundamental brokenness.

### 3.2 NES / Famicom (Ricoh 2A03/2A07) — 1983/1985
- **Channels:** 5 total
  - 2× pulse/square wave (duty cycles: 12.5%, 25%, 50%, 75%)
  - 1× triangle wave (no volume control — fixed volume)
  - 1× noise (pseudo-random, for percussion/effects)
  - 1× DMC (Delta Modulation Channel) — plays short DPCM samples
- **Type:** PSG + one sample channel
- **Polyphony:** Each channel is monophonic — one note at a time, no chords per channel.
- **Standard channel roles:**
  - Pulse 1 & 2: melody and harmony (or melody + countermelody)
  - Triangle: bassline (and sometimes toms/kick)
  - Noise: percussion (hi-hats, snares, crashes)
  - DMC: richer sampled percussion or occasionally bass (Sunsoft games famously used it for bass)
- **Key techniques:**
  - **Arpeggios:** Rapidly cycling a single channel through the notes of a chord (e.g., root-third-fifth every few frames) to *imply* a chord with one monophonic voice. The signature "chirp" of NES chords.
  - **Duty cycle changes mid-note:** Switching pulse width during a note for timbral movement.
  - **Vibrato via pitch sweeps:** Rapid pitch modulation to add expression, since there's no dedicated vibrato.
  - **Rapid envelope updates:** Faking attack/decay by changing volume every frame.
  - **Triangle as lead:** A few games (Kirby's Adventure backing, SMB3 Boom Boom theme, Pipe Dream) broke convention and used triangle for melody.
  - **Channel interruption:** Borrowing a music channel for a sound effect, then returning it.
- **Expansion audio:** Famicom cartridges could add sound chips (Konami VRC6, VRC7, Nintendo FDS, Namco 163, Sunsoft 5B) giving extra channels — but only on Japanese Famicom, since the NES cartridge connector didn't pass the audio pin through. This is why some Japanese versions sound richer.
- **Notable composers:** Koji Kondo (Mario, Zelda), Hip Tanaka (Metroid), Tim Follin (technical showpieces).

### 3.3 Game Boy (DMG-CPU) — 1989
- **Channels:** 4
  - 2× pulse/square (duty cycles 12.5%, 25%, 50%, 75%; channel 1 has a hardware frequency sweep)
  - 1× wave channel — plays a user-definable 32-step, 4-bit waveform stored in Wave RAM ($FF30-$FF3F, 16 bytes)
  - 1× noise (LFSR-based; not true white noise, has audible periodic character)
- **Type:** PSG with a programmable-wavetable twist
- **Distinctive features:** Strong stereo panning (composers used hard-panning for width), and the wave channel's custom waveforms allowed more timbral variety than the NES. The wave channel is often used for bass or a second lead.
- **Key techniques:** Same arpeggio-for-chords approach as NES. Wave RAM can be rewritten mid-song to change the wave channel's timbre. Composers switch instrument parameters mid-channel to make one channel sound like two alternating instruments.
- **Notable composers:** Hirokazu Tanaka, Hip Tanaka, the LSDj/chiptune scene that grew around the hardware later.

### 3.4 Sega Master System / Mark III (SN76489 PSG) — 1985/1986
- **Channels:** 4
  - 3× square/tone
  - 1× noise
- **Type:** PSG (Texas Instruments SN76489, integrated into the VDP)
- **No sample channel** natively — PCM playback only via CPU trickery (rapid volume manipulation), which was expensive.
- **The FM add-on:** Japanese Mark III/Master System units (and the FM Sound Unit) included a **Yamaha YM2413 (OPL-derived FM chip)**. It offered 9 FM channels (or 6 FM + 5 percussion). Most Western games never used it, so Japanese versions of the same game often sound dramatically better.
- **Same chip family** appears in ColecoVision, BBC Micro, IBM PCjr, Tandy 1000.
- **Character:** Feels about half a generation behind the SID or even the NES — no secondary waveforms like the NES triangle, just pulses and noise. Composers leaned hard on arpeggios and rhythmic drive.

### 3.5 Commodore 64 (MOS 6581/8580 SID) — 1982
- **Channels:** 3 voices
- **Type:** Hybrid analog/digital synthesizer-on-a-chip — the standout of the 8-bit era
- **Per-voice features:**
  - 4 waveforms: triangle, sawtooth, pulse (variable width), noise
  - Full **ADSR envelope** per voice (attack, decay, sustain, release)
  - **Ring modulation** and **oscillator sync** between voices
- **Chip-wide:** A multi-mode **analog filter** (low-pass, band-pass, high-pass, notch) — any combination of voices could be routed through it for sweeps, wah, vocal-like timbres.
- **Why it mattered:** Designed by Bob Yannes as a real synth, not a beeper. It still sounds "modern" decades later because it's genuinely an analog subtractive synth. The two revisions (6581 rougher/warmer, 8580 cleaner) sound different, and each individual 6581 chip's filter sounds slightly different — like analog gear.
- **Key techniques:**
  - **Fast arpeggios as chords:** With only 3 voices, composers played chords by cycling one voice through chord tones at high speed — the signature C64 sound.
  - **Filter sweeps:** Timed cutoff automation for movement and drama.
  - **Multi-instrument voices:** Switching a voice's waveform/envelope rapidly so one voice plays bass AND lead in alternation.
  - **The "filter glitch" sample trick:** Rob Hubbard and others exploited SID quirks to play sampled drum hits — CPU-intensive, rarely used in gameplay.
  - **ADSR quirk exploitation:** Working with (not against) the buggy envelope generator.
- **Notable composers:** Rob Hubbard (Monty on the Run, Commando, International Karate), Martin Galway, Jeroen Tel, Chris Hülsbeck, Ben Daglish. These are the legends who established that constraints focus creativity rather than limiting it. Hubbard wrote long-form, prog-rock-inspired dynamic pieces that evolved over time.
- **Legacy:** The High Voltage SID Collection archives tens of thousands of tunes. The chip is still bought, cloned, and built into modern synths.

### 3.6 Arcade FM Era (Yamaha YM2151 and family) — 1984 onward
- **The shift:** Arcades introduced FM synthesis to games in 1984 (Marble Madness, YM2151). Arcades had bigger boards, more chips, and no cartridge memory limit the way consoles did, so they pushed ahead of home systems.
- **Common approach:** Multiple sound chips per board. Konami's Gyruss (1983) used five synthesis chips plus a DAC to render Bach. FM chips (YM2151, YM2203) provided melodic voices; dedicated PCM chips (SegaPCM, OKI ADPCM) provided sampled drums and voices.
- **Why arcades sounded better:** More silicon, more channels, more PCM, and often the composer had a known fixed hardware target to optimize for.
- **The YM2203 (OPN):** 3 FM + 3 SSG (PSG) channels. Progenitor of the whole OPN family that led to the Genesis chip.

### 3.7 Sega Genesis / Mega Drive (YM2612 + SN76489) — 1988/1989
- **Chips:** Yamaha YM2612 (FM) + Texas Instruments SN76489 (PSG, in the VDP)
- **Channels:** 10 total for tone
  - 6× FM (4-operator each), the 6th switchable to an 8-bit PCM sample channel (can't do both FM and PCM at once)
  - 3× PSG square + 1× PSG noise
- **Type:** FM + PSG + one sample channel — stereo output
- **The defining challenge:** FM synthesis is hard to program well. Composers who mastered it (Streets of Rage, Thunder Force, Sonic) got rich, aggressive, "warm" tones. Those who didn't got the thin, honky sound Genesis is sometimes criticized for. The chip rewarded deep understanding.
- **PCM handling:** The DAC/PCM channel had no hardware timing buffer, so the Z80 coprocessor had to babysit sample playback in software to avoid locking up the main 68000 CPU. This is why drum-heavy Genesis music often sacrificed the 6th FM channel.
- **The "ladder effect":** The original YM2612 had a distortion quirk (bit truncation on the negative edge of waveforms) that became part of its signature grit. Later revisions (YM3438/Model 2) cleaned it up, changing the sound.
- **No 16-bit sampling** — the sample channel was 8-bit, used mostly for percussion and voice.
- **Notable composers:** Yuzo Koshiro (Streets of Rage — famous for a custom assembly-language music driver that squeezed dance/house production out of the chip), Masato Nakamura (Sonic).

### 3.8 Super Nintendo / Super Famicom (S-SMP: SPC700 + S-DSP) — 1990/1991
- **Chip:** Sony S-SMP — SPC700 CPU + 8-channel DSP, fully self-contained with its own 64KB RAM
- **Channels:** 8, all sample-based (ADPCM)
- **Type:** Fully sample-based (the opposite philosophy from the Genesis's FM approach)
- **Features:**
  - BRR (Bit Rate Reduction) ADPCM compression — packs 16 samples into 9 bytes
  - Hardware ADSR envelopes per channel
  - Built-in **echo/reverb** (a hardware DSP effect — hugely responsible for the lush SNES sound)
  - Pitch modulation, stereo panning, noise
- **The 64KB constraint:** Everything — sound driver code, all instrument samples, and sequence data — shared one 64KB block. About 3.6 seconds of raw BRR-compressed audio could fit in the whole space. So composers used tiny, cleverly-looped instrument samples and spent the rest of the budget on sequence data. Rich samples meant less room for musical complexity, and vice versa. This is the central trade-off of SNES composition.
- **Channel allocation strategy:** Some developers reserved channels for sound effects; Square (Secret of Mana) used all 8 for music and interrupted channels for SFX, getting richer music at the cost of occasional audible pauses.
- **Why it sounds "warm":** Real sampled instruments + hardware reverb + the gentle low-pass character of BRR/Gaussian interpolation = the signature dreamy SNES tone.
- **Dynamic RAM tricks:** For long set-pieces (FF6's "Dancing Mad," 17:35, and "Balance Is Restored" ending, 21:29), the main CPU streamed new sample/sequence data into the S-SMP's RAM mid-piece, section by section, since these were scripted non-looping events. This is also why some games can't be captured as static SPC dumps.
- **Notable composers:** Koji Kondo (Super Mario World, Zelda: A Link to the Past), Nobuo Uematsu (Final Fantasy), Yasunori Mitsuda (Chrono Trigger), Hiroki Kikuta (Secret of Mana — pushed the hardware further than almost anyone, custom-synced title music to visuals), David Wise (Donkey Kong Country — used long high-quality samples and atmospheric ambient techniques).

### 3.9 Commodore Amiga (Paula) — 1985
- **Chip:** Paula (part of the Amiga custom chipset)
- **Channels:** 4, all sample-based PCM
- **Type:** Fully sample-based, 8-bit, DMA-driven, up to ~28kHz
- **Significance:** First affordable home system with real PCM sample playback. Two channels feed left, two feed right (stereo). The Fairlight CMI synthesizer offered similar sampling for $25,000 a few years earlier; Paula democratized it.
- **The tracker revolution:** In 1987 Karsten Obarski wrote **Ultimate Soundtracker**, creating the **MOD file format** and the tracker workflow — a grid where you enter notes, instrument numbers, and effects across 4 channels, 64 rows per pattern, sequencing patterns into songs. MOD files bundled the samples (up to 15, later 31 instruments) with the pattern data, staying tiny while sounding rich.
- **Constraints:**
  - 4 channels, 8-bit samples, limited Chip RAM (shared with graphics)
  - 31 instrument slots, tight sample-length budgets
- **Key techniques:**
  - **Software channel multiplexing:** OctaMED and others mixed multiple virtual channels into Paula's 4 hardware channels (e.g., Turrican 2 title music uses 7).
  - **Chip-mod / "fakebit":** Playing tiny single-cycle waveform samples to get C64/NES-style timbres out of a sample chip.
  - **Two-channel bit-depth trick:** Combining two channels at different volumes to approximate 14-bit output.
  - **Cross-channel modulation:** Chaining channels to modulate each other, producing FM-like results.
- **Legacy:** The tracker paradigm went straight into PC (FastTracker, Impulse Tracker) and lives on in Renoise and OpenMPT. The demoscene grew up around Amiga music compos.
- **Note:** The MOD format expanded on PC to XM and IT with 32-64 channels in the late '90s. Once "channel economy" disappeared, tracker music ballooned into huge complex arrangements — a lead might use 3 channels (1 main + 2 echo), chords 4-5. This is the tail end of the tracker era edging toward the unlimited zone.

### 3.10 PC Sound Cards (AdLib / Sound Blaster, Yamaha OPL) — 1987 onward
- **AdLib (1987):** Yamaha OPL2 (YM3812) — 9 channels of 2-operator FM. The first widely-adopted PC music standard beyond the internal beeper.
- **Sound Blaster (1989):** Added a DAC for digital sample playback alongside OPL FM. The combination — FM music + digital sound effects/voice — became the DOS gaming standard.
- **Sound Blaster 16 (1992):** OPL3 (YM262) — 18 channels, better FM.
- **General MIDI (1991):** Standardized 128 instruments so composers could write once and play across compatible devices (Roland Sound Canvas, etc.). The Secret of Monkey Island and other adventures leveraged this era.
- **Character:** OPL FM has a distinct "DOS game" sound — brighter and buzzier than the Genesis YM2612, since it's 2-operator vs 4-operator. LucasArts/Sierra adventure scores define the aesthetic.

---

## 4. The Universal Composer Techniques

These recur across nearly every constrained system. If you're emulating or evoking a retro sound, these are the moves:

### 4.1 Arpeggiation (Faking Chords)
The single most important technique. When each channel is monophonic and you only have 2-3 melodic channels, you can't play a full chord AND a melody AND a bass. Solution: cycle one channel rapidly through a chord's notes (root, third, fifth, root, third, fifth...) fast enough that the ear fuses them into a chord. The characteristic fast "bubbling" arpeggio IS the sound of the 8-bit era. NES, C64, Game Boy, SMS all rely on it heavily.

### 4.2 Channel Economy / Voice Allocation
With so few channels, every voice must earn its place. Typical 3-4 channel allocation:
- 1 channel: melody/lead
- 1 channel: bass
- 1 channel: harmony OR arpeggiated chords OR countermelody
- 1 channel: percussion (noise)

Composers constantly make trade-offs: drop the harmony during a drum fill, borrow the bass channel for a fill, etc. The arrangement is a resource-allocation puzzle as much as a musical one.

### 4.3 Rapid Parameter Modulation
Since hardware often lacks dedicated vibrato/tremolo/envelopes, composers fake them by changing parameters every frame (60Hz):
- **Vibrato:** rapid pitch wobble
- **Tremolo:** rapid volume wobble
- **Fake envelopes:** stepping volume down over frames to simulate decay
- **Duty cycle sweeps:** changing pulse width for timbral movement
- **PWM (pulse width modulation):** continuous duty sweeps for a "phasing" lead sound

### 4.4 Instrument Multiplexing on One Channel
Switching a channel's instrument settings mid-pattern so it alternates between roles — e.g., playing a bass note, then instantly reconfiguring to play a lead stab, then back. One channel doing two jobs by never doing them simultaneously.

### 4.5 Sample Looping and Reuse
On sample-based systems, memory is the enemy. Techniques:
- Loop a short sustain portion of a sample indefinitely (a 0.2s violin sustain loops to hold a long note)
- Reuse one sample at different pitches for multiple "instruments"
- Use very short/low-bit samples for percussion where fidelity matters less
- Find clean zero-crossing loop points to avoid clicks

### 4.6 Percussion Strategy
- **PSG systems:** Noise channel shaped with fast envelopes — short burst = hi-hat/snare, pitched noise = tom
- **Sample systems:** Dedicated short drum samples on a sample channel
- **NES/Genesis:** DMC/DAC channel for sampled drums, freeing tonal channels

### 4.7 Composing FOR Repetition (Loops)
Game music loops indefinitely, so it must be written to loop gracefully. Baroque and minimalist styles work well because they're built on repetition. Composers wrote loop points that flow seamlessly back to the start, and avoided dramatic one-time dynamic shifts that would feel wrong on repeat.

---

## 5. Loop Length Reference (Chip/Cartridge Era)

Because storage was sequence data (tiny), loop length was limited more by composition effort and memory for pattern data than by audio storage. Typical single-loop lengths:

| Music Type | Typical Loop | Notes |
|------------|-------------|-------|
| Title/menu | 4-30s | Short; sometimes non-looping jingles |
| Town/area (ambient) | 50-120s | The "place feeling" background loop |
| Overworld/field | 70-140s | More developed melodies |
| Dungeon | 45-90s | Atmospheric, repetition less noticed |
| Battle | 45-75s | Short, urgent |
| Boss | 55-90s | Slightly longer than normal battle |
| Character theme | 50-85s | Quick identity establishment |
| Victory/fanfare | 3-15s | Stingers |

**Reference points:**
- Secret of Mana (SNES): area BGM ~1:30-2:30, average ~2:15 (OST is single-loop length)
- Final Fantasy VI (SNES): estimated single loops ~55-110s
- Chrono Trigger (SNES): estimated single loops ~30-140s
- ActRaiser "Birth of the People": ~40s, heard for huge portions of the game — proves short loops work with the right compositional style (baroque)

**The big exceptions** (10+ minutes) only existed in scripted, non-looping contexts — final boss sequences and endings — where the game engine streamed new data to the sound chip in stages. Nobody wrote a 17-minute loop in 64KB.

---

## 6. The Constraint-to-Aesthetic Principle

The throughline of this entire era: **constraints didn't limit creativity, they focused it and created identity.**

- The NES arpeggio chirp exists because of monophonic channels — and became iconic.
- The C64's fast-arpeggio sound exists because of only 3 voices — and defined a genre.
- The SNES's warm dreaminess exists because of BRR compression + hardware reverb + tiny looped samples.
- The Genesis's aggressive grit exists because of FM synthesis + the ladder-effect distortion.
- The tracker workflow exists because of Paula's 4 channels and the need to bundle samples compactly.

Every "limitation" produced a distinctive sonic signature that people now deliberately recreate. When you remove the constraint (XM/IT trackers with 64 channels, CD audio), the distinctive identity often dissolves into generic capability. This is worth remembering for any project that wants a *specific* retro character — the constraint is the aesthetic.

---

## 7. Timeline Summary

| Year | System | Sound Hardware | Paradigm | Channels |
|------|--------|---------------|----------|----------|
| 1977 | Atari 2600 | TIA | PSG (untuned) | 2 |
| 1982 | Commodore 64 | MOS 6581 SID | Analog synth-on-chip | 3 |
| 1983 | NES/Famicom | Ricoh 2A03 | PSG + 1 sample | 5 |
| 1984 | Arcade (Marble Madness) | Yamaha YM2151 | FM | 8 |
| 1985 | Amiga | Paula | Sample (PCM) | 4 |
| 1985 | Sega Master System | SN76489 (+YM2413 FM) | PSG (+FM add-on) | 4 (+9) |
| 1987 | PC AdLib | Yamaha OPL2 | FM | 9 |
| 1989 | Game Boy | DMG-CPU | PSG + wavetable | 4 |
| 1988 | Sega Genesis | YM2612 + SN76489 | FM + PSG + 1 sample | 10 |
| 1990 | SNES/SFC | Sony S-SMP | Sample (ADPCM) + reverb | 8 |
| 1992 | PC Sound Blaster 16 | Yamaha OPL3 | FM + DAC | 18 |

*(After this: PSX/Saturn CD-DA streaming, full studio recordings off disc — out of scope.)*

---

## 8. Key Sources & Further Reading

- Video Game Music Preservation Foundation Wiki (vgmpf.com) — chip specs, game rips, SPC/SID/etc.
- NESdev Wiki & forums — deep NES/2A03 technical detail
- SMS Power (smspower.org) — Master System / SN76489 / YM2413
- MegaDrive Wiki / consolemods.org — YM2612 detail
- gbdev.gg8.se — Game Boy sound hardware
- Ludomusicology.org — academic analysis of PSG compositional strategies
- High Voltage SID Collection — C64 music archive
- superfamicom.org / wiki.superfamicom.org — SNES/SPC700 detail
- Copetti.org "Architecture of Consoles" series — excellent per-system technical writeups

---

## 9. Application Notes (for generation/composition projects)

If using this to inform AI music generation, tracker composition, or emulation of a specific era:

1. **Pick the paradigm first.** PSG chiptune, FM (Genesis/arcade/DOS), or sample-based (SNES/Amiga) — they sound fundamentally different.
2. **Respect channel counts** if authenticity matters. 3-4 voices forces the arpeggio-and-economy approach that makes it sound right.
3. **Match the era's percussion approach** — noise-channel drums vs sampled drums is a giveaway.
4. **Loop-aware composition** — write for seamless repetition, avoid one-time dramatic shifts.
5. **For "warm SNES" vibe:** sampled real instruments + reverb + gentle high-frequency rolloff.
6. **For "gritty Genesis" vibe:** FM timbres, aggressive, slightly distorted, punchy.
7. **For "chiptune" vibe:** pulse/square leads, triangle/wave bass, noise percussion, fast arpeggios.
8. **The constraint IS the aesthetic** — if you want a specific retro identity, impose the matching limitation deliberately rather than using unlimited modern capability.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Download the .zip below to use this document with your AI assistant.

retro-game-audio-bible-context.zip (Size: 10.92 KB / Downloads: 0)

Public Domain Bestiary

Sun, 23 Aug 2026 03:46:39 +0000

Public Domain Bestiary

376 monsters, demons, spirits, and legendary creatures from world mythology — structured for AI, games, and creative work

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The Public Domain Bestiary is a structured reference dataset of 376 creatures drawn from world mythology, folklore, public-domain literature, and grimoire demonology. Every entry is public domain in the United States as a concept or source material, making the collection a safe, ready-to-use foundation for worldbuilding, game design, writing, illustration, and any other creative work where you need monsters and don't want to worry about stepping on somebody's IP.

─── ◆ ───

Three Formats, Same Data

The dataset ships in three interchangeable formats — pick whichever fits your workflow:

.html — a self-contained, offline, searchable and filterable browser reference for human reading. Open it in any browser, no server needed. Supports dark mode, type filtering, region grouping, and a text search bar. This is the best way to browse the full collection.
.json — clean structured data intended for feeding into AI models or programmatic use. Types are stored as arrays. Includes metadata header with title, note, and total count.
.csv — a spreadsheet- and database-friendly format that imports directly into game engines such as Unreal Engine as a DataTable. Multiple type tags are pipe-separated for easy splitting.

All three files contain identical data. The .zip attachment at the bottom of this post includes all of them.

─── ◆ ───

What It Covers

18 traditions are represented across the collection:

Greek/Roman — Minotaur, Hydra, Cerberus, Chimera, Medusa, Typhon, and more
Norse/Germanic — Fenrir, Jörmungandr, Draugr, Kraken, Nidhogg, Valkyrie
Celtic/British — Banshee, Dullahan, Kelpie, Púca, Fomorian
Slavic — Baba Yaga, Leshy, Rusalka, Strigoi, Zmey Gorynych
Middle Eastern / Mesopotamian — Djinn, Lamassu, Simurgh, Manticore, Pazuzu
Japanese — Oni, Kappa, Tengu, Yuki-Onna, Jorōgumo, Gashadokuro
Chinese — Qilin, Jiangshi, Pixiu, Hundun, Nian
South and Southeast Asian — Naga, Garuda, Rakshasa, Yaksha, Manananggal
African — Grootslang, Impundulu, Adze, Tokoloshe, Ammit
Mesoamerican — Quetzalcoatl, Ahuizotl, Cipactli, Nagual
South American — Mapinguari, Encantado, Yacumama
North American — Wendigo, Thunderbird, Skinwalker, Piasa
Australian/Pacific — Bunyip, Taniwha, Rainbow Serpent
Finnish/Baltic — Iku-Turso, Ajatar, Nakki
Jewish/Biblical — Golem, Leviathan, Behemoth, Dybbuk, Nephilim
Universal Medieval European — Basilisk, Griffin, Wyvern, Werewolf, Will-o'-the-wisp
Public-domain classic literature — Frankenstein's Monster, Dracula, Cthulhu, Morlocks, Martian Tripods
Grimoire demonology — the complete 72 demons of the Ars Goetia from the Lesser Key of Solomon, plus additional figures from the Dictionnaire Infernal and Testament of Solomon

─── ◆ ───

Entry Structure

Every creature carries a consistent set of fields:

Name — the creature's name, with disambiguating notes where two share a name (e.g. the Goetic Asmoday versus Asmodeus of Tobit)
Region / Tradition — the cultural or literary origin it belongs to
Types — one or more classification tags from a consistent vocabulary: undead, beast, spirit, demon, dragon, humanoid, elemental, divine, aquatic, avian, shapeshifter
Description — a concise summary of the creature's appearance, behavior, and role in its source mythology
Caveat — where relevant, a usage warning flagging protected modern depictions, culturally sacred figures, or trademark concerns
Source — for literary and grimoire creatures, the originating work and date

─── ◆ ───

What an AI Can Do With It

Feed any of the three files into an AI assistant as context and it gains a complete, organized reference it can draw on without inventing details or guessing at copyright status. With the data loaded, a model can:

Recommend creatures that fit a given theme, biome, region, or tone
Generate enemy rosters, bestiary entries, or encounter tables for games
Expand any entry into full stat blocks, lore, dialogue, or design notes
Filter by tradition or type — every aquatic dragon, all Slavic spirits, demons suitable for a boss tier
Build new content grounded in real public-domain mythology rather than fabricated or copyright-uncertain material
Cross-reference creatures across traditions for comparative or fusion designs

─── ◆ ───

Important Usage Notes

Public domain does not mean unrestricted in every way. Mythology and folklore carry no copyright, but a specific modern depiction — such as Universal Pictures' Frankenstein design — may still be protected. Work from the original source description, not a film version.
Trademark can persist separately from copyright. Some names like Tarzan and Zorro remain trademarked even where the character is public domain. Check the name before commercial use.
Some entries are culturally sacred. Certain Indigenous, Aboriginal, and Maori figures are legally unrestricted but deserve research and respect before commercial use. These are flagged in the data's caveat field.
Verify 20th-century literary creatures (such as Lovecraft's Cthulhu mythos entities) in your own jurisdiction before release, as public-domain status can vary by country.

─── ◆ ───

Sample Entries

To give you a feel for what the data looks like, here are a few entries pulled from across the collection:

Code:
Fenrir | Norse/Germanic | beast, divine
Monstrous wolf destined to devour Odin at Ragnarök.

Jorōgumo | Japanese | spirit, shapeshifter, beast
Spider-woman who seduces men with her beauty, then ensnares them in webs.

Ammit | African | beast, divine
Crocodile-lion-hippo chimera that devours unworthy souls.

Amduscias (Goetia #67) | Grimoire Demonology | demon
Duke commanding 29 legions; appears as a unicorn, gives concerts of invisible
instruments, bends trees.
Source: Lesser Key of Solomon (Ars Goetia), c. 1641

Frankenstein's Monster | Classic Literature | humanoid, undead
Reanimated creature of stitched corpses, intelligent and tragic.
Caveat: Novel text is public domain. Universal's flat-top bolt-neck design is
NOT — work from Shelley's description.
Source: Frankenstein (Mary Shelley), 1818

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Download the .zip below containing all three formats (.html, .json, .csv).
Open the HTML file in a browser to browse and search the full collection.

public-domain-bestiary-context.zip (Size: 48.27 KB / Downloads: 0)

Pixel Art in ComfyUI

Sun, 23 Aug 2026 03:46:05 +0000

Pixel Art in ComfyUI — Context Document

AI-assisted pixel art generation using ComfyUI workflows, LoRAs, and custom nodes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This context document turns an AI assistant into a knowledgeable guide for generating authentic pixel art using ComfyUI. It covers the two main generation approaches (top-down recommended vs bottom-up), the best models and LoRAs for the job, and the custom node ecosystem that makes clean pixel art output possible.

The document includes detailed coverage of PixelArt Detector, Unfake Pixels, AI Pixel Art Enhancer, and other custom nodes — what each one does, how to configure it, and when to use which. It walks through exact dimension control techniques for img2img same-size output, proper KSampler settings, prompting strategies with era-specific constraints, and palette management best practices.

─── ◆ ───

What It Covers

Two generation approaches — top-down (generate at native resolution, downscale with nearest-neighbor) vs bottom-up (generate at target resolution directly), with clear guidance on why top-down wins
Models and LoRAs — Pixel Art XL, Sprite Shaper, Hard Edge (Flux), and Retro Diffusion with trigger words and weight recommendations
Custom node reference — six nodes from PixelArt Detector, Unfake Pixels edge-aware auto-scaling, AI Pixel Art Enhancer methods, and more
Exact dimension control — five techniques for getting precise output sizes including the Resize Sandwich, VAE encode at native res, and external ImageMagick
Generation resolution table — target size to generation resolution mapping with scale factors
Prompting and palette management — positive/negative prompt templates, era constraints (NES, SNES, Game Boy, modern), Lospec palette integration
Sprite sheet workflow — LoRA training, batch generation, background removal, grid arrangement, and validation
Critical rules — nearest-neighbor only, PNG only, integer multiples only, palette discipline

─── ◆ ───

How to Use It

Paste the contents of the document into a new conversation as context, or attach the file directly. The AI will then have detailed knowledge of ComfyUI pixel art workflows, node configurations, proper scaling techniques, and palette management — enough to help you build and troubleshoot complete pixel art generation pipelines.

The document is workflow-agnostic and works with any ComfyUI setup. All custom nodes referenced are open source with installation commands included.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Document Contents

Code:
# Pixel Art in ComfyUI — Context Reference

## Two Approaches

**Top-Down (Recommended):** Generate at model-native resolution (512×512 SD1.5, 1024×1024 SDXL/Flux) with pixel art LoRA → nearest-neighbor downscale to target (÷8, ÷16) → palette quantize. Best results, most reliable.

**Bottom-Up:** Generate at target resolution directly (32×32, 64×64). Mostly fails — latent space too small (64×64 = 8×8 latent). Only viable with specialized models or heavy ControlNet guidance with low denoise.

## Models & LoRAs

**Pixel Art XL LoRA v1.1 (NeriJS)** — Gold standard. SDXL 1.0 base. No trigger word. Weight 1.0–1.2. Don't use SDXL refiner. Works with 1 text encoder. Downscale 8× with nearest-neighbor for pixel-perfect output. `civitai.com/models/120096/pixel-art-xl`

**Pixel Art Diffusion XL — Sprite Shaper** — Full SDXL checkpoint for 16-bit style. `civitai.com/models/277680`

**Hard Edge Pixel Art LoRA** — Flux.1 Dev compatible. Trigger: "pixel art". Harder edges than SDXL LoRAs.

**Retro Diffusion** — Purpose-built pixel art model (cloud service, not local). Dramatically better than general models. `retrodiffusion.ai`

## Key Custom Nodes

**ComfyUI-PixelArt-Detector (dimtoneff)** — 6 nodes. MIT license. `github.com/dimtoneff/ComfyUI-PixelArt-Detector`
- PixelArt Detector (+Save): all-in-one reduce/resize/save
- PixelArt Detector (Image→): downscale + reduce, forward to next node
- PixelArt Palette Converter: swap palettes. Methods: Image.quantize (fast, MAXCOVERAGE best for pixel art), Grid.pixelate, NP.quantize, OpenCV.kmeans, Pycluster.kmeans/kmedians
- PixelArt Palette Loader: Lospec palettes with visual preview
- PixelArt Palette Generator: extract palette from image → color list output
- PixelArtAddDitherPattern: prepared + custom patterns
- Resize modes (v1.7.0+): "contain" (default, preserves AR), "fit" (crop to fill), "stretch" (exact dims, may distort). Set W&H to 0 to disable.
- cleanup_pixels_threshold: 0.01–0.05 eliminates stray colors. Lower = more colors kept.

**ComfyUI-Unfake-Pixels (tauraloke)** — Edge-aware auto-scale. Sobel filter + tile voting detects true pixel size of AI output, downscales to real grid. `github.com/tauraloke/ComfyUI-Unfake-Pixels`
- downscale_method: "nearest" (crisper) or "dominant" (smoother)
- cleanup_jaggies: removes isolated noise pixels

**ComfyUI-PixelArt-Unfaker** — Enhanced fork. Adds exact target resolution (target_width/target_height), auto background removal, optimal crop/center to pixel grid, K-Means quantization. `github.com/ComfyNodePRs/PR-ComfyUI-PixelArt-Unfaker-4f850341`

**ComfyUI-AI-Pixel-Art-Enhancer (HSDHCdev)** — Output resolution always matches input. Grain sizing control. Palette input forces exact color mapping. Methods: most_frequent (logos/UI), average (portraits), edge_preserving (graphics), neighbor_aware (landscapes). `github.com/HSDHCdev/ComfyUI-AI-Pixel-Art-Enhancer`

**comfy_pixelization (filipemeneses)** — AI-based, higher quality. NON-COMMERCIAL license. Requires 3 checkpoint downloads.

**WAS Node Suite** — Commercial-safe pixelization. Slower, less refined than AI-based.

## Exact Dimension Control (img2img same-size output)

**Technique 1 — Resize Sandwich (most reliable):**
Load Image → upscale to model res with nearest-neighbor at integer multiple (64×64 → 512×512 = 8×) → VAE Encode → KSampler (denoise 0.3–0.6) → VAE Decode → downscale back with nearest-neighbor (÷8) → palette quantize → save. Upscale factor MUST be integer. Same factor up and down.

**Technique 2 — VAE Encode at native res (subtle changes only):**
Load 64×64 → VAE Encode (8×8 latent) → KSampler denoise 0.1–0.3 → VAE Decode → output 64×64. No resize needed. Only for palette shifts/subtle style transfer.

**Technique 3 — PixelArt Detector pipeline:**
Use PixelArt Detector (Image→) with resize_w/resize_h set to target. "stretch" mode forces exact dims.

**Technique 4 — Unfaker pipeline:**
Set target_width/target_height → auto grid detect → crop/align → downscale → pad/crop to exact target.

**Technique 5 — External ImageMagick:**
`magick convert input.png -resize 64x64\! -filter point output.png`
`\!` = force exact dims. `-filter point` = nearest-neighbor.

## Generation Resolution Table

| Target | Generate At | Scale Factor |
|---|---|---|
| 16×16 | 512×512 | ÷32 |
| 32×32 | 512×512 | ÷16 |
| 64×64 | 512×512 | ÷8 |
| 128×128 | 1024×1024 | ÷8 |
| 256×256 | 1024×1024 | ÷4 |

## KSampler Settings

Steps: 20–30. CFG: 5–8 (lower = more natural). Sampler: dpm++ 2m karras or euler_a. Scheduler: karras. Denoise: 1.0 txt2img, 0.3–0.5 img2img (preserve structure), 0.6+ heavy restyle.

## Prompting

**Positive:** `pixelart, {scene}, pixel-art, low-res, blocky, pixel art style, 8-bit graphics, sharp details, less colors, early computer game art`

**Negative:** `sloppy, messy, blurry, noisy, highly detailed, ultra textured, photo, realistic, high-resolution, photo-realistic, 3d render, depth of field, anti-aliasing, smooth shading, gradient`

**Era constraints:** NES: `4 colors, 32×32` | SNES: `16 colors, 64×64` | Game Boy: `4 shades green monochrome` | Modern: `128×128+, detailed shading`

## Palette Management

Palette quantization must happen INSIDE workflow, not as afterthought. Insert Palette Quantize inside KSampler loop to prevent out-of-gamut color propagation.

Sources: Lospec (`lospec.com/palette-list`), bundled PixelArt Detector palettes (NES, Game Boy, etc.), custom 1px-per-color images in palettes/1x directory.

Extract palette from existing art: PixelArt Palette Generator node or AI Pixel Art Enhancer (32×32 swatch grid output).

## Sprite Sheets

1. Train character LoRA (15–20 refs, lr ~0.0002, 15–20 epochs) for consistency
2. Batch generate individual frames with pose-specific prompts, same LoRA/sampler/palette
3. Background removal: Rembg (fast/good enough), SAM2 (better edges), or color-based
4. Grid arrangement via Image Grid node or Python script
5. Validate: identical dims + palette across all frames
- Same seed for related frames. Canvas Align node to center at fixed dims before save. No auto-crop.

## Sprite Size Reference

| Era | Size | Colors | Frames |
|---|---|---|---|
| NES/8-bit | 8–16px | 3–4 | 2–4 |
| SNES/16-bit | 16–32px | 16–24 | 4–8 |
| GBA/32-bit | 32–64px | 16–32 | 6–8 |
| Modern indie | 32–128px | 32+ | 8–12 |

32×32 is the sweet spot for AI generation.

## Critical Rules

- ALWAYS use "nearest-exact" interpolation for any pixel art scaling. Never bilinear/bicubic/lanczos.
- Save as PNG only. Never JPEG for pixel art.
- Integer multiples only for up/downscaling. Never fractional.
- Pixel art scaling must be integer only: 2×, 3×, 4×. Never 1.5×.
- Palette discipline is the #1 differentiator between fake and real pixel art.

## Node Installation

```
git clone https://github.com/dimtoneff/ComfyUI-PixelArt-Detector
git clone https://github.com/tauraloke/ComfyUI-Unfake-Pixels
git clone https://github.com/HSDHCdev/ComfyUI-AI-Pixel-Art-Enhancer
git clone https://github.com/filipemeneses/comfy_pixelization  # non-commercial
git clone https://github.com/WASasquatch/was-node-suite-comfyui
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Download the .zip below to use this document with your AI assistant.

pixel-art-comfyui-context.zip (Size: 3.47 KB / Downloads: 0)

Pi4 Network Server

Sun, 23 Aug 2026 03:45:28 +0000

Pi4 Network Server Head — Context Document

Complete reference for setting up a Raspberry Pi 4 as an always-on network management appliance with Docker, DNS, VPN, smart home, and monitoring

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This context document gives an AI assistant comprehensive knowledge of how to set up and manage a Raspberry Pi 4 as a dedicated network server — the always-on appliance that handles DNS, ad blocking, VPN, smart home control, monitoring, and container orchestration for your home network.

The document covers the full stack from bare metal to running services: hardware selection and storage strategy, OS installation and hardening, Docker deployment, and a complete service catalog with working compose files. Every section includes the actual commands and configuration you need, not just theory.

─── ◆ ───

What It Covers

Hardware baseline — Pi4 specs, storage strategy (SD vs USB SSD and why it matters), touchscreen setup options, and kiosk mode configuration for dashboard display
Base OS installation — Raspberry Pi OS Lite 64-bit, Imager configuration, first boot sequence, and static IP setup with NetworkManager
OS hardening — SSH key auth with port change, UFW firewall rules, Fail2Ban configuration, and additional security measures
Docker and container management — installation, ARM64 considerations, moving Docker root to SSD, Portainer GUI, and CasaOS alternative
Pi-hole + Unbound — network-wide ad blocking with recursive DNS resolution for privacy, including Docker and bare-metal install paths, DNSSEC, and network integration methods
VPN — WireGuard via PiVPN (self-hosted, port forwarding) and Tailscale (zero-config mesh), including split vs full tunnel and Pi-hole integration for mobile ad blocking
Home Assistant — Docker container deployment, Zigbee/Z-Wave/Thread integration, MQTT broker setup, Zigbee2MQTT, and touchscreen dashboard
Network monitoring — Uptime Kuma, Grafana + Prometheus stack, and Gotify push notifications
PC cluster orchestration — using Pi4 as Docker Swarm manager or K3s control plane for desktop worker nodes, with Wake-on-LAN
Reverse proxy — Traefik with auto-discovery and Let's Encrypt, Nginx Proxy Manager alternative, and local DNS names via Pi-hole
Additional services — Nextcloud, Vaultwarden, Gitea, Jellyfin, Syncthing, Homer, Node-RED, and more with ports and notes
Maintenance — backup strategies, update procedures, health monitoring commands, cooling requirements, and reliability practices including UPS and watchdog timer
Complete Docker Compose stack — single reference compose file for the core service stack with .env template
Network architecture diagram — visual layout of how all services connect
Quick-start checklist — ordered deployment steps from flash to finished

─── ◆ ───

How to Use It

Paste the contents into a new conversation when you're setting up or managing a Pi4 server, or attach the file directly. The AI will then have enough context to help with everything from initial setup through troubleshooting running services — it knows the correct commands, the common pitfalls (like SD card write wear and undervoltage throttling), and how the services interconnect.

The document uses generic placeholders throughout (192.168.1.X, youruser, piserver.local) so it works with any network configuration. Swap in your own values as you go.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Document Contents

Code:
# Pi4 Network Server Head — Complete Reference

> Context document for AI-assisted setup and management of a Raspberry Pi 4 as an always-on network management appliance with touchscreen, wired Ethernet, and Docker-based service stack.

---

## 1. Hardware Baseline

**Board:** Raspberry Pi 4 Model B (2GB minimum, 4GB recommended, 8GB ideal for heavy Docker workloads)
**SoC:** Broadcom BCM2711, quad-core Cortex-A72 @ 1.5–1.8 GHz (arm64/aarch64)
**Network:** Gigabit Ethernet (true dedicated bus, not shared with USB like Pi3), dual-band 802.11ac Wi-Fi (not used — Ethernet only for server role)
**USB:** 2× USB 3.0, 2× USB 2.0 (for Zigbee/Z-Wave dongles, USB SSD, etc.)
**GPIO:** 40-pin header (available for relay control, sensors, HATs)
**Display:** DSI port for official 7" touchscreen (800×480, capacitive, 10-point multitouch)
**Power:** USB-C, 5.1V/3A minimum (use official PSU or quality 5V/3.5A to avoid undervoltage throttling — yellow lightning bolt icon = undervoltage)
**Power draw:** 5–15W depending on load; ~$3–8/month to run 24/7

### Storage Strategy

- **SD card:** Use only for boot (Class 10 / A2 minimum, 32GB+). SD cards suffer from write amplification and wear under Docker's overlay2 I/O. Container startup: 5–15s on SD vs 1–2s on SSD.
- **USB SSD (recommended):** Boot from USB SSD for dramatically better I/O. Use `rpi-eeprom-update` to enable USB boot, then flash OS to SSD via Raspberry Pi Imager. A $20–30 120GB SATA SSD via USB 3.0 adapter transforms performance and longevity.
- **If SD only:** Minimize writes — move Docker data dir, logs, and swap to a USB drive if possible. Reduce swappiness (`vm.swappiness=1`). Use `log2ram` to keep logs in RAM.

### Touchscreen Setup

**Official 7" Pi Touch Display:** DSI ribbon cable connection (labelled "DISPLAY" on Pi4). Adapter board mounts behind LCD; Pi4 mounts to adapter board standoffs. No additional drivers needed on Raspberry Pi OS.

**Cases with integrated touchscreen:**
- Official Pi Foundation case for 7" display (~$15)
- SmartiPi Touch 2 (adjustable angle, VESA mount)
- SunFounder 7" or 10" all-in-one kits (IPS, integrated case + cooling)
- 3D-printed "Raspberry Show" style cases (Echo Show–inspired desk form factor)
- 3.5" SPI screens exist but are low-res (480×320) and refresh-limited — use 7" DSI for any dashboard role

**Kiosk mode for dashboard display:**
Install minimal X server + Chromium in kiosk mode to auto-launch dashboards (Home Assistant, Grafana, Pi-hole admin, Portainer) on boot:
```
sudo apt install xserver-xorg xinit chromium-browser openbox
```
Configure `/etc/xdg/openbox/autostart` to launch Chromium fullscreen pointing at `http://localhost:PORT`. Use `unclutter` to hide the mouse cursor after idle. Disable screen blanking with `xset s off` and `xset -dpms` in xinitrc.

---

## 2. Base OS Installation

**OS:** Raspberry Pi OS Lite 64-bit (Bookworm-based, Debian 12). Lite = no desktop, headless. 64-bit required for modern Docker images (most publish arm64 only now). Verify with `uname -m` → must show `aarch64` not `armv7l`.

**Flashing:** Use Raspberry Pi Imager. Under "OS Customisation" (gear icon):
- Enable SSH (password or key)
- Set hostname (e.g., `piserver`)
- Set username/password (do NOT use default `pi`)
- Configure locale/timezone
- (Optional) Configure Wi-Fi for initial headless access, disable after Ethernet is confirmed

**First boot sequence:**
```bash
# SSH in from another machine
ssh youruser@piserver.local

# Full system update
sudo apt update && sudo apt full-upgrade -y
sudo reboot

# Set static IP (edit dhcpcd or NetworkManager depending on OS version)
# Bookworm uses NetworkManager by default:
sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.X/24
sudo nmcli con mod "Wired connection 1" ipv4.gateway 192.168.1.1
sudo nmcli con mod "Wired connection 1" ipv4.dns "127.0.0.1"
sudo nmcli con mod "Wired connection 1" ipv4.method manual
sudo nmcli con up "Wired connection 1"
```

---

## 3. OS Hardening

### SSH Hardening
```bash
# Generate key pair on your workstation (not the Pi)
ssh-keygen -t ed25519

# Copy public key to Pi
ssh-copy-id -i ~/.ssh/id_ed25519.pub youruser@piserver.local

# On the Pi — edit sshd_config
sudo nano /etc/ssh/sshd_config
# Set:
#  PermitRootLogin no
#  PasswordAuthentication no
#  PubkeyAuthentication yes
#  Port 2222  (change from default 22)
sudo systemctl restart sshd
```

### Firewall (UFW)
```bash
sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 2222/tcp  # SSH (your custom port)
sudo ufw allow 53/tcp    # DNS (Pi-hole)
sudo ufw allow 53/udp    # DNS (Pi-hole)
sudo ufw allow 80/tcp    # HTTP (dashboards)
sudo ufw allow 443/tcp    # HTTPS
sudo ufw allow 51820/udp  # WireGuard VPN
sudo ufw enable
```

### Fail2Ban
```bash
sudo apt install fail2ban -y
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo nano /etc/fail2ban/jail.local
# Under [sshd]:
#  enabled = true
#  port = 2222
#  maxretry = 3
#  bantime = 3600
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
```

### Additional Hardening
- Disable unused services: `sudo systemctl disable bluetooth`, `sudo systemctl disable avahi-daemon` (unless using .local mDNS)
- Automatic security updates: `sudo apt install unattended-upgrades -y`
- Remove default `pi` user if it exists: `sudo deluser pi`
- Set `HISTSIZE=1000` and `HISTFILESIZE=2000` in `.bashrc`
- Consider AIDE (file integrity monitoring) for paranoid setups

---

## 4. Docker & Container Management

### Docker Installation
```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group change
docker --version
docker compose version  # v2 included automatically
```

### Key Docker Concepts for Pi4
- Pi4 runs `arm64` (aarch64). `docker pull` auto-selects correct architecture from multi-arch images.
- LinuxServer.io (LSIO) images are reliable ARM64 builds.
- If SD-card storage: move Docker root to USB SSD:
  ```bash
  sudo systemctl stop docker
  sudo rsync -aP /var/lib/docker/ /mnt/ssd/docker/
  # Edit /etc/docker/daemon.json:
  { "data-root": "/mnt/ssd/docker" }
  sudo systemctl start docker
  ```
- Use `restart: unless-stopped` on all services for auto-recovery after reboot.

### Portainer (Container GUI)
```yaml
# docker-compose.yml
services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    ports:
      - "9443:9443"
      - "9000:9000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: unless-stopped
volumes:
  portainer_data:
```
Access at `https://piserver.local:9443`. Provides web GUI for managing all Docker containers, images, volumes, networks. Supports Docker Compose stack deployment from the UI.

### CasaOS (Alternative)
CasaOS is a beginner-friendly GUI layer over Docker. One-line install: `curl -fsSL https://get.casaos.io | sudo bash`. Provides an app store UI for deploying containers (Pi-hole, Nextcloud, Jellyfin, etc.) without writing compose files. Good for non-technical household members. Runs on port 80 by default.

---

## 5. DNS & Ad Blocking — Pi-hole + Unbound

### Pi-hole (Network-Wide Ad Blocker)

Pi-hole acts as DNS sinkhole. All devices on network point DNS to Pi4. Ads, trackers, malware domains get null responses — never load. Blocks 35–45% of all DNS requests in a typical home network (40,000–80,000 queries/day blocked for ~12 devices).

**Pi-hole v6 (current as of 2026):** Major rewrite. FTL has embedded web server (no more lighttpd). Single config file `/etc/pihole/pihole.toml`. Docker image switched from Debian to Alpine (113MB → 38MB).

```yaml
# Docker Compose for Pi-hole
services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "CHANGEME"
    volumes:
      - pihole_data:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
volumes:
  pihole_data:
  pihole_dnsmasq:
```

**Bare-metal install (alternative):**
```bash
curl -sSL https://install.pi-hole.net | bash
# Follow interactive installer
# Set password: pihole -a -p YourPassword
```

**Network integration — two methods:**
1. **Router DNS method:** Set router's DHCP DNS server to Pi4's static IP. All devices auto-use Pi-hole. No per-device config.
2. **Pi-hole as DHCP server:** Disable DHCP on router, enable in Pi-hole admin. Pi-hole assigns IPs and DNS. Better hostname resolution but more complex.

**Blocklists:** Default Steven Black unified list is good baseline. Add community lists from firebog.net for expanded coverage. Admin dashboard: `http://piserver.local:8080/admin`.

### Unbound (Recursive DNS Resolver)

Without Unbound, Pi-hole forwards queries to upstream DNS (Cloudflare, Google, etc.) — those providers see every domain you resolve. Unbound resolves recursively by walking the DNS hierarchy from root servers. No third-party sees your full query history.

**Architecture:** Pi-hole listens on port 53 → filters ads → forwards allowed queries to Unbound on port 5335 → Unbound resolves recursively against authoritative nameservers.

```bash
sudo apt install unbound -y

# Create Pi-hole-optimized config
sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf
```

```yaml
server:
    verbosity: 0
    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-udp: yes
    do-tcp: yes
    do-ip6: no
    prefer-ip6: no
    harden-glue: yes
    harden-dnssec-stripped: yes
    use-caps-for-id: no
    edns-buffer-size: 1232
    prefetch: yes
    num-threads: 1
    so-rcvbuf: 1m
    private-address: 192.168.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
```

```bash
sudo systemctl enable unbound
sudo systemctl start unbound
# Test: dig pi-hole.net @127.0.0.1 -p 5335
```

In Pi-hole admin → Settings → DNS: set Custom Upstream DNS to `127.0.0.1#5335`. Remove all other upstream servers.

**Trade-off:** First lookup for any domain is slower (Unbound must walk hierarchy). Subsequent queries are cached locally. For most home networks the difference is imperceptible.

### DNSSEC
Unbound validates DNSSEC by default. Protects against DNS cache poisoning and response spoofing. Does NOT encrypt queries in transit (use DoT/DoH at the Unbound level for that, but it's optional and adds complexity).

---

## 6. VPN — WireGuard / Tailscale

### WireGuard via PiVPN (Self-Hosted VPN)

WireGuard: modern VPN protocol, ~4,000 lines of code (vs OpenVPN's 70,000+), faster, simpler, ChaCha20 encryption. Pi4 handles 20–50 simultaneous connections comfortably.

```bash
curl -L https://install.pivpn.io | bash
# Select WireGuard (not OpenVPN)
# Choose your Ethernet interface
# Set VPN port (default 51820/UDP)
# Choose DNS provider (select Pi-hole if running)
# Use your public IP or dynamic DNS hostname
```

**Port forwarding required:** Forward UDP 51820 on your router to Pi4's static IP.

**Client management:**
```bash
pivpn add      # Create client profile (generates .conf + QR code)
pivpn list      # Show all clients
pivpn remove    # Remove a client
pivpn qr        # Show QR code for mobile import
```

**Split vs Full tunnel:**
- Split tunnel: only home network traffic goes through VPN (access LAN remotely)
- Full tunnel: ALL traffic routes through VPN (secure public Wi-Fi)
- Create both profiles for different use cases

**Pi-hole + WireGuard combo:** Route VPN DNS through Pi-hole. Ad blocking follows you everywhere — mobile, laptop on public Wi-Fi, travel.

### Tailscale (Zero-Config Mesh VPN)

Alternative to self-hosted WireGuard. No port forwarding needed. Built on WireGuard protocol but with automatic NAT traversal, key management, and mesh networking.

```bash
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
# Authenticate via URL provided
```

**Key features:**
- Mesh network: devices connect directly peer-to-peer
- Subnet router: Pi4 can expose entire LAN to your tailnet (`sudo tailscale up --advertise-routes=192.168.1.0/24`)
- Exit node: route all traffic through Pi4 when remote
- MagicDNS: access devices by hostname
- ACLs: control which devices can see what
- Free tier: up to 100 devices, 3 users

**Pi4 as subnet router:** All devices on tailnet can access your home LAN through the Pi4 — NAS, printers, other PCs — without installing Tailscale on each.

**Disable key expiry** for always-on devices (Pi4, NAS): Tailscale admin console → Machines → select Pi → Disable key expiry.

---

## 7. Smart Home — Home Assistant

### Overview

Home Assistant (HA) is open-source, privacy-first home automation. Emphasis on LOCAL control — devices controlled directly over LAN without cloud dependency. Runs on Pi4 via HAOS image or Docker container. 2,000+ integrations.

### Installation Methods

**Method 1: Home Assistant OS (HAOS) — dedicated Pi4**
Flash the HAOS image directly. Pi4 becomes a dedicated HA appliance. Includes Supervisor for add-on management. Best integration, simplest updates, but Pi4 can't easily run other services.

**Method 2: Docker container — shared Pi4 (recommended for this use case)**
```yaml
services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    privileged: true
    volumes:
      - ha_config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
volumes:
  ha_config:
```
Access at `http://piserver.local:8123`. Loses Supervisor/add-on system but runs alongside Pi-hole, WireGuard, monitoring, etc.

### Offline / Local Control

HA was built for local-first operation. Works without internet if devices use local protocols:
- **Zigbee:** Requires USB coordinator dongle ($15–25, e.g., SONOFF Zigbee 3.0, Conbee II). Use ZHA integration (built-in) or Zigbee2MQTT. Fully local. Wide device support (lights, sensors, switches, locks).
- **Z-Wave:** Requires USB Z-Wave stick (e.g., Aeotec Z-Stick Gen5+). Use Z-Wave JS integration. Fully local. Strong for locks, thermostats, switches.
- **Wi-Fi (local):** Devices running Tasmota, ESPHome firmware communicate over local network only. No cloud.
- **Thread/Matter:** Newer protocol standard. Local-first by design. Pi4 can act as Thread border router with appropriate hardware.

**MQTT broker (Mosquitto):** Central message bus for IoT. Lightweight publish/subscribe protocol. All Zigbee2MQTT and many other integrations route through it.
```bash
sudo apt install mosquitto mosquitto-clients -y
sudo systemctl enable mosquitto
```
Or via Docker:
```yaml
services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - mosquitto_config:/mosquitto/config
      - mosquitto_data:/mosquitto/data
    restart: unless-stopped
```

### Zigbee2MQTT (Alternative to ZHA)
Bridges Zigbee coordinator to MQTT. More device support than ZHA, runs outside HA (survives HA restarts), web dashboard for device management.
```yaml
services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    container_name: zigbee2mqtt
    volumes:
      - z2m_data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8082:8080"
    environment:
      TZ: "America/New_York"
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped
```

### Touchscreen Integration
Run Chromium in kiosk mode (see Section 1) pointing at `http://localhost:8123`. Create a dedicated HA user with a custom dashboard optimized for touch (large buttons, status cards). Auto-login via HA trusted networks or long-lived access token.

---

## 8. Network Monitoring

### Uptime Kuma (Service Monitor)
Lightweight, open-source. Monitors HTTP, TCP, DNS, ICMP ping, Docker containers. Real-time dashboard, historical stats (24h/7d/30d). 90+ notification channels (Telegram, Discord, email, Gotify). Pi4 handles 50–100+ monitors easily. ~76,000 GitHub stars, current version 2.1.3 (Feb 2026). Integrates with Home Assistant as of HA 2025.8 (binary sensors per monitor).

```yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    restart: unless-stopped
```

### Grafana + Prometheus (Advanced Monitoring)
Full metrics stack. Prometheus scrapes time-series data; Grafana visualizes. Pre-built Raspberry Pi dashboards (CPU, memory, disk I/O, temperature). Can ingest Uptime Kuma metrics via Prometheus exporter.

```yaml
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3030:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    restart: unless-stopped
```

### Gotify (Push Notifications)
Self-hosted notification server. Receives alerts from Uptime Kuma, Grafana, custom scripts. Android app available. Replaces dependency on Pushover/Ntfy cloud services.

### Recommended Monitoring Stack
"Holy trinity" for home labs: Uptime Kuma (service uptime) + Beszel or Pulse (host metrics) + Gotify (alerting). Grafana/Prometheus for deep-dive dashboards if desired.

---

## 9. PC Cluster / Network Orchestration

### Using Pi4 as Control Plane for Desktop PCs

The Pi4 can serve as the management/control plane node while desktop PCs (x86_64) serve as worker nodes. Two main approaches:

### Approach A: Docker Swarm (Simpler)
- Pi4 runs as Swarm manager
- Desktop PCs join as worker nodes
- Manages containerized services across the cluster
- Built-in load balancing and scaling
- Good for: distributed web apps, batch processing, CI/CD runners
```bash
# On Pi4 (manager):
docker swarm init --advertise-addr 192.168.1.X
# Shows join token

# On each desktop PC (worker):
docker swarm join --token SWMTKN-xxxxx 192.168.1.X:2377
```
**Mixed architecture caveat:** Images must be multi-arch (arm64 + amd64). Pi4 manager runs arm64; x86 workers run amd64. Use multi-arch images or constrain services to specific node architectures via placement constraints.

### Approach B: K3s Lightweight Kubernetes (More Powerful)
K3s: single binary (~70MB), includes API server, scheduler, controller manager, kubelet, containerd, Flannel CNI, Traefik ingress, CoreDNS. Supports mixed arm64/amd64 clusters natively.

```bash
# On Pi4 (control plane):
curl -sfL https://get.k3s.io | sh -
# Get join token:
cat /var/lib/rancher/k3s/server/node-token

# On each desktop PC (worker):
curl -sfL https://get.k3s.io | K3S_URL=https://piserver:6443 K3S_TOKEN=XXX sh -
```

**Pi4 resource budget for K3s control plane:**
- K3s server: ~500MB RAM
- System: ~300MB RAM
- Available for workloads: ~2.7GB (on 4GB Pi4)
- OS buffer/cache: ~500MB

**Use cases for Pi4-managed PC cluster:**
- Distributed build/CI runners (GitHub Actions self-hosted, Drone)
- Distributed rendering (Blender render farm)
- Game server hosting across machines
- Distributed storage (GlusterFS across nodes)
- Learning enterprise orchestration patterns

### Wake-on-LAN (WoL)
Pi4 can wake sleeping/powered-off PCs on demand:
```bash
sudo apt install wakeonlan -y
wakeonlan AA:BB:CC:DD:EE:FF  # MAC address of target PC
```
Combine with Home Assistant automations or cron jobs. Useful for spinning up worker nodes only when needed (power savings). Requires WoL enabled in each PC's BIOS/UEFI and network adapter settings.

---

## 10. Reverse Proxy

### Traefik (Recommended for Docker)
Auto-discovers Docker containers, auto-configures routing, auto-manages Let's Encrypt TLS certificates. Label-based configuration — no manual config file updates per service.

```yaml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    ports:
      - "80:80"
      - "8180:8080"  # Traefik dashboard
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
```

Other services add Traefik labels:
```yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.pihole.rule=Host(`pihole.local`)"
```

### Nginx Proxy Manager (Alternative)
Web GUI for reverse proxy config. Simpler for those uncomfortable with label/file-based config. Supports Let's Encrypt, access lists, custom locations.

### Local DNS Names
Use Pi-hole's "Local DNS → DNS Records" to create custom hostnames:
- `pihole.home` → 192.168.1.X
- `grafana.home` → 192.168.1.X
- `ha.home` → 192.168.1.X

Combined with reverse proxy, access services by name instead of IP:port.

---

## 11. Additional Services Worth Running

| Service | Purpose | Port | Notes |
|---|---|---|---|
| **Nextcloud** | Self-hosted cloud storage/sync | 8443 | Pi4 handles light use; heavy use benefits from SSD |
| **Vaultwarden** | Bitwarden-compatible password manager | 8081 | Very lightweight, perfect for Pi4 |
| **Nginx/Caddy** | Static site hosting | 80/443 | Host personal website directly |
| **Gitea** | Self-hosted Git | 3000 | Lightweight GitHub alternative |
| **Jellyfin** | Media server | 8096 | Pi4 can direct-play most formats; no hardware transcoding on Pi4 GPU |
| **Syncthing** | File sync between devices | 8384 | Replaces Dropbox/Google Drive |
| **Homer/Homarr** | Dashboard/homepage | 8083 | Landing page linking all services |
| **Node-RED** | Visual automation flows | 1880 | Bridges HA, MQTT, APIs, scripts |
| **n8n** | Workflow automation | 5678 | Self-hosted Zapier alternative |
| **Ntfy/Gotify** | Push notifications | 8085 | Self-hosted push service |
| **Speedtest Tracker** | ISP speed monitoring | 8765 | Tracks download/upload/latency over time |

---

## 12. Maintenance & Best Practices

### Backups
```bash
# Backup all Docker volumes
sudo tar czf /mnt/backup/docker-volumes-$(date +%F).tar.gz /var/lib/docker/volumes/

# Or use restic for incremental encrypted backups
sudo apt install restic -y
restic init --repo /mnt/backup/restic-repo
restic backup /var/lib/docker/volumes/ /etc/pihole/ /etc/unbound/
```

### Updates
```bash
# System
sudo apt update && sudo apt upgrade -y

# Docker images
docker compose pull    # Pull latest images
docker compose up -d  # Recreate with new images
docker image prune -f  # Clean old images

# Pi-hole
pihole -up  # If bare-metal install

# Automate with cron:
# 0 3 * * 0 docker compose -f /home/youruser/docker-compose.yml pull && docker compose -f /home/youruser/docker-compose.yml up -d
```

### Monitoring Pi Health
```bash
# CPU temperature (throttles at 80°C, shuts down at 85°C)
vcgencmd measure_temp

# Voltage/throttling status
vcgencmd get_throttled
# 0x0 = all good
# 0x50005 = throttled due to undervoltage

# Memory
free -h

# Disk
df -h

# Docker resource usage
docker stats --no-stream
```

### Cooling
Pi4 throttles under sustained load without cooling. At minimum: aluminum heatsinks on SoC and RAM. Better: active fan case (e.g., Argon ONE, Flirc, GeeKPi) or PoE HAT with fan. For always-on server duty, active cooling is strongly recommended.

### Reliability
- Use quality USB-C PSU (5.1V/3A minimum, official recommended)
- UPS recommended (small USB UPS or PoE with UPS switch). NUT (Network UPS Tools) on Pi4 can signal other machines to shut down gracefully on power loss.
- Enable watchdog timer: add `dtparam=watchdog=on` to `/boot/firmware/config.txt`, install `watchdog` package. Auto-reboots on system hang.
- Monitor SD card health with `smartctl` (if SSD) or watch for I/O errors in `dmesg`

---

## 13. Complete Docker Compose Stack (Reference)

Single compose file for the core service stack:

```yaml
version: "3.8"

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      TZ: "${TZ}"
      WEBPASSWORD: "${PIHOLE_PASSWORD}"
      PIHOLE_DNS_: "127.0.0.1#5335"
    volumes:
      - pihole_data:/etc/pihole
      - pihole_dnsmasq:/etc/dnsmasq.d
    restart: unless-stopped
    cap_add:
      - NET_ADMIN

  wireguard:
    image: linuxserver/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      PUID: 1000
      PGID: 1000
      TZ: "${TZ}"
      SERVERURL: "${WG_SERVER_URL}"
      SERVERPORT: 51820
      PEERS: "phone,laptop,tablet"
      PEERDNS: "192.168.1.X"  # Pi-hole IP
    volumes:
      - wireguard_config:/config
      - /lib/modules:/lib/modules
    ports:
      - "51820:51820/udp"
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    network_mode: host
    privileged: true
    volumes:
      - ha_config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped

  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - mosquitto_config:/mosquitto/config
      - mosquitto_data:/mosquitto/data
    restart: unless-stopped

  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    ports:
      - "3001:3001"
    volumes:
      - uptime_kuma_data:/app/data
    restart: unless-stopped

  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: unless-stopped

volumes:
  pihole_data:
  pihole_dnsmasq:
  wireguard_config:
  ha_config:
  mosquitto_config:
  mosquitto_data:
  uptime_kuma_data:
  portainer_data:
```

Create `.env` file alongside:
```
TZ=America/New_York
PIHOLE_PASSWORD=changeme
WG_SERVER_URL=your.dynamic-dns.com
```

---

## 14. Network Architecture Diagram

```
[Internet] → [Router/Modem]
                  │
                  ├── Ethernet → [Pi4 Server Head] (192.168.1.X, static)
                  │                  ├── Pi-hole (DNS port 53)
                  │                  ├── Unbound (recursive DNS, port 5335, localhost only)
                  │                  ├── WireGuard VPN (UDP 51820)
                  │                  ├── Home Assistant (port 8123)
                  │                  ├── Mosquitto MQTT (port 1883)
                  │                  ├── Zigbee2MQTT (port 8082) ← USB Zigbee coordinator
                  │                  ├── Uptime Kuma (port 3001)
                  │                  ├── Portainer (port 9443)
                  │                  ├── Grafana (port 3030)
                  │                  ├── Traefik reverse proxy (port 80/443)
                  │                  └── [Touchscreen: kiosk dashboard]
                  │
                  ├── Ethernet/Wi-Fi → [Desktop PCs] (Docker Swarm/K3s workers)
                  ├── Wi-Fi → [Phones, Tablets, Laptops]
                  ├── Wi-Fi/Zigbee → [Smart Home Devices]
                  └── Wi-Fi → [Smart TVs, Consoles, IoT]

Router DNS setting → Pi4 IP (all devices auto-use Pi-hole)
WireGuard clients → Pi4 (remote access + ad blocking away from home)
K3s/Swarm workers → Pi4 control plane (orchestration)
```

---

## 15. Quick-Start Checklist

1. [ ] Flash Raspberry Pi OS Lite 64-bit to SD card (or USB SSD)
2. [ ] Enable SSH, set hostname, set user/password in Imager
3. [ ] Boot Pi4, connect Ethernet, SSH in
4. [ ] Set static IP on Pi4
5. [ ] System update + reboot
6. [ ] Harden: SSH keys, change port, UFW, Fail2Ban
7. [ ] Install Docker + Docker Compose
8. [ ] Deploy Pi-hole (set router DNS to Pi4 IP)
9. [ ] Install Unbound, configure as Pi-hole upstream
10. [ ] Deploy Portainer for container management
11. [ ] Deploy WireGuard (PiVPN) or install Tailscale
12. [ ] Deploy Home Assistant + Mosquitto (if doing smart home)
13. [ ] Deploy Uptime Kuma for monitoring
14. [ ] Set up touchscreen kiosk mode for dashboard
15. [ ] Configure backups (cron + restic or tar)
16. [ ] (Optional) Set up K3s/Docker Swarm for PC cluster
17. [ ] (Optional) Deploy additional services (Vaultwarden, Nextcloud, etc.)

---

## 16. Key Port Reference

| Port | Service | Protocol |
|------|---------|----------|
| 22/2222 | SSH | TCP |
| 53 | Pi-hole DNS | TCP/UDP |
| 80 | HTTP / Traefik / CasaOS | TCP |
| 443 | HTTPS / Traefik | TCP |
| 1883 | Mosquitto MQTT | TCP |
| 3001 | Uptime Kuma | TCP |
| 3030 | Grafana | TCP |
| 5335 | Unbound (localhost) | TCP/UDP |
| 8080 | Pi-hole Admin | TCP |
| 8082 | Zigbee2MQTT | TCP |
| 8123 | Home Assistant | TCP |
| 9000/9443 | Portainer | TCP |
| 51820 | WireGuard VPN | UDP |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Download the .zip below to use this document with your AI assistant.

pi4-network-server-context.zip (Size: 11.32 KB / Downloads: 0)

MyBB 1.8 Theme Generation

Sun, 23 Aug 2026 03:44:28 +0000

MyBB 1.8 Theme Generation — Context Document

Specification for AI-assisted MyBB theme creation — templating rules, variables, and XML packaging

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This is a compact context document that gives an AI assistant the knowledge it needs to generate valid MyBB 1.8 themes — complete with correct template syntax, global variable references, and properly structured XML output ready for import.

MyBB's templating system has specific rules that AI models frequently get wrong without guidance. This document prevents the most common mistakes: using PHP tags inside templates, generating logic tags that don't exist in vanilla MyBB, and producing malformed theme XML.

─── ◆ ───

What It Covers

Templating rules — correct interpolation syntax ({$variable}, {$array['key']}), the prohibition on PHP tags and logic tags (, , ) in vanilla MyBB, and proper sub-component inclusion via variable names
Global variable dictionary — theme assets, settings, viewer profile variables, and core injection points ({$headerinclude}, {$header}, {$navigation}, {$footer})
Theme XML package specification — the complete schema for outputting importable theme XML, including properties, stylesheets with CDATA wrapping, and template sets
Compliance notes — XHTML 1.0 Transitional / HTML5 markup requirements and the core CSS class names (.tborder, .thead, .tcat, .trow1, .trow2, .tfoot) that must be preserved

─── ◆ ───

How to Use It

Paste the contents into a new conversation when you need AI help building or modifying a MyBB theme. The document is deliberately compact — it focuses on the rules the AI needs to follow rather than exhaustive documentation of every MyBB feature. This keeps it small enough to leave room in the context window for your actual design work.

Works best when paired with a clear description of the visual design you want. The AI handles the correct syntax and packaging; you focus on the look and feel.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Document Contents

Code:
# MYBB 1.8 THEME GENERATION ENGINE SPECIFICATION

## TEMPLATING RULES
1. SYNTAX: Use {$variable} or {$array['key']} for interpolation. Never use PHP tags () inside templates.
2. NO ENGINE LOGIC: Vanilla MyBB HAS NO , , , or  tags. Never generate logic tags in template code.
3. INCLUSIONS: Include sub-components via variable names (e.g., {$headerinclude}, {$header}, {$navigation}, {$footer}).
4. COMPLIANCE: Standard XHTML 1.0 Transitional / HTML5 markup with MyBB core class names (.tborder, .thead, .tcat, .trow1, .trow2, .tfoot).

## GLOBAL VARIABLE DICTIONARY
- Theme Assets: {$theme['imgdir']}, {$theme['imglangdir']}
- Settings: {$mybb->settings['bbname']}, {$mybb->settings['bburl']}
- Viewer Profile: {$mybb->user['uid']}, {$mybb->user['username']}, {$mybb->user['avatar']}
- Core Injections: {$headerinclude} (in ), {$header} (top bar), {$navigation} (breadcrumbs), {$footer} (bottom)

## THEME XML PACKAGE SPECIFICATION
When outputting a full theme XML, wrap inside this schema:

    images/[theme_folder]
    4
    1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Download the .zip below to use this document with your AI assistant.

mybb-theme-context.zip (Size: 1,019 bytes / Downloads: 0)

Community Context Library Introduction

Sun, 23 Aug 2026 03:42:13 +0000

Community Context Library

Share and download context documents that turn general-purpose AI models into domain experts

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

This section is a community-driven library of context documents — structured reference files designed to be fed directly to an AI assistant at the start of a conversation. Each one is a condensed knowledge package covering a specific tool, workflow, hardware platform, or creative domain. When you give one of these documents to a model, it doesn't just know the topic exists — it understands the details, the gotchas, the correct settings, and the real-world techniques that separate useful output from generic advice.

Anyone can contribute. If you've built a context document that makes AI genuinely better at something, post it here for others to use. If you're looking for expertise on a topic, browse what's available and grab what fits.

These aren't tutorials or guides written for humans to follow step by step. They're reference material formatted for AI consumption — dense, precise, and structured so a model can absorb the full picture and then help you work within it. You still drive. The document just makes sure the AI actually knows what it's talking about.

─── ◆ ───

How to Use a Context Document

The workflow is simple. Pick a document that covers what you're working on, then at the start of a new conversation with your AI assistant, either paste the document contents in or attach the file directly. The model reads it, absorbs the domain knowledge, and you proceed with your actual questions and tasks. The AI will now have the specific, detailed understanding that the document provides — correct syntax, proper settings, real techniques, known pitfalls — instead of relying on whatever it happens to remember from training.

Some documents pair well together. A music generation reference and a retro audio reference complement each other when you're trying to generate era-accurate game music, for example. Use as many as make sense for your session, keeping in mind that each one uses some of the model's context window.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

How to Build Your Own

A method for turning scattered internet knowledge into dense, reusable guides that make any AI model an instant expert

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

AI models are general-purpose. They know a little about a lot. For niche or technical subjects — setting up pixel art workflows in ComfyUI, modding NES ROMs, configuring servers on Linux — their knowledge is shallow, scattered, and sometimes wrong. But they're extremely good at two things: searching the web for information, and synthesizing large amounts of raw data into organized, coherent documents.

The trick is using those strengths in sequence. Let the AI do what it's good at (searching, reading, condensing) so you end up with a document that solves what it's bad at (deep niche expertise). Once the doc exists, feeding it back in gives the model the equivalent of years of hands-on experience with the topic — in about 6,000 tokens.

A curated 5,000-word doc outperforms a raw 50,000-word dump every time. The editorial pass is what makes it work.

─── ◆ ───

Pass 1 — Cast the Wide Net

Start a conversation with the AI and give it a broad directive. Don't micromanage the search — tell it to go deep and bring back everything it can find.

Example prompt:

Code:
Search every corner of the internet, read every article you can find on [TOPIC].
Learn everything you possibly can about [SPECIFIC ASPECT]. Find every technique,
every tool, every workflow. Then condense all of it into a single comprehensive
reference document.

The AI will run multiple searches, fetch full articles, read documentation pages, and pull from forums, GitHub repos, and guides. It will then synthesize all of that into one structured document covering the entire topic.

What you get is a first-draft document that covers the major territory. It won't be complete yet, but it captures the bulk of available knowledge in one pass. A typical first pass runs 8–12 web searches and 4–6 full page reads, producing a 4,000–7,000 word document at around 20–40KB. That's roughly 70–80% of the available knowledge on the topic, captured in one shot.

─── ◆ ───

Pass 2 — Fill the Gaps

Feed the document back into a new conversation. Ask the AI to read what you already have and search specifically for what's missing.

Example prompt:

Code:
Here is a reference doc I am building on [TOPIC]. Read through it, identify any
gaps or areas that need more depth, then search for additional information to
fill those gaps. Update the document with the new findings.

Because the AI can see what's already covered, it won't waste searches re-finding the same material. Every fetch brings back new information only. The context window stays clean because you're not carrying redundant data.

─── ◆ ───

Pass 3+ — Refine and Verify

Repeat Pass 2 as needed. Each round gets more targeted and brings back less — that's how you know you're approaching completeness. When a pass comes back with only minor additions or confirmations of what's already there, you're done.

Typical progression:

Pass 1: Major findings, core structure, 70–80% coverage
Pass 2: Gap filling, edge cases, alternative approaches, 90% coverage
Pass 3: Verification, corrections, minor additions, 95%+ coverage

Most topics reach diminishing returns by pass 2 or 3. Extremely broad subjects might benefit from 4–5 passes.

─── ◆ ───

Maintenance — Keep It Current

When you need to check if anything has changed:

Example prompt:

Code:
Here is my reference doc on [TOPIC], last updated [DATE]. Search for any new
developments, updated tools, new versions, or changed information since then.
Update the document with anything new and note what changed.

This is cheap — one pass, only fetching what's actually new. The doc stays current without rebuilding from scratch.

─── ◆ ───

What Makes a Good Topic

The method works best on subjects where information is scattered across many sources (forums, GitHub, wikis, blog posts, documentation), where no single definitive guide exists or the ones that do are outdated, where the subject is technical or procedural with specific tools, settings, and parameters, and where you'll need this knowledge more than once.

Good candidates: tool-specific workflows, hardware configuration guides, game technical breakdowns, niche software ecosystems, creative production pipelines, anything where AI models handle the topic poorly out of the box because it's too niche for their training data.

─── ◆ ───

Document Structure Tips

Lead with the core problem the doc solves — why does this knowledge need to exist in one place
Organize by task, not by source — readers need to find what to do, not where you found it
Include specific settings, parameters, and values — these are what people actually need and what AI models get wrong most often
Note tradeoffs and pitfalls — "this works but breaks if you do X" is more valuable than "this works"
Keep a sources section at the bottom for anyone who wants to dig deeper
Density over length — every line should earn its place. No filler, no padding, no restating things the model already knows. Maximum knowledge transfer per token.

─── ◆ ───

The Economics

A finished doc is typically 20–40KB. That's smaller than a single thumbnail image. Storage cost is effectively zero.

In token terms, a full guide is roughly 5,000–8,000 tokens when fed into a model. Most modern context windows are 100,000–200,000 tokens. Your reference doc uses 3–5% of the available space and gives the model expert-level knowledge on the entire subject.

Building the initial doc takes about 10–20 minutes of AI conversation time. The alternative — manually searching, reading, bookmarking, and re-searching every time you need the information — costs hours per session, every session, forever.

Plain text files. The oldest, smallest, most universal data format in computing — and now one of the most powerful tools in an AI-assisted workflow.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Post Format Guidelines

How to structure your library posts so everything stays consistent and usable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Every document posted in this library should follow a three-part format to keep things browsable and functional:

Part 1 — Description

The top section of your post is a human-readable overview. Describe what the document covers, what it makes an AI an expert on, and when someone would want to use it. This is what people read to decide if the document is relevant to their needs. Write it for humans, not machines — the document itself is the machine-readable part.

Part 2 — Code Block

Below the description, include the full contents of your context document inside a

Code:
...

block. This lets people read through the actual material without downloading anything. It's the same content that's in the file — just displayed inline so they can preview it before committing to a download.

If your document is too large for the forum's character limit, skip this section and note in the description that the content is available in the download only. A good description with sample entries works fine as a substitute.

Part 3 — Attachment

Attach the document as a .zip file at the bottom of the post. This is the grab-and-go download — unzip it and feed the file directly to your AI assistant.

If for any reason the attachment fails or isn't available, users can always copy the contents directly from the code block in Part 2 and save it as a .md or .txt file. The code block is there as a built-in fallback so the document is always accessible regardless of what the forum attachment system decides to do on any given day.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Browse the threads below. Grab what's useful. Build your own and share it back.