simfinity.js / rules

---
description: Maintain the monorepo, package and public website documentation for both databases
globs: README.md, AGENTS.md, packages/*/README.md, examples/barber/**/README.md, examples/barber/README.md, docs/**
alwaysApply: false
---

# Documentation Maintenance

## Documentation locations

- `README.md`: repository overview and shared API examples, with MongoDB/PostgreSQL setup links.
- `packages/*/README.md`: each published package's installation, entry points and responsibilities. MongoDB's directory is `packages/mongodb`, but its public name remains `@simtlix/simfinity-js`.
- `examples/barber/README.md` and app READMEs: runnable MongoDB/PostgreSQL stacks, shared frontend, environment settings, synthetic seeds, reset commands and independent CI. Keep the public overview in `docs/resources/barber.md` linked to these runbooks.
- `docs/guide/`, `docs/reference/`, `docs/resources/`: the VitePress website. Keep shared semantics consistent and identify backend-specific storage, initialization and native APIs.
- `docs/postgresql.md` and `docs/compatibility.md`: detailed PostgreSQL contract and verification notes; distinguish historical snapshots from current support.
- `AGENTS.md` and `.cursor/rules/`: development guidance for the current architecture. Globs must cover the owning packages, not only the MongoDB facade.

Consolidate useful material into these locations instead of creating backup READMEs at the root. Generate local release/test archives outside the repository. Downloads and checksums under `docs/public/` are intentional site assets; retain linked historical downloads and verify every affected link before removing an artifact.

## When to Update README.md

- **New public API**: document the function signature, purpose, and a usage example.
- **Changed behavior**: update relevant sections and code examples to reflect the change.
- **New feature**: add a new section in the appropriate position (see section order below).
- **Removed/deprecated feature**: mark as deprecated with migration guidance; do not silently remove.

## Section Order

Maintain this logical flow (define -> operate -> protect -> advanced):

1. Overview / Quick Start
2. Schema Definition (defining `GraphQLObjectType` with Simfinity)
3. Relationships (embedded, non-embedded, one-to-many)
4. Validations (field-level, type-level, declarative validators)
5. Queries (single entity, list, filtering, pagination, sorting)
6. Mutations (add, update, delete)
7. State Machines (states, transitions, actions)
8. Controllers & Lifecycle Hooks (onSaving, onSaved, onUpdating, onUpdated, onDelete)
9. Query Scope (row-level security via scope functions)
10. Authorization (Envelop auth plugin, permission maps, rule helpers)
11. Middlewares (runtime middleware via `use()`)
12. Plugins (count plugins, auth plugin re-export)
13. Custom Scalars (pre-built and factory functions)
14. Error Handling
15. Resources (links to example projects, API docs)

## Table of Contents

Update the Table of Contents whenever sections are added, removed, or reordered. Ensure every `##` and `###` heading has a corresponding ToC entry.

## Naming in Code Examples

Use Simfinity's auto-generated endpoint names consistently:

- **Queries**: `{plural}` for list (e.g., `series`), `{singular}` for single entity (e.g., `serie`)
- **Mutations**: `add{singular}` (e.g., `addserie`), `update{singular}` (e.g., `updateserie`), `delete{singular}` (e.g., `deleteserie`)
- **State actions**: `{actionName}_{singular}` (e.g., `approve_serie`)
- **Aggregation**: `{plural}_aggregate` (e.g., `series_aggregate`)

Names preserve the strings supplied to `connect()`; examples use lowercase. Authorization maps use the actual GraphQL root type names, `RootQueryType` and `Mutation`.

## Reference Project

Use `docs/guide/getting-started.md` for MongoDB and `docs/guide/postgresql.md` for PostgreSQL. The released starters linked from `docs/guide/databases.md` cover both adapters. The [Series Sample Project](https://github.com/simtlix/series-sample) is an additional MongoDB example; do not present it as a PostgreSQL example.

Feature the in-repository Barber example on the homepage and in links to a complete application. It is a complete MVP app with two backend implementations and one frontend. Describe its scopes, controllers, GraphQL IDs, MCP and generated PostgreSQL FKs without claiming native database APIs are interchangeable or that the demo is production-ready. Preserve source-commit provenance and the frontend license. Document generated schema output under ignored `generated/`, not as committed archives or historical API snapshots.

## Build and release consistency

Run `npm run docs:install` and `npm run docs:build` from the private root. The independent docs project reads the root `package.json` version and does not install a database adapter. See `docs/.vitepress/README.md` for theme, navigation, link and deployment conventions.

The release helper aligns the private root and all five package versions with exact internal dependencies. Package tarballs retain consumer-facing paths even when repository directories change. Publish documentation for a new release only after the matching npm versions are verified; repository/documentation-only edits do not require a new npm release.

## Style Guidelines

- Use fenced blocks with the appropriate language: `javascript`, `graphql`, `sh` or `sql`.
- Use actual Barber types and operation names for homepage examples; label simplified excerpts and illustrative data. Focused tutorials may retain the smaller Series domain (Serie, Season, Star, etc.).
- Show both the type definition and the resulting GraphQL operation where appropriate.