docs: clarify AI reference structure and streaming examples

[tonytlwu]

Product areas affected

Developer documentation: Fliplet.AI JavaScript reference, model catalog, chatbot and transcription guides, and app AI REST reference.

What does this PR do?

Clarifies the separation between API contracts, model information, app workflows and framework integration guidance. Makes the streaming return values and transport boundary explicit, and places rendering prerequisites before examples.

• Replace duplicated model catalogs and the full recording workflow in the main reference with links to their canonical pages, preserving existing public anchors.
• Document buffered and streaming return values separately; label the streaming sample as incremental console output and link to on-screen rendering guidance before the code.
• Identify chatbot and transcription examples as vanilla JavaScript browser examples; place framework state/lifecycle guidance before them and reuse Vue's existing general asynchronous-state reference.
• Correct heading hierarchy, restore the Conversation history heading, complete the main contents list and expose the REST streaming boundary before request examples.

The guidance describes general API and rendering mechanisms without prescribing a particular chatbot architecture. Complete guide examples and model catalog values are unchanged.

JIRA ticket

N/A

Result

• Main JavaScript reference reduced from 969 to 592 lines by removing duplicated content.
• All previous public anchors preserved; 66 internal fragment links checked.
• Frontmatter, cross-links, capabilities and namespace uniqueness validation passed.
• Console streaming example executed with controlled chunks, empty events and completion resolving without an assembled reply.
• 162 automated checks passed across the guide examples, Vue asynchronous-state regression, AI documentation discovery and agent-index suites. Checks cover progressive rendering before completion, safe formatting, request adapters, cancellation/retry, audio capture and Vue reactive-state updates.
• Compared the chatbot and transcription HTML/CSS/JSON/JavaScript blocks against master: executable examples are unchanged.
• git diff --check passed.

Checklist

• Ran existing automated coverage appropriate for this documentation change.
• Checked moved content, links and compatibility anchors.
• Reviewed accuracy, comprehension and specificity; detailed Vue reactivity behavior remains in the framework reference.

Deployment instructions

Publish through the existing developer-docs build after merge. Confirm the rendered pages, raw Markdown siblings and discovery indexes resolve, including links from the main reference to the split guides and model catalog.

Author concerns

• Independent subagent review was unavailable under the side conversation's restrictions; separate author accuracy and comprehension reviews were completed.
• Tests used locally available libraries: Marked 17.0.5, DOMPurify 3.4.16, Vue 3.5.25 and JSDOM 29.0.1. The guide's pinned CDN Marked version was not separately exercised.
• Live provider requests and fresh Studio-generated builds were not run for this documentation change.

Follow-up

The sidebar hierarchy correction is submitted separately in PR #314. It is not included in this merged PR.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T06:27:02.674962Z	e8d5d9d	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[cloudflare-workers-and-pages]

Deploying fliplet-cli with    Cloudflare Pages

Latest commit:	e8d5d9d
Status:	✅  Deploy successful!
Preview URL:	https://21ac5127.fliplet-cli.pages.dev
Branch Preview URL:	https://codex-ai-docs-structure.fliplet-cli.pages.dev

View logs