darkwatch/docs/specs/2026-04-11-handbook-changelog-design.md

Handbook & Changelog — Design Spec

Last updated: 2026-04-11

---

Goal

Two reference documents and two maintenance skills:

1. CHANGELOG.md — version history at the repo root; updated every time a feature ships or a bug is fixed
2. docs/HANDBOOK.md — single-file project reference for all collaborators; two sections: product overview (RPG-first) and technical guide (developer-first)
3. update-changelog skill — helps write new changelog entries in the right format when features change
4. update-handbook skill — helps update the handbook when features are added, changed, or removed

---

CHANGELOG.md

Location

Repo root: CHANGELOG.md

Format

Keep a Changelog format with Semantic Versioning.

# Changelog

All notable changes to Darkwatch will be documented here.
Format: [Keep a Changelog](https://keepachangelog.com)
Versioning: [Semantic Versioning](https://semver.org)

## [Unreleased]

## [0.1.0] - 2026-04-11
### Added
- ...features...

Versioning convention

• Patch (0.1.x): bug fixes, minor UI polish, no new features
• Minor (0.x.0): new features or meaningful enhancements
• Major (x.0.0): breaking changes or significant redesigns (rare)

Initial v0.1.0 entry

Groups all currently shipped features under ### Added:

• Auth — email/password, JWT httpOnly cookies, register/login/logout
• Campaign management — CRUD, real-time sync via Socket.IO, invite links, DM/player roles
• Character system — stats, gear, talents, HP, XP, currency, auto-calculated AC and attacks
• Talent effects — stat bonuses, AC, attack/damage, gear slots, HP scaling
• Character creation wizard — 4-step modal (name/class/ancestry → stat rolling → background/alignment/deity → review)
• Spellcasting — 34 Tier 1–2 spells, 1d20 cast checks, exhaustion, Wizard mishap table, Priest penance, rest recovery
• 3D dice rolling — predetermined outcomes, character-colored dice, delayed roll log, advantage/disadvantage
• Torch timer — 60-min countdown, synced across clients
• Luck tokens
• DiceBear avatars with style picker
• Per-character color picker
• Atmosphere panel — fog, fire, rain, embers; DM-only, synced via socket
• Initiative tracker — team-based Shadowdark initiative (rolling phase, active phase), enemy HP tracking (DM-only), add/remove enemies mid-combat, DB-persisted
• Compact DM character cards — 3-up grid, HP/AC/luck/torch/modifiers
• Mobile layout — full-screen sheet, long-press adv/dis, roll log drawer
• Medieval visual theme — Cinzel + Alegreya, parchment, gold, color schemes
• MariaDB migration — replaced SQLite with MariaDB 11 in Docker

---

docs/HANDBOOK.md

Location

docs/HANDBOOK.md — a single file with a top-level table of contents linking to both parts.

Structure

# Darkwatch Handbook

## Table of Contents
- [Part 1: Product Overview](#part-1-product-overview)
- [Part 2: Technical Guide](#part-2-technical-guide)

---

# Part 1: Product Overview

## What is Darkwatch?
## Who is it for?
## How a session works
## Features
  ### Characters
  ### Dice Rolling
  ### Spellcasting
  ### Torch Timer & Luck Tokens
  ### Atmosphere Effects
  ### Initiative Tracker
  ### DM Tools
## What's Coming Next
## Known Limitations

---

# Part 2: Technical Guide

## Stack
## Running Locally
## Repo Structure
## Key Patterns
  ### Socket events
  ### CSS Modules & variables
  ### Database migrations
  ### Auth & roles
## Development Workflow
  ### Brainstorm → Spec → Plan → Implement
  ### Specs and plans: docs/superpowers/
## Roadmap

Part 1 tone

Written for someone who plays or runs TTRPGs. Explains what Darkwatch does and why, without assuming any coding knowledge. Feature descriptions focus on what the DM or player experiences, not how it's implemented.

Part 2 tone

Written for a developer joining the project. Assumes familiarity with Node/React but not with this specific codebase. Covers how to get running locally, where things live, and how we work (the spec/plan/implement loop).

---

Maintenance Skills

Both skills are project-local markdown files stored in .claude/skills/ at the repo root.

update-changelog skill

Trigger: Invoked after a feature ships, bug is fixed, or feature is removed.

Behavior:

1. Read CHANGELOG.md to find the current version
2. Read recent git commits and/or docs/ROADMAP.md for context on what changed
3. Determine the appropriate version bump (patch/minor) based on the nature of the change
4. Write a new versioned entry above the previous one, using the correct section headers (Added, Changed, Fixed, Removed, Security)
5. Commit CHANGELOG.md

Invocation: Via the Skill tool as a project-local skill. Exact storage path (.claude/skills/ or similar) to be confirmed during implementation based on Claude Code's project-local skill conventions.

update-handbook skill

Trigger: Invoked after a feature is added, changed, or removed.

Behavior:

1. Read docs/HANDBOOK.md
2. Identify which sections are affected (Part 1 features, Part 2 patterns, etc.)
3. Update those sections to reflect the current state
4. Commit docs/HANDBOOK.md

Scope: The skill updates prose and feature lists. It does not manage screenshots (those are manual).

---

Out of Scope

• Screenshots — the handbook is text-only; screenshots belong in the marketing site (separate project)
• A separate marketing site (separate project, separate spec)
• GitHub wiki or any external hosting for these docs
• Automated changelog generation from git commits (entries are written intentionally, not mechanically)

---

Notes

• Both skills live in .claude/skills/ inside the repo so all collaborators using Claude get them automatically
• The update-changelog skill should check recent git commits and the roadmap for context on what changed since the last entry, making it easy to catch anything that slipped through without a manual trigger