Docs Updater

Keep documentation in sync with code. Generates concise, user-friendly summaries.

Context Files (Read First)

For current state, read from Docs/context/:

• Docs/context/conventions.md - Documentation standards
• Docs/context/repo-structure.md - File organization
• Docs/ai/CHANGELOG.md - Recent changes to sync

Quick Summary Format

Every doc should start with a TL;DR section for human readers:

# Document Title

> **TL;DR:** [1-2 sentence summary of what this covers]
>
> **Key Points:**
> - [Most important fact 1]
> - [Most important fact 2]
> - [Most important fact 3]
>
> **Quick Links:** [Table](#tables) | [RPC](#rpc-functions) | [Edge Functions](#edge-functions)

Documentation Files

TODO List Management

The project TODO list is at Docs/TODO.md. Use this for tracking:

• Deferred tasks (waiting on dependencies like URLs, assets)
• Future improvements
• Known issues to fix later

Adding Tasks

## Category Name

- [ ] **Task title** — Brief description
- [ ] **Another task** — Description with context

Completing Tasks

Change - [ ] to - [x] and optionally add completion date:

- [x] **Task title** — Completed 2026-02-03

Cron/Scheduled Invocation

This skill supports automated execution for documentation audits.

Invocation Modes

Manual: claude /docs-updater "check api docs are current"

Scheduled (cron): Set up with CI/CD or cron job:

# Weekly docs audit (Sundays at midnight)
0 0 * * 0 claude --skill docs-updater --task "audit" --output report.md

# Pre-release docs check
claude --skill docs-updater --task "release-check" --output docs-status.md

Supported Tasks

Audit Report Format

# Documentation Audit Report
Generated: 2026-01-08

## Summary
- Total docs: 15
- Up-to-date: 12
- Needs update: 3
- Critical: 1

## Issues Found

### Critical
- [ ] `03-API.md`: Missing `token_pools` table (added 2026-01-07)

### Warnings
- [ ] `02-DESIGN.md`: Edge Function list outdated
- [ ] `07-ADMIN-GUIDE.md`: Missing Subscriptions page section

## Recommendations
1. Run `sync-schemas` to update API docs
2. Add new admin page to guide

Writing User-Friendly Summaries

Good Summary (DO)

> **TL;DR:** Token-based quota system limits AI usage per subscription plan.
>
> **Key Points:**
> - Users get tokens per 6-hour window (Guest: 50, Pro: 500)
> - Each AI operation costs fixed tokens (Search: 20, Study: 100)
> - Admin can adjust all limits via `/admin/subscriptions`

Bad Summary (DON'T)

## Overview
This document describes the token pool subscription system architecture
which was redesigned from a complex per-feature quota model...

Update Workflow

1. Identify change type → Which docs affected?
2. Update TL;DR first → Most critical information
3. Update details → Tables, examples, diagrams
4. Cross-reference → Update related docs
5. Update changelog → If significant (see criteria below)
6. Validate → Run audit task

Changelog Decision

After updating docs, add a changelog entry if ANY of these apply:

• New feature or capability added
• Database schema changed (tables, columns, migrations)
• API changed (RPC, Edge Function, breaking change)
• Major refactoring (hooks, components extracted/split)
• Bug fix with user-visible impact

Skip changelog for: typo fixes, comment updates, minor doc rewording.

Lean Changelog (Database)

Primary changelog system - stored in admin.changelog_entries table.

IMPORTANT: The table is in admin schema, NOT public or bible_schema. Use MCP tool: mcp__plugin_supabase_supabase__execute_sql

Table Schema

admin.changelog_entries
├── id: uuid (auto-generated)
├── date: date (defaults to CURRENT_DATE)
├── description: text (required)
├── category: text (default: 'feature')
├── importance: integer (default: 3)
├── version_id: uuid (optional, links to changelog_versions)
├── created_at: timestamptz (auto)
└── created_by: uuid (optional)

Quick Add (SQL)

-- Minimal (uses defaults: date=today, category='feature', importance=3)
INSERT INTO admin.changelog_entries (description)
VALUES ('Added verse annotation dialog with tags and notes');

-- With explicit values
INSERT INTO admin.changelog_entries (date, description, category, importance)
VALUES ('2026-01-23', 'Supabase typing infrastructure', 'infrastructure', 2);

Importance Levels

Achievement Rules

Always Level 1:

• Plan was made and implemented
• Multiple related tasks bundled as one
• Major refactoring or new system

Always Level 2:

• Refactoring (use 1 if major)
• New user-visible feature
• Important bug fix

Skip changelog: Typo fixes, comments, failed attempts.

Categories

feature | fix | refactor | infrastructure | docs | chore

Admin UI

Manage at /admin/changelog → "Muutokset" tab.

Full guide: See references/ai-changelog-guide.md

Detailed Changelog (Markdown)

For verbose documentation, use Docs/ai/CHANGELOG.md.

When to Add Changelog Entries

Add entries for significant changes:

• New features implemented
• Database schema changes (new tables, columns, migrations)
• API changes (new RPCs, Edge Functions, signature changes)
• Breaking changes
• Major refactoring (hook extractions, component splits)
• Bug fixes with significant impact
• New admin pages or tools

Entry Format

## [TAG] Short Descriptive Title

### Summary
One paragraph describing what changed and why.

**Date:** YYYY-MM-DD

### Problem
Why was this change needed? What was the motivation?

### Solution
What was implemented? High-level approach.

### Files Created
- `path/to/new-file.ts` - Brief description

### Files Modified
- `path/to/existing-file.ts` - What changed

### Impact
- **Files:** N (number of files affected)
- **Breaking:** Yes/No
- **Migration:** migration_filename.sql (if applicable)

---

Tags

Use these tags to categorize changes:

Creating Releases

When releasing a new version:

1. Add release header at top of changelog (after main title):

   markdownCopy

   ## v1.X.0 - YYYY-MM-DD
   
   Brief summary of this release.
   
   ---
   

2. Group unreleased changes under the new version header

3. Mark breaking changes clearly with [BREAKING] tag

Changelog Tasks

Admin Dashboard

The changelog can be viewed and edited at /admin/changelog:

• View/edit changelog content
• See GitHub commit status (commits since last update)
• Create new version releases with auto-increment

References

• AI changelog guide: See references/ai-changelog-guide.md
• Update examples: See references/examples.md
• Doc templates: See references/templates.md
• Quality checklist: See references/checklist.md