Merge main into stable#3803
Merged
Merged
Conversation
## Summary Merges latest stable patches into main with a real merge commit so stable release tags remain reachable from main. This keeps `@next` prerelease version calculation ahead of the latest published stable release. ## Merge requirement This PR must be merged with GitHub's merge-commit option. Squash or rebase merging will discard stable ancestry and break `@next` version calculation again. ## Conflict handling Merge status: `clean`. Version-only release artifact conflicts are auto-resolved to keep stable's already-published versions. Non-version conflicts fail this workflow instead of committing conflict markers. --- _Auto-created by sync-patches workflow._ Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com> Co-authored-by: semantic-release-bot <semantic-release-bot@martynus.net> Co-authored-by: Caio Pizzol <caio@superdoc.dev> Source-PR: #3800 Closes #3800 Ported-From-Source-Repo: superdoc/orbit Ported-From-Source-Commit: 7302c2f935324898524bfd2edaaef349d3e1cd4b Ported-Public-Prefix: superdoc/public
* docs(ai): core preset action-surface reference + LLM tools overview rewrite (WIP) SD-3553 work in progress: architecture diagram, two-preset guide, 40-action reference, receipts/redlining, excludeActions, provider loops (OpenAI + Anthropic, Node + Python), token budget, error codes, troubleshooting, streaming guidance. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(examples): core-actions-agent runnable example (Node + Python) SD-3553: minimal headless agent on the core preset — 2 tools, receipts printed as streamable status lines, --tracked flag for redlining. Verified end-to-end: tracked insert lands as <w:ins> in the saved docx. Registered in examples manifest/README; docs nav gains the core-preset reference page; lockfile gains only the example's importer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): cover createAgentToolkit and MCP core preset Bring the pages up to the final 3316 surface: the one-call toolkit as the recommended setup (coherent tools/prompt/dispatch, Node + Python), its row in the SDK functions table, the same-list rule for standalone functions, and the MCP_PRESET=core serving path on both pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): move_range is direct-only after PR #346 Tracked mode on move_range now fails pre-mutation (block-range deletion cannot be tracked); the reference row and the always-direct list say so and point tracked moves at move_text. Also documents the reversed-range refusal. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): dedicated architecture + legacy preset pages; toolkit-first everywhere - New 'How it works' page: the pieces-fit diagram at full size plus the SDK ↔ CLI ↔ LLM mechanics — spawn/handshake/sessions/revisions and a complete tool-call round trip as sequence diagrams (was cramped into one overview section) - New legacy preset page: catalog, search/ref-expiry/mutations behaviors, migration mapping — with an explicit not-recommended-for- new-integrations callout (legacy stays the default for compatibility) - Overview slimmed: compact flow diagram linking to the full page, recommendation callout, quick starts rebuilt on createAgentToolkit; the old 'Legacy tool catalog' heading remains as an anchor-stable pointer (no page links broken, nav only gains entries) - Core preset: quick start via createAgentToolkit; 'Create custom actions' section marked coming soon (defineAction / SD-3317) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): nest preset pages under Agents > Presets Nav-only change — page URLs unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): sidebar reads 'Core preset (recommended)' Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(mcp): real architecture diagrams + core preset coverage on the overview Replaces the ASCII block with a proper flowchart (client ↔ stdio ↔ server internals ↔ disk) and a session-lifecycle sequence diagram, matching the agents architecture page style. Documents the two tool surfaces with the MCP_PRESET=core config snippet (recommended) and keeps the legacy tables as the default reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): preset-aware guidance across the Agents section Follows the pattern the major API vendors converged on for a recommended-vs-legacy surface split (OpenAI Responses/Chat Completions, Stripe PaymentIntents/Charges): the recommended surface is the default in every guide, legacy is contained with explicit status callouts and a migration path, and no per-page toggles. - best-practices: restructured into shared practices + two main preset sections (core playbook written around receipts/inspect-windows/ selector batching; legacy's search-then-edit guidance preserved intact) - integrations: core-first via createAgentToolkit end to end (steps, all three full examples, Bedrock); legacy delta as one callout - debugging: new 'read the receipt first' section; failure-mode tables split shared / core / legacy - eval-results: core revision-fidelity suite documented with current results (24/28, July 2026) alongside the legacy tool-quality suites All page URLs unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(mcp): note that the intent tools table is the legacy surface Points MCP_PRESET=core users at the core preset reference for its tool set instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): custom tools guide moves to the legacy page; overview keeps a pointer stub The step-by-step custom-tools walkthrough (provider schemas, dispatcher, merging) is legacy-flavored — it now lives on the legacy preset page. The overview's #creating-custom-tools anchor survives as a stub pointing at both presets: legacy's custom tools and core's 'Creating custom actions' (defineAction — coming soon), which is renamed for parity. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): restore eval-results to its published state Internal eval data stays internal — the page is byte-identical to main again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): snippet gate — every agents code block validated against the real SDK New check:ai-snippets script verifies all 43 code blocks across the four agents pages: jsonc action/selector/placement/inspect examples against the LIVE core-preset catalog schemas (action enum + declared arg keys), TypeScript snippets compiled with tsc against the SDK dist types (with conditional ambient context for intentional fragments), Python snippets parsed with imports checked against the package exports, and bash CLI lines replayed against the built CLI. Three snippets were genuinely broken for strict-TS copy-pasters and are fixed: untyped messages arrays (OpenAI + Anthropic loops) and untyped dispatch results now use the exported types / honest result shapes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): address PR #348 review — Bedrock parity, example hardening, gate coverage CodeRabbit findings, all seven fixed: - Bedrock Python migrated to create_agent_toolkit + core preset (was silently teaching legacy); both Bedrock loops now send the toolkit's bundled system prompt instead of a hardcoded string - Vercel conversion snippets fixed for the FLAT vercel dialect — t.function does not exist on those tools and would throw at runtime (pre-existing bug the widened gate caught) - example agent.mjs: --out without a value fails at parse time; the loop and save run inside try/finally so API errors or malformed tool calls can't leak the session/CLI process; JSON.parse feeds back as an error receipt - example agent.py: full parity with the Node twin (same guards, same structured {code, message} error shape, verification-failed suffix) - example README: preset wording matches the actual call shapes - snippet gate now also covers integrations.mdx and best-practices.mdx (65 blocks total) with legacy-action-aware JSON validation Example re-verified end-to-end: tracked insert lands as w:ins in the saved docx; --out guard confirmed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): snippet-gate hardening from PR #348 round 2 - explicit exit when the core catalog is missing the expected tools - aliased named imports (x as y) resolve to the exported name - fence regex accepts info strings (```lang Title) so titled blocks are validated instead of silently skipped Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(examples): valid manifest metadata for core-actions-agent Codex caught the examples validator rejecting the entry: 'agent-example' is not an allowed kind and subsection was missing. Now minimal-example / agents like its siblings; validate-examples-demos passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): Codex round-3 fixes — CLI flag casing, cache markers, gate mask Both verified against the built artifacts before fixing: - the preset commands accept only the camelCase --excludeActions flag (kebab --exclude-actions is rejected with Unknown option) — CLI tab updated to what actually parses - cache_control markers only appear with cache: true — the Anthropic provider snippet now passes it and the comment states the condition - the snippet gate's bash check ran with --help appended, which short-circuits before flag validation and masked exactly this class; it now runs the real invocation and fails on unknown-option / INVALID_ARGUMENT while tolerating session preconditions Note for follow-up: --excludeActions is the CLI's only camelCase flag (everything else is kebab-case) — worth accepting both spellings in the CLI parser eventually. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): document the real cacheStrategy union values Codex verified against the SDK contract: the values are disabled | explicit | automatic | unsupported (confirmed live: openai/no-cache → disabled, anthropic + cache:true → explicit) — not the invented none/anthropic-ephemeral, which no branch could ever match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(ai): mark the core preset as beta * docs(ai): address final review round — 10-tool catalog, snippet gate in CI, provider prompt caching --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Note: this ports only the public subtree changes from a mixed source commit (19 public paths, 1 non-public path ignored). Ported-From-Source-Repo: superdoc/orbit Ported-From-Source-Commit: b9165a37070487f320735f13ed98894f2ce8533d Ported-Public-Prefix: superdoc/public
Contributor
|
📖 Docs preview: https://superdoc-merge-main-into-stable-2026-07-06.mintlify.app |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ef7abb912b
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| - name: Build CLI | ||
| run: pnpm --prefix apps/cli run build | ||
|
|
||
| - name: Check AI Snippets |
There was a problem hiding this comment.
This new gate validates docs snippets against the built Node SDK and CLI, but the workflow is still path-filtered only to docs/superdoc/editor/document-api files at the top of this YAML. A PR that changes packages/sdk/** or apps/cli/** can break createAgentToolkit, CLI flags, or tool schemas without running this check at all, so the gate misses the exact drift it was added to catch; add the SDK/CLI paths to on.pull_request.paths.
Useful? React with 👍 / 👎.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
Author
|
🎉 This PR is included in superdoc-cli v0.21.1 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in superdoc-sdk v1.20.1 |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/mcp v0.16.1 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in superdoc v1.44.1 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/react v1.15.1 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in vscode-ext v2.16.1 |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/fonts v0.2.0 The release is available on GitHub release |
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
3 participants
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
merge/main-into-stable-2026-07-06fromstablemaininto the candidate branchstableAuto-created by promote-stable workflow.