docs-updater

name	docs-updater
description	Expert assistant for keeping documentation synchronized with code changes, maintaining the AI index manifest, creating ASCII flow diagrams, explaining how features/systems work, and reporting changes to Obsidian vault. Use when (1) updating API docs, maintaining architecture diagrams, syncing README, updating CLAUDE.md, or generating documentation from code, (2) updating the AI index — `Docs/ai-index/manifest.yml` (domains, task_playbooks, cross-cutting patterns/components) and its generated catalogues (db-rpc/db-table/code-map/edge-fn/client-map) ("update manifest", "ai index", "päivitä manifesti", "add domain", "add task playbook", "regenerate catalog", "manifest stale"), (3) creating ASCII flow diagrams or workflow visualizations of any feature or system ("piirrä kaavio", "flow diagram", "ASCII kaavio", "workflow"), (4) explaining how something works ("miten toimii", "selitä", "kuvaile arkkitehtuuri", "millainen on", "mistä koostuu"), (5) reporting changes or documentation to Obsidian ("obsidian", "vault", "raportoi obsidianiin", "obsidian note").
invocable	true
cron	true

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
Docs/ai-index/manifest.yml	AI index (domain map)	New domain/feature area, invariant, playbook, cross-cutting pattern
Docs/ai-index/*-catalog.md, code-map.md, client-map.md	Generated catalogues	DB/RPC/edge-fn/client change — regenerate, never hand-edit

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

AI Index Maintenance

The AI index (Docs/ai-index/) is the first thing Claude reads for non-trivial tasks. Keeping it current is core docs-updater work — stale entries cost every future session 30–50k tokens of redundant exploration.

Two maintenance modes:

• manifest.yml — hand-maintained. Edit the relevant section (domains, task_playbooks, cross_cutting_patterns, cross_cutting_components, deployment, typed_clients, …). Bump updated: and prepend an internal-changelog comment line citing the source session/commit.

• The five catalogues (db-rpc-catalog.md, db-table-catalog.md, code-map.md, edge-fn-catalog.md, client-map.md) — generated, never hand-edited. Regenerate:

  bun scripts/build-db-catalog.mjs    # db-rpc + db-table (regen types.ts FIRST)
  bun scripts/build-code-map.mjs      # code-map + edge-fn + client-map
  

A non-blocking pre-commit hook (scripts/check-ai-index-stale.mjs) warns when a *-types.ts / edge-fn / lib/*Client.ts change is staged without its catalogue.

When working on any code change, ask: did this add a domain, an invariant, a table/RPC/edge-fn, or a repeated task type? If yes, update the index.

Full procedures (domain template, playbook structure, trigger table, checklist): see references/ai-index-maintenance.md

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

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. Report to Obsidian → If importance 1-2 or architecture change (see Obsidian section)
7. 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) ← INTERNAL/technical, never shown publicly
├── title: text (optional) ← PUBLIC, generic marketing-style headline
├── is_publishable: boolean (default false) ← may this entry be shown publicly?
├── 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)

Publishability (title + is_publishable) — read before logging. The public changelog surface (/premium/changelog via the get_publishable_changelog RPC) shows ONLY rows with is_publishable = true AND a non-null title, and it renders the title — never the raw description.

• Always write a generic, marketing-style title (one short user-benefit line; no internal names — no RPC / schema / file / edge-fn names).
• Set is_publishable = true ONLY when the entry leaks nothing sensitive. Default is false (opt-in). Never flag security-fix detail publishable (vuln class, SSRF/RBAC/quota/PII, internal names) — leave is_publishable = false.
• Admin UI (/ohjaamo/changelog) has a title field + "Julkaistavissa" toggle; RPCs add_changelog_entry / update_changelog_entry take p_title + p_is_publishable.

Quick Add (SQL)

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

-- Publishable feature: generic public title + flag = true
INSERT INTO admin.changelog_entries (date, description, category, importance, title, is_publishable)
VALUES ('2026-01-23', 'Lisätty jaeannotaatiodialogi (tagit + muistiinpanot)', 'feature', 2,
        'Merkitse ja muistiinpanota jakeita', true);

-- 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');

-- Security fix — keep internal: write a generic title but DO NOT publish
INSERT INTO admin.changelog_entries (date, description, category, importance, title, is_publishable)
VALUES ('2026-01-23', 'Korjattu SSRF pixabay-proxyssä + RBAC-bypass', 'fix', 1,
        'Tietoturvaparannuksia', false);

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.

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:

Tag	Use For
[FEATURE]	New user-facing features
[SCHEMA]	Database table/column changes
[API]	RPC or Edge Function changes
[COMPONENT]	React component refactoring
[BREAKING]	Breaking changes (often combined with others)
[FIX]	Bug fixes with significant impact
[REFACTOR]	Code restructuring without behavior change
[ADMIN]	Admin panel additions/changes

Creating Releases

When releasing a new version:

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

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

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

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

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":

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

Obsidian Vault Reporting

Mirror significant documentation updates to the Obsidian vault at /Users/opj/dev/obsidian/opeejii/.

When to Report to Obsidian

Report to Obsidian when ANY of these apply:

• Changelog entry added (importance 1-2)
• Audit report generated
• New system/feature explained with ASCII diagram
• Architecture documentation created or significantly updated

Skip Obsidian for: typo fixes, minor doc rewording, importance 3-4 technical changes.

Workflow

1. Complete the Docs/ update first — Obsidian is a mirror, not the source of truth
2. Determine note type — changelog, audit, architecture, or feature (see templates in reference)
3. Create or update note in the project's dev/ subfolder, never the project root — pages/hankkeet/Raamattu Nyt/dev/ (IdeaMachina → pages/hankkeet/Idea Machina/dev/). Convention: <Project>/dev/ = AI's technical layer, project root = hub + human content. See obsidian-reporting.md. Create folder if needed.
4. Use Obsidian syntax — Mermaid diagrams (not ASCII), callouts, wikilinks, properties frontmatter
5. Cross-link — wikilink related notes within the vault

For Obsidian-specific syntax (callouts, properties, Mermaid, kanban), invoke the obsidian-markdown skill.

Note Routing

Change Type	Vault Path	Filename Pattern
Changelog (importance 1-2)	Raamattu Nyt/dev/Changelog/	YYYY-MM-DD Changelog.md
Audit report	Raamattu Nyt/dev/Audits/	YYYY-MM-DD Audit.md
System/architecture	Raamattu Nyt/dev/Architecture/	Descriptive name
Feature docs	Raamattu Nyt/dev/Features/	Feature name

Changelog Notes

Append to today's note if it exists, create new if not. Use callout blocks per category:

> [!success] Features
> - Feature description

> [!fix] Fixes
> - Fix description

Quick Reference

Full templates, tag conventions, and wikilink patterns: see references/obsidian-reporting.md

---

References

• AI index maintenance: See references/ai-index-maintenance.md
• 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
• Obsidian reporting: See references/obsidian-reporting.md