Guided route first. Shelves second.
Keep the docs inside a guided route, not a blob dump.
This route exists so visitors can learn the product in the same order a reviewer would: guided path first, proof second, operator desk third, and the longer shelves only after the first-screen story is clear.
Discovery order
README storefront
Explain what the product is, who it is for, and where to go next without dropping visitors into source files.
Front door
Introduce the product sentence, guided paths, builder order, and the shortest trust ladder.
First-minute walkthrough
Give newcomers the shortest recommended route from front door to proof, workbench, and one real repo-owned command.
Read the product in this order.
The goal is simple: guided route first, proof second, operator context third, then the longer shelves and machine-readable surfaces. That keeps discovery from feeling like a source-code scavenger hunt.
README storefront
Explain what the product is, who it is for, and where to go next without dropping visitors into source files.
Front door
Introduce the product sentence, guided paths, builder order, and the shortest trust ladder.
First-minute walkthrough
Give newcomers the shortest recommended route from front door to proof, workbench, and one real repo-owned command.
Proof desk
Show what the repo already proves, what still needs human judgment, and which next route makes sense.
Operator desk
Help an operator decide the next move once the proof meaning is already clear, without pretending to be a live control plane.
Docs discovery route
Keep README, proof FAQ, evaluator guidance, release shelf, and ecosystem ledgers inside one in-app discovery route instead of dumping visitors into GitHub blob pages.
Compare
Explain why OpenUI fits repo-aware UI shipping better than hosted builders or generic coding-agent traffic when category fit is still the open question.
Machine-readable discovery
Expose the shortest English-first route, builder, and boundary summary for LLM, search, and tooling consumers.
Frontdoor JSON
Expose routes, bindings, builder order, public bundle pointers, and operator-only follow-through in one JSON surface.
Manifest and crawl metadata
Expose install metadata plus manifest, sitemap, and robots hints for browsers and crawler-adjacent tooling.
Ask one reviewer question first, then open one shelf.
This docs hub should behave like a concierge desk. Start from the question you are holding, then open the one route that best answers it.
What is this product really promising right now?
You want the shortest human-readable path from front door to one real prompt-to-workspace workflow claim.
What counts as proof versus human judgment?
You are evaluating review language, proof semantics, and the operator-only tail before making a trust call.
Which doc shelf should I open next?
You already understand the shape and now need the exact shelf for README, evaluator checklist, release bundle, or ecosystem lane.
The human-readable shelves
The shelves should feel like curated exhibits, not a warehouse. Each one answers one clear question and hands you forward deliberately.
First-minute walkthrough
Use this when you want the shortest guided route from front door to proof, workbench, and one real command before you branch into longer docs.
Proof FAQ
Use the proof desk when you need the meaning of proof, review, acceptance, and the boundaries between repo-owned evidence and human judgment.
README storefront
Open the README after the route is already clear and you want the GitHub-facing storefront wording in its canonical home.
Evaluator checklist
Use this when you want the shortest decision sheet instead of the full narrative.
Public surface guide
Use this when the question becomes how README, routes, release assets, and GitHub storefront should keep telling one story.
Release proof shelf
Use this when you need the public bundle and release shelf explained in one place.
External activation ledger
Use this when you want the storefront and GitHub control split written down as one ledger.
Ecosystem ledger
Use this when you want the current Codex / Claude bundle, OpenClaw public-ready bundle, Skills starter, and supporting SDK / hosted lanes in one bounded view.
Public Skills / plugin-like ledger
Use this when you want the repo-owned starter-pack packaging and plugin-like install surface split written down clearly.
SDK / hosted API ledger
Use this when you want the supporting / parked SDK package, hosted runtime, proof path, and operator-only tail in one place.
Public distribution bundle
Use this when you want the package-ready Codex / Claude bundle, the OpenClaw public-ready bundle, and the repo-owned install/proof/troubleshooting artifacts in one place.
What belongs on the public shelf
This is the part that should feel installable, shareable, and reviewable without leaking settings-level or operator-only control.
Visual proof assets
- - openui-mcp-studio-demo.gif
- - openui-mcp-studio-workbench.png
- - openui-mcp-studio-comparison.png
- - openui-mcp-studio-trust-stack.png
- - openui-mcp-studio-use-cases.png
- - openui-mcp-studio-visitor-paths.png
- - openui-mcp-studio-social-preview.png
Narrative docs
- - README.md
- - docs/discovery-surfaces.md
- - docs/proof-and-faq.md
- - docs/evaluator-checklist.md
- - docs/public-surface-guide.md
- - docs/release-template.md
- - examples/public-distribution/README.md
Plugin-grade bundles
- - .claude-plugin/marketplace.json
- - examples/codex/marketplace.sample.json
- - plugins/openui-workspace-delivery/.claude-plugin/plugin.json
- - plugins/openui-codex-delivery/.codex-plugin/plugin.json
Machine-readable discovery
- - /llms.txt
- - /api/frontdoor
- - /manifest.webmanifest
- - /sitemap.xml
- - /robots.txt
What still stays settings-level
Think of this like the back office. It matters, but it should not invade the front shelf or blur what the public product is today.
GitHub Homepage
Attach a real landing page or docs site only when that URL is verified live. Leaving Homepage blank is more honest than pointing at an unverified or misleading site.
GitHub Social Preview
Uploading or selecting the social preview image remains a GitHub settings action. Repo assets can prepare the image, but they cannot prove the setting is live by themselves.
Published release proof bundle
Draft releases and local assets can prepare the bundle, but publishing the release and refreshing attached assets is still a remote mutation step.
Discussion seeding and curation
Enabling Discussions is only the start. Keeping starter threads visible and current remains a GitHub/operator task.
Domain, DNS, and TLS for OneClickUI.ai
The repo can prepare the front-door story, but a real domain cutover still depends on external deployment, DNS, and certificate ownership.
Current versus bounded ecosystem surfaces
This section should tell a reviewer what is already real, what is intentionally bounded, and which lanes are only parked for later.
Public Skills starter kit
Current truth now includes an installable public starter package while staying explicitly short of a marketplace or hosted Skills runtime.
Audience: maintainers and builders drafting future skill-shaped integrations
Best for: installable starter contracts, manifests, and examples that stay honest about the current builder surface
Read when: Open this after the main MCP, OpenAPI, and workflow surfaces are clear and you need a formal public starter contract.
Not for: claiming a marketplace listing, hosted Skills runtime, or vendor-approved plugin catalog
Codex and Claude plugin-grade public package
The strongest current packaging is a repo-owned official-surface-ready package; official directory or marketplace publication is still a separate claim.
Audience: Codex and Claude Code users who install local MCP servers
Best for: configuration snippets, starter bundles, proof loop, and discovery metadata that make local MCP installation feel productized
Read when: Open this when the next question is how to add OpenUI to Codex or Claude Code without inventing an official plugin marketplace story.
Not for: claiming a Codex marketplace item or a published Claude Code plugin before those artifacts exist
OpenClaw public-ready bundle
The repo now ships a ClawHub-facing bundle at the artifact layer, and the page is listed live, but the current moderation label still reads suspicious.llm_suspicious.
Audience: OpenClaw-side builders and operators who need a discoverable repo-owned install and proof path
Best for: starter config, proof loop, and machine-readable discovery artifacts while the live ClawHub page stays visible but still under moderation warning
Read when: Open this when the next question is how to present OpenUI honestly to OpenClaw-side users without pretending the listed-live page is trust-cleared approval.
Not for: claiming an official OpenClaw runtime, trust-cleared ClawHub approval, or vendor approval
Hosted client SDK
Current truth still includes a real @openui/sdk package with install, import, and proof paths, but it is now a supporting or parked lane.
Audience: developers evaluating future thin-client or package surfaces
Best for: installing a thin HTTP client for the self-hosted OpenUI Hosted API with explicit auth and boundary semantics
Read when: Open this when the question becomes how to call the self-hosted HTTP surface from code.
Not for: claiming registry publication, front-door primary status, or replacing the local stdio MCP runtime
Self-hosted OpenUI Hosted API
Current truth still includes a self-hosted OpenUI Hosted API runtime with auth, rate limiting, observability, and proof paths, but it is now a supporting or parked lane.
Audience: adapter authors and future hosted-surface planners
Best for: running an authenticated HTTP surface with discovery, workflow, and tool endpoints around the current repo-owned runtime
Read when: Open this after the compatibility bridge semantics are clear and you need a real self-hosted service/runtime surface.
Not for: claiming a managed SaaS deployment, front-door primary status, control plane, or remote write surface