Skip to content

DEV-2386: Regenerate the V3 agent indexes so Chat carries its V3 recipe - #328

Merged
ysolodka merged 2 commits into
masterfrom
fix/DEV-2386-v3-catalog-regen
Nov 17, 2026
Merged

ysolodka merged 2 commits into
masterfrom
fix/DEV-2386-v3-catalog-regen

Conversation

@farhantariq12b

@farhantariq12b farhantariq12b commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

JIRA Issue

https://weboo.atlassian.net/browse/DEV-2386

Upstream half of QA defect FUNC-004 (NO-GO, 2026-11-12). Paired with fliplet-studio PR #9164 — this one must merge and publish first (see Sequencing).

Why this is needed

PR #327 corrected the frontmatter of docs/API/fliplet-chat.md to document the V3 path, but the generated artifacts were never rebuilt. So the published catalogue kept telling the V3 AI builder "V3 apps can't use Fliplet.Chat: build messaging on the app's own data sources". fliplet-studio refetches that published manifest at CI build time, so the stale text reached the builder fleet-wide and QA returned DEV-2386 NO-GO.

Corroborating evidence that the artifacts were never regenerated together: the committed llms-full.txt already carried the Chat capabilities line (with the stale text) while the committed v3/capabilities.md did not — the two were mutually inconsistent.

Summary

  • Regenerated .well-known/llms-v3-libraries.json, llms.txt, llms-full.txt, agent-skills/fliplet-js-api/SKILL.md and agent-skills/index.json from the existing frontmatter with npm run build:agent-indexes. No file was hand-edited.
  • Removed a hardcoded exclusion in docs/bin/emitters.mjs that skipped API/fliplet-chat.md when emitting v3/capabilities.md. Chat now appears under ## Communications, so the published index of "every JS API surface available to V3 apps" finally includes it.
  • Flipped the matching test, which asserted Chat must not be emitted.

⚠️ This reverses a deliberate decision — needs @ianbroom's sign-off

The exclusion came from 080f5b7a "Exclude V2 Chat from generated V3 capabilities" (2026-11-03) and its test 24b35c42, made under the pre-DEV-2386 assumption that V3 apps cannot use Fliplet.Chat. That premise no longer holds: PR #327 documented the V3 connect({ dataSourceId }) + login({}) path.

One consequence worth knowing: with the code-level skip gone, v3/capabilities.md is derived purely from frontmatter, so the only supported way to exclude a doc is exclude_from_v3_catalog: true in its frontmatter. That is the right direction — it makes docs/CLAUDE.md:306-311's claim that the page "cannot drift" true for the first time — but it does remove the escape hatch that commit used.

Chat entry, before → after

  • description: "Chat API for V2 apps with a Chat component. Not available to V3 apps: build messaging on the app's own data sources." → "Chat API for one-to-one chats, group chats and public channels. V2 apps use a Chat component; V3 apps connect with a login data source."
  • notes: "V3 apps can't use Fliplet.Chat: its server routes need a Chat component on a screen…" → "V3 apps: call Fliplet.Chat.connect({ dataSourceId }) with a data source that has a login, then await chat.login({})… Message encryption is not access control."

Testing

  • npm run test:unit: 228/228 passing
  • npm run check:docs (--strict): exit 0
  • Regeneration is byte-stable: run twice, the only difference is the generatedAt timestamp
  • All 46 catalogue entries compared against base — only fliplet-chat (index 4) differs; no unrelated catalogue churn
  • Chat entry verified strict-equal to the docs/API/fliplet-chat.md frontmatter
  • Repo-wide grep for "Not available to V3", "can't use Fliplet.Chat" and "build messaging on the app's own" across .well-known, v3 and bin: 0 hits

Testing notes

  1. Open https://developers.fliplet.com/v3/capabilities (after deploy) and look under Communications → Fliplet.Chat should be listed, with wording that says V3 apps connect with a login data source.
  2. Open the Fliplet.Chat page itself → the description and the Security and identity section should agree with it: V2 apps use a Chat component, V3 apps sign in through a data source.
  3. Search that page for "not available to V3" or "can't use" → there should be no such claim anywhere.

Risk Assessment

  • Risk Level: LOW — documentation and generated indexes only; no runtime code
  • Files Modified: 8 (6 generated, 1 emitter, 1 test)
  • Type: Bug fix

Sequencing

This must be merged and published to developers.fliplet.com before fliplet-studio PR #9164 reaches a staging build, because Studio's prebuild refetches this manifest and overwrites its committed copy. After deploying, confirm by running npm run fetch-fliplet-apis in fliplet-studio and checking the diff is empty — do not infer publication from the merge.

Known gap, deferred by decision: DEV-2778

Nothing in CI compares the generated artifacts against the doc frontmatter, which is exactly how this defect shipped. A guard was built and then removed from this branch because it carried its own problems (its paths filter did not cover the generated files, and it would have obliged every docs author to commit regenerated artifacts while CONTRIBUTING.md says the opposite). It is tracked with the full diagnosis in DEV-2778. Until that ships, a doc edit can still land without regenerated artifacts.

🤖 Generated with Claude Code

farhantariq12b and others added 2 commits November 12, 2026 20:47
…et.Chat V3 recipe

Generated artifacts still held the pre-PR #327 text saying V3 apps cannot use Fliplet.Chat.
Regenerated with docs/bin/build-agent-indexes.mjs; no hand edits.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Remove the emitters.mjs skip that hid Fliplet.Chat from v3/capabilities.md (its premise,
that V3 apps cannot use Chat, no longer holds), flip its unit test, and regenerate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying fliplet-cli with  Cloudflare Pages  Cloudflare Pages

Latest commit: 45d6e16
Status: ✅  Deploy successful!
Preview URL: https://9e4984d0.fliplet-cli.pages.dev
Branch Preview URL: https://fix-dev-2386-v3-catalog-rege.fliplet-cli.pages.dev

View logs

@ysolodka
ysolodka merged commit d5914dc into master Nov 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants