docs: restructure and rewrite for current AskUI product by philipph-askui · Pull Request #6 · askui/docs-rewrite

philipph-askui · 2026-07-09T12:47:23Z

Summary

New quickstart guide — register, install, first run in under 10 minutes
Rewritten home page — product overview, how it works, why AskUI, where to start
Corrected install story — CLI ships with Desktop installer; no Python runtime (pure C#); standalone AgentOS installer coming soon
Legacy section — Python SDK and TypeScript SDK pages with strong deprecation notices and migration pointers
AgentOS restructured — "How-to guides" renamed to "Deployment"; Troubleshooting elevated to top-level AgentOS page; new CI examples page (GitHub Actions, GitLab CI, Azure DevOps)
New Support section — FAQ, Get help (with upcoming AskUI Diagnostic Tool callout), index
New Reference pages — environment variables, network requirements, glossary
Removed internal pages — workspace API and inference API removed from Reference
New Account & Billing pages — members (roles, invite flow) and usage dashboard
New uninstall guide — Windows (Add/Remove Programs + silent MSI) and macOS
OpenAI-compatible BYOM — marked experimental with no-support disclaimer
Cleanup — all Discord links removed, all scaffold/placeholder notes removed

- Add prominent quickstart guide (< 10 min: register, install, first run) - Rewrite home page with product overview, how it works, and why AskUI - Remove all Python/legacy SDK references from main docs; add Legacy section for Python SDK and TypeScript SDK with migration guidance - Correct CLI and AgentOS install story: CLI ships with Desktop installer, standalone AgentOS installer coming soon, no Python runtime (pure C#) - Restructure AgentOS nav: rename "How-to guides" to "Deployment" section, elevate Troubleshooting to top-level AgentOS page - Add CI examples page (GitHub Actions, GitLab CI, Azure DevOps) - Add Support section: FAQ, Get help (with diagnostic tool callout), index - Add Reference pages: environment variables, network requirements, glossary - Remove internal-only workspace API and inference API pages - Add Account & Billing pages: members (roles/invite), usage dashboard - Add uninstall guide (Windows + macOS) - Mark OpenAI-compatible BYOM providers as experimental with no support - Remove Discord links throughout; remove all scaffold placeholder notes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Remove the secrets/ folder from all scaffold/structure lists (quickstart, first-run, project-structure, glossary) since the app no longer scaffolds it - Reword credentials guidance to a generic local credentials file instead of secrets/credentials.txt - Rework the landing page hero: new breadth-led headline and subhead, larger type, and a subtle brand-tinted glow Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Split monolithic FAQ into subpages under faq/ (General, Getting started, Technical, Runs & reports, Pricing & licensing, Use cases) - Move troubleshooting-oriented FAQ content into troubleshooting.mdx: new sections for Connection & session issues, Agent behavior, and Performance & cost - Move troubleshooting.mdx from agentos/ to support/; update all inbound links across service.mdx, get-help.mdx, environment-variables, network-requirements, and support/index - Absorb IT firewall and admin-rights questions into FAQ Technical page - FAQ index now points to Troubleshooting for error/symptom queries Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Move prompting-best-practices and system-prompt from using-askui-desktop/ to guides/ - Add new writing-tests guide - Refactor guides into three focused pages: what-goes-where, system-prompt quality, test quality - Shorten agents-and-prompts.mdx to show only real defaults, cross-reference guides - Update all inbound links across quickstart, first-run, project-structure, troubleshooting Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- run-report: add full coverage of markdown reports, summary report, and HTML report; demote live run viewer to a brief section - agents-and-prompts: clarify scratchpad use case, rename per-folder to per-suite, use suite terminology consistently - project-structure: tighten description, note subsuites as subfolders - model-providers: remove trailing Next cards section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- guides/index: convert Coming soon bullet list to Cards - guides/system-prompt: soften error-discipline framing, add naming conventions bullet to UI information, retitle report format section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Create content/docs/troubleshooting/ with index + 8 subpages: connection-sessions, agent-behavior, performance-cost, agentos-service, proxy-ssl, run-failures, model-providers, licensing - Add troubleshooting to top-level meta.json nav - Remove troubleshooting from support/meta.json and delete the old support/troubleshooting.mdx - Update all inbound links across faq/, support/, agentos/, reference/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

remarkMermaid rewrites ```mermaid fences to a <Mermaid> component that renders client-side (dynamic import, theme-aware via next-themes). Registered globally in the MDX component map. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- quickstart: 4-step flow (download w/ direct CDN links, sign in, onboarding wizard, first local run from the default template) - install-desktop: direct files.askui.com download cards, shorter steps - first-run: rewrite around a hello_world example — conversation-log walkthrough (timeline mock w/ Setup/Test/Teardown/Upcoming acts, coordinate clicks, real screenshot) and example markdown test report, explained for ISTQB testers; five statuses spelled out - remove the standalone onboarding page (folded into install/quickstart) - CLI is not shipped yet: install-cli/index/quickstart/install-desktop now say coming soon; uninstall.mdx matches the real NSIS uninstaller - app/global.css: AskUI Desktop theme tokens; layout tweaks Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…uns for docs screenshots

…ts incl. a live Android demo run (npm run screenshots)

…tures, best practices Replaces the "Using AskUI Desktop" / "Guides" grab-bags with four explicit content layers: - Concepts (foundation): how AskUI works (CUA loop), how a run executes (phases + why execution differs), architecture & data flow (components, ports, what leaves the network, storage, runtime downloads, infrastructure Q&A), team setups (testers-only / developers-only / shared). - Guides (end-to-end journeys): test an Android app, test a web app, AskUI in CI — thin, linking into the feature pages. - Feature sections (flat, app-shaped): Projects, Devices (one page per profile kind with Create it / Run it, field docs with type+default, lifecycle + emulator start states, real-device discovery), Writing Tests (working with test cases incl. the seeded templates, plans & procedures), Running Tests (running + watching live, scheduling, CLI), Results (report, conversation log, dashboard), Extending (tools, custom tools, MCP, secrets, model providers — previously undocumented or orphaned). - Best Practices (craft): writing good tests (+ non-determinism takeaways), what goes where, system prompt. Presentation: sidebar + page-title icons (lucide + hand-rolled Android/ Chrome brand glyphs), warn callouts for platform limits, Preconditions lines linking to AgentOS install, numbered steps with exact UI labels, param-doc field bullets, screenshot embeds throughout (captured window-scoped by screenshots-capture). All internal links rewritten; fumadocs loader gained a shared icon resolver. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…s into working-with-test-cases, plans-only page - test-case-formats: Template / Markdown / CSV / JSON as tabs (seeded examples) - index: suite-file templates as one tab group; procedures with explicit Define it / Use it; page shortened - plans-and-procedures -> plans (selection only); links swept Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…es folder tree, suite files as single steps - FAQ index: 'Find your question' — every audited question linked to the page that answers it (concepts, devices, writing, running, extending) - Test cases: platforms: line documented (authoring-only warn), skip guidance, tests/ folder tree, setup/teardown/rules split into per-file subsections with their templates Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…eenshot - Scope subsection: exact execution order for a nested case, single-file framing, failing-setup blast radius - Capture step + embed for the file tree's context menu (how to reach create/run/manage actions) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ope at a glance Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…suite run Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… concept headlines - Page order: tree/structure + steering files + procedures first, the create/run/manage functions at the bottom - Steering headlines use concepts (Setup — runs first) with file names in code titles; stable #steering-files anchor, links updated - Chain diagram starts from the Run action with numbered phases Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… compact md/csv/json tabs; formats page removed, links swept Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ce + chain diagram carry it Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ardown/Rules + Procedures Hub keeps the concepts diagram, create/formats/platforms, secrets usage, run and manage; deep dives get their own pages; anchors and FAQ swept. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ions Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>