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

Per-app changelogs (read the one relevant to current work):

• Docs/ai/CHANGELOG.md - Raamattu Nyt
• Docs/idea-machina/CHANGELOG.md - IdeaMachina
• Future apps: Docs/<app-id>/CHANGELOG.md

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

App-Specific Documentation

The monorepo has a centralized app registry at apps/raamattu-nyt/src/lib/systems.ts. Each app has a unique id used as system_id across the database.

Convention: Each non-default app gets its own docs folder: Docs/<app-id>/

Rules:

• App-specific docs (plans, specs, changelogs) go to Docs/<app-id>/
• Shared/cross-app docs stay in Docs/ root
• Do NOT place app docs in supabase/migrations/
• When a new app is added to appRegistry, create its Docs/<app-id>/ folder

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

System Routing

Each changelog entry belongs to an app via system_id. Always set the correct system_id.

The app registry (apps/raamattu-nyt/src/lib/systems.ts) is the source of truth. Each app's id is used as system_id.

How to determine system_id: Match the change to its app's packagePath:

• Change in apps/idea-machina/ → system_id = 'idea-machina'
• Change in apps/raamattu-nyt/ or shared packages/ → system_id = 'raamattu-nyt'
• Future app in apps/<new-app>/ → system_id = '<new-app-id>' (read systems.ts for the id)

Corresponding files:

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)
├── system_id: text (default: 'raamattu-nyt') ← ALWAYS SET THIS
├── version_id: uuid (optional, links to changelog_versions)
├── created_at: timestamptz (auto)
└── created_by: uuid (optional)

Quick Add (SQL)

-- Raamattu Nyt (default system_id)
INSERT INTO admin.changelog_entries (description)
VALUES ('Added verse annotation dialog with tags and notes');

-- IdeaMachina — MUST set system_id
INSERT INTO admin.changelog_entries (date, description, category, importance, system_id)
VALUES ('2026-01-23', 'IdeaMachina: Context tiering system', 'feature', 2, 'idea-machina');

-- Raamattu Nyt 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)

Use the correct file based on system_id (see System Routing above):

• Docs/ai/CHANGELOG.md for raamattu-nyt
• Docs/<app-id>/CHANGELOG.md for other apps (e.g. Docs/idea-machina/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

ASCII Flow Diagrams & Workflows

Create ASCII diagrams to visualize how features, systems, or workflows operate. Also use when explaining "miten X toimii" or "millainen X on".

Workflow

1. Read the code — explore the relevant components, hooks, RPCs, and data flow
2. Choose diagram pattern — see references/diagram-patterns.md for 6 patterns
3. Draw the diagram — use Unicode box drawing characters (see patterns file)
4. Place in docs — save to Docs/context/ or embed in the relevant doc file

Pattern Selection

Explain Mode

When user asks "millainen on X" or "selitä X":

1. Read relevant code to understand the system
2. Write a concise summary (TL;DR style)
3. Include an ASCII diagram showing the key flow or structure
4. List key files involved

Output format:

## [Feature Name]

> **TL;DR:** One sentence explaining what it is and does.

### Flow
[ASCII diagram here]

### Key Files
- `path/to/file.tsx` — role
- `path/to/hook.ts` — role

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
• Diagram patterns: See references/diagram-patterns.md