Docs Contribution

This page explains when to update apps/docs, how the documentation is structured, and how to keep it in sync with code changes.

When to update apps/docs

apps/docs is the published, user-facing documentation site. Update it whenever you:

• Add or change a user-facing feature in apps/web or apps/mobile
• Add or change an API endpoint in apps/api
• Change admin workflows in apps/admin that curators or operators need to know about
• Expose a new public API surface in packages/database

Content-only edits (typos, copy improvements) require no extra documentation work — the edit is the update.

What lives where

Content type	Location
User-facing features (web, mobile)	Audience-first section (admins/, developers/, integrations/) or legacy guide/features/ only when updating an existing product page
Admin runbooks	apps/docs/admins/
Developer guides	apps/docs/developers/
API reference	apps/docs/api/
Integration contracts	apps/docs/integrations/
Site changelog	apps/docs/changelog.md
Monorepo-wide ADRs	docs/architecture/
Per-app engineering record	apps/{app}/docs/

Engineering record vs apps/docs

The apps/{app}/docs/ directories are the engineering record — implementation plans, specs, and fix logs for the development team. They are not published to the docs site.

apps/docs is the published surface — what admins, developers, and external integrators read.

Do not copy implementation notes into apps/docs. Summarize the user-relevant outcome instead.

Updating API reference

1. Make your endpoint changes in apps/api/app/routes/.
2. Update the OpenAPI spec in apps/api/app/lib/openapi-spec.ts.
3. Run pnpm --filter=@kubuli/api openapi:export to regenerate apps/api/docs/openapi.json.
4. Update or add the corresponding page under apps/docs/api/.
5. Update the status table in apps/docs/api/overview.md if the endpoint status changed.

Updating the changelog

All user-facing or developer-facing changes get a brief entry in apps/docs/changelog.md under [Unreleased]. Use Keep a Changelog format.

When a version ships, a maintainer bumps the version heading and date.

Local preview

pnpm dev --filter=@kubuli/docs

Runs at http://localhost:4173.

Build to check for dead links before pushing:

pnpm --filter=@kubuli/docs build

VitePress reports dead links as build errors — fix them before committing.