[#67] Added AI agents docs and a JSON Schema agent surface, with single-line doc formatting.#71
Merged
Merged
Conversation
This comment has been minimized.
This comment has been minimized.
|
🚀 Deployed on https://6a5db49ded3dbdb48436aa19--tui-docs.netlify.app |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe change adds an agent-oriented headless CLI example and documentation for ChangesAgent workflow and documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Sequence Diagram(s)sequenceDiagram
participant ConsumerCLI
participant agent-cli.php
participant Tui
participant Form
ConsumerCLI->>agent-cli.php: Run consumer help command
agent-cli.php->>Form: Build Produce order form
agent-cli.php->>Tui: Generate agentHelp()
Tui-->>agent-cli.php: Return driving guide
agent-cli.php-->>ConsumerCLI: Print consumer and agent help
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/ai-agents.mdx`:
- Around line 14-16: Update AgentHelp::generate() and the --agent discovery flow
to include allowed values for constrained select options, reusing
SchemaGenerator’s exposed option metadata or an equivalent agentHelp() field.
Ensure the generated guide identifies each select option’s valid values so
agents can construct non-default answers without guessing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: fbb8c4dc-d114-488a-a507-7b88de62bfc7
⛔ Files ignored due to path filters (1)
docs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (39)
docs/.prettierignoredocs/.prettierrc.jsondocs/content/ai-agents.mdxdocs/content/architecture.mdxdocs/content/configuration.mdxdocs/content/contributing.mdxdocs/content/discovery.mdxdocs/content/display-modes.mdxdocs/content/field-behaviour.mdxdocs/content/headless-collection.mdxdocs/content/index.mdxdocs/content/installation.mdxdocs/content/key-bindings.mdxdocs/content/panels.mdxdocs/content/playground.mdxdocs/content/self-describing-answers.mdxdocs/content/testing.mdxdocs/content/themes.mdxdocs/content/translations.mdxdocs/content/widgets/calendar.mdxdocs/content/widgets/confirm.mdxdocs/content/widgets/filepicker.mdxdocs/content/widgets/index.mdxdocs/content/widgets/number.mdxdocs/content/widgets/option-groups.mdxdocs/content/widgets/password.mdxdocs/content/widgets/pause.mdxdocs/content/widgets/reorder.mdxdocs/content/widgets/search.mdxdocs/content/widgets/select.mdxdocs/content/widgets/suggest.mdxdocs/content/widgets/text.mdxdocs/content/widgets/textarea.mdxdocs/content/widgets/toggle.mdxdocs/cspell.jsondocs/package.jsondocs/sidebars.jsplayground/05-headless/agent-cli.phpplayground/README.md
AlexSkrypnyk
force-pushed
the
feature/67-agent-docs
branch
from
July 20, 2026 02:09
b4ef383 to
44f07bc
Compare
This comment has been minimized.
This comment has been minimized.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #71 +/- ##
==========================================
+ Coverage 98.27% 98.29% +0.01%
==========================================
Files 98 98
Lines 3252 3276 +24
==========================================
+ Hits 3196 3220 +24
Misses 56 56 ☔ View full report in Codecov by Harness. |
This comment has been minimized.
This comment has been minimized.
… demo. Documents the self-describing surface for driving a form unattended - 'agentHelp()', 'schema()' and 'validate()' - and the consumer-side pattern of exposing it through a '--agent' CLI flag. Adds a runnable 'playground/05-headless/agent-cli.php' that parses '--agent', '--no-interaction' and '--prompts', links the new page into the Guides sidebar, and cross-links it from the introduction, headless-collection and playground pages.
Adds Prettier as a docs devDependency, configured with 'proseWrap: never' so prose and bullets stay on one line while the JSX image tags and embedded code are left untouched. Wires 'format' and 'format:check' scripts (the latter gating the docs test run) and reformats all existing content to the single-line style.
Single-lining a paragraph whose wrapped continuation began with '- ' let the fragment parse as a bullet list. Rejoined the asides in the architecture and option-groups pages into one paragraph each.
The flag with no following argument now writes a usage error and exits 2, rather than silently falling through to an interactive or default-driven run.
The '--agent' text guide names a 'select' but not its allowed values, so an agent could not build a valid non-default choice from it alone. A '--schema' flag now prints 'schema()' (which lists each option), and the AI agents page documents both flags in the discovery loop.
The playground demo no longer parses invented '--agent'/'--schema'/'--no-interaction'/'--prompts' flags - those belong to the consumer's own CLI, not the library. It now retrieves 'agentHelp()' and prints it inside the tool's own help output. The AI agents page and its cross-links reframe 'agentHelp()' and 'schema()' as text a consumer surfaces however it likes, not flags the library ships.
AlexSkrypnyk
force-pushed
the
feature/67-agent-docs
branch
from
July 20, 2026 04:46
59751f3 to
4894552
Compare
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/ai-agents.mdx`:
- Around line 40-42: Update the “Machine-readable schema and validation” section
to consistently call schema() output a machine-readable schema rather than JSON
Schema. Clarify that it returns the custom { "prompts": [...] } format and is
not a standards-compliant JSON Schema document, so consumers do not pass it to
incompatible validators.
In `@docs/content/architecture.mdx`:
- Line 60: Correct the misspelled “scolling” reference in the architecture
documentation to “scrolling,” without changing the surrounding explanation.
In `@docs/content/themes.mdx`:
- Line 32: Update the introductory sentence around the “Each theme below is
shown in its four looks” statement to scope the four-look claim to adaptive
themes only, while preserving the existing descriptions of dark/light palettes
and framed/unframed variants.
In `@docs/package.json`:
- Around line 45-46: Pin the prettier dependency in docs/package.json to the
exact 3.9.5 version by removing the caret range, and regenerate the
corresponding lockfile entries so they resolve and record 3.9.5 consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 65e93ca4-3c01-478e-bba9-365e4db18c3e
⛔ Files ignored due to path filters (1)
docs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (39)
docs/.prettierignoredocs/.prettierrc.jsondocs/content/ai-agents.mdxdocs/content/architecture.mdxdocs/content/configuration.mdxdocs/content/contributing.mdxdocs/content/discovery.mdxdocs/content/display-modes.mdxdocs/content/field-behaviour.mdxdocs/content/headless-collection.mdxdocs/content/index.mdxdocs/content/installation.mdxdocs/content/key-bindings.mdxdocs/content/panels.mdxdocs/content/playground.mdxdocs/content/self-describing-answers.mdxdocs/content/testing.mdxdocs/content/themes.mdxdocs/content/translations.mdxdocs/content/widgets/calendar.mdxdocs/content/widgets/confirm.mdxdocs/content/widgets/filepicker.mdxdocs/content/widgets/index.mdxdocs/content/widgets/number.mdxdocs/content/widgets/option-groups.mdxdocs/content/widgets/password.mdxdocs/content/widgets/pause.mdxdocs/content/widgets/reorder.mdxdocs/content/widgets/search.mdxdocs/content/widgets/select.mdxdocs/content/widgets/suggest.mdxdocs/content/widgets/text.mdxdocs/content/widgets/textarea.mdxdocs/content/widgets/toggle.mdxdocs/cspell.jsondocs/package.jsondocs/sidebars.jsplayground/05-headless/agent-cli.phpplayground/README.md
Pinned 'prettier' to '3.9.5' (no caret) so the 'format:check' CI gate cannot pull a later formatter and fail unchanged docs. Described 'schema()' output as structured JSON - a custom shape, not a standards-compliant JSON Schema document - and scoped the themes page "four looks" claim to adaptive themes.
This comment has been minimized.
This comment has been minimized.
'agentHelp()' now emits a JSON Schema (draft 2020-12) keyed by question id - each property carrying its type, allowed values (a select's 'enum', a number's bounds), title, description, default and the 'env' variable that sets it, with the resolution order as the root 'x-precedence'. It no longer names the consumer-owned CLI flags. Updated the AI agents page, the demo, the tests and the chrome catalog, which drops the now-unused instruction strings.
|
AlexSkrypnyk
changed the title
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.
Closes #67
Summary
Adds a new "AI agents" documentation page and reshapes the form's agent-facing surface around it.
agentHelp()now returns a JSON Schema (draft 2020-12) of the answers - each question keyed by id, carrying its type, allowed values,title/description,defaultand theenvvariable that sets it, with the resolution order as the rootx-precedence. It no longer names any CLI flags, because the flags an agent ultimately calls are the consumer's to define. A new runnableplayground/05-headless/agent-cli.phpdemonstrates the pattern by foldingagentHelp()into a consumer tool's own help output.Alongside this, installs Prettier as a
docs/devDependency configured for single-line prose and reformats all existingdocs/content/**/*.mdxfiles to that style, fixing two dash-aside paragraphs that the reformat caused to mis-render as stray bullet list items.Changes
Agent-facing surface (
agentHelp())src/Schema/AgentHelp.phpto emit a JSON Schema of the answers instead of a plain-text guide: standard keywords (type,enum,minimum/maximum,required,default,title,description) plus anenvkey per property and a rootx-precedence. Apausecarries no answer and is omitted.translations/tui.phpand updatedAgentHelpTest,TuiTestandTranslationRenderTestto assert on the schema.AI agents documentation page
docs/content/ai-agents.mdxto the "Guides" sidebar category indocs/sidebars.js, presentingagentHelp()(the answer schema),schema()(the fuller raw metadata) andvalidate(), and documenting the precedence andTUI_<ID>environment convention.docs/content/index.mdx,docs/content/headless-collection.mdxanddocs/content/playground.mdx; addedrequirednesstodocs/cspell.json.Consumer-help playground demo
playground/05-headless/agent-cli.php: a self-contained produce-order form that prints the consumer tool's own help withagentHelp()folded in under an "AI agents" heading. It takes no CLI options - the flags an agent uses are the consumer's own interface.playground/README.mdto list it among the05-headless/scripts.Prettier tooling and single-line prose enforcement
docs/.prettierrc.json(proseWrap: never, a highprintWidthso JSX image tags stay untouched,embeddedLanguageFormatting: off) anddocs/.prettierignore.prettier, pinned to an exact3.9.5, withformatandformat:checkscripts;format:checkgates the docstestscript alongsidejestandspellcheck.docs/content/**/*.mdxto single-line prose.Rendering and wording fixes
architecture.mdxandoption-groups.mdxthat the reformat turned into stray bullet lists; describedschema()output as structured JSON and scoped the themes "four looks" claim to adaptive themes.Before / After