feat(docs): V3 library catalog manifest + 5 new dev docs#254
Merged
feat(docs): V3 library catalog manifest + 5 new dev docs#254
Conversation
Adds emitV3LibraryCatalog() to bin/build-agent-indexes.mjs which filters API/fliplet-*.md docs (skipping exclude_from_v3_catalog: true) and emits .well-known/llms-v3-libraries.json — the agent-facing catalog consumed by Fliplet Studio's V3 builder via search_libraries. Schema is intentionally minimal: package, title, description, docUrl. Title and description reuse the existing build-pipeline extraction (frontmatter or H1 + first paragraph). Package defaults to URL slug with optional package: frontmatter override. Adds bin/check-v3-catalog-drift.mjs (npm run check:v3-catalog) that validates the manifest against the live /v1/widgets/assets: - Errors on catalog packages not present in the live API - Warns on first-party assets without a V3 catalog entry Tests: 11 new test cases for emitV3LibraryCatalog and deriveV3Package; 87 total now passing. Plan: studio/docs/plans/v3-library-catalog.md (Phase 4). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Curates the V3 library catalog consumed by Fliplet Studio's V3 builder
via search_libraries. The catalog ships with 14 packages — anything AI
cannot replicate natively in V3 (native bridges, server-coordinated
flows, secure data primitives, realtime, audio).
26 docs flagged exclude_from_v3_catalog: true. Reasons grouped:
- Bucket 1 (15) — covered by V3 design system / AI-native generation
(table, themes, helper, csv, gamify, ui-* inputs, audio-player)
- Bucket 2 (2) — subsumed by another catalog entry
(content, profile-content — DataSources covers it)
- Bucket 3 (2) — preloaded ambient (core, page)
- Bucket 4 (4) — non-installable pattern docs (toast, ui-actions, ui)
- Bucket 5 (3) — deprecated / scheduled-for-removal
(database, encryption.deprecated, oauth2)
oauth2 excluded because the third-party-IdP path relies on an open
proxy slated for deprecation; preempts steering AI builds onto a
removed path.
5 new V3-essential docs written via /fl-write-dev-doc (source-verified
against ~/Sites/fliplet/api/public/assets/<pkg>/):
- fliplet-chat.md (506 lines) — realtime chat/messaging
- fliplet-security.md (210 lines) — encrypted device storage
(clearly differentiated from fliplet-encryption to disambiguate
the V3 catalog "encrypt" query)
- fliplet-socket.md (251 lines) — realtime websocket primitive
with server URL discovery + auto-auth + transport fallback
- fliplet-tokens.md (130 lines) — app API tokens
- fliplet-app-submissions.md (225 lines) — App Store / Google Play
submission metadata
fliplet-page.md frontmatter corrected to v3_relevant: false (red-team
verification confirmed V2-only; V3 SPA apps use Fliplet.Router, not
Fliplet.Page).
Plan + curation: studio/docs/plans/v3-library-catalog{,-curation}.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying fliplet-cli with
|
| Latest commit: |
a98fe95
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://2b3d8a8d.fliplet-cli.pages.dev |
| Branch Preview URL: | https://v3-library-catalog-manifest.fliplet-cli.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
emitV3LibraryCatalog()tobin/build-agent-indexes.mjswhich emits.well-known/llms-v3-libraries.json— the V3-curated agent-facing library catalog consumed by Fliplet Studio's V3 builder viasearch_librariesexclude_from_v3_catalog: true(UI primitives covered by the V3 design system, AI-replicable libraries, deprecated packages, preloaded ambient runtime)fliplet-chat,fliplet-security,fliplet-socket,fliplet-tokens,fliplet-app-submissionsbin/check-v3-catalog-drift.mjs(npm run check:v3-catalog) — validates the catalog against the live/v1/widgets/assets; errors on missing packages, warns on first-party assets without a catalog entryfliplet-page.mdfrontmatter tov3_relevant: false(red-team verification confirmed V2-only — V3 SPA apps useFliplet.Router, notFliplet.Page)Why
The Fliplet Studio V3 AI builder's
search_librariestool currently fetches/v1/widgets/assets(sourced fromfliplet/api/config/common/assets.json), which conflates runtime contract with agent-facing catalog and is hard to maintain. This PR moves the agent-facing catalog into the developer docs, where descriptions can be tuned for AI ranking and curation lives close to authoritative API documentation.assets.jsonremains the runtime contract (file lists, dependency graph, version pinning, anddependencyDetector'sprovidesregex source — unchanged in this scope).Plan + curation in the studio repo:
studio/docs/plans/v3-library-catalog.mdstudio/docs/plans/v3-library-catalog-curation.mdCatalog (14 packages)
fliplet-app-submissions,fliplet-audio,fliplet-barcode,fliplet-chat,fliplet-communicate,fliplet-datasources,fliplet-encryption,fliplet-media,fliplet-notifications,fliplet-payments,fliplet-security,fliplet-session,fliplet-socket,fliplet-tokensThe catalog is intentionally lean — anything that V3's design system covers, or that AI generates well natively (toasts, tables, date pickers, simple typeaheads, theme primitives), is excluded. The
descriptionfield in the new tool description tells the agent: "if a typical UI input/widget/table/picker returns nothing, that is BY DESIGN. Generate it natively."Test plan
npm run test:unit— 87 tests pass (54 existing + 33 new foremitV3LibraryCatalog+ tests added by other recent changes)npm run check:docs(strict frontmatter validation) — cleannpm run build:agent-indexes— emits 14 entries tollms-v3-libraries.jsonmatching the curationnpm run check:v3-catalog— 0 errors, 27 warnings (all warnings are intentional curation exclusions:fliplet-table,fliplet-themes,fliplet-helper, etc.)https://<preview>.pages.dev/.well-known/llms-v3-libraries.jsoncorrectlysearchLibraries.jsrewrite (separate Studio PR, gated on this merging)🤖 Generated with Claude Code