Docs Updater Skill | Agent Skills

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

| Doc | Purpose | Update Trigger | |-----|---------|----------------| | CLAUDE.MD | AI context | Architecture changes | | README.md | Project overview | Feature/setup changes | | Docs/TODO.md | Tracked tasks | New tasks, completed work | | Docs/01-PRD.md | Requirements | Vision changes | | Docs/02-DESIGN.md | Architecture | System design changes | | Docs/03-API.md | API contracts | DB/RPC/Edge changes | | Docs/06-AI-ARCHITECTURE.md | AI system | AI feature changes | | Docs/07-ADMIN-GUIDE.md | Admin panel | Admin changes | | Docs/13-SUBSCRIPTION-SYSTEM.md | Plans/quotas | Subscription changes | | Docs/idea-machina/*.md | Idea Machina docs | Idea Machina changes |

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>/

| App ID | Docs folder | DB tables prefix | |--------|-------------|-----------------| | raamattu-nyt | Docs/ + Docs/ai/ (default, root-level) | various schemas | | idea-machina | Docs/idea-machina/ | pm_* in ai_prompt schema | | future apps | Docs/<app-id>/ | TBD |

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

| Task | Description | Output | |------|-------------|--------| | audit | Check all docs for staleness | Markdown report | | release-check | Pre-release documentation verification | Pass/fail + issues | | sync-schemas | Update docs from database schema | Updated doc files | | generate-api | Generate API docs from Edge Functions | API documentation |

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

Identify change type → Which docs affected?
Update TL;DR first → Most critical information
Update details → Tables, examples, diagrams
Cross-reference → Update related docs
Update changelog → If significant (see criteria below)
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:

| system_id | DB changelog | Markdown changelog | |-----------|-------------|-------------------| | raamattu-nyt | system_id default | Docs/ai/CHANGELOG.md | | idea-machina | system_id = 'idea-machina' | Docs/idea-machina/CHANGELOG.md | | future apps | system_id = '<app-id>' | Docs/<app-id>/CHANGELOG.md |

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

| Level | Label | When to Use | |-------|-------|-------------| | 1 | Saavutus | Plan completed, major milestone, bundled tasks | | 2 | Tärkeä | Significant feature, important fix, refactoring | | 3 | Normaali | Standard change (default) | | 4 | Tekninen | Minor technical detail |

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.

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)

---

Creating Releases

When releasing a new version:

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

## v1.X.0 - YYYY-MM-DD

Brief summary of this release.

---

Group unreleased changes under the new version header
Mark breaking changes clearly with [BREAKING] tag

Changelog Tasks

| Task | Description | Output | |------|-------------|--------| | log-change | Add new entry to changelog | Updated CHANGELOG.md | | release | Create new version release header | Version header added |

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

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

Pattern Selection

| User asks | Pattern | |-----------|---------| | "Miten X toimii?" (sequential) | Linear Flow | | "Mitä tapahtuu kun...?" (branching) | Decision Tree | | "Mistä osista X koostuu?" | Layered Architecture or Component Tree | | "Miten data liikkuu X:ssä?" | Data Flow (sequence diagram) | | "Missä tilassa X voi olla?" | State Machine | | "Mikä renderöi mitäkin?" | Component Tree |

Explain Mode

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

Read relevant code to understand the system
Write a concise summary (TL;DR style)
Include an ASCII diagram showing the key flow or structure
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

Agent Skills: Docs Updater

Install this agent skill to your local

Skill Files