Contributing to developer documentation

This is the contributor checklist for adding or updating Fliplet developer documentation. Lint errors in the build pipeline link back to this page, so what’s here is what CI is checking for.

The reference reading underneath this checklist is docs/CLAUDE.md — the canonical schema for frontmatter, the build pipeline, and the rules for what NOT to add. This page is the human-facing walkthrough.

Adding a new package doc

When you add a new fliplet-* package, follow this 10-step checklist:

Start from the template. Copy _templates/doc-template.md (or _templates/js-api.md for a JavaScript API reference) to docs/API/fliplet-<package>.md. Filename must match the npm package name, prefixed with fliplet-.
Set the required frontmatter. Every doc needs:
- title: matching the H1 with backticks stripped — the Jekyll layout prints title: as literal text in the page header, so backticks would render as \Fliplet.X` instead of formatted code. Body H1 keeps the backticks for code formatting; frontmatter title: does not. Example: title: Fliplet.Payments in frontmatter; # Fliplet.Payments ` in body. Lint enforces this.
- description: 1–2 sentences, ≤160 chars, standalone
- type: one of api-reference / guide / how-to / concept / tutorial / reference / integration
- tags: first tag is the canonical area (js-api, rest-api, etc.), then 1–5 specifics, lowercase dash-separated
- v3_relevant: true (default; set false only for clearly V1-only content)
- deprecated: false (default)
Add capabilities: — 6–12 lowercase keywords. Describe what this API does in user-facing terms (“stripe”, “barcode scan”, “send email”), including named third-party services where relevant. The V3 AI builder uses these to anchor user-described capabilities to your API without a search_libraries round-trip. Examples:
```
capabilities: [stripe, checkout, subscription, recurring billing, refund, webhook, customer portal, payment intent, ecommerce]
capabilities: [barcode scan, qr code, ean, upc, code 128, code 39, camera scanner]
```
Add category: — pick exactly one. Allowed values (see docs/v3/capabilities for what’s in each):
- data — persistence, query, real-time, encryption, offline storage
- identity — auth, sessions, biometrics, profile, orgs, tokens
- communications — email / SMS / push, chat, websockets
- media — upload, transform, audio, scanning, barcode
- native — native-only APIs (Cordova bridge)
- commerce — payments, subscriptions, app store / play store metadata
- integration — REST API, OAuth, webhooks
- automation — AI, app actions runtime, hooks, scheduling
- analytics — event tracking, custom metrics, page views (user behaviour)
- observability — logs, error capture, audit trails (app health — distinct from analytics)
- framework — runtime, registry, environment, widget, locale, dynamic loading (framework-level glue)
- navigation — screen navigation, URL routing, screen listing
- meta — residual catch-all (app metadata, encoding helpers, error parsing, common functions). Keep small — if meta exceeds 6-8 entries, propose a split rather than letting it absorb new entries
Pick the dominant facet. A cross-cutting API like Fliplet.Notifications (communications + native) picks communications because that’s how end-users describe what it does.
Set exclude_from_v3_catalog: true ONLY if the package shouldn’t appear in the V3 builder’s anchored prompt. Cases where exclusion is correct:
- The package is a UI primitive replaced by the V3 design system (fliplet-ui-*, fliplet-table, fliplet-modal)
- The package is deprecated, V1-only, or a redirect stub
- The doc is meta (overview pages, framework docs)
Most installable docs SHOULD be in the catalog. Add a one-line notes: field too if the exclusion needs context.
Write the intro paragraph between H1 and the first H2. The llms.txt extractor and the agent-skills/SKILL.md generators both depend on prose between the title and the first subheading. Don’t jump straight from # Title into ## Subheading.
Document each public method with a runnable code example. Code examples must work — the V3 AI builder follows the docs literally. Verify signatures against ~/Sites/fliplet/api/public/assets/<package>/ source before publishing.
Verify the doc against source. For JS APIs, cross-check every method name, parameter list, and return shape against the package source. If a method exists in source but isn’t documented, decide whether it’s public-API-worthy (document) or internal (omit). Don’t document methods that don’t exist.
Run --strict locally. From docs/:
```
node bin/build-agent-indexes.mjs --strict
```
Fix any errors before opening a PR. The lint will catch:
- Empty/non-lowercase/duplicate capabilities[] tokens
- Tokens >40 chars (likely a missing comma)
- Tokens that start with [ (bracket-mismatch in your YAML flow list)
- Missing category: or values outside the allowed enum
- Standard frontmatter violations from validateFrontmatter
- Broken internal cross-links (from validateCrossLinks — see “Internal links” below)
Open the PR. CF Pages will build a branch preview. Visit the preview URL to confirm:
- Your doc renders with the right layout
- It appears under the correct section on /v3/capabilities (auto-generated index)
- The .well-known/llms-v3-libraries.json diff in the PR shows your new entry with the right category, capabilities, and preloaded flag

Updating an existing doc

The same rules apply with two adjustments:

Don’t change title: casually — the V3 AI builder embeds the namespace title in its system prompt; renaming silently shifts what the agent recognises.
Don’t reorder capabilities[] — the field is hashed downstream; reordering = diff churn without semantic change.

Internal links

Write internal cross-links the natural way — directory-relative to the target’s .md, exactly as Jekyll and the published site resolve them:

[joins](datasources/joins) — bare, relative to the current doc’s directory
[routing](../routing) — parent-relative
[guides](/Quickstart) — root-absolute
A full https://developers.fliplet.com/API/...md URL also works

--strict runs validateCrossLinks, which resolves each link the way CF Pages serves clean URLs (.md/.html/extensionless all map to the .md source) and fails the build if the target file doesn’t exist — that’s how link rot is caught at review time instead of shipping a dead link. External links (openai, github, help.fliplet.com, api.fliplet.com, …) and asset links (.png, .txt, …) are left alone.

Two escape hatches for a deliberate exception (e.g. a forward-reference to a doc landing in a later PR):

Inline: put  anywhere on the link’s line.
Whole-target: add it to LINK_ALLOWLIST in bin/build-agent-indexes.mjs.

Note the asymmetry: AI skills (src/v3/ai/skills/, Studio repo) auto-resolve relative sibling links at load time and silently drop unresolvable ones, whereas these docs fail the build on a broken link. They differ on purpose — the skills bundle is fully in memory at load, the docs validator runs statically over the file tree. Don’t assume one’s behaviour from the other.

Where does each thing live?

docs/API/fliplet-*.md — installable packages (catalog: preloaded: false)
docs/API/core/*.md — ambient namespaces preloaded via fliplet-core (catalog: preloaded: true)
docs/API/components/*.md — components framework (not in V3 catalog)
docs/API/helpers/*.md — helpers framework (not in V3 catalog)
docs/REST-API/*.md — REST endpoints (not in V3 catalog)
docs/v3/*.md — V3-specific generated pages (e.g. capabilities.md — do not hand-edit)

What gets generated, what doesn’t

bin/build-agent-indexes.mjs runs on every CF Pages deploy and regenerates these on every push:

.well-known/llms.txt — per-page index
.well-known/llms-full.txt — concatenated content
.well-known/llms-v3-libraries.json — the V3 library catalog
.well-known/agent-skills/* — cluster-shaped skill registry
v3/capabilities.md — the auto-generated capabilities index

You can edit any of these manually but the next build will overwrite. The single source of truth is your doc’s frontmatter + body.